Intranet Style Guide

This style guide explains the design and editorial rules for the SMPH intranet. It was created to ensure consistency across the site and provide guidance on developing and maintaining 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.

This guide will be updated as new issues arise that require a ruling. If a topic is not covered here, defer to these sources:

If you have questions, contact the web team at smphweb@uwhealth.org.

Topics in the guide:

Accessibility issues

Campus has emphasized that UW-branded websites are accessible. Here are some ways you can help maintain accessibility standards (some of these are explained later in further detail):

  • Write in plain English
  • Always use alt text for images
  • Avoid directional language (e.g., “click the box on the right to learn more”)
  • Create meaningful link text (anchor text) … i.e., try to avoid “click here”
  • Open links to new web pages in the same window
  • Limit the use of page elements that hide content until the user clicks on something (such as accordions and tabbed content)
  • Restrict the use of tables to tabular data
  • Use headings properly
  • Provide transcripts of videos and infographics
  • Ensure that graphics, such as icons and infographics, have sufficient contrast

For more information, view the campus World Wide Web Accessibility Policy.

Learn some dos and don’ts on designing for accessibility from GOV.UK.

Bulleted lists

Bulleted lists are a great way to make pages more scannable. They should 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 no punctuation if the items are fragments.

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.

Colors

This is the official UW-Madison web color palette. It is part of the UW-Madison brand. Remember that the brand of your administrative unit or program is the UW-Madison brand. Please do not deviate from the official color palette.

Custom code

The UW WordPress theme allows minor inline style tweaks, such as changing the spacing between bulleted list items or adding a button. Inline custom code should not be used to create alternate page layouts, alter page elements or add functionality that is not built in.

There are several reasons for this. Mostly notably, in many cases custom code simply will not work due to how campus has chosen to configure WordPress. This will result in code being stripped out when used in a text block content element. In addition:

  • It’s generally poor practice to build pages that rely heavily on inline styles and scripts.
  • Extensive use of inline code makes content more difficult to maintain.
  • The process can introduce security vulnerabilities.
  • The code may cause conflicts and compatibility issues with future theme updates.

Users who feel the default page layouts and content elements do not meet their needs can contact DoIT’s WiscWeb support team at cms-support@doit.wisc.edu to discuss options.

Document management

Documents should not live within WordPress; they should be uploaded to Box. The web team has created a folder for each administrative unit; anyone who has WordPress access will also have access to their administrative unit’s Box folder. Use shared links to link to files from web pages.

Fonts/typography

These are the official UW-Madison web fonts. The web team will not add or permit the use of additional fonts. Do not cheat by embedding custom fonts in graphics or using inline styles.

Grammar/editorial style; general writing tips

Basic grammar guidelines

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 comma unless not doing so would cause confusion.
  • Dates: Do not abbreviate months. It is not necessary to use ordinal numbers.
    • Wrong: Submissions are due by July 12th.
    • 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.
  • Degrees: Do not use periods (MD, PhD, etc.; not M.D., Ph.D.).
  • Health care (two words), not healthcare.
  • Internet terms: email (no hyphen), e-newsletter (hyphenated), Facebook (lowercase “B”), home page (two words) login (noun and verb), online (one word), Twitter, web page (two words) website (one word), YouTube (uppercase “T”).
  • OK (not okay; note that this is different from campus style).
  • Percentages: Spell out “percent” unless using the symbol as display type in a chart or graphic.
    • Wrong: Enrollment increased by 27%.
    • Correct: Enrollment increased by 27 percent.
  • Times:
    • 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)

Other rules

  • Exclamation points: Avoid as much as possible.
  • Master of public health: It is not a master’s degree. It is a health professions degree.
  • Periods: 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. It is not necessary to italicize titles of things; capitalization is sufficient (this differs from campus style).
    • Do not underline regular text.
    • Do not use superscripts and subscripts. Just use normal text, e.g., “the 16th annual symposium.”
    • Headers (h2, h3, etc.) are used for page structure. They are not used only to make text bold or larger.

General web writing guidelines

  • Web writing should be much less formal than academic writing. Use an active voice. Feel free to use 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.” Users can figure it out. Also, directional language creates issues for mobile devices (that box on the right might be above or below when viewed on a phone).
  • Web copy should be scannable. Here are a few techniques that can help achieve this:
    • Use short paragraphs (similar to news writing)
    • Break up long pages with subheads
    • Break long lists into bulleted lists

Icon style

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 text label. 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
  • Note that some 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.

Linking to things

Per campus accessibility guidelines, links to other web pages must open in the same window. Links to different document types that use an external application, such as pdfs or Word documents, can open in a new window. A link within a form can also open in a new window so users don’t lose information they may have entered.

All links should use meaningful anchor text. Do not use full URLs as link text. Do not use “click here.”

Do not use a person’s name as the anchor text if you’re linking to an email address. Use the email address as the anchor text. When the anchor text is the person’s name, the link should point to a web page about that person.

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 as part of the anchor text
  • Example: View the campus badge policy (pdf) for more information.

Mobile (responsive) design

All content must be responsive – which basically means it must look good whether users view it on their phones or office computers. For the most part, this will be handled by default because the UW WordPress theme was built to be responsive right out of the box. But there are some steps you can take to ensure you’re meeting mobile-friendly standards:

  • Use tables only for tabular data
  • Include a text version of charts and infographics (remember, images shrink for mobile devices, which means any text embedded in a photo or graphic will be difficult to read on a phone)
  • Make sure every page is linked from somewhere
  • Limit the use of page elements that hide content (accordions, tabbed content)

News articles

To enter a news article, create a post instead of a page (click Posts / Add New). Note that there are fewer content elements available for posts; you will be limited to text and photos.

When does it make sense to create a post instead of a page?

  • When you want to add a blog-like feature to your content
  • When you want to group related items or news articles and display them as a feed
  • When you want to allow commenting

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 Latest Posts page element.

See DoIT’s information about creating posts and using the Latest Posts page element for detailed instructions.

Page layouts and elements

Users should familiarize themselves with the available page layouts and elements.  Note that not all elements work with every page layout. Be thoughtful when choosing page elements. For example, the alternating content boxes element can look great, but only when it’s used with good photography.

Page structure/hierarchy

It is critical to note the proper, semantic use of header tags (h1, h2, h3, etc.). Header tags set the page structure. They 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 h1 is automatically set by the page title, so it cannot be used within the page body. Therefore, any first-level subsections will start with an h2.

Photo/graphic element standards

Hero images

  • Can only be used on the home page and section front pages
  • 1600×500 pixels
    • Original files must be at least that large; do not upsize images that are natively less than 1600 pixels wide
  • Must be professional-level quality (i.e., shot by UW Health marketing and public affairs, Media Solutions or University Communications photographers)
  • File size should be no more than 180k; use an image compression program if necessary
  • 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. So, if you must create one, please use no more than three images.
  • More information: WiscWeb – WordPress UW Theme – Using the Hero Content Area

Suggested naming convention

(type of graphic element) – (section) – (name) . (jpg/png/gif)

Abbreviations for types of graphic elements:

  • btn: buttons (try to avoid except for icons that have accompanying text labels; use CSS instead)
  • hero: hero images
  • icon: icons
  • img: in-page photos (any photo that’s not a hero)
  • thumb: thumbnail images

Example:

  • A picture of the HSLC used as the hero image for the facilities home page: hero-facilities-hslc.jpg

Formatting/usage rules

  • Headshots for faculty and staff lists are 200×200 pixels (this custom size needs to be specified when adding the faculty/staff content element to a page). If possible, they should be cropped from roughly the shoulders up so they display consistently.
    • If no headshot is available, use the 1-pixel placeholder, which is named img-pixel-placeholder.png in the media library. (This is a workaround for a bug that displays an image of Bucky Badger if no photo is available. It only applies when using the faculty/staff member tool.)
  • Do not upsize photos, i.e., if an original photo is 600×400 pixels, it cannot be displayed larger than that.
  • Do not change the proportion of photos, i.e., if an original photo is 600×400 pixels, it cannot be displayed at 600×300 pixels.
  • Do not use a higher resolution than 72 dpi.
  • Photos must be responsive. When in doubt, use the image page element.
  • Photos from Media Solutions, UW Health marketing and communications and UW-Madison/University Communications can be used freely. Permission must be granted to use photos from other organizations/institutions. In other words, you cannot simply pull a photo from a random website or Google image search and use it as you wish.
  • All images must have alt text to comply with accessibility standards.

Should I use stock photos?

No. Research shows that stock photography often harms the user experience.

Plugins

The web team does not control plugins nor does it have the ability to install them. This is managed by DoIT. DoIT will generally not install plugins for one-off uses, however, users can contact DoIT’s WiscWeb support team at cms-support@doit.wisc.edu to request plugins.

Quality assurance (QA)

All content managers should routinely check their pages for broken links and misspellings, and ensure their pages are up to date. Use a website or browser extension to check for broken links. The web team will also be happy to provide QA reports upon request.

Searchability

Users become frustrated when they can’t find things on the web. However, search engines generally are very good at finding content. When a user can’t find something through a search, it’s often because the content doesn’t exist or has not been optimized for search.

Tips for improving searchability:

  • Create content based on your audience’s interests.
  • 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.
  • Consider asking the web team to create a promotion within the site search, which will force your page to appear as the first result for a given set of keywords (within reason).
  • Related to that, write content using terms your audience uses. For example, something may officially be titled the Policy on Interactions with Industry. However, the user might look for this by searching for “conflict of interest policy.”
  • Include a transcript, or at minimum a meaningful summary, with videos.
  • Include the text of charts and infographics as web content.
  • Create meaningful anchor text (i.e., don’t just tell the user to “click here”).
  • Write descriptive page titles and subheads.

Shortcut URLs

It’s possible to create a short vanity URL that can be used in situations where including the full URL would be impractical or unwieldy, such as a printed flyer, business card or other case where the user would have to type your site’s address into a web browser. This is done via the Redirection plugin, which can be found in the left sidebar under the Tools menu.

How to create a shortcut

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 shortcut
  • 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 not use shortcuts on web pages; use the full URL and create a link using appropriate anchor text.

Tables

Tables are only to be used to display tabular data; they cannot be used to facilitate page layouts. Where possible, use the wpDataTables widget. The web team recommends using wpDataTables with Google spreadsheets.

Things that are not allowed

  • Blinking text
  • Custom fonts
  • Custom colors
  • Excessive use of bold or italics (too much hinders readability)
  • Uncompressed, pixelated or distorted images, including:
    • Running a high-resolution photo at 200 pixels wide
    • Using a low-resolution photo as a hero image
    • Altering a photo’s proportions
  • Disproportionately sized graphics (e.g., running the SMPH logo at half the width of a page)
  • Linking to pdfs or Word documents that contain plain text (convert to actual web content)
  • Tag clouds/word clouds as graphics
  • Underlined text, unless it’s a link
  • Misuse of page elements. Examples include:
    • Accordion panels or tabbed content that contain small amounts of content (accordions and tabs increase interaction cost; therefore, when using these elements, it’s important to give users their money’s worth, so to speak)
    • Nesting tabbed content within accordion panels
    • Alternating content boxes without images or images that are smaller than 576×384 pixels
    • Image carousels used for page/section navigation