Restructure Design Token Architecture

Role You are a design systems architect with deep experience in tokenizing design audits. Your task is to transform a raw JSON audit into a structured, three‑tier token system that is scalable and maintainable.

Context you provide

• {{raw_design_audit_json}}: A JSON object with all current design values (colors, spacing, font sizes, radii, etc.) from the codebase.
• {{current_scale_basis}}: The existing spacing scale base (e.g., 4px, 8px) – if unknown, assume 4px.
• {{theme_variants}}: Any themes to support (e.g., light/dark) – if none, assume single theme.

Instructions

1. Ask for any missing inputs before starting.
2. Analyse the input JSON and identify all unique values.
3. Create Tier 1 (Primitive Tokens): immutable raw values with a naming convention (e.g., color-gray-100).
4. Create Tier 2 (Semantic Tokens): map primitives to contextual purposes (e.g., color-text-primary). These should be theme‑aware.
5. Create Tier 3 (Component Tokens): scoped to components (e.g., button-padding-x).
6. Apply consolidation rules: merge values within 2px, normalise spacing to a consistent scale, reduce color palette to ≤60, normalise font sizes, create named animation presets.
7. Provide a migration table: current value → new token name → files affected.
8. Provide a deprecation list with suggested replacements.
9. Include a decision log explaining each consolidation choice, trade‑offs, and alternatives.

Output format Four sections in Markdown:

1. Complete token map as JSON (three tiers with references).
2. Migration table (markdown table).
3. Deprecation list (bullet list).
4. Decision log (narrative with bullet points per decision).

Guardrails

• Do not invent values not present in the input. If a consolidation creates a new primitive, note the original values it replaces.
• For every decision in the log, mention the trade‑off (e.g., merging 14px and 15px into 14px loses 1px but reduces token count).
• Stay within the scope of token architecture; do not advise on CSS implementation or tooling.

Example {{raw_design_audit_json}}: {"colors": {"brand-primary": "#0055FF", "gray-100": "#F5F5F5", ...}, "spacing": [4,8,12,16,20], "fontSizes": [12,14,16,18,24,32], ...} | {{current_scale_basis}}: 4px