Design Tooling

Design tools are where token systems go to be reborn as palettes. The failure is rarely malicious: a designer under deadline grabs the nearest swatch, the file ships, and six months later nobody can say which colors are the system. Tooling is the counter-pressure—when the fastest way to paint is also the system way, drift stops being a discipline problem and becomes a tooling property.

The other half is verification. The same WCAG math the code side enforces in CI exists as design-side plugins, so a pair can be checked while the color is still a decision rather than a deployment. When both sides compute the same numbers from the same source values, contrast stops being a hand-off argument.

This page covers the design-side tooling as this repository practices it—and the tool categories that earn their keep in any tokenized system.

Figma Variables as the Token Mirror

Figma variables are the design tool's native token primitive: named, aliased, and mode-aware. The mapping that keeps file and code aligned is structural:

• Variable collections mirror core groups — a collection per domain (color palettes, spacing, motion), variables named by the same paths (brand.primary/500) so "600" means the same thing in both worlds.
• Aliases mirror semantic references — a semantic variable's value is the core variable, exactly as foreground.primary references {color.mode.dark} in the JSON.
• Modes mirror theme resolution — light/dark modes re-bind the alias per mode, matching design.paths.light/dark; brand collections mirror the brand files' accent remapping.

The test of the mirror is the round trip: any variable in the file, read as a path, emits the CSS name the generator would produce. When that holds, the design file is a second consumer of the token system rather than a parallel source of truth.

Token Plugins: The Pipeline's Design End

Plugins bridge file and pipeline in both directions. Push-style plugins (Tokens Studio for Figma is the category leader) serialize variables to token JSON—the design tool becomes an authoring surface for the same files the build consumes. Pull-style pipelines (this repository's shape) generate the design-side libraries from the token sources, as the Adaptive-DS-Colors plugin does for ramps: contrast-keyed generation in the tool, verified values in the repo. The choice is authority—which side is the source—and it must be exactly one side.

Contrast Checking at the Point of Choice

Design-side contrast plugins implement the same relative luminance math the repo's tokenValidator.ts enforces (AA 4.5:1 / 3:1, AAA 7:1 / 4.5:1). The workflow worth institutionalizing: pair checks inside the design file against the role pairs—foreground.secondary on background.primary (≈7.5:1 light, ≈9.5:1 dark)—so the numbers a designer sees while choosing are the numbers CI will compute later. Disagreements between the two are tooling bugs, not judgment calls.

Library Structure as Drift Detector

The component library's structure does quiet enforcement: component variants' layers named for slots (matching the contract anatomy), painted only with bound variables. Off-system color becomes visiblyoff—any raw swatch in a layer is a defect by definition, findable by inspection. The enforcement is cheap because it is structural; nobody audits what the structure already prevents.

Design Impact

Designers own the file-to-mirror fidelity: variable naming, mode wiring, and the discipline of painting only with variables. The tooling makes the discipline easy; the review keeps it true.

Engineering Impact

Engineers own the bridge code—serializers, generators, and the sync scripts that keep one side authoritative. The invariants (round trips, no dual sources of truth) are code review questions with tooling answers.

Accessibility Impact

Accessibility owns the checker configuration: which pairs are checked, at which level, per mode—so the design-side numbers and the CI numbers cannot silently diverge.

The first week on a tokenized toolchain, compressed to four moves:

1. Paint only with variables—if a color, size, or radius cannot be found in the collections, that is a system gap report, not a raw-swatch situation.
2. Switch modes before judging dark mode— never re-paint for dark; the aliases re-resolve. If the result is wrong, the fix is a paths entry, not the file.
3. Check pairs while choosing—run the contrast plugin on any new pairing before it leaves the canvas; the thresholds are the same four numbers from the foundations pages.
4. Round-trip one token a week—pick any variable, read its path, confirm the CSS name. Two minutes that keep the mirror honest and the drift caught.

• Push vs pull authority: file-authoring plugins put designers in control and risk schema drift; pipeline-generated libraries guarantee fidelity and make the tool a viewer. This repo pulls; teams with strong design-engineering overlap can push safely.
• Variable coverage vs tool limits: Figma variables cannot express every token shape (keyframe strings, structured shadows); the unexpressible stays code-side and documented, never approximated in-file.
• Checker strictness vs designer autonomy: failing builds on contrast in the design tool is premature; surfacing numbers is the right pressure at the point of choice, with CI as the hard gate.

1. Two sources of truth

Variables hand-edited away from the pipeline (or JSON hand-edited away from the plugin) fork the system at the file boundary. One side writes; the other reads.

2. Detached styles

// Bad: A style whose fill is a literal
Fill: #717171
// Good: A style bound to the variable
Fill: neutral/500  (variable)

3. Mode-painting dark themes

Duplicate frames with re-painted colors defeat the entire mode mechanism and diverge from the JSON paths on the next change.

4. Plugin numbers taken on faith

A checker whose math or background assumption differs from the validator produces confident wrong answers. Calibrate once against the same pairs CI checks.

• Code Tooling — the pipeline this file mirrors (/blueprints/foundations/tooling/code)
• Color Foundations — the pair numbers the checkers share (/blueprints/foundations/color)
• Theming Strategies — what modes and brands mean mechanically (/blueprints/foundations/meta/theming)