How to Use the Design System Doctor: A Beginner’s Guide

Know what the Doctor creates

The tool turns colors into a structured system rather than merely displaying swatches.

Primitive tokens store available source colors. Semantic tokens describe product roles such as canvas, text, border, action, focus, and status. Component tokens apply those roles to concrete states such as a primary button hover background.

The Doctor also creates light, dark, and high-contrast contexts, then lets you add arbitrary themes such as OLED, campaign, seasonal, or low-vision variants.

Option 1: start with one brand color

This is the simplest workflow for a first project.

1. 1

   Enter a project name.

2. 2

   Enter or pick the canonical brand color.

3. 3

   Review the automatically generated brand scale, semantic roles, component tokens, and built-in themes.

4. 4

   Open Architecture Linter and resolve errors before optional governance warnings.

5. 5

   Open Advanced Repair and review contrast evidence before applying selected changes.

6. 6

   Check State Coverage, then export the system pack.

Option 2: start with an existing palette

Upload a local JSON, CSS, tokens, or text file and let the detection summary confirm what will be imported.

1. 1

   Choose Start a new system.

2. 2

   Select Choose local file and pick the palette file.

3. 3

   Confirm the detected format, color count, aliases, ignored values, and sample paths.

4. 4

   Select Import detected colors.

5. 5

   The first detected literal color becomes the canonical brand color; remaining colors are preserved as imported tokens.

6. 6

   Review semantic mappings because a palette alone cannot know which color should be used for every UI role.

{
  "name": "Product palette",
  "colors": [
    { "name": "Brand", "hex": "#2563EB" },
    { "name": "Accent", "hex": "#0F766E" },
    { "name": "Canvas", "hex": "#F8FAFC" },
    { "name": "Text", "hex": "#0F172A" }
  ]
}

Review the workspace in a safe order

Each tab answers a different engineering question.

Treat scores as review signals, not certification

A high score means the implemented checks passed; it does not prove every screen is accessible.

The Doctor can measure token resolution, contrast pairings, architecture rules, and expected state coverage. It cannot verify that every exported token is used correctly in every real component.

Test focus behavior, zoom, content changes, responsive layouts, browser rendering, assistive technology, and the final product before release.

Save and export without creating an account

Projects remain browser-first and can be backed up in portable formats.

• Save locally for the current browser.
• Copy a share URL for smaller systems.
• Download a complete system pack for reliable backup.
• Export DTCG JSON, CSS, SCSS, TypeScript, Tailwind CSS, audit evidence, and multi-brand files.
• Keep the project backup when you expect to reopen the full Doctor workspace later.

Troubleshoot common beginner problems

Most import problems are caused by file shape, unsupported values, or choosing the wrong import behavior.

Frequently asked questions

Primary references

These sources support the standards and technical explanations in this guide. Color Pick recommendations and product-specific limitations are identified separately in the article.

1. Design Tokens Format Module 2025.10W3C Design Tokens Community Group
2. Using files from web applicationsMDN Web Docs
3. Understanding Success Criterion 1.4.3: Contrast (Minimum)W3C Web Accessibility Initiative