Standards and Governance

The greatest enemy of a design system isn't "failing to build it" — it's drift: resources and code each changing on their own, until six months later the spec says one thing and production runs another. swift-web prevents this with three disciplines. None of them is complicated, but they require both the design side and the frontend side to hold the line.

Discipline 1: color changes only at the semantic token layer

When designing a new site or recoloring an existing one, color adjustments must land on semantic tokens (--primary, --background…) — scattered color picks inside the draft are not allowed.

  • In Claude Design: tell the AI to "switch the primary to X" instead of recoloring element by element (see quick start, step 4).
  • In Figma: change the values in the Variables collection, and bind element colors to variables rather than hard-coding values.

Why: scattered colors can't make it into the contract — at implementation time the frontend has no way to tell "which of these 7 similar golds is the primary," so they guess or normalize, and design intent is lost in translation. Token-layer changes, by contrast, are inherently consistent across the whole draft and inherently deliverable. Brand-specific colors that semantic tokens can't cover (VIP gold, tier colors, payment channel colors) are explicitly listed as supplementary tokens in the list (mapped to the --brand-* namespace on the code side) — equally named, equally deliverable. The discipline constrains "scatter," not "color richness."

Discipline 2: design resources are derived artifacts — never hand-edit them

swift-web's design resources (the 20 Claude Design cards, the Open Design design-system bundle, the Figma Variables and component library) are all auto-derived from framework source code. Which means:

  • Do not edit the design system cards directly in Claude Design, do not hand-edit the DESIGN.md / tokens.css inside the Open Design bundle, and do not hand-edit the token values in the Figma resource library — manual edits get overwritten at the next derivation, and in the meantime the draft and the code have quietly forked.
  • Have opinions about component forms or token defaults? (A default style feels wrong, or you want a new general-purpose token.) Take it to the framework maintainers and let it go through normal framework iteration: source updates → resources re-derive automatically → both tracks receive the new version in sync. Designers' feedback absolutely drives the framework's evolution — the path just runs through code, the single source of truth.
  • Using the resources to design is completely unrestricted — the discipline constrains "modifying the resources themselves," not "producing drafts with them." How you compose things in a draft, or which tokens you override there, is entirely design freedom.

Why: one resource maintained in two places will inevitably drift — the number one cause of death for design systems everywhere. Converging the trusted source to the framework code means the resources always reflect what's actually live — which is precisely why designers can draft against the cards with confidence.

This discipline has a natural corollary: onboarding a new design tool = adding one more derivation target to the pipeline, while the core asset stays put. That's exactly how Open Design was onboarded — the framework source didn't change; there's simply one more resource format generated from it. When the next tool worth using appears, same play: first ask "what design-system format does it consume," then have the pipeline produce one more output — never hand-maintain a separate resource set for that tool.

Organization admin note: in Claude Design Team / Enterprise organizations, any member can publish or modify design systems by default; the Enterprise plan can restrict publishing rights to designated members via the Claude Design Admin permission, guaranteeing the single source of truth at the mechanism level. Worth configuring when the organization is onboarded.

Discipline 3: onboarding a new brand = one token list

To establish design resources for a new brand or site, the input is exactly one thing: the brand token list (the designer's finalized token values; see the color workflow for how it's produced).

The process:

  1. The designer explores from the base design system and settles the brand palette at the token layer;
  2. They compile the brand token list (15–25 entries plus optional --brand-* supplements) and deliver it alongside the final draft;
  3. The framework maintainers feed the list into the automated pipeline, which generates in one pass: the brand's Claude Design design system variant (all future designs for that brand draft from it) + the code-side brand override styles (the project rebrand);
  4. From then on, the brand's design and code share the same token values — any recoloring request on either side goes back to updating the list and re-deriving.

Why: compressing "onboarding a brand" into a single input plus automated output makes the cost low enough to build dedicated resources for every project — the opposite of "all projects share one generic resource set that matches reality less with every use."

Quick self-check table

Scenario✅ Right way❌ Wrong way
New site colorsAdjust at the token layer, deliver a token listScattered picks in the draft, deliver "eyedrop it from the image"
Component default style feels wrongFile a request with the framework maintainersEdit the design system cards / resource library directly
Brand-specific colorsList them as --brand-* supplementary tokensLeave them unnamed, mixed into the draft
Starting a new brandDraft from the base → onboard via the listCopy another brand's resources and hand-edit
Draft doesn't match productionReport it to the maintainers to check the derivation chainHand-edit the resources to match production