Token Governance | Prisma Design System

Token Governance - Design System Rules

All rules governing the token system. Anyone creating, modifying, or deleting tokens MUST follow this skill.

How to Use This Skill

This skill is organized in 3 layers:

This file (SKILL.md) - Architecture overview, tier permissions, reference chains, validation checklist. Read this first.
references/ - Deep-dive on sync engine, gap reporting, and tier decision trees. Read only what's relevant.
Automated scripts - Run the DS scripts listed below for machine-checkable compliance.

Quick navigation:

Creating a new token? Read Tier Permissions then Validation Checklist then references/tier-decision-tree.md
Reviewing token changes? Read Reference Chain then Anti-patterns
Debugging sync/drift? Read references/sync-engine-audit.md
Missing token in DS? Read references/gap-reporting.md

1. Token Architecture - Source of Truth

The token system is a layered hierarchy. Each tier has a different level of access control. Lower tiers reference higher tiers - never the reverse. This enforces a single source of truth for every design value, making global changes safe and predictable.

text

design-system/tokens/
+-- primitives/          LOCKED - brand colors + icons only
|   +-- color-palette    (brand: prisma-blue, prisma-red + base alphas)
|   +-- icon-catalog     (icon set definitions)
|   +-- icon             (icon sizing)
|   Spacing, typography, radius, shadow: Tailwind v4 built-in
|   Z-index: tailwind.css @theme block
|   Motion: shared/motion.tokens.json
|
+-- shared/              CONTROLLED - cross-cutting presets
|   +-- type-scale       (heading/body presets, ref primitives)
|   +-- motion-presets   (transition combos, ref primitives)
|   +-- decoration       (effects, ref primitives)
|   +-- focus            (focus ring, ref primitives)
|
+-- modes/               THEME-SCOPED - light/dark color mapping
|   +-- light            (semantic colors, ref primitives/color-palette)
|   +-- dark             (semantic colors, ref primitives/color-palette)
|
+-- themes/              BRAND-SCOPED - brand color overrides
|   +-- prisma           (Prisma brand, ref primitives/color-palette)
|   +-- aurora           (Aurora brand, ref primitives/color-palette)
|
+-- style-modes/         DENSITY - spacing/radius density
|   +-- default          (BASELINE - all others scale from this)
|   +-- compact          (-1 step from default)
|   +-- comfortable      (+1 step from default)
|
+-- styles/              STYLE-SPECIFIC - visual overrides per showcase
    +-- liquid.json      (glass effects, refraction, shimmer)

Component mapping:       NOT A TOKEN TIER - documentation only
    components md/ATOMIC-MAPPING.md  (component to semantic token map)

Why this hierarchy matters: Primitives are the "atoms" of the system - every other token ultimately traces back to them. If you change spacing.4 in primitives, every component, every style-mode, every showcase that references it updates automatically. Breaking this chain (by hardcoding values) defeats the entire purpose of having a token system.

2. Tier Permissions

Each tier has different access controls. Lower tiers are more open because their blast radius is smaller - they only affect specific components or showcases. Higher tiers require human approval because changing them affects the entire system.

Tier	Path	Create?	Why
Primitives	`tokens/primitives/`	NO	Foundation values, system-wide impact. Agent proposes, User decides.
Shared	`tokens/shared/`	NO	Cross-cutting presets. Agent proposes, User decides.
Modes	`tokens/modes/`	LIMITED	Light/dark semantic colors. Only when adding new brand theme, with User approval.
Themes	`tokens/themes/`	LIMITED	Brand colors. Only when onboarding new brand, with User approval.
Style-modes	`tokens/style-modes/`	OK	Density variations. MUST add to all 4 modes when creating.
Styles	`tokens/styles/`	OK	Showcase-specific overrides. MUST reference primitives.

Note: Component tokens (old Tier 7) have been removed. Components now map directly to semantic tokens via ATOMIC-MAPPING.md.

3. Reference Chain

Tokens MUST reference other tokens, NEVER hardcode raw values (outside primitives). This is the backbone of the entire system - it's how a single change propagates everywhere.

text

CORRECT:
"$value": "{spacing.4}"                            ref primitive
"$value": "{border-radius.xl}"                     ref primitive
"$value": "{base.primary}"                         ref semantic (themes)
"$value": "{comp-radius}"                          ref style-mode
"$value": "{duration.fast-2} {easing.standard}"    ref combo

WRONG:
"$value": 16                       raw number outside primitives
"$value": "#3B82F6"                raw color outside primitives
"$value": "0.2s ease-in-out"       raw transition outside primitives

Exceptions (raw values allowed):

primitives/*.json - the ONLY place for raw values (that's their purpose)
$value: 0 - zero doesn't need a token
$value: "transparent" - CSS keyword
$value: "none" - CSS keyword

4. Validation Checklist

Before creating any new token, run through this checklist. It prevents the two most common mistakes: duplicating existing tokens and placing tokens in the wrong tier.

text

1. Which tier does this token belong to?
     (primitives/shared/modes/themes/style-modes/styles)
2. Does an equivalent token already exist? (search primitives first!)
3. Is this shared across components or specific to one?
     Used by >=2 components: shared/ or primitives/
     Used by 1 component: add to ATOMIC-MAPPING.md, use semantic token directly
4. Does the value reference primitives? (MUST ref, not hardcode)
5. Does it have $description? (REQUIRED - future you will thank you)
6. If color: does it have light + dark variants? (REQUIRED)
7. If spacing/sizing: is the value in the current scale?
     If not: ask User before adding to primitives
8. Correct naming convention?
     primitives: category.subcategory (e.g., spacing.4, color.green.500)
     shared: preset-name.variant (e.g., motion-preset.hover)

Need help deciding the tier? Read references/tier-decision-tree.md for the full decision tree with examples.

5. Anti-patterns

These are the most common governance violations. Each has a real cost - from broken token chains to unreachable dark mode bugs.

Anti-pattern	Correct approach	Why it matters
Create primitives without asking	Propose then wait for User confirm	Primitives affect the entire system
Raw value outside `primitives/`	Reference a primitive (or create one first)	Breaks the reference chain, no auto-update
Component token used only once	Use inline ref: `var(--spacing-4)`	Unnecessary abstraction adds maintenance cost
Duplicate token with different name	Find and reuse existing token	Creates confusion about which is canonical
Add color without dark variant	Always add both light + dark	Dark mode breaks silently
Create `--custom-*` outside system	Map into the appropriate tier	Orphan tokens can't be managed
Hardcode fallback in `sync-tokens.js`	Move value into token JSON file	Sync engine should be logic-only, not data

6. Audit Trail

When creating, modifying, or deleting tokens, always document the change. This creates a traceable history that helps debug regressions and understand design decisions.

text

TOKEN CHANGE LOG:
- Action: CREATE / MODIFY / DELETE
- File: tokens/shared/focus.tokens.json
- Token: focus.ring-offset
- Value: "{spacing.0-5}" (ref primitives/spacing)
- Reason: User requested thinner focus offset
- Approved by: User (conversation #xxx)

7. Commands

bash

## Full pipeline (sync, build, review, verify, drift, audit)
node design-system/scripts/pipeline/run-pipeline.js --all

## Sync single showcase only
node design-system/scripts/pipeline/sync-tokens.js showcase-default

## Preview changes without writing
node design-system/scripts/pipeline/sync-tokens.js --dry-run --all

Individual scripts (sync-tokens.js, verify-output.js, lint-css.js) can still be used for debugging. See full list: node design-system/scripts/pipeline/run-pipeline.js --help

Reference Files

File	Contents	Read when...
sync-engine-audit.md	Sync architecture, drift detection, unified engine rules	Debugging sync issues, understanding token to CSS pipeline
gap-reporting.md	Gap report format, severity levels, workaround protocol	DS is missing a needed token, reporting gaps to User
tier-decision-tree.md	Decision tree for tier placement, mapping examples	Unsure which tier a new token belongs to