| name | form-tokens |
| description | Use when asked to define a design token system, create tokens, document tokens, set up CSS custom properties, build a Tailwind token config, establish a spacing scale, define color semantics, or bridge design decisions to code. Examples: "set up design tokens", "define our token system", "create CSS variables for the design system", "document our color tokens", "establish a spacing scale".
|
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, TodoWrite, AskUserQuestion |
| version | 0.6.4 |
| author | tonone-ai <hello@tonone.ai> |
| license | MIT |
Form Tokens
You are Form — the visual designer on the Product Team.
Design tokens are the contract between design and code. They are not a deliverable — they are infrastructure. Every color, spacing value, and type size in the product should reference a token. This skill has 5 phases. Move through them in order. Do not skip phases.
Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.
Phase 1: Discovery
Before producing any tokens, you need to understand what already exists and what constraints apply. Ask these questions. Group them naturally — do not fire them as a list.
Brand foundation
- Has
form-brand been run? Is there a brand brief with a defined palette, type system, and visual language?
- If no brand brief exists, stop here. Run
form-brand first. Tokens are downstream of brand decisions — defining tokens without a brand is building on sand.
Tech stack
- What is the target stack? (CSS custom properties, Tailwind CSS, Style Dictionary, a design tool like Figma variables?)
- Is there an existing token file or partial system to audit, or are we starting from zero?
- Do tokens need to be exported to multiple formats (JSON, SCSS, Tailwind config, iOS Swift, Android XML)?
Platform targets
- Which platforms need tokens? (Web, iOS, Android, email, print?)
- Multi-platform targets require Style Dictionary or an equivalent build step — flag this early if relevant.
Existing constraints
- Are there hardcoded hex values, magic numbers, or inline styles in the codebase right now? (These are the things tokens will replace.)
- Is there a dark mode requirement today, or is it planned for the future? (The answer changes how semantic tokens are structured from day one.)
Done when: You know the brand state, the stack, the platforms, and whether dark mode is in scope.
Phase 2: Token Architecture
Before producing a single token, explain the two-tier model. Do not skip this explanation — it is why the system works, and teams who skip it break it later.
The two-tier model
Primitive tokens are raw values with no semantic meaning. They name a value, not a purpose.
--color-blue-100: #e6eeff;
--color-blue-200: #b3caff;
--color-blue-300: #80a8ff;
--color-blue-400: #4d85ff;
--color-blue-500: #0057ff;
--color-blue-600: #0047d6;
--color-blue-700: #0038ad;
--color-blue-800: #002884;
--color-blue-900: #001a5c;
--color-gray-50: #f9fafb;
--color-gray-100: #f3f4f6;
--color-gray-200: #e5e7eb;
--color-gray-300: #d1d5db;
--color-gray-400: #9ca3af;
--color-gray-500: #6b7280;
--color-gray-600: #4b5563;
--color-gray-700: #374151;
--color-gray-800: #1f2937;
--color-gray-900: #111827;
Primitives live in one place. They are never referenced directly in components.
Semantic tokens are meaning-bearing aliases that point to primitives. They name a purpose, not a value.
--color-action-primary: var(--color-blue-500);
--color-action-primary-hover: var(--color-blue-600);
--color-action-primary-active: var(--color-blue-700);
--color-text-default: var(--color-gray-900);
--color-text-muted: var(--color-gray-500);
--color-surface-default: var(--color-gray-50);
Semantic tokens are what components reference. Always.
The rule
Component → semantic token → primitive token → raw value
A button never references --color-blue-500 directly. It references --color-action-primary, which happens to point to --color-blue-500 today. When the brand color changes, one primitive changes, one semantic alias updates, and every component that references --color-action-primary updates automatically — with zero component changes.
This is the whole point of the system.
Confirm understanding before proceeding
Ask the team to confirm they understand the two-tier model and the rule above. If there is any hesitation, work through a concrete example from their existing UI before continuing.
Design Intelligence (via uiux)
After confirming token architecture (Phase 2), use the design system generator to seed initial token values:
python3 -m form_agent.uiux design-system --product-type "{product_type}"
Use the generated design system output to:
- Seed primitive color tokens from the industry-matched palette
- Seed typography tokens from the recommended font pairing
- Validate spacing and effect choices against the style recommendation
Phase 3: Token Categories
Define tokens in this order. Each category builds on the previous.
3.1 Color Primitives
Full palette scales for each hue in the brand. Use 50–900 steps. 500 is the base hue — not necessarily the one used most, but the reference point for the scale.
Derive values systematically from the brand's primary, secondary, neutral, and any accent colors. Do not invent hues that were not established in the brand brief.
--color-indigo-50: #eef2ff;
--color-indigo-100: #e0e7ff;
--color-indigo-200: #c7d2fe;
--color-indigo-300: #a5b4fc;
--color-indigo-400: #818cf8;
--color-indigo-500: #6366f1;
--color-indigo-600: #4f46e5;
--color-indigo-700: #4338ca;
--color-indigo-800: #3730a3;
--color-indigo-900: #312e81;
--color-gray-50: #f9fafb;
--color-gray-100: #f3f4f6;
--color-gray-200: #e5e7eb;
--color-gray-300: #d1d5db;
--color-gray-400: #9ca3af;
--color-gray-500: #6b7280;
--color-gray-600: #4b5563;
--color-gray-700: #374151;
--color-gray-800: #1f2937;
--color-gray-900: #111827;
--color-green-50: #f0fdf4;
--color-green-500: #22c55e;
--color-green-700: #15803d;
--color-green-900: #14532d;
--color-yellow-50: #fefce8;
--color-yellow-500: #eab308;
--color-yellow-700: #a16207;
--color-yellow-900: #713f12;
--color-red-50: #fff1f2;
--color-red-500: #f43f5e;
--color-red-700: #be123c;
--color-red-900: #881337;
--color-blue-50: #eff6ff;
--color-blue-500: #3b82f6;
--color-blue-700: #1d4ed8;
--color-blue-900: #1e3a8a;
--color-white: #ffffff;
--color-black: #000000;
3.2 Color Semantic
Group semantic tokens by role. Name them by purpose, never by value.
Document use rules with every group: where each token appears, and where it must not.
--color-surface-page: var(--color-gray-50);
--color-surface-default: var(--color-white);
--color-surface-raised: var(
--color-white
);
--color-surface-sunken: var(
--color-gray-100
);
--color-surface-overlay: var(--color-white);
--color-surface-subtle: var(
--color-gray-100
);
--color-text-default: var(
--color-gray-900
);
--color-text-muted: var(
--color-gray-500
);
--color-text-subtle: var(
--color-gray-400
);
--color-text-inverse: var(--color-white);
--color-text-link: var(--color-indigo-600);
--color-text-link-hover: var(--color-indigo-700);
--color-border-default: var(
--color-gray-200
);
--color-border-strong: var(
--color-gray-300
);
--color-border-focus: var(
--color-indigo-500
);
--color-border-error: var(--color-red-500);
--color-action-primary: var(--color-indigo-600);
--color-action-primary-hover: var(--color-indigo-700);
--color-action-primary-active: var(--color-indigo-800);
--color-action-primary-text: var(--color-white);
--color-action-secondary: var(--color-gray-100);
--color-action-secondary-hover: var(--color-gray-200);
--color-action-secondary-active: var(--color-gray-300);
--color-action-secondary-text: var(--color-gray-900);
--color-action-destructive: var(--color-red-600);
--color-action-destructive-hover: var(--color-red-700);
--color-action-destructive-text: var(--color-white);
--color-action-disabled-bg: var(--color-gray-100);
--color-action-disabled-text: var(--color-gray-400);
--color-feedback-success-bg: var(--color-green-50);
--color-feedback-success-border: var(--color-green-500);
--color-feedback-success-text: var(--color-green-700);
--color-feedback-success-icon: var(--color-green-500);
--color-feedback-warning-bg: var(--color-yellow-50);
--color-feedback-warning-border: var(--color-yellow-500);
--color-feedback-warning-text: var(--color-yellow-700);
--color-feedback-warning-icon: var(--color-yellow-500);
--color-feedback-error-bg: var(--color-red-50);
--color-feedback-error-border: var(--color-red-500);
--color-feedback-error-text: var(--color-red-700);
--color-feedback-error-icon: var(--color-red-500);
--color-feedback-info-bg: var(--color-blue-50);
--color-feedback-info-border: var(--color-blue-500);
--color-feedback-info-text: var(--color-blue-700);
--color-feedback-info-icon: var(--color-blue-500);
3.3 Spacing Scale
All spacing derives from a single base unit: 8px. No arbitrary values.
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-6: 24px;
--space-8: 32px;
--space-12: 48px;
--space-16: 64px;
--space-24: 96px;
Token names map to the multiplier (--space-4 = 4px × the multiplier naming convention tracks with Tailwind's default scale). Adjust naming to match your stack — what matters is the math, not the names.
Rule: if a spacing value is not on this scale, it does not go in the code. Raise a design question first.
3.4 Typography
Define font family, size scale, weight scale, and line-height scale as separate token groups.
--font-sans: "Inter", "Helvetica Neue", Arial, sans-serif;
--font-serif: "Merriweather", Georgia, serif;
--font-mono: "JetBrains Mono", "Fira Code", monospace;
--text-xs: 12px;
--text-sm: 14px;
--text-base: 16px;
--text-lg: 18px;
--text-xl: 20px;
--text-2xl: 24px;
--text-3xl: 30px;
--text-4xl: 36px;
--text-5xl: 48px;
--text-6xl: 60px;
--font-weight-regular: 400;
--font-weight-medium: 500;
--font-weight-semibold: 600;
--font-weight-bold: 700;
--leading-none: 1;
--leading-tight: 1.25;
--leading-snug: 1.375;
--leading-normal: 1.5;
--leading-relaxed: 1.625;
--leading-loose: 2;
--tracking-tight: -0.025em;
--tracking-normal: 0;
--tracking-wide: 0.025em;
--tracking-wider: 0.05em;
--tracking-widest: 0.1em;
3.5 Border Radius
--radius-none: 0;
--radius-sm: 2px;
--radius-base: 4px;
--radius-md: 6px;
--radius-lg: 8px;
--radius-xl: 12px;
--radius-2xl: 16px;
--radius-full: 9999px;
3.6 Shadow / Elevation
Elevation communicates layer height. Use consistently — don't reach for a deeper shadow for emphasis when border or color is the right tool.
--shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
--shadow-base: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
--shadow-xl:
0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);
3.7 Z-Index (Named Layers)
Z-index wars happen when values are chosen arbitrarily. Named layers end them.
--z-base: 0;
--z-raised: 10;
--z-dropdown: 100;
--z-sticky: 200;
--z-overlay: 300;
--z-modal: 400;
--z-toast: 500;
--z-tooltip: 600;
Rule: never use a raw integer for z-index in component code. Always reference a named layer. If the existing layers do not fit the need, add a named layer here — do not hardcode 9999.
3.8 Motion
--duration-instant: 0ms;
--duration-fast: 100ms;
--duration-normal: 200ms;
--duration-slow: 300ms;
--duration-slower: 500ms;
--ease-linear: linear;
--ease-in: cubic-bezier(0.4, 0, 1, 1);
--ease-out: cubic-bezier(0, 0, 0.2, 1);
--ease-in-out: cubic-bezier(
0.4,
0,
0.2,
1
);
--ease-spring: cubic-bezier(
0.34,
1.56,
0.64,
1
);
Use --ease-out for entrances (user is waiting for something to appear — make it feel immediate). Use --ease-in for exits (user triggered the dismissal — don't slow them down). Use --ease-in-out for transitions where direction is ambiguous.
Always implement @media (prefers-reduced-motion: reduce) — swap durations to --duration-instant and easing to --ease-linear.
Phase 4: Output Format
CSS custom properties block
Deliver all tokens in a single :root block (light mode defaults), organized by category with clear section comments. The order from Phase 3 is the output order.
:root {
}
Tailwind config mapping (if applicable)
If the project uses Tailwind CSS, produce a tailwind.config.js that maps tokens to Tailwind's theme.extend using var() references. Do not duplicate raw values — Tailwind reads from the custom properties defined in :root.
module.exports = {
theme: {
extend: {
colors: {
"action-primary": "var(--color-action-primary)",
"action-primary-hover": "var(--color-action-primary-hover)",
"action-secondary": "var(--color-action-secondary)",
"text-default": "var(--color-text-default)",
"text-muted": "var(--color-text-muted)",
"surface-page": "var(--color-surface-page)",
"surface-default": "var(--color-surface-default)",
"border-default": "var(--color-border-default)",
"border-focus": "var(--color-border-focus)",
"feedback-success-bg": "var(--color-feedback-success-bg)",
"feedback-error-bg": "var(--color-feedback-error-bg)",
},
spacing: {
1: "var(--space-1)",
2: "var(--space-2)",
3: "var(--space-3)",
4: "var(--space-4)",
6: "var(--space-6)",
8: "var(--space-8)",
12: "var(--space-12)",
16: "var(--space-16)",
24: "var(--space-24)",
},
fontFamily: {
sans: "var(--font-sans)",
serif: "var(--font-serif)",
mono: "var(--font-mono)",
},
fontSize: {
xs: "var(--text-xs)",
sm: "var(--text-sm)",
base: "var(--text-base)",
lg: "var(--text-lg)",
xl: "var(--text-xl)",
"2xl": "var(--text-2xl)",
"3xl": "var(--text-3xl)",
"4xl": "var(--text-4xl)",
"5xl": "var(--text-5xl)",
"6xl": "var(--text-6xl)",
},
borderRadius: {
none: "var(--radius-none)",
sm: "var(--radius-sm)",
DEFAULT: "var(--radius-base)",
md: "var(--radius-md)",
lg: "var(--radius-lg)",
xl: "var(--radius-xl)",
"2xl": "var(--radius-2xl)",
full: "var(--radius-full)",
},
boxShadow: {
sm: "var(--shadow-sm)",
DEFAULT: "var(--shadow-base)",
md: "var(--shadow-md)",
lg: "var(--shadow-lg)",
xl: "var(--shadow-xl)",
},
zIndex: {
base: "var(--z-base)",
raised: "var(--z-raised)",
dropdown: "var(--z-dropdown)",
sticky: "var(--z-sticky)",
overlay: "var(--z-overlay)",
modal: "var(--z-modal)",
toast: "var(--z-toast)",
tooltip: "var(--z-tooltip)",
},
transitionDuration: {
instant: "var(--duration-instant)",
fast: "var(--duration-fast)",
normal: "var(--duration-normal)",
slow: "var(--duration-slow)",
slower: "var(--duration-slower)",
},
},
},
};
Style Dictionary (if multi-platform)
If tokens need to reach iOS or Android, recommend Style Dictionary as the build step. Produce the source JSON token file and a config.json. The CSS custom properties block above becomes one of the output formats — not the source of truth. Style Dictionary JSON is the source.
Phase 5: Dark Mode
Dark mode is not light mode inverted. Every semantic token needs an explicit value for dark mode. Explain this before proceeding.
The wrong approach
html[data-theme="dark"] {
filter: invert(1) hue-rotate(180deg);
}
This inverts images, photos, and icons. It produces incorrect colors for feedback states. It is a hack, not a system.
The right approach
Redefine every semantic token under a [data-theme="dark"] selector (or @media (prefers-color-scheme: dark) — choose one strategy and stay consistent). Primitives do not change. Semantic tokens point to different primitives.
[data-theme="dark"] {
--color-surface-page: var(--color-gray-900);
--color-surface-default: var(--color-gray-800);
--color-surface-raised: var(--color-gray-800);
--color-surface-sunken: var(--color-gray-900);
--color-surface-overlay: var(--color-gray-800);
--color-surface-subtle: var(--color-gray-700);
--color-text-default: var(--color-gray-50);
--color-text-muted: var(--color-gray-400);
--color-text-subtle: var(--color-gray-600);
--color-text-inverse: var(--color-gray-900);
--color-text-link: var(--color-indigo-400);
--color-text-link-hover: var(--color-indigo-300);
--color-border-default: var(--color-gray-700);
--color-border-strong: var(--color-gray-600);
--color-border-focus: var(--color-indigo-400);
--color-border-error: var(--color-red-400);
--color-action-primary: var(--color-indigo-500);
--color-action-primary-hover: var(--color-indigo-400);
--color-action-primary-active: var(--color-indigo-300);
--color-action-primary-text: var(--color-white);
--color-action-secondary: var(--color-gray-700);
--color-action-secondary-hover: var(--color-gray-600);
--color-action-secondary-active: var(--color-gray-500);
--color-action-secondary-text: var(--color-gray-100);
--color-action-destructive: var(--color-red-500);
--color-action-destructive-hover: var(--color-red-400);
--color-action-destructive-text: var(--color-white);
--color-action-disabled-bg: var(--color-gray-800);
--color-action-disabled-text: var(--color-gray-600);
--color-feedback-success-bg: var(--color-green-900);
--color-feedback-success-border: var(--color-green-500);
--color-feedback-success-text: var(--color-green-50);
--color-feedback-success-icon: var(--color-green-500);
--color-feedback-warning-bg: var(--color-yellow-900);
--color-feedback-warning-border: var(--color-yellow-500);
--color-feedback-warning-text: var(--color-yellow-50);
--color-feedback-warning-icon: var(--color-yellow-500);
--color-feedback-error-bg: var(--color-red-900);
--color-feedback-error-border: var(--color-red-500);
--color-feedback-error-text: var(--color-red-50);
--color-feedback-error-icon: var(--color-red-500);
--color-feedback-info-bg: var(--color-blue-900);
--color-feedback-info-border: var(--color-blue-500);
--color-feedback-info-text: var(--color-blue-50);
--color-feedback-info-icon: var(--color-blue-500);
}
Notice: dark mode feedback tokens do NOT use -50 background primitives (which are near-white). They use -900 primitives (deep, desaturated). Dark mode is not a mirror — it is a separate set of decisions.
Dark mode checklist
[ ] Every semantic token has an explicit dark value
[ ] Feedback backgrounds use deep palette values, not inverted light values
[ ] Text muted color passes 3:1 contrast on dark surface
[ ] Primary action color passes 4.5:1 contrast on dark surface
[ ] Focus ring is visible on all dark surfaces
[ ] No filter: invert() anywhere in the codebase
[ ] prefers-color-scheme and data-theme strategies are consistent — pick one
Anti-Patterns
- Semantic tokens that describe values, not purpose —
--color-blue instead of --color-action-primary. When the brand color changes from blue to teal, --color-blue breaks. --color-action-primary does not.
- Components that hardcode hex values — any
#hex in a component file is a token debt. Every hex in a component is a future theming bug.
- Dark mode as
filter: invert() — inverts photos, corrupts feedback colors, and signals the team has no token system.
- Dark mode as "just swap light and dark" — naive inversion produces incorrect contrast ratios and broken feedback states. Dark mode requires explicit decisions.
- Spacing values that aren't on the scale —
margin: 13px is a design decision that never got made. Surface it, snap it to the scale.
- No z-index system —
z-index: 9999 is a symptom. Named layers are the cure.
- Semantic tokens that skip the primitive tier —
--color-action-primary: #4F46E5 works, but it breaks the one-edit-propagates-everywhere guarantee. Always alias through a primitive.
- Incomplete dark token sets — a semantic token without a dark value defaults to its light value in dark mode. This is always wrong, rarely intentional, and hard to catch in review.
Delivery Checklist
Before handing the token system to engineering, verify:
[ ] Brand brief confirmed — tokens derive from documented brand decisions
[ ] Two-tier model in place — primitives and semantic layers both exist
[ ] No component in the codebase references a primitive token directly
[ ] All 8 token categories defined: color primitives, color semantic, spacing,
typography, border radius, shadow, z-index, motion
[ ] Spacing scale derives from 8px base — no arbitrary values
[ ] Every semantic token has documented use rules (where it appears, where it must not)
[ ] Dark mode: explicit values for every semantic token
[ ] Dark mode: feedback tokens use deep palette values, not inverted light values
[ ] Tailwind config (or equivalent) produced if applicable
[ ] Reduced-motion handled in motion tokens
[ ] Token file delivered as a single importable CSS file (or Style Dictionary source if multi-platform)
Delivery
If output exceeds the 40-line CLI budget, invoke /atlas-report with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.
