Skip to main content
Prompts Design Audit JSON to Token Architect

developer analysis template risk: low

Design Audit JSON to Token Architect

Transforms raw design audit JSON from a codebase into a structured 3-tier token system with primitive, semantic, and component tokens following consolidation rules. Outputs a compl…

PROMPT 

You are a design systems architect. I'm providing you with a raw design audit JSON from an existing codebase. Your job is to transform this chaos into a structured token architecture.

## Input
[Paste the Phase 1 JSON output here, or reference the file]

## Token Hierarchy

Design a 3-tier token system:

### Tier 1 — Primitive Tokens (raw values)
Named, immutable values. No semantic meaning.
- Colors: `color-gray-100`, `color-blue-500`
- Spacing: `space-1` through `space-N`
- Font sizes: `font-size-xs` through `font-size-4xl`
- Radii: `radius-sm`, `radius-md`, `radius-lg`

### Tier 2 — Semantic Tokens (contextual meaning)
Map primitives to purpose. These change between themes.
- `color-text-primary` → `color-gray-900`
- `color-bg-surface` → `color-white`
- `color-border-default` → `color-gray-200`
- `spacing-section` → `space-16`
- `font-heading` → `font-size-2xl` + `font-weight-bold` + `line-height-tight`

### Tier 3 — Component Tokens (scoped to components)
- `button-padding-x` → `spacing-4`
- `button-bg-primary` → `color-brand-500`
- `card-radius` → `radius-lg`
- `input-border-color` → `color-border-default`

## Consolidation Rules
1. Merge values within 2px of each other (e.g., 14px and 15px → pick one, note which)
2. Establish a consistent spacing scale (4px base recommended, flag deviations)
3. Reduce color palette to ≤60 total tokens (flag what to deprecate)
4. Normalize font size scale to a logical progression
5. Create named animation presets from one-off values

## Output Format

Provide:
1. **Complete token map** in JSON — all three tiers with references
2. **Migration table** — current value → new token name → which files use it
3. **Deprecation list** — values to remove with suggested replacements
4. **Decision log** — every judgment call you made (why you merged X into Y, etc.)

For each decision, explain the trade-off. I may disagree with your consolidation
choices, so transparency matters more than confidence.

INPUTS

phase1_json REQUIRED

Paste the Phase 1 JSON output or file reference

REQUIRED CONTEXT

  • raw design audit JSON

ROLES & RULES

Role assignments

  • You are a design systems architect.
  1. Merge values within 2px of each other (e.g., 14px and 15px → pick one, note which)
  2. Establish a consistent spacing scale (4px base recommended, flag deviations)
  3. Reduce color palette to ≤60 total tokens (flag what to deprecate)
  4. Normalize font size scale to a logical progression
  5. Create named animation presets from one-off values

EXPECTED OUTPUT

Format
markdown
Schema
markdown_sections · Complete token map, Migration table, Deprecation list, Decision log
Constraints
  • Complete token map in JSON — all three tiers with references
  • Migration table — current value → new token name → which files use it
  • Deprecation list — values to remove with suggested replacements
  • Decision log — every judgment call with trade-offs

SUCCESS CRITERIA

  • Design a 3-tier token system
  • Transform raw design audit JSON into structured token architecture
  • Follow consolidation rules
  • Provide complete token map in JSON with all three tiers
  • Provide migration table
  • Provide deprecation list
  • Provide decision log with explanations and trade-offs

FAILURE MODES

  • May make consolidation decisions without transparency
  • May fail to reference or depend on input JSON
  • May not flag deviations or deprecations properly
  • May create tokens without semantic hierarchy

CAVEATS

Dependencies
  • raw design audit JSON
  • Phase 1 JSON output
Missing context
  • Structure/format of the raw design audit JSON.
  • How to obtain file usage data for migration table.
  • Theme details or examples.
Ambiguities
  • 'Phase 1 JSON output' assumes prior context without description.
  • Unclear if ≤60 total tokens applies to primitives, all tiers, or colors only.
  • Migration table requires 'which files use it' but input is JSON only, no file info specified.

QUALITY

OVERALL
0.90
CLARITY
0.90
SPECIFICITY
0.95
REUSABILITY
0.90
COMPLETENESS
0.85

IMPROVEMENT SUGGESTIONS

  • Define the expected structure of the input JSON with an example.
  • Specify data sources for file usage in migration table or note assumptions.
  • Add JSON schema for the 'Complete token map' output.
  • Clarify '≤60 total tokens' scope (colors only? all primitives?).
  • Provide a sample spacing scale (e.g., 4,8,12,16,...).

USAGE

Copy the prompt above and paste it into your AI of choice — Claude, ChatGPT, Gemini, or anywhere else you're working. Replace any placeholder sections with your own context, then ask for the output.

MORE FOR DEVELOPER