CASL KB Style Guide

Documenting the Interface: What Verb, What to Call It

Our articles are worded so they are accurate whether readers are using a laptop or a mobile device.

Use "Select," Not "Click"

Use select as the everyday verb for choosing a button, link, menu item, tab, or list option. Not because of a style fad, but because many of our readers are on phones and tablets: they don't click, they tap. "Select" is the one word that's true whether the reader clicks, taps, or uses a keyboard. Keep the verb quiet and let the bold label carry the meaning.

Common Interface Verbs

Verbs to Use

The following table lists the standard verbs to use when documenting software procedures.

Verbs to Avoid

Avoid using these words and phrases:

• Click on (just "select")
• Type in or input (use "enter")
• Hit a key (use "press")
• Navigate to (use "go to")

What to Call Each Control

Name the Control Type Only When It Helps

Include the type of control (drop-down list, tab) when the reader needs it to find the thing. Drop it when the bold label alone is obvious.

Menu Paths and Keyboard Keys

Menu/Navigation Paths

To document a menu navigation path:

1. Type each menu element, making sure the first letter of the element is capitalized.
2. Use a greater-than symbol (>) with a space on each side as a menu path separator. For example: File > Save.
3. Select the entire menu navigation path so that it is highlighted.
4. Select the Navigation Path style. Applying this style makes the path elements bold and leaves the greater-than symbol as-is. For example: File >then Save.

Keyboard Keys

To document the keys a user has to press:

1. Type each keyboard key, making sure the first letter of the key is capitalized.
2. If the user needs to press multiple keys, use a plus symbol (+) with a space on each side between each key. For example: Ctrl + Shift + R.
3. Select the entire keyboard key combination so that it is highlighted.
4. Apply the Keyboard Keys style. For example: Ctrl + Shift + R.

Numbered Steps

When you write steps that happen in order, use the editor's Numbered List format. Never type the numbers yourself.

A typed number is just text: a screen reader doesn't announce it as a step in a list, the numbers don't renumber when you add or remove a step, and the spacing and style won't match the rest of the KB. A real numbered list is structure the page understands, so it stays correct and accessible.

When a Screenshot Interrupts the Steps

Placing a screenshot (or a callout, or any other block) in the middle of a numbered list splits it into two lists, and the second list restarts at 1. To fix this, put your cursor in the restarted list and select Continue Numbering from the KB Styles menu. The numbering picks up where the first list left off.

Pronouns and How to Address the Reader

Speak to the reader directly as "you," and for anyone you describe in general (an instructor, a student, a user) always use they / their. Never "he," "she," "his," "her," or "his/her" for a generic person.

Acronyms

Spell out the full term on first use, with the acronym in parentheses right after. After that, use the acronym alone for the rest of the article.

• Introduce the acronym on first use even if you only use it once. Spelling it out with the acronym in parentheses tells the reader what the short form means and what they will see elsewhere in Canvas.
• Reintroduce per article, not per section. Define the acronym once at its first appearance. You don't need to redefine it in every section. In a very long reference article, you may reintroduce it at a major section if the first use was far above.
• Some well-known acronyms can be used directly without spelling out, because they are more familiar than their expansions: FAQ, PDF, URL, HTML, and UWM.
• Make acronyms plural or possessive without an apostrophe. Write FAQs, not "FAQ's." Use a lowercase "s" with no apostrophe.

Canvas Terms and Capitalization

This is the easiest place to slip. The rule: capitalize a word when you mean the Canvas feature; use lowercase when you mean the everyday thing. The same word often changes based on what you mean.

A helpful tell: the feature-area name (the things in Course Navigation: Assignments, Pages, Modules, Files) is usually the capitalized one; a single everyday instance (an assignment, a page) is lowercase.

Some Canvas names are always capitalized because they're proper names with no everyday version: SpeedGrader, DocViewer, Dashboard, Rich Content Editor (RCE), Course Navigation, Global Navigation, Inbox, Syllabus, New Quizzes, Classic Quizzes, Blueprint Course, Course Home Page.

When you name a Canvas icon, use its real name (Assignment icon, Attachment icon (the paper clip), Discussion icon (the comment bubble), Quiz icon, Visibility icon (the eye), Warning icon) rather than inventing a description.

Everyday Computing Terms

• log in / log out are verbs ("Log in to the website"); login / logout are nouns or adjectives ("the login button"). Same for sign in / sign out. Never "log into" or "sign into."
• email (not "e-mail")
• website is one word; web page is two; home page is two
• plugins (no hyphen); add-ons (with a hyphen)
• Internet is capitalized

Naming UWM and the Universities

• University of Wisconsin-Milwaukee: hyphen, no spaces. UWM is fine on first reference in KB articles; both UWM and UW-Milwaukee work afterward.
• Use Universities of Wisconsin (not "UW System") in current references.
• Lowercase university as a common noun, even for UWM ("the university recently…").
• What used to be UW Extended Campus (UWEX) is now the Office of Online & Professional Learning Resources (OPLR).

Punctuation, Spacing, and Numbers

• Use the Oxford comma: assignments, quizzes, and discussions.
• One space after a period.
• Percent: use the % sign with a number, no space (95%); add a leading zero below 1% (0.7%). Spell it out in casual phrasing ("a zero percent chance").
• Phone numbers use hyphens: 414-229-4035.
• that vs. which: "that" (no commas) for essential information; "which" (with commas) for information you could drop without changing the meaning.
• Ampersands (&) only in official names or logos, never in place of "and" in a sentence.

Bolding

Bold marks a role, not loudness. A bolded word should be doing a specific job: naming a control, leading a list item, or marking a term where it's defined. It is not for stressing a word or sentence in running text. The value of bold comes from being rare. If everything is bold, nothing stands out, and the bolded labels readers rely on stop signaling "this is the thing to act on."

When to Bold

• UI labels in instructions. Bold the name of the control the reader acts on, so their eye can find it: select Save.
• Lead-in terms in a rule or definition list. Bold the term the list item is about, so readers can skim the bolded terms to find what they need. (This guide's lists use this convention throughout.)
• A key term where it is first defined. Bold the term once, at the moment you introduce it: write in active voice.

Callout labels ("Tip:", "Important:") and the Navigation Path style also appear bold, but their bold comes from the theme style, so you don't add it by hand.

When Not to Bold

• Don't bold for emphasis. To stress that something matters, use sentence structure or an Important callout, not bold running text. Bolding a phrase mid-sentence to make it louder competes with the bold labels readers depend on.
• Don't bold whole sentences or paragraphs. Long bold runs are harder to read, the same reason you color the status word and not the whole sentence.
• Don't use bold to fake a heading. Use a real heading in order (see Accessibility Essentials). Bolded text that looks like a heading isn't announced as one to screen readers.

Headings and Structuring an Article

The KB makes your article title the top heading (Heading 1) automatically, so your own sections start at Heading 2. Never put a Heading 1 in the body.

• Heading 2 for your top-level sections, Heading 3 for subsections, Heading 4 beneath those, always in order, never skipping a level.
• Break up dense content with headings so readers (and screen-reader users) can scan and jump.
• Headings use title case: capitalize the major words (the same as article titles). Example: Creating an Assignment, not Creating an assignment.
• For long, dense reference articles, you can use the H2 Bar style for stronger top-level section breaks, but use it for every Heading 2 on the page or none, and save it for genuinely long pages.

Adding a Table of Contents

The KB can build a clickable Table of Contents for you with Insert > Table of Contents. It pulls your Heading 2 and Heading 3 sections automatically and publishes as the boxed "In this article" panel; you don't type the heading or the box, and there's nothing to style. (This very guide uses one.)

The question is when it's worth it. A Table of Contents earns its place when a reader needs to jump to a section rather than scroll. On a short article, scanning a list of links is slower than just reading. So:

• Add one when the article has about four or more sections, or runs longer than a screenful. That's enough structure for the map to be useful.
• Skip it on short articles: three or fewer sections, or anything a reader takes in at a glance. A three-paragraph article doesn't need one.
• It's most useful on reference and informational articles people land on to find one specific part (an "Assignments" overview where someone wants just the grading section).
• It's least useful on simple step-by-step procedures meant to be followed in order; inviting readers to jump around can work against the sequence. A long how-to may still skip it.

Because it builds from your headings, a Table of Contents is only as good as your heading structure, one more reason to use real Heading 2 and Heading 3 levels, in order, rather than faking sections with bold text.

Images and Screenshots

Most of our images are screenshots, and a few consistent habits keep them readable, accessible, and stable across theme changes. (Screenshot capture settings (the SnagIt tool configuration, annotation colors, and capture rules) live in the separate Screenshot Standards document. This section covers how an image behaves once it's in a KB article.)

Placement and Sizing

• Align images to the left. Left-aligned images give every reader a consistent starting edge to scan from.
• Under an indented step, align the image's left edge to the indented text, not the page margin, so the image visually belongs to the step it illustrates.
• Apply the Image Border style to every screenshot so it separates cleanly from the page.
• Insert images at 100% and keep screenshots no wider than 600px. Don't resize an image after it's placed in the article; capture or scale it correctly first.

File Format and Naming

• Save images as .png.
• Give every image a meaningful, unique file name that describes its content: assignment-settings-panel.png, not image1.png or an auto-generated string like b64_20240709085148-1.png. The name must be unique: uploading a file with a name already in the KB overwrites the existing one.
• Keep names short, lowercase, and free of special characters. Don't add a second extension (e.g. .jpg onto a .png).

Alt Text

Every image needs alt text that conveys what the image communicates, or it must be marked decorative if it carries no information the surrounding text doesn't already give.

• Describe the image's purpose, not every pixel. Aim for under about 120 characters: long enough to be useful, short enough to be heard in one breath.
• Mark purely decorative images as decorative so screen readers skip them. A screenshot that repeats what a step already says in words can often be decorative.
• Don't start with "Image of…" or "Screenshot of…"; a screen reader already announces that it's an image.

When an Image Needs a Long Description

Rarely, an image carries more than 120 characters of essential information, such as a complex diagram or a data-heavy chart. When that happens (and it should be rare, since most screenshots don't), put the full description at the end of the KB and point to it with an anchor, rather than entering a paragraph into the alt attribute:

• Add a Long Descriptions Heading 2 at the end of the article.
• Write the full description in Long Descriptions under its own subheading.
• Link to  the full description from a link you insert near the image (e.g. "See the full description"), using an anchor jump.
• Keep the image's own alt text short (just a summary), and have it point the reader to the long description.

Accessibility Essentials

These are quick to get right and matter a great deal to readers using assistive technology:

• Every image needs alt text, or mark it decorative if it carries no information.
• Every data table needs a caption and real header cells.
• No merged or split cells in a data table; keep it a simple grid. Split a complicated table into two.
• Never use a table to lay out a page: tables are for data only.
• Use real headings in order: never make text look like a heading by bolding it.
• Write meaningful link text: "Register for an accessibility workshop," never "click here" or a bare web address.
• Never rely on color alone to carry meaning.
• Avoid all caps. All-capital text is harder to read and can be misread by screen readers, so use normal capitalization.

Titles, Summaries, and Keywords

Titles

Start with the tool name, then a spaced hyphen, then the topic: Canvas - Topic. Add the audience in parentheses when an article is just for one group.

• How-to / process guides use an "-ing" phrase: Canvas - Creating an Assignment.
• Overviews and informational articles use a topic noun: Canvas - Course Navigation.
• FAQs use a topic plus "FAQ": Canvas - Assignment Settings FAQ.
• Audience-specific articles add it at the end: Canvas - Grading in SpeedGrader (Instructors).

Use title case (capitalize the important words). Question phrasing like "How do I…" belongs only inside an FAQ's entries, not in the title.

Summary

The Summary you enter becomes the article's opening paragraph and the snippet people see in search results, so write it as a friendly first sentence that leads with the topic. Use the pattern that fits the article:

Keep it to one or two sentences, and don't just repeat the title word for word.

Keywords

List the feature name, the words people actually search for (including other names for the same thing. For example, "course code" is also a "reference code" or "short name"), and the task verbs. Separate them with commas, use lowercase, and don't repeat words already in the title.

Appendix of the KB Theme's Styles

This appendix is a reference for each of our KB theme's styles.

The formats in our KB's styles live in the theme's CSS, so when you apply a style, the page automatically displays the correct fonts, colors, spacing, and structure associated with the style in our theme's CSS. This allows our KB articles to remain consistent.

You can apply a style in either of the following ways:

• Use the KB Styles Tampermonkey tool: In the editor, select your text or click inside your table, pick a style from Tampermonkey, and the correct format is applied for you.
• Copy the HTML from the style's entry in the Style Appendix below, and paste it into the editor's HTML view. Toggle back to the WYSIWYG mode of the editor, and replace the placeholder text with your own.

Callout: Tip

Use a Tip callout for helpful, optional advice such as: a shortcut, a best practice, a nice-to-know. Tips are friendly, not urgent.

Callout: Tip HTML Code

<div class="callout callout--tip">
  <p><span class="callout__label">Tip:</span> Your tip text here.</p>
</div>

Callout: Important

Use an Important callout for something the reader must not miss such as a warning, a required step, a consequence. Reserve it for genuinely critical information so it keeps its weight.

Callout: Important HTML Code

<div class="callout callout--important">
  <p><span class="callout__label">Important:</span> Your important text here.</p>
</div>

Legacy alert--info, alert--warning, and alert--error classes still render (mapped onto these callout styles), but use callouts for new content.

Color

Red and Green Text for Yes/No or On/Off THIS WILL BE THE TAMPERMONKEY STYLE NAME

You can color short status words(sparingly) to reinforce a clear positive/negative contrast: green for yes, on, correct, or do; red for no, off, incorrect, or don't. It works best for one or two words doing real comparison work, such as the Do/Don't labels in this guide. Bold the words you are applying color to.

• Use the standard colors. Green is #1d7a3a and red is #b0271b. Both meet WCAG 2.1 AA contrast on a white background. Don't substitute brighter or lighter shades, which may fail contrast and look inconsistent across articles.
• Color the word, not whole sentences. Reserve it for the status word itself ("Do," "Yes," "On"), not the explanation that follows. Coloring full sentences is harder to read and dilutes the signal.
• Never let color be the only signal. The meaning must survive with the color removed, for readers who are colorblind, use a screen reader, or view the page in grayscale or high-contrast mode. Always pair the color with a word that carries the same meaning.

Procedure Bar: Video

Use a Video procedure bar to introduce steps shown in a video. Place it just before the video or the steps it labels.

Procedure Bar: Video HTML Code

<div class="procedure-bar procedure-bar--video">
  <h4>Video: Task name</h4>
</div>

Procedure Bar: Written

Use a Written procedure bar to introduce written, step-by-step instructions. Pair it with a Video bar when you offer both formats.

Procedure Bar: Written HTML Code

<div class="procedure-bar procedure-bar--written">
  <h4>Written: Task name</h4>
</div>

Keyboard Keys

Use keyboard keys to show a key or combination the reader should press. Put each key in its own <kbd> and join a combination with a plus sign.

Press Ctrl + Shift + R to hard-refresh the page.

Keyboard Keys HTML Code

<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>R</kbd>

Inline code

Use inline code for a short snippet inside a sentence. For example, apply this style to a filename, a setting name, a value, a short command, etc.

Open config.json and set debug to true.

Inline Code HTML Code

<code>config.json</code>

Preformatted (code block)

Use a preformatted block for multi-line code, command output, or a template the reader will copy. It preserves spacing and line breaks, and gets a Copy button automatically on the published page. For a short snippet inside a sentence, use Inline code instead.

Example:

cd /var/www/site
npm install
npm run build

Preformatted HTML Code

<pre>cd /var/www/site
npm install
npm run build</pre>

Label Chip

Use a label chip for a small inline tag. For example, apply this style to a status, category, or UI label. It is just decorative emphasis, not a heading.

Course status: New

Label Chip HTML Code

<span class="kb-label">New</span>

Indent

Use indent to offset a block (a paragraph, list, etc.) from the left margin. Apply this style to a nested note or secondary detail under a step.

Step 1. Open the settings panel.

This indented note sits under the step above.

Indent HTML Code

<p class="offset-left-40">Indented text.</p>

Blockquote

Use a blockquote to set off a quotation or an excerpt from another source.

The system will be unavailable Saturday from 2–4 a.m. for scheduled maintenance.

Blockquote HTML Code

<blockquote>
  <p>Quoted text.</p>
</blockquote>

Continue Numbering

When a screenshot, callout, or other block splits a numbered list in two, the second part restarts at 1. Continue Numbering resumes the count. Put your cursor in the restarted list and select Continue Numbering from the KB Styles menu, and the numbering picks up where the previous list left off. 

To continue the numbering by changing HTML code, switch to source view and add a start attribute to the second list's <ol> tag, set to the number the list should resume at. For example, if the first list ended at step 4, the second list starts at 5:

Continue Numbering HTML Code

<ol start="5">
  <li>Fifth step.</li>
  <li>Sixth step.</li>
</ol>

Table Formats

The KB Styles Tampermonkey tool provides standard table formats you can apply to your tables. This keeps every table in the KB consistent without hand-styling.

To apply a table format with the KB Styles Tampermonkey:

1. Click in an existing table. (If you don't have a table yet, simply create a plain blank table by selecting Insert > Table in the editor.)
2. Choose a table format from the Tampermonkey menu. Your table's format should change to the standard format you selected.

A few rules apply to every table:

• Header cells are tagged for you. A table's labeling cells need to be marked as headers (<th>) with the correct scope, so screen readers can announce which row or column each data cell belongs to. The table formats in the KB Styles Tampermonkey tool set this automatically: column headers get scope="col", row headers get scope="row", so you shouldn't need to tag anything by hand.
• Don't split or merge cells. Merged and split cells break the row-and-column structure that assistive technology relies on to read a table.
• Don't use tables for layout. Use a table only when rows and columns carry meaning (an item and its attributes), never just to position content side by side.
• Shade cells only to signal status, using the approved tints, and always pair the shade with text or a symbol. See "Red and Green Cell Shading" for when and how.

Table: Column Headers Only

Use this table format for tabular data. Always include a caption (the table's title).

The header row (top row) is tagged with <th scope="col"> so screen readers announce each column.

Table: Column Headers Only HTML Code

<div class="kb-table-wrap">
  <table class="kb-table">
    <caption>Table title</caption>
    <thead>
      <tr><th scope="col">Column A</th><th scope="col">Column B</th></tr>
    </thead>
    <tbody>
      <tr><td>Cell</td><td>Cell</td></tr>
    </tbody>
  </table>
</div>

Table: Row Headers Only

Use this format when each row represents a distinct item and the cells across it are that item's details, with no column categories worth labeling. The reader finds their item in the first column, then reads across. Common uses: a list of tools with their settings, courses with their attributes, or roles with their permissions.

The first cell of each body row is tagged with <th scope="row"> so screen readers announce that label when reading the other cells in the row.

Table: Row Headers Only HTML Code

<div class="kb-table-wrap">
  <table class="kb-table">
    <caption>Table title</caption>
    <tbody>
      <tr><th scope="row">Row label</th><td>Cell</td><td>Cell</td></tr>
    </tbody>
  </table>
</div>

Table: Column + Row Headers

Use this table format for comparison tables.

The header row (top row) is tagged with <th scope="col"> so screen readers announce each column. The first cell of each body row is tagged with <th scope="row">.

Table: Column + Row Headers HTML Code

<div class="kb-table-wrap">
  <table class="kb-table">
    <caption>Table title</caption>
    <thead>
      <tr><th scope="col">Feature</th><th scope="col">Free</th><th scope="col">Pro</th></tr>
    </thead>
    <tbody>
      <tr><th scope="row">Storage</th><td>5 GB</td><td>1 TB</td></tr>
    </tbody>
  </table>
</div>

Collapsible Panel (Accordion)

Use a collapsible panel to tuck supplementary content (FAQs, optional detail) behind a clickable title. Add accordions through the editor via Insert > Collapsible Panel rather than typing it. The expand/collapse behavior is added automatically on the published page. It's shown expanded here. Keep the heading level in order with the rest of your page.

What if I forget my password?

Collapsible Panel HTML Code

<h3 class="panel-head">Panel title</h3>
<div class="panel-content">
  <p>Hidden content.</p>
</div>

H2 Bar

Use an H2 Bar for a bold, full-width section divider (a white-on-teal heading that stands out more than a normal H2). It's still a real H2 in the page outline, so use it for actual sections, not decoration. (Shown as code only here so it doesn't add an extra entry to this guide's table of contents.)

I NEED TO INSERT A SCREENSHOT HERE.

<h2 class="invertedcolor">Section title</h2>

Headings (H2–H5)

Structure every article with headings in order: H2 for main sections, H3 for sub-sections, then H4 and H5. Don't skip levels, and pick a level for its place in the outline, not its size. The section titles throughout this guide are themselves live examples of Headings 2–4.

Heading 2–Heading 5 HTML Code

<h2>Main section</h2>
<h3>Sub-section</h3>
<h4>Smaller heading</h4>
<h5>Smallest heading</h5>

Image with Standard Border

Give screenshots and figures the standard border so they separate from the page. Add it in the editor via Insert/Edit Image > Advanced (Border width 2, Border style solid), the KB Styles Image border toggle, or the style below. Always write meaningful alt text describing what the image shows.

Image with Standard Border HTML Code

<img src="YOUR-IMAGE-URL" alt="Describe what the image shows"
     style="border-width: 2px; border-style: solid;">

Table of Contents

An "In this article" table of contents is generated automatically when you select Insert >then Table of Contents in the editor. It builds itself from your H2/H3 headings when the page publishes, so there's no HTML to copy. (See "Adding a Table of Contents" above.)