Skip to content

SOP-101 — Design-tokens + UI-spec production

Guide

<!-- last-reviewed: 2026-06-01 · owner: Creative — Brand & Marketing (Visual Designer) -->

SOP-101 — Design-tokens + UI-spec production

SOP · owner: Creative — Brand & Marketing (Visual Designer). Layer: SOP/Runbook (docs/canon.md). How the Visual Designer produces the visual identity system, the design-token reference, and per-feature UI design specs — accessible, token-based, and self-sufficient — reviewed by the Creative Director before they reach Engineering. The stack target is CLAUDE.md (Astro 6 / Tailwind v4; linked, not restated).

Interface Contract

  • Inputs: scoped visual brief ← from <Creative Director> · trigger: creative brief issued
  • Inputs: user/audience research findings (visual preference, readability) ← from <Design Research Director> · trigger: research findings issued
  • Inputs: structural wireframe spec (to skin) ← from <UX Designer> · trigger: document changed
  • Outputs: delivered visual artifact (tokens / UI spec / identity / thumbnail) → to <Creative Director> · trigger: brand artifact delivered
  • Outputs: approved design-token reference / UI spec → to Engineering Director · trigger: ui design spec approved
  • Outputs: stable visual identity / tokens added/changed → to Documentarian · trigger: document changed
  • Outputs: approved visual artifact → to Archivist · trigger: artifact approved
  • Handoff trigger (in): the Creative Director commissions a visual identity / token / UI-spec / thumbnail brief
  • Handoff trigger (out): the artifact is delivered to the Creative Director for sign-off (brand artifact delivered); on approval the spec goes to Engineering (ui design spec approved)
  • Definition of Done before handoff:
    • [ ] Every color pair has a documented WCAG ratio ≥ AA (no waived failures)
    • [ ] Every type usage references a named scale step; every spacing value a named token
    • [ ] Every token has a Tailwind v4 custom property name (--color-…, --spacing-…)
    • [ ] Coherent with all existing visual identity artifacts in docs/brand/
    • [ ] For thumbnail / channel art: legibility at minimum rendering size documented
    • [ ] Spec is self-sufficient — Engineering / a human can execute without asking intent
    • [ ] Delivered to the Creative Director (brand artifact delivered); on approval, to Engineering (ui design spec approved), stable docs to the Documentarian (document changed), artifact to the Archivist (artifact approved)
    • [ ] Learnings captured to docs/knowledge/ if any

creative brief issued, brand artifact delivered, ui design spec approved are proposed to Operations, pending registration (Phase 0 reports). document changed, artifact approved, research findings issued are registered. The Visual Designer’s output is not finalized without Creative Director review (sub-hire rule, JD); the Engineering Director is an authored (Wave 2) counterparty — the ui design spec approved edge is pending until registered and named back by Engineering (interface-contract-spec.md §3.1 R3). The Visual Designer writes no intranet/ code; the seam is one-way (spec → implementation).

Purpose

Produce the visual identity, design tokens, and UI specs that make the product legible, coherent, and accessible — and give Engineering a single source of truth to implement from, so visual intent is never guessed.

When to use

When the Creative Director commissions a visual identity system, design-token reference, UI design spec, or YouTube visual asset (creative brief issued). On a greenfield system (no docs/brand/design-tokens.md yet), the first move is to reverse-document the intranet’s live Tailwind v4 values into named tokens, then forward-own them.

Flow

flowchart LR
  A["creative brief issued"] --> B["Visual foundation<br/>palette+contrast · scale · spacing"]
  B --> C["Produce artifact<br/>tokens / UI spec / thumbnail"]
  C --> D{"Self-check:<br/>contrast · tokens · v4 map"}
  D -->|fail| C
  D -->|pass| E["brand artifact delivered<br/>→ Creative Director"]
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef d fill:#0f766e,color:#fff,stroke:#134e4a
  class A,B,C,E s
  class D d

Text fallback: a brief arrives (creative brief issued) → establish the visual foundation (palette with verified contrast, type scale with a ratio, spacing base unit) → produce the artifact (token reference, UI spec, or thumbnail brief) → run the self-check (JA-101: every contrast pair documented, every value a named token, every token mapped to a Tailwind v4 custom property) → if it passes, deliver to the Creative Director (brand artifact delivered); if it fails, fix and re-check.

Steps

  1. Read the existing visual record (docs/brand/design-tokens.md, visual-identity.md) and CLAUDE.md (Tech Stack). Extend what exists; do not reinvent a scale or palette that’s already decided.
  2. Establish / confirm the foundation — palette with semantic roles and a documented WCAG ratio for every text-on-surface pair; a type scale with a named ratio (1.25 Major Third for the compact portal UI); a spacing base unit (8px) as named tokens.
  3. Produce the artifact to its home — docs/brand/visual-identity.md, docs/brand/design-tokens.md, specs/ui-design-<slug>.md, or the YouTube docs.
  4. Map every token to a Tailwind v4 custom property (--color-primary: #hex, --spacing-4: 1rem) — this mapping is the handoff artifact Engineering implements.
  5. Run the self-check (JA-101) — contrast documented, no snowflakes, coherence verified, spec self-sufficient. Fix any failure before delivery.
  6. Deliver to the Creative Director (brand artifact delivered). On approval, the spec goes to Engineering (ui design spec approved), stable docs to the Documentarian (document changed), the artifact to the Archivist (artifact approved).

Roles / approvers

Run by the Visual Designer (author). Approved by the Creative Director (visual sign-off; output is finalized only with it). Engineering implements from the approved spec; Engineering does not make visual decisions without the Director’s sign-off.

Guardrails

  • No code — produce specs and token references; never edit intranet/. No “quick CSS fix.”
  • Accessibility is the floor — WCAG AA minimum (4.5:1 normal, 3:1 large/UI); fix a failing pair, do not waive it as a first move.
  • No visual snowflakes — every value resolves to a named, reusable token; name and flag any exception to the Creative Director.
  • No brand-strategy decisions — positioning, voice, naming are the Brand Strategist’s lane; execute the visual system within the brand direction given.
  • No distribution (Growth) and no research (Design Research — consume, don’t run).
  • No foundational-doc edits — provide content for the Documentarian to encode.
  • Personal information is PA-only.

Job aid: JA-101 — UI-spec / design-token readiness checklist. See also: docs/units/creative/manuals/visual-designer.md · docs/units/creative/charter.md · SOP-099 (the Director’s visual-direction gate) · docs/units/engineering/manuals/engineering-director.md · CLAUDE.md · docs/handoff-triggers.md.