Color-system engineering workspace

Design System Doctor

Turn a brand color or existing token file into a traceable production architecture. Lint structural debt, create arbitrary inherited themes, audit 178 component states, repair selected failures with CIEDE2000 evidence, identify migration regressions, compile multiple brands, and export implementation-ready files—all in your browser.

Open the Doctor Beginner guide Import your palette

Direct answer

What does a Design System Doctor do?

A Design System Doctor converts source colors into primitive, semantic, and component tokens; lints architecture; resolves arbitrary inherited themes; tests measurable constraints; exposes downstream impact; proposes selective, reversible repairs; detects migration regressions; and compiles one shared system across multiple brands. It is an engineering aid, not automatic accessibility certification.

Start here

Choose the workflow that matches your input.

New users can begin with one brand color. Existing palettes can be loaded from common JSON, token, CSS, and text formats with a detection summary before import.

Start with one brand color

Enter the canonical color, review the generated scale and themes, then follow the linter, repair, coverage, and export tabs.

Follow the beginner guide

Import an existing palette

Choose a local file, confirm detected colors and aliases, then start a new system or merge deliberate token paths.

See supported formats

Loading Design System Doctor…The advanced token engine runs locally in this browser.

Advanced capabilities

One connected system, not six disconnected utilities.

Every advanced capability uses the same local token model, custom rules, arbitrary themes, constraints, lineage graph, and project state, so evidence and exports remain internally consistent.

Advanced token architecture linter

Find duplicate and near-duplicate primitives, orphan tokens, hard-coded role colors, naming drift, stale overrides, deprecated references, layer skips, and inheritance cycles.

Arbitrary theme compiler

Create, clone, inherit, rename, and export custom contexts such as OLED, seasonal, campaign, low-vision, and multi-brand themes.

Evidence-rich selective repair

Compare three repair strategies with ΔE00, OKLCH deltas, downstream token impact, affected components, locking, selective apply, and rollback.

Full component state coverage

Audit 178 expected states across 25 component families covering actions, forms, navigation, feedback, overlays, data, and loading.

Migration regression engine

Detect token changes, alias-lineage changes, affected components, contrast regressions, theme regressions, replacement maps, and semantic-version impact.

Multi-brand production compiler

Generate shared-core and brand-override packages, inheritance metadata, theme-by-brand evidence, repair projections, CSS, DTCG-style JSON, and manifests.

Token architecture

Primitive → semantic → component.

Primitive tokens preserve the available color scale. Semantic tokens define intent across themes. Component tokens narrow those roles to explicit states. The resolver exposes every dependency rather than hiding the final HEX value.

primitive.brand.600
  ↓
semantic.action.primary
  ↓
component.button.primary.background

Important limitation

Evidence needs implementation context.

Contrast ratios and token paths can be tested deterministically, but a token file cannot prove that focus styles are rendered, labels remain visible, disabled controls are understandable, or every screen uses the intended token. Validate the generated system in real components before release.

Plan a safe token migration

Questions

Design System Doctor FAQ

What is a color design token?

A color design token gives a reusable name and purpose to a color value. Primitive tokens describe source colors, semantic tokens describe roles such as text or action, and component tokens describe specific uses such as a primary button background.

Does Color Pick upload token files?

No upload endpoint is required for the Design System Doctor. CSS and JSON files are read locally with browser APIs, processed in the page, and exported by the browser.

Does a passing score guarantee WCAG or legal compliance?

No. The score summarizes the checks implemented by the tool. Teams must also test real components, content, states, zoom, assistive technology, browser behavior, and applicable legal requirements.

What does the migration assistant detect?

It detects supported color tokens that were added, removed, changed, deprecated, or probably renamed. A probable rename is an inference based on matching token values and layers, so it should be reviewed by a developer.

Is the DTCG export certified?

The export follows core Design Tokens Community Group format concepts such as groups, typed values, aliases, descriptions, and deprecation metadata. Integration must still be tested with the target design-token toolchain.