brocade

draft 1.0.0
  status draft
  title brocade — design tokens
  date 2026-05-24
  license Open

---

spec brocade

  section three-layers
    title Three-layer cascade
    level 1

    prose
      value
        Raw primitives at the bottom (hex colors, pixel sizes,
        unitless ratios). Semantic tokens map onto primitives by
        purpose (text-primary, surface-elevated, space-tight).
        Application code reads only semantic tokens.

    requirement BR-001
      level MUST
      value
        Application CSS MUST reference only semantic tokens or
        component-scoped tokens, never primitives directly.

  section modes
    title Modes
    level 1

    prose
      value
        Modes override what a semantic token means. light/dark are
        the primary modes; accessibility modes
        (high-contrast/reduced-motion/reduced-transparency) compose
        on top. The semantic-token layer survives mode changes; only
        what tokens resolve to changes.

    requirement BR-010
      level MUST
      value
        Modes MUST be expressed as token overrides at the semantic
        layer, not by rewriting application CSS.

  section themes
    title Themes
    level 1

    prose
      value
        Themes replace the raw layer entirely. Semantic tokens
        survive — only what they resolve to is different. Breakpoints
        are not tokenized; the spec is honest about what tokens
        cannot do.