0–5 min: choose a slice
Pick one component family and list its colors, typography, spacing, radius, icon, and mode needs.
Success checkThe test scope is small enough to review manually.
Design systems guide · Updated 2026-06-28
Design Token Export Checklist: Figma, Penpot, Sketch, DESIGN.md, JSON Tokens, Naming, Modes, Assets, and Code Handoff
A practical checklist for turning design-system decisions into reviewable code artifacts without losing names, modes, aliases, semantic intent, accessibility constraints, or developer ownership.
Design tokens fail when teams treat export as a button instead of a contract. A token pipeline has to preserve naming, modes, aliases, source ownership, accessibility intent, platform transforms, and rollback rules across design tools and code repositories.
This checklist connects Penpot, Figma, Sketch, DESIGN.md, and Excalidraw-style ideation into one adoption flow: decide what counts as a token, map raw values to semantic names, export to a reviewable JSON shape, transform into platform outputs, and make every handoff auditable by designers and engineers.
RepoDaily verdict
Do not start by asking which design tool exports the most token formats. Start by defining the token contract your codebase can review: source, name, type, mode, alias, fallback, accessibility note, owner, and consuming package. A good export pipeline makes design decisions boring to diff and safe to ship.
RepoDaily fixture evidence: local token-to-code regression test
This is not a benchmark of Figma, Penpot, Sketch, Style Dictionary, or any design-token vendor. RepoDaily created a small local JSON token contract to check whether a token export workflow can generate reviewable CSS/TypeScript outputs, preserve aliases and modes, keep asset metadata visible, expose rename and dark-mode diffs, and reproduce baseline outputs for rollback.
| Evidence item | Fixture result | Why it matters | Limitation |
|---|---|---|---|
| Local token regression fixture | 7/7 local token-to-code checks passed. | Validates the checklist mechanics, not a vendor or design-tool ranking. | Small local JSON fixture only; no real design-tool account is connected. |
| Generated code outputs | One token contract generates both `tokens.css` and `tokens.ts`. | Design decisions become reviewable code artifacts instead of one-off copy-paste values. | Only CSS and TypeScript outputs are generated. |
| Alias and mode preservation | The action-primary token keeps its raw color alias, and light/dark surface modes generate separate outputs. | Aliases and modes are where many token pipelines lose intent. | The fixture uses a simple resolver rather than a full design-token build system. |
| Rename and mode diffs | Renaming `action.primary` and changing the dark surface value both create explicit reviewable diffs. | A team should be able to see what will break before exporting tokens into production code. | Diff artifacts stand in for visual regression screenshots. |
| Asset metadata and rollback | The fixture keeps icon path/license/owner metadata and can reproduce the baseline output from the original contract. | Tokens and assets need ownership and rollback, not just generated variables. | No full component renderer or browser screenshot test is run. |
- Read this as a RepoDaily self-test of the token export checklist, not as a benchmark of any design tool.
- The test supports the page recommendation: export should be treated as a reviewable contract with names, aliases, modes, assets, diffs, and rollback.
- The evidence is intentionally small, so it proves checklist sanity rather than full design-system migration readiness.
Quick matrix
| Export surface | What to preserve | Good signal | Failure signal |
|---|---|---|---|
| Raw values | Colors, typography, spacing, radius, shadows, opacity, motion | Every value has type, source, owner, and intended use | Values copied as anonymous hex codes or pixel numbers |
| Semantic tokens | Role names such as background/default, text/subtle, action/primary | Components consume semantic names rather than raw palette slots | Developers import blue-500 directly into product code |
| Modes and themes | Light/dark, brand, density, platform, locale or high-contrast variants | Mode changes are explicit and testable | Dark mode is a separate spreadsheet or manual override |
| Aliases and references | Token-to-token links and fallback chains | Aliases survive export and can be resolved deterministically | Aliases are flattened without review history |
| Assets | Icons, logos, illustrations, fonts, image exports | Assets have version, license, size, and platform output rules | Screenshots or SVGs are manually copied into apps |
| Code outputs | CSS variables, TS constants, Swift, Android XML, Tailwind config, docs | Generated outputs are reviewed from one source file | Design and code pipelines generate different names |
| Governance | Owners, review gates, changelog, deprecation, rollback | Token changes behave like code changes | A designer can silently rename a token that breaks production |
Design token export readiness scorecard
Score one design-system slice before exporting a full library.
| Control | 0 points | 1 point | 2 points | Owner question |
|---|---|---|---|---|
| Token inventory | Unknown values in files | Partial naming list | Typed token inventory with source and owner | Which values are tokens and which are local overrides? |
| Naming policy | Names follow visual appearance only | Some semantic names | Raw, semantic, component, and mode names are separated | Can code consume names without knowing the design tool? |
| Mode handling | Light/dark handled manually | Modes exist but are not tested | Mode matrix is exported and diffed | What breaks when a mode is renamed? |
| Transform rules | Manual copy-paste | One generated output | Transforms for CSS, JS/TS, mobile, docs are explicit | Which generated files are source of truth? |
| Review workflow | No review for token changes | Designer-only review | Design and engineering review the same diff | Who approves a breaking token change? |
| Rollback | No rollback path | Can revert code only | Can revert source tokens and generated outputs together | How do we undo a bad token export today? |
30-minute design token export test plan
Use this before committing to a tool-specific export workflow.
5–10 min: export source tokens
Export or manually normalize the slice into a JSON-like token contract with name, type, value, mode, alias, and source.
Success checkA designer and engineer can read the same file.
10–16 min: generate one code target
Create CSS variables, TS constants, or another single code output and wire it into one demo component.
Success checkThe component renders from generated tokens, not copied values.
16–22 min: change one semantic token
Rename or update one semantic token and inspect the diff, generated files, and visual result.
Success checkThe change is understandable and reversible.
22–30 min: review failure modes
Check alias loss, mode mismatch, asset handling, accessibility notes, changelog, and rollback path.
Success checkThe team knows whether to scale, restrict, or redesign the pipeline.
Token export decision flow
- Pick one real component family, such as buttons, alerts, or navigation, instead of exporting the entire design system first.
- List raw values, semantic roles, component-level names, modes, assets, and the consuming code packages for that slice.
- Choose the source of truth: design tool, token repository, DESIGN.md-style spec, or a hybrid with explicit ownership boundaries.
- Export to a reviewable JSON shape and keep the original names, aliases, modes, comments, and source references visible.
- Transform the JSON into one code target first, such as CSS variables or TypeScript constants, and compare the rendered component before and after.
- Add changelog, deprecation, rollback, accessibility review, and ownership rules before scaling the pipeline across platforms.
Scenario table
| Scenario | Minimum checklist | Stop if |
|---|---|---|
| Figma library to web app | Map variables/styles to semantic JSON and generate CSS or TS from one reviewed source | Token names change during export or aliases are flattened silently |
| Penpot self-hosted design system | Test ownership, backups, export fidelity, SVG/assets, and developer handoff on one component slice | Self-hosting makes design data available but token review remains manual |
| Sketch Mac workflow to multi-platform code | Export symbols/styles, map names, and test generated web/mobile outputs | Mac-only source creates unreviewed manual translation for non-Mac teams |
| DESIGN.md for coding agents | Write token rules as machine-readable constraints and compare agent output against the token source | Agents implement stale brand rules or raw values without citing the spec |
| Excalidraw-to-design-system handoff | Treat sketches as intent only; convert final decisions into typed tokens later | A sketch file is treated as production token authority |
| Multi-brand or dark-mode rollout | Require mode matrix, fallback rules, visual regression, and owner signoff | Dark mode is shipped as a separate hand-tuned stylesheet |
Design token export risks
Name drift
A visual name in the design tool can become a semantic API in code. Rename policy must exist before export.
Alias loss
Flattened values hide why one token references another, making future theme changes risky.
Mode ambiguity
Light, dark, brand, density, and platform modes need a matrix; otherwise teams ship manual overrides.
Asset mismatch
Icons and fonts are part of the design system, but token exports often ignore licensing, size, and platform constraints.
Stale agent spec
AI-readable design rules help coding agents only when the spec is versioned and reviewed like code.
No rollback
Generated outputs without a source-token rollback path make a bad design decision hard to undo.
Implementation patterns
Token contract file
Keep a small canonical JSON file with name, type, value, mode, alias, source, owner, and deprecation fields.
Design-to-code pull request
Review source token changes and generated code outputs together, with visual examples attached.
Semantic-first naming
Use raw palette names internally but expose semantic roles to product code.
Mode matrix snapshot
Export light, dark, high-contrast, brand, and density modes as an explicit matrix before generating code.
Agent-readable summary
Mirror the token contract into DESIGN.md-style instructions so coding agents know which names are allowed.
Deprecation lane
Never delete or rename widely used tokens without a replacement, changelog, and release window.
FAQ
Short answers for teams trying to move tokens from design tools into code.
Should the design tool be the source of truth?
Only if engineers can review the exported contract, generated code, changelog, and rollback path. Otherwise, use a token repository as the reviewable source.
Are design tokens just colors?
No. Mature token systems include typography, spacing, radius, shadows, opacity, motion, assets, modes, aliases, and semantic roles.
Where does DESIGN.md fit?
It can summarize token rules for coding agents, but it should mirror the canonical token source instead of becoming an unreviewed second source of truth.
What is the smallest useful pilot?
One component family with light/dark modes, one generated code target, one visual comparison, and one rollback test.
Related radar
Related RepoDaily briefs
Penpot: Open-Source Design Collaboration Built for Designers and Developerspenpot/penpot · Design / Creative appFigma Explained: Collaborative Product Design, Design Systems, Plugins, and Developer Handofffigma/rest-api-spec · Design / Creative appSketch Explained: macOS-Native Product Design, Local Files, Plugins, and Developer Handoffsketch-hq/SketchAPI · Design / Creative appDESIGN.md: A Design System Format Built for AI Coding Agentsgoogle-labs-code/design.md · Library / FrameworkExcalidraw Explained: Open-Source Whiteboarding for Diagrams, Sketches, and Embeddable Visual Workflowsexcalidraw/excalidraw · Design / Creative app
Sources
Feedback
Did this page help you make a decision?
Anonymous feedback helps RepoDaily improve what is actually useful.