Semantic Color Mapping

Map primitive color values to semantic design tokens with clear intent, usage rules, and accessibility notes.

All Prompts

When to Use

  • Building the semantic layer on top of existing primitive colors
  • Documenting why specific colors were chosen for specific roles
  • Onboarding new designers or engineers to the token system
  • Auditing whether semantic tokens cover all UI needs

The Prompt

Map these primitive colors to a complete set of semantic design tokens.

For each semantic token, provide:
1. **Token name** — following the pattern: color.[category].[role].[state]
2. **Primitive reference** — which primitive it aliases (e.g., blue-600)
3. **Hex value** — resolved value
4. **Intent** — what it communicates to the user
5. **Where to use** — specific UI elements
6. **Where NOT to use** — common misuse

Categories to cover:
- background (primary, secondary, elevated, inverse, brand, overlay)
- text (primary, secondary, disabled, inverse, link, on-brand)
- border (default, strong, focus, error)
- status (success, warning, danger, info — each with bg, text, border, icon variants)
- interactive (default, hover, active, disabled — for clickable elements)

Flag any gaps where a primitive doesn't exist for a needed semantic role.

Here are my primitives:
[paste your primitive color tokens]

Example Output

## Background Tokens

| Semantic Token              | Primitive  | Hex     | Intent                | Use                    |
|-----------------------------|------------|---------|-----------------------|------------------------|
| color.background.primary    | white      | #FFFFFF | Default page surface  | Page bg, card bg       |
| color.background.secondary  | gray-50    | #F8FAFC | Subtle separation     | Sidebar, table stripe  |
| color.background.elevated   | white      | #FFFFFF | Raised surface        | Modals, dropdowns      |
| color.background.brand      | blue-600   | #2563EB | Brand emphasis        | Hero, CTA sections     |
| color.background.inverse    | gray-900   | #0F172A | High contrast flip    | Tooltips, toasts       |

## Status Tokens

| Semantic Token              | Primitive   | Hex     | Use                         |
|-----------------------------|-------------|---------|-----------------------------|
| color.status.success.bg     | green-50    | #F0FDF4 | Success banner background   |
| color.status.success.text   | green-700   | #15803D | Success message text        |
| color.status.success.border | green-200   | #BBF7D0 | Success banner border       |
| color.status.success.icon   | green-500   | #22C55E | Success icon fill           |

## Gaps Found

- No primitive exists for a "warning" orange in the 50-100 range.
  Needed for: color.status.warning.bg
  Suggestion: Add orange-50 (#FFF7ED) to primitives.

- No dark brand color for text-on-brand.
  Needed for: color.text.on-brand
  Suggestion: Use white (#FFFFFF) if brand bg is blue-600 (contrast: 8.6:1).