# How OpenDesigner works

Follow one request through OpenDesigner: the two ways in, the engine's math, the files it writes to your project, what protects you and how it learns.

OpenDesigner is a set of skills and a small engine that your AI tool loads. It reads your project, asks only what it can't find there, and writes the rules your screens follow into your own files.

## The flow

1. You ask, in Claude, ChatGPT, Cursor or another AI tool.
2. It reads your CSS, tokens, logo and fonts before it asks anything.
3. It takes one of two paths: fix what you built, or build a system from five answers.
4. The engine does the math (color, type, spacing, corners, depth, motion), offline.
5. Files land in your project: tokens, CSS, Tailwind, Figma, Swift, Compose, DESIGN.md.
6. New screens follow them. Your AI reads DESIGN.md first, and a review flags values that skip the tokens.

A mistake the maintainer confirms comes back as a new check for everyone who updates.

In numbers, read from the repository: 188 questions (6 more planned), 8 dials, 455 house standards (the ones that set a value are locked), 49 preflight checks, 70 review cases and 82 library components.

## 01 Two ways in

- **Fix** (you already built something): it measures your pages at each screen size, marks each problem on the page with the measured number, fixes one page from design tokens and shows it beside the original. The rest changes only after you say yes.
- **Build** (you're starting): it reads your files, asks up to five questions, and the engine builds the whole system. Then you zoom in or stop.

Zoom levels: sketch (up to 5 questions, about 3 minutes); broad (8 questions, about 8 minutes); defined (1 to 15 questions per area); detailed (the rest).

## 02 Inside the engine

Your answers set 8 dials from 0 to 100: Expression, Brand presence, Density, Energy, Roundness, Depth, Colorfulness, Warmth. Fixed band formulas in levers.json turn each position into values. For example, Roundness 45 falls in the band 38 to 47, which gives 6 px control corners. The same answers always give the same files.

## 03 What you keep

DESIGN.md, PRODUCT.md, opendesigner/tokens/ (DTCG 2025.10), opendesigner/build/ (CSS variables, Tailwind v4, Figma variables, Swift, Jetpack Compose, DTCG 2025.10, Paper), opendesigner/decisions.md and opendesigner/overview.html, all in your own repository.

## 04 What protects you

- Accessibility floors are locked: WCAG 2.2 AA contrast, 24 px targets, a visible focus ring and reduced motion.
- Every value records how it was set: chosen, confirmed default, picked for you, assumed or from a reference.
- Checks report and don't rewrite. A fix to code you already have waits for your yes.
- It asks you for the logo, photos, typeface and voice, and never fakes them.

## 05 How it learns

You notice something; your AI saves a note in your project with a ready-to-file issue link (nothing is posted unless you submit it); when the maintainer confirms it, a gap or a bug is fixed in the source and a visual mistake becomes a preflight check or a review case; the tests run again before the change reaches you. No version is tagged yet. Test results: https://opendesigner.dev/docs/evals/

Get started: https://opendesigner.dev/docs/install/ · Every step in detail: https://opendesigner.dev/docs/how-it-works/