For a charity's design system shipping to web, native apps and a design editor, should tokens be authored in a tool-agnostic token file or design-file-first, and what does each cost?
answer
- who changes tokens most often
- reviewable, diffable history
- can the editor express every type
- tool lock-in versus designer flow
- one writable source, many readers
basics
~20 sA tool-agnostic token file in version control gives review, history and tool independence but adds friction for designers; design-file-first gives designers immediacy but ties the system to one editor's model. Either way, only one place may be writable.
solid answer
~50 sA **token file in version control** as the source means every change is reviewed and diffed, types, references and composites are explicit, and web, native and the design editor are equal consumers - you can change any tool without losing the truth, which is exactly what a tool-agnostic format is for. The cost is friction for designers, who either edit structured text or depend on tooling to push values into their editor. **Design-file-first** puts authorship where designers explore and see changes in context, but the editor's variable model may not express every type or reference shape, review and history are weaker, and the system is tied to that editor. I choose by who changes tokens most, how many platforms consume them and how much audit the organisation needs. Often the editor is the authoring surface but its export lands in the reviewed file, which stays canonical. The one arrangement I reject is two independently editable sources.
go deeper
Recall that tokens need one authoritative source, and that a tool-agnostic file lets web, native and design tools read the same data.
Explain what each option gives and costs: review and expressiveness for the file, immediacy and ownership for the design file.
Show how you would pick for a real multi-platform system, test export fidelity for the middle path, and prevent two writable sources.
Frame it as ownership and lock-in strategy: who owns visual decisions, what audit the organisation needs, and how cheaply it can change tools later.
## The decision A design system's tokens reach at least three places: the web front end, the native mobile apps and the design editor where designers build screens. Every system has to decide where tokens are **authored** - the one place a change is made - and which places only **read**. The **Design Tokens Community Group format** exists to make that decision less painful: it defines one JSON file shape so tokens can move between tools without bespoke glue, and so a team can change tools without rewriting its integrations. It does not decide where authoring happens. ## Option A: the token file is the source The canonical tokens live in files in the format, in version control, and every consumer - including the design editor - is fed from them. - **Review and history.** Every change is a diff someone approves; you can answer 'when did the donate action's fill change, and why?'. - **Full expressiveness.** Types, references, composites, descriptions and deprecation markers are all first-class, whatever any single tool supports. - **Equal consumers.** Web, native and the editor are all downstream, so no platform's model shapes the source. - **Tool independence.** Replacing the design editor or the build tool changes an adapter, not the truth. The format also lets each tool keep its own metadata in `$extensions`, which other tools must preserve. - **Cost:** designers edit structured text or a form on top of it, and see changes in their editor only after a sync. Exploration feels slower. ## Option B: the design file is the source Designers define variables and styles in the editor; an export produces the token file that engineering consumes. - **Immediacy.** Designers change a value and see every screen update in context, which suits exploration and fast brand work. - **Ownership.** Those who make visual decisions own them directly. - **Cost: model fidelity.** The editor's variable model may not match the format one to one - some types, composite shapes or reference patterns may be flattened or lost on export. - **Cost: review.** Editor changes are rarely reviewed like code; an accidental change can reach production through the next export. - **Cost: lock-in.** The source now lives in one vendor's file; engineers cannot propose a token change without the editor. ## Comparing the two | Concern | Token file first | Design file first | |---|---|---| | Designer iteration speed | slower | fast | | Review and audit trail | strong | weak unless added | | Expressing every type and reference | complete | depends on the editor | | Changing tools later | cheap | expensive | | Engineers proposing changes | natural | awkward | ## The common middle path Many teams split authoring from canon: designers author in the editor, an export writes the standard format, and the export is committed and reviewed like any other change. The reviewed file is canonical; the editor is a convenient authoring surface. This keeps designer flow and review, but only works if the export is lossless enough for the tokens the system uses - which is worth testing before committing to it. ## Choosing for a charity For a charity's donation site and apps, a few questions settle it: 1. **Who changes tokens most?** A small brand team making frequent campaign tweaks leans towards editor authoring; engineering-heavy teams lean towards the file. 2. **How many consumers?** Web plus two native apps plus email templates rewards a neutral source. 3. **How much audit?** A charity that must evidence accessible donation flows benefits from reviewed, dated changes. 4. **How rich is the model?** Heavy use of composites and references favours the file. ## The failure to avoid Whatever is chosen, **only one place may be writable**. When designers edit the editor's variables and engineers edit the file independently, the two drift, and nobody can say which donate color is correct. How the read-only copies are kept in sync and audited is a separate discipline; the source decision comes first.
- What would make you move a design system from design-file-first to a token file in version control?Signals that review and fidelity now matter more than designer speed: more consuming platforms, tokens using references or composites the editor's export flattens, production incidents traced to unreviewed editor changes, or a planned change of design tool. At that point the file becomes canonical and the editor becomes a reader or an authoring surface whose exports are reviewed.
- How does a tool-agnostic format help if a team later replaces its design editor?The canonical tokens are in a neutral file rather than in the old editor, so only the adapter that feeds the new editor changes. Tool-specific metadata kept in `$extensions` survives in the file even while no tool uses it. Without a neutral file, the migration means re-deriving the truth from the old tool's export.
saying these in an interview costs you the question
- Designers and engineers can both edit their own copy as long as they talk.
- Any design editor's export captures every token type and reference losslessly.
- Choosing the token file means designers must never touch tokens.
- A tool-agnostic format decides where tokens must be authored.
- Review is unnecessary for token changes because they are only values.