Conventions

How to write and structure pages built on CMU's template and the kit: wording, headings, links, images and accessibility.

AP Style

Follow The Associated Press Stylebook for grammar, punctuation, numbers and dates. CMU names AP style as its preferred standard in its Brand Standards writing guide. The kit's docs follow it too. The rules that come up most on web pages:

• No comma before the last item in a simple series: "red, white and blue." Add one only when the sentence would be unclear without it.
• Dates: abbreviate the month with a date, "Jan. 11," but not alone or with only a year: "January 2027." Spell out March, April, May, June and July. Ranges take a hyphen with no spaces: "Dec. 7-18," "2-3 p.m.," "2026-27."
• Times: "9 a.m.," "2:30 p.m.," "noon" and "midnight." Drop ":00."
• Numbers: spell out one through nine and use figures for 10 and up, except for measurements, percentages, ages, dates and times, which always take figures: "three columns," "a 768px screen."
• Keep "a" with its noun. If a lone "a" would end a line, join it to the next word with  , as in a camera. Don't use nonbreaking spaces to force whole sentences onto one line.

CMU Names and Terms

Follow the university's naming and capitalization guidance:

When You're Writing About…	Use This Pattern
The university	Carnegie Mellon University on first reference; Carnegie Mellon or CMU after that.
An unfamiliar acronym	Environmental Health and Safety (EHS) on first reference; EHS after that.
Students and semesters	"First-year students can register in the fall semester." Keep both terms lowercase in prose.
Departments and subjects	"The Department of Physics offers courses for physics majors." Capitalize the formal name; lowercase the subject.
Signing in	"Sign In" on buttons and links, never "Log In"; in a sentence, "Sign in with your Andrew ID."

Headings

• Capitalize the principal words, as AP does for the titles of works: headings, buttons, navigation and labels. That includes every word of four or more letters, such as "With" and "From," and the first and last word: "Upload Your Syllabus." Use sentence case for prose: "Upload your syllabus before classes start."
• Leave periods off headings and hero titles. Use normal punctuation in full sentences.
• Put the important words first. People read the first two or three words of a heading, link or list item and move on: "Syllabus Due Dates for Spring," not "Information About When Spring Syllabi Are Due."
• Choose heading levels by what they contain, never by how big they look, and don't skip a level. Screen reader users move through a page by its headings, so the headings alone should outline the page.
• Read the page as a task. Can someone scan the headings, find the main action and tell what happens after they select it?

Buttons and Links

The template gives buttons, calls to action and ordinary links different visual weight. Match that weight with words that say what happens next, starting with a verb and naming the task.

A link goes somewhere; a button does something. Use a link (<a>) even when it looks like a button, and a <button> for an action even when it looks like a link: screen readers announce them differently, and the keyboard works them differently. These examples lead to real kit pages:

• A button and a call to action side by side go in one paragraph, button first; the kit spaces them as in a hero.
• Never write "click here." A link should make sense on its own, because people scan links and screen readers list them: "Read the Instructor Guide," not "Click here for the guide." Give links on the same page different words, so that list doesn't read "Read More, Read More, Read More."
• Label special destinations. After a link that requires sign-in, add [login required] as plain text outside the link. After a file link, add its type, such as [PDF]. These labels tell people what to expect before they select it.
• Omit [login required] when the link text already makes it clear, as in "Sign In to See Your Courses." Use only one label: a syllabus link gets [login required] when signed out and [PDF] when signed in.

Heroes

Say what the site or app does, then give it two next steps: a button for the main action and a "Get Started" call to action. That second link jumps to the first section below, also headed Get Started. Here's the pattern from the kit's home page:

The title names the purpose, the lead says who it's for and the button names the action. The screenshot shows what people can expect. Use the hero component to build your own.

Instructions

Write to the person doing the task, in the active voice: "Upload your syllabus," not "Syllabi may be uploaded by instructors." Name each control exactly as it appears on screen, and put steps in the order people follow them, one main action in each.

Don't point by color, shape or position alone: "Select Join the Queue," not "Click the red button on the right." People using a screen reader, a phone or a zoomed-in screen may not see it where you do. Say "select," not "click," since not everyone uses a mouse.

Messages

"An error occurred" leaves the reader stuck. An error message names the problem and offers a way forward; a success message confirms what changed. Say it in words, not just color: each of these sample flash messages starts with what happened, so it reads the same without the red or green.

Your syllabus wasn't uploaded. Choose a PDF file and try again.

Your syllabus was uploaded. Students can now find it in the course list.

Images

• Alt text describes what the picture shows, in a sentence or less, without "Image of" or "Photo of": screen readers already say it's an image. For a screenshot, describe what the reader should notice, not every detail.
• A decorative image gets empty alt text (alt=""), so screen readers skip it. A linked image's alt text says where the link goes.
• Captions add what alt text doesn't: who's in the photo, where and when, and the credit. Don't repeat the caption in the alt text. See Photo Captions and Credits.
• A photo set as a background, such as the template's hero, gets role="img" and an aria-label describing it, since it has no alt.
• Keep words out of images. Put them in the page, where they can be resized, translated and read aloud.
• Videos need checked captions and a title on the frame. See Videos.

Accessibility

Under the university's Digital Accessibility Policy, CMU websites and web apps must meet WCAG 2.1 Level AA. The template and the kit's components give you a start; the words, headings, images and links are yours. The Digital Accessibility Office has guidance, training and help, and the CMU Web team's accessibility best practices cover Cascade sites.