write-design-system-content

name	write-design-system-content
description	Use when writing or revising longer-form content for the Design system website, including component and pattern documentation, usage guidance, how-to steps, release notes, and FAQ-style explanations. Enforces plain-language voice, mechanics, inclusive language, and approved terminology. Do not use for in-component microcopy or code.

Skill: Write Design system content

When to use this skill

Use when writing or revising longer-form written content for the Design system website: component and pattern documentation, usage guidance, how-to instructions, release notes, and FAQ-style explanations.

Do not use for UI microcopy inside components (button labels, inline error text) or for code comments.

What good output looks like

Content a product team member with mixed technical skill can read once and act on. Plain language, scannable structure, consistent terminology, and accessible by Alberta government standards. When in doubt, pair this skill with the DS evolution reference for the approved terms table.

1. Voice

• Clear and direct: use plain language. If a technical term is unavoidable, define it on first use.
• Supportive: guide the reader toward the next action.
• Professional but approachable: authoritative without being stiff or formal.
• Inclusive and respectful: language that welcomes all readers.

Do not use:

• Hedging words that remove certainty (maybe, might) unless the uncertainty is real and you state why.
• Passive voice where it weakens meaning.
• Acronyms without explanation.

2. Mechanics

• Write short, focused sentences.
• Be concise and precise.
• Use active voice.
• Use second person ("you") for tasks and UI actions.
• Front-load the action. Start with the verb where possible.
• Use headings and bullet lists so readers can scan.
• Use numbered lists for procedural steps and bullet lists for collections of items.
• Expand each acronym on first use.
• Use Canadian English spelling.
• Use sentence case for all headings.
• Capitalize proper nouns and named, established patterns. Do not capitalize generic terms (button, component example).

Do not use:

• Passive constructions. Rewrite "is required to be entered" as "enter".
• Blame, apology, or emotional language.
• Filler phrases ("please note", "it is important to").
• Marketing language ("seamless", "robust", "powerful").

3. Inclusive language

• Use gender-neutral language.
• Avoid idioms, metaphors, and culture-specific references that exclude readers who use English as an additional language.
• Do not assume the reader's ability, prior knowledge, or intent.
• Avoid directional references ("above", "below"). Name or link the thing instead.
• If a term may be sensitive, offer a clear alternative.
• Aim for a grade 6 to 8 reading level.

4. Terminology and consistency

• Use one approved term per concept. See the approved terms table in the DS evolution reference.
• Match UI labels exactly when documenting them.
• Do not invent synonyms.
• Keep sentence case consistent across headings and labels.

Examples

Before: The form is required to be completed by the user before submission can occur. After: Complete the form before you submit it.

Before: Our powerful new design system seamlessly migrates your robust components. After: The updated design system includes new tokens, refreshed components, and templates.

Before: Click the button below to get started. After: Select Start to begin. (Name the control. Avoid "below".)

Before: Users might want to maybe consider updating at some point. After: Plan your update window between March and September 2026.

Self-check before finishing

• Reading level is grade 6 to 8.
• Every term matches the approved terms table. No invented synonyms.
• Active voice, second person, verb first where natural.
• No marketing words, no filler, no unexplained acronyms.
• All headings in sentence case.
• No directional references.