@nusoft/nuos-build-catalogue 0.12.0 → 0.14.1

package/templates/starter-kit/docs/build/decisions/_index.md

@@ -1,30 +1,34 @@
 # Decisions
 
-> Architectural commitments made by this project. Each decision lives in its own D-NNN file. Decisions are dated, justified, and have a status (`accepted`, `superseded`, `withdrawn`).
+A **decision** is a choice that's been made and shouldn't drift. Once accepted, a decision isn't edited — if circumstances change, you file a new decision that supersedes the old one and link forward. Decisions are the project's load-bearing commitments: the things future work has to honour. See [the glossary](../GLOSSARY.md#decision) for the full definition.
 
 ## Index
 
 | ID | Title | Status | Date |
 | --- | --- | --- | --- |
-| _none yet — see the template_ | | | |
+| _none yet — file your first one with `/decision-new` or `nuos-catalogue decision create`_ | | | |
 
-## How to add a decision
+## When to file a decision
 
-1. Copy `D001-template.md` to `DNNN-short-title-with-dashes.md` (next available number)
-2. Fill in the template
-3. Add a row to the table above
-4. If the decision affects a work unit's acceptance criteria, link it from the WU
-5. If the decision supersedes a prior one, mark the prior one's status as `superseded` and link forward
+- You're choosing between two reasonable approaches and want the choice to stick
+- You're adopting a constraint future work will need to honour (e.g. "all data stays on-device", "no third-party trackers")
+- You're overriding something previously decided — file the supersede; don't silently shift
+- You're committing to a technology, a deployment target, a major design principle
 
-## When to write a decision
+> Example: "D003 — All overnight processing happens on the school's own server, never in the cloud."
 
-- An architectural commitment is being made
-- Two reasonable approaches are being chosen between
-- A constraint is being adopted that future work will need to honour
-- A prior decision is being overridden (write the supersede; don't silently shift)
+## When NOT to file a decision
 
-## When NOT to write a decision
+- The choice is an implementation detail and easy to reverse
+- It belongs inside a work unit's notes — local to that work unit, not a project-wide commitment
+- The matter is still open and unresolved — file it as an **open question** ([Q-NNN](../open-questions/_index.md)) instead
 
-- The choice is implementation-detail and easy to reverse
-- The work unit's notes are sufficient to capture the rationale
-- The matter is open and unresolved — file it as an open question (Q-NNN), not a decision
+## What never to do
+
+**Never edit an accepted decision file.** The pre-commit hook will block it. If you need to change something material, file a new decision that supersedes the old one — `nuos-catalogue decision supersede D003 --by=D012 --reason="..."`. Typo or link fixes that don't change meaning are the only edits allowed.
+
+## How to file one
+
+Easiest way: run `/decision-new` (or `nuos-catalogue decision create`). The AI walks you through the prompts and files the result with a fresh D-NNN handle.
+
+The file is short — a one-paragraph context, the decision itself in one sentence, why it was made, and what it commits future work to. It doesn't need to be long. It needs to be unambiguous.

package/templates/starter-kit/docs/build/design-system/_index.md

@@ -0,0 +1,57 @@
+# Design System
+
+The **design system** is the shared visual and interaction language every part of {{PROJECT_NAME}}'s user-facing experience uses. End-to-end: design tokens (colour, type, spacing, motion) → components (buttons, cards, navigation) → patterns (form layouts, page templates) → voice (microcopy, error messages) → accessibility commitments. Every per-surface file in `ui-ux/` references this register. See [the glossary](../GLOSSARY.md#design-system) for the full definition.
+
+## Why a design system from the start
+
+Many projects sprout UI/UX surfaces first and add a design system later as a "consistency pass". By then the surfaces are inconsistent, components are duplicated, and harmonising them takes longer than building them in the first place. This catalogue requires a design system to exist before per-surface files are written. Phase C of planning produces both, in parallel.
+
+If a change to a colour, a heading style, a button shape, or an error message tone needs to happen, it happens **here**, once. Every surface that references the design system picks up the change. That's the system's load-bearing job.
+
+## Index
+
+| File | What it captures |
+| --- | --- |
+| `tokens-colour.md` | Colour palette, semantic colour roles |
+| `tokens-typography.md` | Type scale, font families, line heights, weights |
+| `tokens-spacing.md` | Spacing scale, layout grid, breakpoints |
+| `tokens-motion.md` | Easing curves, duration scale, motion principles |
+| `tokens-radius-elevation.md` | Border radii, shadow scale, elevation tokens |
+| `components/_index.md` | Index of components with status |
+| `patterns/_index.md` | Index of recurring page-level patterns |
+| `voice.md` | Voice, tone, microcopy principles |
+| `accessibility.md` | Project-wide accessibility commitments |
+
+Each section is filled in during the UI/UX + Design System phase of planning (phase C).
+
+## What status means for design system pieces
+
+- 🔵 **proposed** — drafted, not yet adopted across surfaces
+- 🟡 **in flight** — being refined; surfaces may reference older + newer simultaneously
+- 🟢 **active** — in use; the canonical version
+- ⚫ **deprecated** — kept for reference but no new surfaces should use it; existing surfaces should migrate
+
+## How design system pieces connect to everything else
+
+- Every UI/UX surface in `ui-ux/` references design-system pieces by name
+- Architecture modules that involve UI reference the surfaces (and thereby the design system)
+- Decisions that materially change a token, component, or voice principle are filed in `decisions/`
+- Work units that ship UI either consume the design system (most cases) or extend it (when a new component or pattern is needed)
+
+## When the design system gets populated
+
+During Phase C of planning (UI/UX + Design System). The AI walks you through:
+
+1. **Voice and tone first** — how does {{PROJECT_NAME}} sound when it speaks?
+2. **Tokens** — colour, type, spacing, motion. The atomic units.
+3. **Components** — the buttons, cards, navigation, forms. Each with variants, states, and accessibility commitments.
+4. **Patterns** — how components combine into recurring page-level layouts.
+5. **Accessibility commitments** — what the project promises end-to-end.
+
+You don't need to design every component upfront. The first pass establishes the language; components get added as work units need them. But the **language exists from the start** — every surface references it from day one.
+
+## How to add a design system piece
+
+During planning: the AI walks you through it.
+
+Outside planning: each piece is a standalone file with its own template (see the relevant subdirectory). For a new component, copy `components/_template.md` to `components/<name>.md`. For a new pattern, copy `patterns/_template.md`. Tokens are edited directly in the `tokens-*.md` files.

package/templates/starter-kit/docs/build/design-system/accessibility.md

@@ -0,0 +1,77 @@
+# Accessibility commitments
+
+> *Filled in during the UI/UX + Design System phase of planning. These are the project-wide promises every surface honours.*
+
+**Status:** 🔵 proposed
+**Last updated:** {{TODAY}}
+
+## Standards we meet
+
+[Pick the standard the project commits to. WCAG 2.1 AA is the typical floor; AAA where appropriate.]
+
+- **WCAG 2.1 Level AA** — minimum across all surfaces
+- **WCAG 2.1 Level AAA** — for [specific contexts; e.g. "reading-focused screens"]
+
+## Specific commitments
+
+Each of these is a project-wide promise. They are not aspirational; every surface in `ui-ux/` must honour them.
+
+### Colour and contrast
+
+- All body text meets AA contrast (4.5:1) against its background
+- All text 18px+ and bold 14px+ meets AA Large (3:1)
+- Critical UI (focus rings, error states) is never communicated by colour alone
+
+### Keyboard
+
+- Every interactive element is reachable via keyboard alone
+- Focus order matches visual order
+- Focus rings are visible, distinct, and never suppressed
+- No keyboard traps anywhere
+
+### Screen reader
+
+- Every interactive element has an accessible name (label, aria-label, or visible text)
+- Landmarks are used correctly (header, nav, main, aside, footer)
+- Heading hierarchy is correct (h1 → h2 → h3, no skipping)
+- Form labels are always present and programmatically associated
+
+### Motion
+
+- All non-essential motion respects `prefers-reduced-motion`
+- No auto-playing video or audio
+- No flashing content above 3 Hz
+
+### Touch and pointer
+
+- Touch targets are at least 44 × 44 px
+- Multiple input methods supported (touch, mouse, keyboard, switch)
+- No actions require hover (which doesn't exist on touch)
+
+### Forms
+
+- Errors are described in text, not just colour
+- Errors appear inline next to the affected field
+- Submit buttons remain enabled until submitted; loading state replaces "submit" text
+- Required fields are marked in text ("required"), not just by an asterisk
+
+### Language and reading
+
+- Page language is declared (`lang="en"` etc.)
+- Reading level appropriate for the persona (most adult-facing surfaces target ~Grade 8-10)
+- Long content has summaries; short content avoids unnecessary text
+
+## How we test
+
+- **Automated**: axe-core (or equivalent) on every page in CI
+- **Keyboard-only walkthrough** as part of pre-merge for any new surface
+- **Screen reader spot-check** (VoiceOver or NVDA) on changes to forms and primary flows
+- **Real user testing** with one or more users who rely on assistive technology, before each major release
+
+## When to file an accessibility-related decision
+
+- A trade-off between accessibility and another goal arises (rare; document the resolution)
+- A new accessibility commitment is added or an existing one is loosened
+- A pattern is adopted that requires special accessibility care (drag-and-drop, complex grids, charts)
+
+Accessibility is not a phase; it's a baseline. Every work unit that ships a surface checks against these commitments before completing.

package/templates/starter-kit/docs/build/design-system/components/_index.md

@@ -0,0 +1,29 @@
+# Components
+
+The reusable pieces every UI/UX surface uses. Each component has its own file documenting variants, states, accessibility commitments, and how it consumes tokens. See [the design system index](../_index.md) for the overall shape.
+
+## Index
+
+| Component | Status |
+| --- | --- |
+| _none yet — components are added as work units need them; the first batch is sketched during Phase C of planning_ | |
+
+## What goes in a component file
+
+Each component documents:
+
+- **What it is** — one sentence
+- **When it's used** — the role it plays
+- **Variants** — primary / secondary / destructive / link, etc.
+- **States** — default, hover, focus, active, disabled, loading
+- **Tokens consumed** — colour, type, spacing, radius, motion — linked to the token files
+- **Accessibility commitments** — keyboard, screen reader, contrast
+- **Examples** — concrete uses; which surfaces in `ui-ux/` consume it
+
+## How to add a component
+
+Copy `_template.md` to `<component-name>.md`. Fill in. Add a row to the table above. Surfaces that use this component reference it by name from their surface file.
+
+## Component naming
+
+Use plain lowercase-with-dashes names that describe the role: `button`, `card`, `input-text`, `nav-primary`, `modal`. Avoid framework-specific names (no `material-button`, no `bootstrap-card`). The catalogue describes design; implementation maps to it.

package/templates/starter-kit/docs/build/design-system/components/_template.md

@@ -0,0 +1,60 @@
+# [Component name]
+
+> *Replace bracketed placeholders. Delete this hint block once filled in.*
+
+**Status:** 🔵 proposed / 🟡 in flight / 🟢 active / ⚫ deprecated
+**Last updated:** {{TODAY}}
+
+## What it is
+
+[One sentence. *"A button that performs an action when clicked or pressed."*]
+
+## When to use it
+
+[The role it plays. When this component is the right answer vs. a different one. *"Use a `button` for actions that change state. Use a `link` for navigation between surfaces."*]
+
+## Variants
+
+| Variant | When |
+| --- | --- |
+| `primary` | The main call-to-action on a surface; one per visible region maximum |
+| `secondary` | Lower-priority actions |
+| `destructive` | Actions that delete or undo |
+| `link` | When the action is navigation rather than a state change (rare; usually use a `link` component instead) |
+
+## States
+
+| State | Behaviour |
+| --- | --- |
+| default | The resting visual |
+| hover | Subtle visual feedback that the element is interactive (desktop only) |
+| focus | Visible focus ring; meets WCAG focus indicator requirements |
+| active | The brief moment of being pressed/clicked |
+| disabled | Visually muted; not focusable; cursor: not-allowed |
+| loading | After click, before the action completes; spinner replaces label; not pressable |
+
+## Tokens consumed
+
+- **Colour:** `colour.action.primary` (background), `colour.text.inverse` (text)
+- **Typography:** `text.label.medium`
+- **Spacing:** internal padding `space.3` vertical × `space.4` horizontal
+- **Radius:** `radius.medium`
+- **Motion:** `motion.duration.quick` with `motion.ease.standard` on hover/focus
+
+## Accessibility
+
+- Reachable via keyboard (Tab moves to it; Space or Enter activates)
+- Has an accessible name (visible label, or aria-label if icon-only)
+- Focus ring is visible and meets 3:1 contrast against the surrounding surface
+- `aria-disabled` when disabled (not just the visual style)
+- `aria-busy` when loading
+
+## Examples
+
+| Surface | How it's used |
+| --- | --- |
+| [Surface link] | [the variant used and what it does there] |
+
+## Notes
+
+[Date-stamped notes about how this component has evolved.]

package/templates/starter-kit/docs/build/design-system/patterns/_index.md

@@ -0,0 +1,37 @@
+# Patterns
+
+Recurring page-level shapes that combine components in consistent ways. A **pattern** is a step up from a component — it's a layout, a flow, or a structural rule that multiple surfaces use. See [the design system index](../_index.md) for context.
+
+## Index
+
+| Pattern | Status |
+| --- | --- |
+| _none yet — patterns emerge as the project develops; sketch the first ones during Phase C of planning_ | |
+
+## Typical patterns
+
+Most projects develop a handful of patterns like these:
+
+- **Form layout** — how labels, inputs, helper text, and errors arrange themselves on a form
+- **List with actions** — how an item in a list shows primary content + secondary metadata + row-level actions
+- **Empty state** — what every surface shows when there's no content yet
+- **Loading state** — skeleton screens, spinners, progress; when to use which
+- **Page template** — the standard header/main/footer arrangement, with breakpoint behaviour
+- **Navigation** — how primary and secondary navigation arrange themselves; how the active state is shown
+
+You don't define all of these upfront. Patterns get documented as the project produces them. The discipline is: **the second time a layout repeats, document it as a pattern** — before it diverges into two slightly-different one-off layouts.
+
+## What goes in a pattern file
+
+Each pattern documents:
+
+- **What it is** — one sentence describing the recurring shape
+- **When to use it** — the contexts it fits
+- **Anatomy** — the components and their arrangement
+- **Tokens consumed** — spacing, breakpoints, type
+- **Behaviour** — at different breakpoints, with different content lengths, in different states (empty, loading, error)
+- **Examples** — which surfaces in `ui-ux/` use this pattern
+
+## How to add a pattern
+
+Copy `_template.md` to `<pattern-name>.md`. Fill in. Add a row to the table above.

package/templates/starter-kit/docs/build/design-system/patterns/_template.md

@@ -0,0 +1,57 @@
+# [Pattern name]
+
+> *Replace bracketed placeholders. Delete this hint block once filled in.*
+
+**Status:** 🔵 proposed / 🟡 in flight / 🟢 active / ⚫ deprecated
+**Last updated:** {{TODAY}}
+
+## What it is
+
+[One sentence describing the recurring shape. *"A form layout in which labels sit above inputs, helper text sits below, errors replace helper text inline."*]
+
+## When to use it
+
+[The contexts this pattern fits. *"Any form with more than one input. Use a single-input pattern (label inline with input) when only one field is asked."*]
+
+## Anatomy
+
+[Describe the components that make up the pattern, in order. Link to component files.]
+
+1. [Component or element] — [what it does in this pattern]
+2. [...] — [...]
+3. [...] — [...]
+
+## Tokens consumed
+
+- **Spacing:** [which spacing tokens, and where]
+- **Typography:** [type tokens for labels, helper text, error messages]
+- **Breakpoints:** [how the pattern adapts; e.g. "mobile: stacked; tablet+: 2-column"]
+
+## Behaviour
+
+### At different breakpoints
+
+[How the pattern arranges itself across the breakpoints from `tokens-spacing.md`.]
+
+### With different content lengths
+
+[What happens when labels are long, when helper text wraps, when error messages exceed one line.]
+
+### In different states
+
+| State | Behaviour |
+| --- | --- |
+| Empty | [...] |
+| Loading | [...] |
+| Error | [...] |
+| Success | [...] |
+
+## Examples
+
+| Surface | How it's used |
+| --- | --- |
+| [Surface link] | [the variant used and what it does there] |
+
+## Notes
+
+[Date-stamped notes about how this pattern has evolved.]

package/templates/starter-kit/docs/build/design-system/tokens-colour.md

@@ -0,0 +1,52 @@
+# Colour tokens
+
+> *Filled in during the UI/UX + Design System phase of planning. The AI walks you through this in conversation — start with brand colours, then derive a semantic palette (success, warning, danger, info), then accessibility-checked surface and text combinations.*
+
+**Status:** 🔵 proposed
+**Last updated:** {{TODAY}}
+
+## Brand colours
+
+[The 1-3 primary brand colours. Each as a name + a hex value + a description of when it's used.]
+
+| Token | Hex | Used for |
+| --- | --- | --- |
+| `colour.brand.primary` | `#000000` | [...] |
+| `colour.brand.secondary` | `#000000` | [...] |
+
+## Semantic colours
+
+[Roles, not specific colours. The mapping lets you change a colour later without renaming everywhere.]
+
+| Token | Hex | Role |
+| --- | --- | --- |
+| `colour.surface.canvas` | `#ffffff` | The default page background |
+| `colour.surface.raised` | `#fafafa` | Cards, modals, raised elements |
+| `colour.text.primary` | `#1a1a1a` | Default text colour |
+| `colour.text.muted` | `#666666` | Secondary text, captions |
+| `colour.text.inverse` | `#ffffff` | Text on dark / brand backgrounds |
+| `colour.feedback.success` | `#000000` | Positive confirmations |
+| `colour.feedback.warning` | `#000000` | Caution states |
+| `colour.feedback.danger` | `#000000` | Errors, destructive actions |
+| `colour.feedback.info` | `#000000` | Informational notices |
+| `colour.action.primary` | `#000000` | The main call-to-action |
+| `colour.action.secondary` | `#000000` | Less prominent actions |
+
+## Accessibility
+
+[List the contrast pairs that must hold. Project-wide commitments live in `accessibility.md`; the table here documents which colour combinations are accessible.]
+
+| Foreground × Background | Contrast | Standard met |
+| --- | --- | --- |
+| `colour.text.primary × colour.surface.canvas` | [4.5:1+] | AA / AAA |
+| `colour.text.muted × colour.surface.canvas` | [4.5:1+] | AA / AAA |
+
+> Test every text/background pair against [WebAIM's contrast checker](https://webaim.org/resources/contrastchecker/) or equivalent. AA is the minimum commitment; AAA where it matters.
+
+## Dark mode (if applicable)
+
+[Either a full second set of tokens or a transformation rule. Leave out if dark mode isn't planned for this project.]
+
+## How to change a colour
+
+A colour change is a design-system decision. File it as a D-NNN if the change is project-wide and load-bearing (e.g. the brand changes). Day-to-day refinements to specific hex values can happen in this file directly during early planning — once the design system reaches 🟢 active status, changes get more deliberate.

package/templates/starter-kit/docs/build/design-system/tokens-motion.md

@@ -0,0 +1,42 @@
+# Motion tokens
+
+> *Filled in during the UI/UX + Design System phase of planning.*
+
+**Status:** 🔵 proposed
+**Last updated:** {{TODAY}}
+
+## Duration scale
+
+| Token | Value | Typical use |
+| --- | --- | --- |
+| `motion.duration.instant` | 0ms | Hovering between focused/unfocused |
+| `motion.duration.quick` | 150ms | Hover states, focus rings, small UI feedback |
+| `motion.duration.medium` | 250ms | Modal open/close, page transitions, accordion |
+| `motion.duration.slow` | 400ms | Larger view transitions, complex reveals |
+| `motion.duration.long` | 700ms | Onboarding moments, celebratory feedback |
+
+## Easing
+
+| Token | Curve | Used for |
+| --- | --- | --- |
+| `motion.ease.standard` | `cubic-bezier(0.4, 0, 0.2, 1)` | Default; balanced acceleration + deceleration |
+| `motion.ease.enter` | `cubic-bezier(0, 0, 0.2, 1)` | Things appearing on screen |
+| `motion.ease.exit` | `cubic-bezier(0.4, 0, 1, 1)` | Things leaving the screen |
+| `motion.ease.emphasis` | `cubic-bezier(0.2, 0.7, 0, 1)` | Big moments that should feel deliberate |
+
+## Principles
+
+- **Motion communicates state change**, not decoration. Every animation should answer "what just changed?"
+- **Faster is friendlier for repetitive interactions.** A modal opening 60 times a day at 600ms is annoying; the same modal at 250ms feels right.
+- **Slower is friendlier for rare, big moments.** A celebration animation can take 700ms; nobody minds.
+- **Respect `prefers-reduced-motion`.** All non-essential motion should be substantially reduced or removed when the user has set this preference.
+
+## Accessibility
+
+When `prefers-reduced-motion: reduce` is set:
+
+- Replace transition-based motion (slide, scale, fade) with instant state changes
+- Keep durations for unavoidable transitions under 150ms
+- No parallax, no auto-playing media
+
+The full accessibility commitment lives in `accessibility.md`.

package/templates/starter-kit/docs/build/design-system/tokens-radius-elevation.md

@@ -0,0 +1,34 @@
+# Radius and elevation tokens
+
+> *Filled in during the UI/UX + Design System phase of planning.*
+
+**Status:** 🔵 proposed
+**Last updated:** {{TODAY}}
+
+## Border radius
+
+| Token | Value | Typical use |
+| --- | --- | --- |
+| `radius.none` | 0 | Sharp corners (full-width banners, separators) |
+| `radius.small` | 4px | Small UI elements (tags, badges, inputs) |
+| `radius.medium` | 8px | Cards, buttons, modals |
+| `radius.large` | 16px | Feature cards, prominent containers |
+| `radius.full` | 9999px | Pills, avatars, circular buttons |
+
+## Elevation / shadow
+
+Shadows are used to indicate hierarchy and interactivity — what's pressable, what's floating, what's pinned.
+
+| Token | Value | Used for |
+| --- | --- | --- |
+| `elevation.none` | none | Default; in-flow elements |
+| `elevation.low` | `0 1px 2px rgba(0,0,0,0.05)` | Cards, raised surfaces |
+| `elevation.medium` | `0 4px 8px rgba(0,0,0,0.08)` | Hover states, popovers |
+| `elevation.high` | `0 8px 24px rgba(0,0,0,0.12)` | Modals, dropdowns |
+| `elevation.highest` | `0 16px 48px rgba(0,0,0,0.16)` | Notifications, toasts (briefly) |
+
+## Principles
+
+- **Pick a small set and use it consistently.** Two or three elevation levels usually beats five. Hierarchy is communicated by *which* level something uses, not by having many.
+- **Shadows belong on light surfaces.** On dark themes, the analog is a subtle border or a brighter background rather than a shadow.
+- **Radius is part of brand voice.** Sharp corners feel different from rounded ones. Pick once; apply consistently. A button that's `radius.medium` and a card that's `radius.large` is fine; a button that's `radius.medium` in one place and `radius.small` in another is design drift.

package/templates/starter-kit/docs/build/design-system/tokens-spacing.md

@@ -0,0 +1,48 @@
+# Spacing tokens
+
+> *Filled in during the UI/UX + Design System phase of planning.*
+
+**Status:** 🔵 proposed
+**Last updated:** {{TODAY}}
+
+## Spacing scale
+
+A small set of consistent values used everywhere. Build everything from these. Don't introduce custom one-off values.
+
+| Token | Value | Typical use |
+| --- | --- | --- |
+| `space.0` | 0 | Reset |
+| `space.1` | 4px | Tight pairs (icon next to label) |
+| `space.2` | 8px | Internal padding of small elements |
+| `space.3` | 12px | Default gap between related items |
+| `space.4` | 16px | Comfortable padding inside cards/buttons |
+| `space.5` | 24px | Section padding |
+| `space.6` | 32px | Between sections |
+| `space.7` | 48px | Between major page regions |
+| `space.8` | 64px | Hero/breathing room |
+| `space.9` | 96px | Above-the-fold space |
+
+## Layout grid
+
+[The column system used for major page layouts. Most projects use a 12-column grid; some use 8 or 16. Pick one and stick to it.]
+
+- **Columns:** 12
+- **Gutter:** `space.4` (16px)
+- **Margin:** `space.5` (24px) on mobile, `space.7` (48px) on desktop
+- **Max content width:** 1200px (or as appropriate)
+
+## Breakpoints
+
+| Token | Width | Targets |
+| --- | --- | --- |
+| `bp.mobile` | up to 639px | Phones |
+| `bp.tablet` | 640px – 1023px | Tablets, small laptops |
+| `bp.desktop` | 1024px+ | Larger laptops, monitors |
+
+Mobile-first by default — design for `bp.mobile`; add styling at larger breakpoints as needed.
+
+## Principles
+
+- **Use multiples of 4px.** The scale above is built from a 4px base. Custom values that aren't multiples of 4 produce subtle visual noise.
+- **Vertical rhythm matters.** Consistent spacing between text blocks does more for legibility than any single typography choice.
+- **More space than you think.** When in doubt, increase the gap. Crowded interfaces feel harder to use than they are.

package/templates/starter-kit/docs/build/design-system/tokens-typography.md

@@ -0,0 +1,46 @@
+# Typography tokens
+
+> *Filled in during the UI/UX + Design System phase of planning.*
+
+**Status:** 🔵 proposed
+**Last updated:** {{TODAY}}
+
+## Font families
+
+| Token | Value | Used for |
+| --- | --- | --- |
+| `font.sans` | `[font name]`, system-ui, sans-serif | Body text, UI |
+| `font.serif` | `[font name]`, serif | Long-form reading (if applicable) |
+| `font.mono` | ui-monospace, monospace | Code, numerical alignment |
+
+## Type scale
+
+| Token | Size | Line height | Weight | Used for |
+| --- | --- | --- | --- | --- |
+| `text.display.large` | 56px | 1.1 | 700 | Hero headings |
+| `text.display.medium` | 40px | 1.15 | 700 | Section headings |
+| `text.title.large` | 28px | 1.2 | 600 | Page titles |
+| `text.title.medium` | 22px | 1.25 | 600 | Subheadings |
+| `text.body.large` | 18px | 1.5 | 400 | Lead paragraphs |
+| `text.body.medium` | 16px | 1.5 | 400 | Default body |
+| `text.body.small` | 14px | 1.5 | 400 | Captions, hint text |
+| `text.label.medium` | 14px | 1.3 | 500 | Form labels, button text |
+| `text.label.small` | 12px | 1.3 | 500 | Tags, badges |
+
+> Adjust the scale as needed. A few principles: keep the scale modular (each step a constant ratio from the next, e.g. 1.25× or 1.333×); cap the largest size at what's legible on the smallest target screen; line height tightens as text gets bigger.
+
+## Weight scale
+
+| Token | Numeric | Used for |
+| --- | --- | --- |
+| `weight.regular` | 400 | Body |
+| `weight.medium` | 500 | Labels, emphasis |
+| `weight.semibold` | 600 | Titles |
+| `weight.bold` | 700 | Display, strong emphasis |
+
+## Notes on readability
+
+- **Body text is the default.** Optimise for `text.body.medium` first; everything else is built around it.
+- **Line length matters as much as type size.** Aim for 60-80 characters per line in body text.
+- **Headings should be readable at glance.** A large heading that takes effort to parse is worse than a smaller one.
+- **Test on the target devices.** Type that works on a designer's 27" monitor often fails on a 13" laptop or a phone in bright sunlight.

package/templates/starter-kit/docs/build/design-system/voice.md

@@ -0,0 +1,53 @@
+# Voice and tone
+
+> *Filled in during the UI/UX + Design System phase of planning. The AI walks you through it — start by describing how {{PROJECT_NAME}} should "sound" to the people using it, then derive principles, then build out specific microcopy examples.*
+
+**Status:** 🔵 proposed
+**Last updated:** {{TODAY}}
+
+## How {{PROJECT_NAME}} sounds
+
+[One paragraph describing the personality. Honest, warm, direct, calm, professional, playful, etc. Pick three or four words; explain in plain language. *"Calm, direct, never patronising. Speaks to teachers the way a trusted colleague speaks to another teacher."*]
+
+## Five rules of voice
+
+[List the load-bearing principles for any writing in the product. Examples:]
+
+1. **Plain language, no jargon.** If a word would lose a domain expert, use a different word.
+2. **Acknowledge the person.** Address them in the second person ("you"), not the third ("the user").
+3. **Be specific.** *"You'll get an email tomorrow morning"* beats *"Notification will be sent."*
+4. **Own mistakes.** When the system breaks, say what happened, what we're doing about it, and what they can do next. Never blame the user.
+5. **Never patronise.** Domain experts can read; don't explain things they obviously know.
+
+## Tone by context
+
+| Context | Tone | Example |
+| --- | --- | --- |
+| Welcoming a new user | Warm, calm | *"Welcome — let's get you set up. This takes about ten minutes."* |
+| Confirming success | Direct, brief | *"Saved. {{PROJECT_NAME}} will email you tomorrow at 7am."* |
+| Asking for input | Specific, calm | *"What does tomorrow's class look like? Tell us what you'd usually note down."* |
+| Reporting an error | Honest, helpful | *"The morning briefing didn't reach you today. We've already fixed it. You can run it manually with this button, or wait for tomorrow."* |
+| Asking the user to slow down | Gentle | *"This will undo {{PROJECT_NAME}}'s overnight work. Are you sure you want to start over?"* |
+| Empty states | Encouraging | *"No students yet. Add one with the button above — or import a class from yesterday."* |
+
+## Words we use
+
+| Use | Not |
+| --- | --- |
+| sign in | log in |
+| email | electronic mail |
+| {{PROJECT_NAME}} | the system, the app, the platform |
+| school server | backend |
+| your students | "the cohort", "the user base" |
+
+[Add to this list as patterns emerge. Voice and tone live by examples; abstractions don't help.]
+
+## Words we never use
+
+[Project-specific banned words. Often: corporate jargon, false urgency, dark patterns.]
+
+- "Click here"
+- "Unfortunately"
+- "Oops!"
+- "We've sent you an email — it might be in your spam folder" (just acknowledge it might not have arrived; don't blame their inbox)
+- [project-specific additions]