Book a callGitHub1

Reference03/06

The files it writes

Updated · Edit on GitHub

OpenDesigner writes DESIGN.md and PRODUCT.md at the root of your project, and everything else into an opendesigner/ folder. The token files in opendesigner/tokens/ are the source of truth, and every other file is made from them. In a test run, one sketch and build wrote 50 files with no errors.

your-project/
1DESIGN.md your rules in plain words
1PRODUCT.md what it is, who it is for, where it runs
opendesigner/
2tokens/ 11 DTCG files, the source of truth
primitives.tokens.json semantic.tokens.json semantic.color.light.tokens.json semantic.color.dark.tokens.json semantic.density.spacious.tokens.json semantic.density.comfortable.tokens.json semantic.density.compact.tokens.json motion.standard.tokens.json motion.reduced.tokens.json opendesigner.resolver.json opendesigner.meta.json
3build/ the exports, rewritten by every build
css/tokens.css tailwind/theme.css figma/variables.json · figma/import/ paper/tokens.json · tokens.light.css · tokens.dark.css swift/DesignTokens.swift compose/DesignTokens.kt dtcg/ artifact/project/
3overview.html the whole system on one page
3preview.html · preview/ every token; seven filled templates
4decisions.md every decision, how it was set and why
4standards.md · standards-state.json
4state.json where you left off
  • 1
    At the root. For people and AI tools. Commit both.
  • 2
    The source of truth. DTCG 2025.10 tokens. Every other file is made from these.
  • 3
    Made from the tokens. Exports and pages. Every build rewrites them, so don't edit them by hand.
  • 4
    The record. Append-only decisions, the locked standards, and the state a later session continues from.
  • +
    Only when you ask. RATIONALE.md, feedback.md, references/ and the private journey/ log, which stays out of git.
Everything OpenDesigner writes, as one sketch and build leaves it: two files at the root, the tokens as the source of truth, the exports and pages made from them, and the record of how each value was set.

At the root of your project

  • DESIGN.md: your design rules in plain words, for people and AI tools. It refreshes after every decision, and each section shows its zoom level.
  • PRODUCT.md: what the product is, who it is for and where it runs, so later sessions don't have to guess.

The tokens

opendesigner/tokens/ holds 11 files in the open DTCG 2025.10 format:

  • primitives.tokens.json: the raw palette and scales;
  • semantic.tokens.json: roles that don't change by mode;
  • semantic.color.light.tokens.json and semantic.color.dark.tokens.json;
  • three density files: spacious, comfortable and compact;
  • motion.standard.tokens.json and motion.reduced.tokens.json;
  • opendesigner.resolver.json, which ties the modes together;
  • a small metadata file.

See Design tokens and DTCG.

The exports

All of these are in opendesigner/build/. Every build rewrites them, so don't edit them by hand.

Change the decision

Record it with set, then build. Every export changes together, and the log says why.

$ engine.py set dials.roundness 60 --why "softer corners for a friendlier feel"
$ engine.py build
Rewritten together 
css/tokens.css
  --ds-radius-control: var(--ds-radius-8);
swift/DesignTokens.swift
  public static let radiusControl: CGFloat = 8
compose/DesignTokens.kt
  val radiusControl = 8.dp
decisions.md
  ## D-0009 · dials.roundness = 60

Edit an export by hand

The next build rewrites it from the tokens. Swift, Compose and Tailwind never changed, and the log knows nothing.

opendesigner/build/css/tokens.css
- --ds-radius-control: var(--ds-radius-6);
+ --ds-radius-control: 8px;   typed in by hand
After the next build 
$ engine.py build
css/tokens.css
  --ds-radius-control: var(--ds-radius-6);   back to the tokens
swift/DesignTokens.swift
  radiusControl: CGFloat = 6   never changed
decisions.md
  (no entry)
Everything in opendesigner/build/ is made from the tokens and rewritten by every build. Record the decision instead, and CSS, Swift and Compose move together with a reason in the log.
  • css/tokens.css: CSS variables you can use in any web project.
  • tailwind/theme.css: a Tailwind CSS v4 theme, so utility classes use your colors, spacing, radii and type.
  • figma/: Figma variables, with one import file per collection and mode in figma/import/, and figma/variables.json for Tokens Studio.
  • paper/: tokens for the Paper design tool, in light and dark.
  • swift/DesignTokens.swift: the same values for iOS apps.
  • compose/DesignTokens.kt: the same values for Android apps built with Jetpack Compose.
  • dtcg/: one DTCG resolver file for token tools that take a single entry point.
  • artifact/project/: the system as files for a Claude Design System artifact: tokens, a brand book, a cover and a button preview.

See Export for how to use each one.

Pages you open in a browser

  • opendesigner/overview.html: your whole system on one page, including what is still missing. It works offline and loads nothing from the web.
  • opendesigner/preview.html: every token on one page.
  • opendesigner/preview/: seven visual templates filled with your own values: palette, type scale, spacing ruler, radius, elevation, motion and component sheet. The option gallery is filled per question with engine.py show, and the taste poll is built by taste.py build into opendesigner/preview/taste-poll/.

The record

  • opendesigner/decisions.md: every decision, how it was set and why. It is append-only, so a later session doesn't quietly undo a choice.
  • opendesigner/standards.md: the house and project standards this project follows, locked, with their sources.
  • opendesigner/state.json: where you left off, so you or another AI tool can continue later. DESIGN.md and the tokens are made from it.
  • opendesigner/standards-state.json: a copy of each standard this system follows, as it follows it. Keep it next to state.json.

See Decisions, DESIGN.md and the overview page.

Written by the skill, or only when you ask

These are not part of an engine build:

  • opendesigner/RATIONALE.md: one page for the team on what was chosen, why, and what is still open. The skill writes it from a template.
  • A short note in your AGENTS.md, added only after you say yes. It tells later AI agents to read DESIGN.md, use the tokens and run engine.py review.
  • opendesigner/feedback.md, written only if you report something with engine.py feedback.
  • opendesigner/references/, written only when you share a reference with the extract skill. It holds the measurements taken from it.
  • opendesigner/journey/, written only if you said yes to the private log. It is kept out of git.

What to commit

Commit DESIGN.md, PRODUCT.md and the opendesigner/ folder, so your team and your next AI session work from the same rules. The private log in opendesigner/journey/ stays out of git.

Because the exports are made from the tokens, you can rebuild them at any time with engine.py build. You can commit them so your apps import them directly, or rebuild them when you need them.

How the files relate

  • opendesigner/state.json holds your answers and settings.
  • The tokens in opendesigner/tokens/ are made from it. They are the source for everything else.
  • The exports, the pages and DESIGN.md are made from these.
  • The decision log records why each value is what it is.

To change anything, record a decision with engine.py set, then run engine.py build. See Engine commands.