| skill_id | nezam-design-tokens |
| name | nezam-Design Token Architecture |
| tier | 3 |
| description | W3C-style design tokens, theme switching, fluid typography, and spacing matrices — the design-system core contract. Includes system build and frontend integration workflows. |
| version | 2.0.0 |
| updated | "2026-06-04T00:00:00.000Z" |
| changelog | [{"version":"2.0.0","date":"2026-06-04T00:00:00.000Z","notes":"Merged full workflow, anti-patterns, external references, System Build Mode, and Frontend Integration Mode from legacy design-tokens skill."},{"version":"1.0.0","date":"2026-05-12T00:00:00.000Z","notes":"Initial stub — hierarchy definition, naming governance, multi-platform strategy."}] |
Design Token Architecture Skill
Purpose
Build deterministic token manifests, theme scopes, and CSS-variable exports that satisfy token-first gates before /DEVELOP. Covers the full stack: token hierarchy governance, system build contracts, and frontend integration direction.
Inputs
- Repository root
DESIGN.md sections: Visual Theme, Color Roles, Typography, Layout, Components.
- Existing token drafts (if any) under
.nezam/core/plans/05-design/.
- SEO/IA constraints affecting content density and hierarchy.
- A11y contrast requirements from
@.cursor/skills/nezam-a11y-automation/SKILL.md.
Procedure
1. Hierarchy Definition
- Primitive Tokens (Base): Raw values (
blue-500, spacing-16). No semantic meaning.
- Semantic Tokens (Alias): Meaningful names (
action-primary-bg, surface-default-padding).
- Component Tokens (Override): Component-specific (
button-primary-shadow, input-border-focus).
2. Naming Governance
- Follow
[Category]-[Property]-[Concept]-[Variant]-[State].
- Example:
color-background-primary-hover.
- Enforce lowercase hyphenated strings. Every semantic token must map to a primitive.
3. Multi-Platform Strategy
- CSS Variables for Web.
- XML/JSON for Android/iOS.
- Inline styles/table-constants for Email.
- Single source of truth:
tokens.json → platform targets via Style Dictionary or Tokens Studio.
4. Step-by-Step Workflow
- Parse semantic roles (
bg, fg, accent, danger, surface-*, border-*) and map to base palettes; document base ↔ semantic ↔ component-alias tiers.
- Create token groups in W3C-format JSON:
color, spacing, radius, elevation, zIndex, typography, motion, breakpoint.
- Define fluid typography tokens with
clamp(min, preferred, max) for display, h1–h6, body, label, caption tiers; emit line-height + tracking pairs.
- Produce breakpoint and container tokens:
mobile → tablet → desktop → wide.
- Define theme scopes:
:root (light), [data-theme='dark'], optional prefers-color-scheme mirror; ensure swap is paint-only (no layout shift).
- Export CSS variables (
tokens.css) and platform manifests (Style Dictionary, Theo, or Tokens Studio export).
- Component aliases (
--surface-card, --text-muted) protect components from base-token churn.
- Add token drift checks: lint hardcoded
px, rem, hex outside the token sources.
Output Artifacts
tokens/base.json (raw scales) and tokens/semantic.json (usage semantics).css/tokens.css (:root + theme scopes + dark mode)..nezam/core/plans/05-design/TOKEN_NAMING_CONVENTION.md: naming rulebook..nezam/core/plans/05-design/PLATFORM_MAPPING.yaml: cross-platform token map.- Updated root
DESIGN.md reflecting the architectural tiers.
- Token drift checklist (pass/fail).
- Theme switch behavior memo (FOUC prevention strategy).
Validation & Metrics
- Zero hardcoded
px/rem/hex outside approved token sources.
- Typography scales use
clamp() for primary roles.
- Theme switching does not cause CLS; FOUC prevented.
- Contrast pairings (token × token) satisfy WCAG 2.2 AA (4.5:1 / 3:1).
- Token traceability to
DESIGN.md maintained (round-trip identifiable).
- Every semantic token maps to a primitive.
- Naming follows
[Category]-[Property]-[Concept]-[Variant]-[State].
- Platform mapping covers all targets in the PRD.
Anti-Patterns
- Hardcoded hex/px/rem in component styles.
- Single semantic name reused across conflicting roles.
- Theme variables overridden inline at component level.
- Token JSON not exported to platform-native targets.
- Adding a new base token without updating semantic + component alias tiers.
Integration Hooks
/PLAN design for token planning./DEVELOP only after token validation passes./SCAN code a11y perf during hardening.- Pairs with
@.cursor/skills/design/token-grid-typography/SKILL.md, @.cursor/skills/design/nezam-component-library-api/SKILL.md, @.cursor/skills/design/nezam-motion-3d/SKILL.md.
- Enforces
[.cursor/rules/design-gates.mdc](.cursor/rules/design-gates.mdc) Gate 1.
External References
System Build Mode
Use during /PLAN system or any design-system alignment pass before /DEVELOP.
Create a governed design-system contract that implementation teams can follow without design drift.
Output artifacts
Create or update:
.nezam/core/plans/05-design/UI_FOUNDATION.md.nezam/core/plans/05-design/tokens.css.nezam/core/plans/05-design/TOKEN_NAMING.md.nezam/core/plans/05-design/COMPONENT_BLUEPRINT.md
Include:
- Token taxonomy — color (semantic roles), typography (roles + clamp strategy), spacing, radius, elevation, z-index.
- Theme model — light or dark mapping, contrast targets (WCAG 2.2 AA minimum), CSS-variable-first theming with
prefers-color-scheme baseline.
- Component primitives — canonical naming; variant and state conventions; CVA-friendly typed APIs with
className passthrough; direction-aware (dir) composition and logical CSS guidance.
- Motion hooks — approved easing or timing primitives; reduced-motion contract.
- Implementation constraints — no hardcoded primitives outside token sources.
Output structure reference
token_sets:
- colors
- typography
- spacing
themes:
- light
- dark
component_contracts:
- Button
- Card
compliance:
wcag_level: "2.2 AA"
reduced_motion_required: true
rtl_support_required: true
Core rules
- Token-first always.
- Accessibility is a system requirement, not optional polish.
- Keep naming consistent with existing component architecture.
- Docs must support FE handoff without ambiguity.
Dependencies
Pairs with nezam-wireframe-to-spec, token-grid-typography, nezam-css-architecture.
Frontend Integration Mode
Use during /PLAN design or any visual refinement pass before /DEVELOP.
Turn DESIGN.md intent into production-grade frontend design direction without generic UI output or gate violations.
Inputs
- Repository root
DESIGN.md (full document).
- SEO, IA, and content artifacts from SDD planning stages.
- Existing component constraints and brand priorities.
Workflow
- Confirm phase readiness: SEO, IA, and content artifacts exist before visual refinement.
- Select a coherent design direction (tone, density, typography, color strategy).
- Map typography and spacing to tokenized scales using
clamp() and container-aware rules.
- Define component-level visual patterns tied to variant APIs.
- Attach motion guidance that respects composited properties and reduced-motion constraints.
- Document anti-patterns and drift checks for implementation review.
- Prepare handoff summary for
/DEVELOP with explicit pass or fail gates.
Validation targets
- Visual decisions reference tokens, not ad-hoc values.
- LCP
< 2.5s and CLS < 0.1 targets preserved in design choices.
- WCAG 2.2 AA contrast and focus visibility documented.
- Motion specs include reduced-motion parity.
Outputs
- Design direction summary.
- Token-aligned component styling matrix.
- Handoff checklist with blocking and non-blocking findings.
Integration
/PLAN design as primary entry point./SCAN perf + /SCAN a11y before phase transition./FIX for gate-breaking regressions.
