How to Import an Existing Color Palette into Design System Doctor

Use one of the supported palette structures

The importer recognizes common files instead of requiring one proprietary schema.

• Color Pick palette JSON with palette or colors arrays
• A raw JSON array of CSS colors
• Objects containing name plus hex, color, value, or $value
• Design System Doctor project backups with a tokens array
• DTCG typed color values and aliases
• Tokens Studio or Style Dictionary-style value objects
• Tailwind theme.extend.colors objects
• CSS custom properties and var() references
• Named lines such as Primary: #2563EB
• HEX, RGB, HSL, OKLCH, Display-P3, and named CSS colors when the browser color parser supports them

Use a named colors array for the simplest palette file

Names improve imported token paths and make the next review easier.

{
  "name": "My product palette",
  "colors": [
    { "name": "Primary", "hex": "#2563EB" },
    { "name": "Secondary", "hex": "#7C3AED" },
    { "name": "Success", "hex": "#0F766E" },
    { "name": "Warning", "hex": "#D97706" },
    { "name": "Canvas", "hex": "#F8FAFC" },
    { "name": "Text", "hex": "#0F172A" }
  ]
}

Upload and import the file step by step

The file is loaded first and imported only after you review the detection summary.

1. 1

   Open Design System Doctor and stay on Build & themes.

2. 2

   Select Start a new system for a standalone palette or Merge into current system for deliberate token updates.

3. 3

   Select Choose local file and choose a JSON, tokens, CSS, or TXT file smaller than 1.5 MB.

4. 4

   Review Detected format, Color values, Aliases, Ignored values, and Sample paths.

5. 5

   If the counts look correct, select Import detected colors.

6. 6

   Review the canonical brand color and generated product preview.

7. 7

   Open Architecture Linter to identify raw semantic values, duplicate colors, missing ownership, or layer problems.

8. 8

   Map product roles, run repair evidence, check state coverage, and export a project backup.

Understand how imported colors are mapped

A palette supplies colors, but it does not always supply product meaning.

Import files exported by other Color Pick tools

The enhanced importer recognizes several existing Color Pick JSON shapes.

• Color Picker JSON containing baseColor and palette
• Image Color Picker JSON containing colors
• Palette Readiness reports containing palette items
• Semantic UI exports containing tokens or colors with value fields
• Context Role Mapper exports containing named role colors
• Local Color Pick projects containing palette and roles
• Design System Doctor project backups containing tokens, themes, constraints, and custom rules

Fix “No supported color tokens were found”

The old message usually meant the JSON was valid but its colors were stored in a shape the parser did not traverse.

The updated importer traverses arrays, nested palette objects, common value fields, Color Pick exports, Tailwind colors, and project token arrays. It also shows a detection summary before import instead of returning only a generic error.

If zero colors are still detected, confirm that actual color values exist as strings or DTCG color objects. Image URLs, palette names, IDs, CMYK-only numeric objects, screenshots, and arbitrary metadata are not automatically converted into web color values.

Keep the local-processing guarantee in context

The importer reads the selected file in the browser and does not need a token upload endpoint.

Normal site requests such as analytics, consent, advertising, fonts, or page assets are separate from token-file processing. The token importer does not intentionally send the selected filename or token contents to those services.

Imported names and mappings should still be reviewed. A parser can identify color values and aliases, but it cannot know your brand governance, product intent, legal requirements, or every component implementation.

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. CSS Color Module Level 4W3C