The goal of this style guide is to provide a reference for design and editorial styles specific to the SMPH intranet and to promote consistency of web content. It combines campus policies and guidelines with data-backed best practices from sources like the W3C, Nielsen Norman Group and other industry and peer leaders.
If a topic is not covered here, please refer to the UW-Madison Guidelines or the WiscWeb KnowledgeBase.
All content managers should routinely check their pages for accessibility issues, broken links and misspellings, and ensure their pages are up to date. Use a website or browser extension to check for broken links and to check for accessibility issues.
Contact email@example.com with questions.
This is an accordion element with a series of buttons that open and close related content panels.
Campus websites must be accessible.
- Write in plain English.
- Always use alt text for images (unless the image is purely “decorative“or descriptive text is in the caption or beside the image).
- Avoid directional language (e.g., “click the box on the right to learn more”).
- Use meaningful link text and avoid using “click here”, “more” and “read more.”
- Open links to new web pages in the same window.
- Restrict the use of tables to tabular data.
- Use headings properly.
- Avoid linking PDFs and Docs. Users strongly dislike PDFs and they present accessibility issues. Create HTML gateway pages if a PDF version is needed.
- Convert PDF and Excel forms to Gravity Forms
- Provide closed captioning and transcripts for videos and long descriptions for complex images like infographics, charts and diagrams.
- Ensure that graphics, including icons and infographics, have sufficient color contrast (WebAIM Color Contrast Checker).
More information is available in the UW–Madison Digital Accessibility Policy and on the Accessibility @ UW–Madison website.
It is critical to make semantic use of heading tags (h1, h2, h3, etc.). These tags define the page structure and screen readers rely on them. Heading tags are not to be used merely for text formatting. An h3 is a child section of an h2, which is a child section of an h1. In other words, if a page has an h3, it must have a parent h2.
The WiscWeb theme’s page title is automatically set to h1, so h1 cannot be used within the page body. Therefore, any first-level subsections will start with an h2.
Links: Text, Email and Documents
Per campus accessibility guidelines, links to other web pages must open in the same window. A link within a form can open in a new window so users don’t lose information they may have entered.
Write meaningful link labels. Keep the 4 Ss in mind: link labels should be specific, sincere (accurate), substantial, and succinct. Do not use full URLs as link text. Do not use “click here.” Also see the UW links and calls to action guidance.
- Correct: View information about GravityForms
- Incorrect: View information about GravityForms here: https://kb.wisc.edu/wiscweb/page.php?id=70108
- Incorrect: Click here to view information about GravityForms
Do not use a person’s name as the link text if you’re linking to an email address; instead use the email address. If the person’s name is linked, the link should point to a web page about that person.
- Correct: Contact Samantha Jones at firstname.lastname@example.org.
- Incorrect: Contact Samantha Jones.
If linking to an external file, provide a hint to the user by putting the file type in parentheses.
- Use standard PC file extensions (.pdf, .doc, .ppt, etc.)
- Include the file type in the link. Example: View the campus badge policy (PDF) for more information.
Bulleted lists are a great way to make pages more scannable. Follow this format:
- Capitalize the first letter of each list item.
- Don’t use semicolons after each list item. Use periods if each item is a sentence (or completes the opening stem sentence). Don’t use punctuation if the items are fragments.
- Be consistent in verb tense and punctuation.
Correct bulleted list
The capstone project will include one of the following:
- A written report
- An oral presentation
- A multimedia project
Incorrect bulleted list
The capstone project will include one of the following:
- a written report;
- an oral presentation; or
- a multimedia project.
Editorial Style/General Writing Tips
For consistency, follow the UW-Madison Editorial Style Guide. Here are some rules of particular note, and some not covered in the guide:
- Acronyms and jargon should be used sparingly, preferably not at all, especially when abbreviations and terminology aren’t likely to be known outside of your administrative unit or department
- Ampersands: Do not use unless part of a proper name
- Brackets vs. parentheses: Brackets are used for shortcodes (e.g., inserting a plugin), so they should not be used in body copy. If it’s necessary to denote that inserted text is the writer’s and not the speaker’s, use parentheses and include an editor’s note, or paraphrase. This is usually only an issue in first-person essays or interviews that use a Q&A format. For example:
- “Smith: After 20 years, I’m excited to return to Madison and reconnect with my Badger roots. (Editor’s note: Smith earned his medical degree at UW-Madison.)”
- Capitalization: Avoid excess capitalization, particularly with titles
- Commas: Do not use a serial/Oxford comma with 3 or more items, unless not doing so would cause confusion.
- Dates: Do not abbreviate months. It is not necessary to use ordinal numbers
- Correct: Submissions are due by July 12
- Correct: Meeting dates are March 5, 12 and 19
- Correct: The event takes place October 13-14
- Correct: The event will be held 8 a.m. August 12 at the Health Sciences Learning Center
- Incorrect: Submissions are due by July 12th
- Degrees: Do not use periods (MD, PhD, etc.; not M.D., Ph.D.)
- Health care (two words), not healthcare
- Health professions student, not health professional student
- UW–Madison uses an en dash not a hyphen; he same is true for University of Wisconsin–Madison.
- University-wide but no hyphen in other “-wide” words (schoolwide, campuswide, systemwide, statewide, citywide, countywide, nationwide, worldwide)
- Internet terms:
- email (no hyphen), e-newsletter (hyphenated)
- login, logon, logoff (nouns); log in, log on, log off (verbs)
- home page (two words), web page (two words) website (one word), online (one word)
- Facebook (lowercase “B”), YouTube (uppercase “T”)
- Percentages: Spell out the word percent. The symbol % is acceptable in lists, tables, and charts, but not in running text except in scientific, mathematical, and highly technical contexts
- Correct: Enrollment increased by 27 percent
- Incorrect: Enrollment increased by 27%
- Use a.m. or p.m. (use periods)
- Use noon or midnight instead of 12 p.m. or 12 a.m.
- Do not use :00 for times on the hour
- In a range of times, include a.m. or p.m. with the later time only, unless the range includes both (8 to 11:30 a.m.; 1:30-5 p.m.; but, 9 a.m.-2 p.m. or 8 a.m. to noon)
- Exclamation points: Avoid as much as possible
- Master of public health is not a master’s degree; it is a health professions degree
- Periods: Use one space following a period.
- Redundancies: You can clean up your copy by avoiding phrases like these:
- “Advance registration” or “preregistration” (to register for something means to do so in advance)
- “Is currently” (“is” and “currently” both refer to present time)
- “Including, but not limited to” (“including” denotes that there could be additional items)
- “Join together” (“join” means to bring together)
- “Joint collaboration” (collaborations are joint ventures)
- Text formatting:
- Avoid excess use of bold and italicized text.
- Do not underline regular text. Underlining indicates that text is a link.
- Do not use superscripts and subscripts. Use normal text, e.g., “the 16th annual symposium.”
- Headers (h2, h3, etc.) are used for page structure. Headings are not used simply to make text bold or larger.
General web writing guidelines
- Underlined text should only be used for links on the web, not for emphasis
- Web writing should be much less formal than academic writing — use an active voice and a more conversational tone
- Cut the clutter. Use the inverted pyramid
- Eliminate platitudes such as “welcome to our website!” and other blah-blah text
- Avoid jargon. Use plain language
- Avoid directional language, such as “click the box on the right” or “read below to learn more” — directional language is not relevant to those using screen readers and can change on mobile devices (the “box on the right” might be above or below when viewed on a phone)
- Web copy should be scannable — a few techniques that can help achieve this include:
- Short paragraphs (similar to news writing)
- Subheads to break up long pages
- Bulleted lists
Photos, Images and Icons
Follow the WiscWeb – Image Sizing Recommendations.
- Images should not be larger than 180k. Use an image compression program (like Photoshop) to optimize images for web.
- Use professional quality images (i.e., shot by professional photographers with UW–Madison or UW Health). Use authentic imagery, and ensure that imagery is not taken out of its original context. Do not use stock photography or videography. Follow best practices described in the UW–Madison Inclusive Communications Guide.
- UW–Madison/University Communications photos can be used within the photo use guidelines.
- Published photos must include a credit (“photographer’s name/University of Wisconsin–Madison” or “courtesy of …”).
- UW–Madison photo library photos are available for noncommercial communication pieces about UW–Madison.
- The images are not available for generic use unrelated to UW–Madison.
- You must have an authorization form on file to use any photos and videos that show patients and clinical research participants. Consent forms for UW Health patients are available in English and Spanish. Consent forms for clinical research participants at UW–Madison are available through the Office of Compliance.
- Permission must be granted to use photos from other organizations/institutions. Do not use images from websites or Google image search without permission.
- Add alt text for images to comply with accessibility standards.
- Be accurate and equivalent in representing content and function.
- Be succinct without sacrificing accuracy. Typically, only a few words are necessary.
- Do not be redundant or provide the same information as text near the image.
- Do not include phrases like “photo of …”, “graphic of …”, or “headshot of …” etc. This is redundant since screen readers already announce “graphic” along with the alt text.
- A resolution higher than 72 dpi
- Images scaled larger than the source file size
- Dimensions that are not proportional to the source file, causing distortion
- Stock imagery (research shows that stock photography often harms the user experience)
- Should only be used on the home page and section front pages
- Should I use a carousel? Probably not. Most users will not linger on a page long enough to flip through a carousel. If you need convincing, here’s a blunt explanation of why carousels generally are a bad idea. However, the web team recognizes that photo carousels often are a good political solution. If you must create one, please use no more than three images.
- More information: WiscWeb – Using the Hero Content Area
Icons can be an effective way to visually convey information, but they can also confuse users. Choose icons that are easily recognized and understood. If the concept is esoteric or doesn’t have an obvious visual association, then it’s better not to use an icon.
Icons must always have an accompanying alt text. The text should be html and not embedded in the graphic. The suggested specs are:
- Red circle background, 100×100 pixels, standard UW red (#c5050c)
- Inner element (the symbol or icon itself) is white
- Save as a png with a transparent background
- Do not add bevels, drop shadows or other effects
- The home page has examples of the suggested icon style
- Experience with an image editing or illustration program (e.g., Photoshop or Illustrator) is necessary to create icons. If you’re not comfortable creating graphics, ask the web team for help.
In addition to the URL, captions, surrounding text and alt text, Google uses the file name to help it understand your images and rank them in image searches. File names give Google clues about the subject matter of the image. For example, HSLC-main-atrium.jpg is better than IMG00023.JPG.
Search and Keywords
The intranet uses Google Programmable Search. If you recently added a page and need it to show in search ASAP, please contact the web team to have the page submitted for indexing. After submission, indexing is typically done within a few days. If indexing is not requested, it may take a few weeks for Google to index new pages.
Tips for improving searchability:
- Convert pdfs, Word documents and PowerPoints to web content (as a bonus, this also improves user experience).
- Include an introductory paragraph on each page that explains what the page is about and includes keywords.
- Use keywords and phrases your audience will use to search. The official title may be “Policy on Interactions with Industry” but users may search for “conflict of interest policy.”
- Include transcripts with videos.
- Include descriptions of charts and infographics as web content.
- Consider asking the web team to add a promotion which will cause your page to display as the first result for a given keyword(s) (within reason).
When to Use a Post
Use a post instead of a page when you want to:
- Add a blog-like feature to your content.
- Group related items by category or tag, like “News.”
- Allow comments.
To create a post click Posts > Add New. Note that there are fewer content elements available for posts; you will be limited to text and photos.
Customized news feeds
You can select or add additional categories to create a feed of articles for the area of the intranet you manage. To display a feed on a page, use the Posts Listing element.
See DoIT’s information about creating posts and using the Posts Listing page element for detailed instructions.
A short “vanity” URL can be helpful when using the full URL is impractical or unwieldy, such as a printed flyer or other case where the user would have to type in the URL. The redirection plugin, found under Tools in the left admin menu, can be used to create shortened URLs. QR codes are also a good option for print and signage.
How to create a shorted URL
First, check to see whether the shortcut is already in use. Then, from the Redirections plugin, fill out these fields listed under “Add new redirection”:
- Source URL: The shortened URL
- Query parameters: Leave as is (exact match all parameters in any order)
- Target URL: The page the shortcut will redirect to (you only need the relative path)
- Group: Redirections
Guidelines and considerations
- Do not create shortcuts indiscriminately.
- Do not create multiple shortcuts for the same page.
- Words are more easily remembered than letters, so shorter isn’t necessarily better.
- Use lowercase; shortcuts are case-sensitive.
- Do not use special characters except hyphens, which can help with clarity (compare /gored to /go-red).
- Do link to shortcuts on web pages; use the full URL.
- Colors or fonts outside of the UW-Madison web color palette and UW-Madison web fonts
- Uncompressed (>180k), pixelated or distorted images
- Tables to facilitate layout, instead:
- Use tables only when displaying tabular data
- Consider using wpDataTables with Google spreadsheets
- The media library in WordPress for document storage, instead:
- Store documents in your unit’s Box folder (each administrative unit has a Box folder and WordPress editors have access)
- Use shared Box links in web pages
- Pdfs or Word documents that contain plain text and/or don’t have a business need to be printed (convert them to HTML web content)
- Accordions or tabs with small amounts of content (these elements increase interaction cost)
- Word cloud images, button images, or text as images
- Excessive amounts of bold or italic text (too much hinders readability)
- Underlined text, unless it’s a link
- Page elements incorrectly
Plugins are managed by DoIT. Contact email@example.com with questions or requests. View a list of available WiscWeb plugins.