Style Guide
Voice and tone
- Second person, active, present tense.
- "Select Save", not "The user should click Save" or "Click on Save".
- Reassuring but direct; no jargon without a glossary link.
Titles
- Task how-tos: verb first — "Record attendance for a class".
- Module references: noun first — "Assessment module".
- Concept pages: noun phrase — "Grade scales".
Structure
How-to
## Before you start
- Role required: …
- Tier: …
- Setup needed: …
## Steps
1. …
2. …
## What happens next
…
Module reference
## Overview
## Screens and fields
## Statuses
## Related tasks
## Troubleshooting
Tier nouns
Always use the tier's own vocabulary. Never mix tiers in one article without an explicit note.
| Concept | Primary | Secondary | University |
|---|---|---|---|
| Top-level unit | School | School | College |
| Sub-unit | Department | Faculties / Departments | Faculty |
| Grouping level | Year Group | Year Group | Level |
| Class grouping | Class | Form | Department |
| Curriculum | Curriculum | Curriculum | Program |
| Course | Subject | Subject | Course |
| Person in charge | Teacher | Teacher | Supervisor |
Brand and visual identity
The help site uses the same identity as the ImpartLab product. Do not introduce off-brand colours, fonts, or recreated logos in articles or CSS.
| Token | Value | Use |
|---|---|---|
| Primary | #4f46e5 (indigo) | Navbar links, active navigation, buttons |
| Accent | #06b6d4 (cyan) | Focus rings, active marker, highlights |
| Logo blue | #0054a6 | Logo loop; inline code text |
| Logo sky | #00b2e4 | Logo loop |
| Logo yellow | #ffc629 | Logo dot; hero glow |
| Logo lime | #a7ce39 | Logo dot |
- Typography: Inter (400–800) for UI and prose; JetBrains Mono for code.
- Tokens: defined in
site/src/css/custom.cssand mirrorImpartLab.Web/ClientApp/src/styles/_il-design-system.scss. - Assets:
site/static/img/logo.svg(footer lockup),logo-mark.svg(navbar mark extracted from the lockup, transparent background),favicon.ico/favicon-*.png. These are derived fromImpartLab.Web/ClientApp/src/assets/img/brand/andassets/icons/; update both copies together. - Rules: use CSS variables, never raw hex values, in new styles; keep the logo lockup unmodified; check both light and dark mode before merging.
Screenshots
- One per major step maximum; crop to the relevant panel.
- Name:
<module>-<screen>-<tier>-<lang>-<yyyy-mm>.png. - Alt text: describe what is shown, not what to do.
- No PII, no real tenant names.
Links
- Descriptive link text — "See Assessment overview", not "click here".
- Every module reference links up to its role handbook.
Accessibility
- Headings in order (h1 → h2 → h3, no skipping).
- No colour-only meaning.
- Tables have header rows.
- Code blocks have a language tag.
Length
- How-to: ≤ 400 words.
- Module reference: ≤ 1 200 words per page.
- Concept page: ≤ 800 words.