Governance

Contrast ratio requirements

• Body text: ≥ 4.5:1 (AA minimum), aim for ≥ 7:1 (AAA) on primary body copy
• Large text (18pt+ or 14pt bold): ≥ 3:1 (AA)
• Non-text UI elements (icons, focus rings, chart elements): ≥ 3:1
• Decorative-only elements: exempt from contrast requirements
• Failing combinations must be flagged "FAIL — do not use" with an alternative pairing suggested

Accessibility Verification Table

Every spec page MUST include this table computed from actual token values. Do not omit. Do not estimate.

• Every interactive element reachable via Tab in DOM order
• Focus indicator visible: 2px outline, offset 2px, using --color-focus-ring (defined per archetype)
• Use :focus-visible, NOT :focus — suppress ring for pointer users
• Focus trapping required for modal dialogs, drawers, command palettes — Esc returns focus to trigger
• Skip-to-content link required at the top of every page

Standard key bindings — full map

• All icon-only buttons must have aria-label
• All form fields must have programmatic labels: label[for] or aria-labelledby — never placeholder-as-label
• Live regions for toasts, async results, validation errors: aria-live="polite" default; "assertive" only for errors blocking task completion
• Decorative SVGs: aria-hidden="true". Meaningful SVGs: role="img" + <title>

Test matrix

• prefers-reduced-motion: reduce → fall back to fade-only or no animation. Never just shorten duration — remove transform animation entirely.
• No autoplay video or animated backgrounds without explicit user consent
• Vestibular safety: avoid parallax > 20% offset, scroll-jacking, spinning loaders > 2s without a text label

• Zero raw hex in component CSS — every color, size, and shadow goes through var(--token-name)
• Components reference SEMANTIC tokens, never primitives
• Both light and dark mode tokens defined for every semantic token, even if a mode is unshipped
• Tokens declared in a single :root + [data-theme="dark"] override block — never inside component scope

color: var(--color-link);
background: var(--color-surface);
border: 1px solid var(--color-border);

color: var(--color-blue-500);
background: #F8F9FA;
border: 1px solid rgba(0,0,0,0.1);

Every interactive component must implement these 8 states — visually distinct, not just functionally present.

Form field additional states

Form fields additionally implement: empty, filled, required, read-only.

Every error message follows What → Why → How.

Banned error patterns

• Stack traces in user-facing copy
• Error codes without explanation (e.g. "Error 403" with no context)
• Generic "Oops!" / "Whoops!" / "Uh-oh!" messaging in product UI

• Sentence case for headings, buttons, labels — not Title Case, not ALL CAPS (except overline/eyebrow style)
• No emoji in UI copy — SVG icons only (emoji acceptable in user-generated content rendering)
• Contractions allowed (we'll, don't, can't) — softer voice
• Verb-first CTAs: "Save changes" not "Changes can be saved"

Banned copy patterns

• SVG only. Inline SVG preferred for color inheritance
• fill="currentColor" or stroke="currentColor" — never hardcoded hex on icon paths
• aria-hidden="true" for decorative icons; <title> for meaningful icons
• Consistent grid: 24px standard; archetype may override (Lattice uses 16px dense)
• Consistent stroke width within a family — never mix stroke widths on the same surface
• Never mix icon families on the same surface

Banned icon patterns

• Emoji used as icon in product UI
• Raster (.png) icons — not theme-aware, not scalable
• Animated GIF icons — motion not controllable by user

All design system releases follow MAJOR.MINOR.PATCH semantic versioning.

Every release entry follows this canonical structure. A11y improvements are called out separately.

## [VERSION] — YYYY-MM-DD

### Added
- [new components, tokens, variants]

### Changed
- [modifications to existing surfaces]

### Deprecated
- [old → new migration path, removal version]

### Removed
- [breaking removals — MAJOR only]

### Fixed
- [bug fixes]

### A11y
- [accessibility improvements — call out separately]

All 12 items are PR / release blocking. A release cannot ship until every gate is green.

• Contrast ratios verified (AA minimum, AAA for primary body)
• Keyboard navigable (Tab / Space / Enter / Esc / Arrows all wired)
• Screen-reader tested (VoiceOver + NVDA minimum)
• prefers-reduced-motion honored (transform animations removed, not just shortened)
• Both light + dark mode tokens defined for every semantic token
• Storybook (or equivalent) story per variant + state
• No raw hex in component CSS (all colors via semantic tokens)
• No emoji in product UI (SVG icons only)
• Component implements all 8 states: default / hover / focus-visible / active / disabled / loading / error / success
• Error messages follow What/Why/How formula
• Visual-regression snapshot committed and passing
• Changelog entry filed under correct SemVer bump

Every generated spec page must contain these sections in this order, even if the archetype spec doesn't enumerate them explicitly. Prompt 49 derives missing details from archetype rules.

Performance is a design system concern. Slow systems erode every other quality choice. These are the universal floor targets — every archetype must meet them at a minimum.

Universal targets (every archetype, every page)

Per-archetype tightening (overrides to universal floor)

Every component must work across writing directions, character ranges, and locale-sensitive data formats. i18n failures are a11y failures.

Writing direction

Character ranges

• Latin (basic + extended): default font stack covers this
• CJK (Chinese, Japanese, Korean): taller line-heights needed (1.6+ minimum); fonts may need to swap to region-appropriate (Noto Sans CJK). Never assume Latin character widths.
• Cyrillic, Greek, Devanagari: support per product market reach; verify font coverage before shipping

Locale-sensitive tokens — use the Intl API

// Date/time — never hardcode "MM/DD/YYYY"
new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }).format(date);

// Numbers — handles locale separators, currency, units
new Intl.NumberFormat(locale, { style: 'currency', currency: 'USD' }).format(1234.56);
// → en-US: $1,234.56  |  de-DE: 1.234,56 $  |  ja-JP: $1,234.56

// Sort order — use Intl.Collator for string comparison
new Intl.Collator(locale, { sensitivity: 'base' }).compare(a, b);

// Pluralization — use ICU MessageFormat, not string concatenation
// BAD:  "You have " + count + " items"
// GOOD: new Intl.PluralRules(locale).select(count)
//       → MessageFormat("{count, plural, one {# item} other {# items}}")

Banned i18n antipatterns

• Hardcoded English strings in components — use i18n keys
• Concatenated strings ("You have " + count + " items") — use ICU plurals
• Fixed-width buttons that truncate German text (German averages 30%+ longer than English)
• Direction-aware icons (chevrons, arrows, play buttons) without RTL flip
• Assuming Latin characters in regex / validation patterns
• ASCII-only password rules (blocks non-Latin users from using their native characters)

Validation behavior is a tonal choice — get it wrong and the form feels nagging or surprises the user at submit time.

When to validate

What to validate

• Required field empty
• Format mismatch (email, URL, phone, date)
• Range / length violations (min/max characters, min/max values)
• Server-side rules (uniqueness, conflict, capacity limits)

How to display validation errors — the canonical pattern

<!-- What: field border turns error color -->
<!-- Why: aria-invalid tells screen readers the value is wrong -->
<!-- How: error message below with icon + text = redundant encoding -->

<label for="email">Email</label>
<input
  type="email"
  id="email"
  aria-invalid="true"
  aria-describedby="email-error"
  style="border-color: var(--color-error);"
>
<div id="email-error" role="alert" aria-live="polite">
  <!-- Icon (color + icon = colorblind-safe redundant encoding) -->
  <svg aria-hidden="true">...error icon...</svg>
  <!-- What / Why / How message -->
  Email format isn't recognized. Try name@example.com.
</div>

<!-- Submit stays ENABLED — disabling hides the form's validation
     state from the user (WCAG SC 3.3.4 violation) -->
<button type="submit">Create account</button>

Display rules

• Error message replaces helper text below the input (same slot)
• Field gets --color-error border + 3px focus ring when focused
• Error message follows the What/Why/How formula (§7)
• Error icon to the left of message — color + icon = redundant encoding for colorblind accessibility
• Submit button stays enabled — disabling submit hides validation state from the user

Per-archetype overrides

Choose the right loading affordance — wrong choice feels broken. Operation duration drives the decision, not developer preference.

Decision tree: operation duration → preferred loading state

Per-archetype tightening

Banned loading antipatterns (universal)

• Spinner with no text after 1s — ambiguous: is it stuck or working?
• Full-screen blocker for partial-page loads
• Skeleton shimmer in Meridian / editorial contexts (violates motion policy)
• Hide nav / sidebar / chrome behind a loading state — keyboard navigation must remain functional
• Disabling Submit button "to prevent double-click" — use debounce + button loading state instead

Most real products are hybrids. One archetype is rarely sufficient for an entire product surface. These are the five most common patterns.

Each archetype inherits this governance spec in full and adds its own overrides. Below is the canonical aggregated summary. Updated whenever any archetype's overrides change.