Meridian Field Services: instructional example, not project evidence
The code's token file (DTCG format) feeds both the design tool and the build; this brief records the decisions, not a second copy.
| Tier | Tokens (example) | Owner |
|---|---|---|
| primitive | The teal ramp (teal-50…teal-900), the slate ramp, the amber accent: raw hex | UX owner |
| semantic | color-primary → teal-600 · color-danger → the red sibling · color-surface → slate-50 · color-ink → slate-900; a rebrand reassigns the primitive, these names hold | UX owner |
| component | chip-status-late-bg → a semantic reference · board-row-hover → another | The component's owner (§5) |
Naming: category-concept-property-variant-state; no inline hex documented as a token; sprawl is a defect.
The ratio, not just the hex; hex without a ratio is not evidence.
| Pairing | Ratio · level | Cited |
|---|---|---|
| color-ink on color-surface | 15.8:1 · AAA | 1.4.3[1] |
| color-primary (teal-600) on white | 4.6:1 · AA normal text | 1.4.3[1] |
| Late-status chip (amber-ink on amber-50) | 4.9:1 · AA | 1.4.3[1] |
| Map band colors (non-text) | 3:1 · the band scale was darkened one step from the initial design to clear it (the exception recorded) | 1.4.11[1] |
Theming: a high-contrast mode reassigns the semantic tokens to the darker primitives; it is a token remap, not a second palette, so every pairing's ratio is re-checked once at the semantic tier.
Scale decision: the Minor Third ratio (1.200), chosen for density. The dispatch board packs rows, and a looser ratio would cost vertical rows per screen (NFR-P1 the board liveness the density serves[2]); rationale recorded. Roles to steps: display (reserved), heading (step +3), body (base), label (base, medium weight), caption (step −1). Families: Inter for UI, JetBrains Mono for identifiers (the chip convention the whole artifact set uses); weights and line-heights are tokens.
Base unit: 4 pixels, scale 4/8/12/16/24/32/48; a decision, not an emergent pile. Application: component padding and grid gaps resolve to steps; the board's dense row uses step-2 vertical, the card uses step-3; a new spacing value resolves to a step or goes through the contribution flow; no one-off pixels.
| Component | Status | Owner | A11y contract |
|---|---|---|---|
| Board row | STABLE | UX owner | state machines[3] · component contracts[1] |
| Suggestion card | STABLE | A. Reyes's UX partner | state machines[3] |
| Status chip | STABLE | UX owner | as above |
| Intake form field | STABLE | UX owner | form validation[3] |
| Map band legend | DRAFT | UX owner | Interaction unspecified pending the a11y audit |
Governance: the UX owner owns tokens and base components; a product team proposes a domain component through a review that checks the a11y contract and the token resolution; drift detection: the build lints against hard-coded hex and spacing, and a monthly visual diff compares the design tool against the rendered components; token drift does not ship silently.
| Question | Owner | Answer by | Blocks |
|---|---|---|---|
| Does the map band legend (DRAFT) need a non-color redundancy (pattern or label) to clear the a11y audit, or does the band list text alternative suffice (map band contract[1])? | UX owner with the accessibility owner | At the accessibility audit | The legend's promotion to STABLE only |