Brocade

draft 1.0.0
  status stable
  title Brocade Specification
  date 2026-04-02
  license All Rights Reserved

---

spec brocade

  section purpose
    title Purpose
    level 1

    prose
      value
        Brocade is the @byre federation's design token layer. It
        defines a three-layer cascade — primitives, semantic
        tokens, and modes — that determines every visual property
        of a federation-built UI. Brocade publishes the tokens as
        CSS custom properties; consumers reference the tokens
        rather than raw values.

  section primitives
    title Primitive tokens
    level 2

    prose
      value
        Primitives are raw values: hex colors, pixel measurements,
        unitless type ratios. They are never used directly by
        application code; semantic tokens map onto primitives.

    requirement B-001
      level MUST
      value
        Primitive tokens MUST be authored in the brocade source
        and published as CSS variables. Consumers MUST NOT inline
        primitive values; they MUST reference the variable.

  section semantic
    title Semantic tokens
    level 3

    prose
      value
        Semantic tokens give primitives a purpose: text-primary,
        surface-elevated, border-subtle, space-tight. Application
        code reads only semantic tokens; the primitive layer is an
        implementation detail.

    requirement B-010
      level MUST
      value
        Component CSS MUST reference only semantic tokens or
        component-scoped tokens, never primitives directly. This
        permits the primitive layer to change without component
        churn.

  section modes
    title Modes
    level 4

    prose
      value
        Modes are switchable token sets selected at runtime via a
        single CSS class on document.body. Primary modes are
        mode-light, mode-dark, and mode-system. Accessibility
        modes (high-contrast, reduced-motion,
        reduced-transparency) compose on top of the primary mode.

    requirement B-020
      level MUST
      value
        All modes MUST be defined in the brocade source and ship
        in the published CSS. Consumers MUST NOT define mode
        variants in application code.