Token Architecture
Designtoken-architectureToken Architecture is an Agent Skill for design published in the Owl-Listener/designpowers repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when building or restructuring design token systems — global tokens, semantic tokens, component tokens, naming conventions, theming, and multi-platform token distribution
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Owl-Listener/designpowers/blob/HEAD/skills/token-architecture/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/token-architecture, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Token Architecture
Design tokens are the single source of truth for visual decisions. They bridge design intent and code. This skill structures how tokens are named, layered, and distributed.
When to Use
- When starting a new design system
- When
design-system-alignmentidentifies inconsistency - When adding theming (dark mode, brand variants)
- When shipping across web, iOS, and Android
The Three-Layer Model
Layer 1: Global Tokens (the palette)
Raw values. Named by what they are, not what they do.
--color-green-500: #2D6B4F;
--space-4: 16px;
--radius-md: 12px;
These never appear in component CSS.
Layer 2: Semantic Tokens (the meaning)
Map global tokens to roles. Named by what they do.
--color-surface: var(--color-green-100);
--color-text-primary: var(--color-green-900);
--color-accent: var(--color-green-500);
Theming happens here — dark mode swaps semantic mappings, not global values.
Layer 3: Component Tokens (the specifics)
Map semantic tokens to component contexts. Optional but valuable at scale.
--button-bg: var(--color-accent);
--card-bg: var(--color-surface);
Naming Convention
--{category}-{property}-{variant}-{state}
Categories: color, space, font, radius, shadow, motion. Never use hex values in names or ambiguous abbreviations.
Theming
Dark mode is a semantic token remap:
[data-theme="dark"] {
--color-surface: var(--color-grey-900);
--color-text-primary: var(--color-grey-100);
}
Global tokens stay. Semantic tokens swap. Component tokens inherit.
Accessibility
- Always define foreground/background pairs together and verify AA contrast
- Motion tokens must include
--motion-duration-none: 0msfor reduced-motion
What You Deliver
- Token file (CSS custom properties, JSON, or both) with all three layers
- Naming convention document
- Theme variants if applicable
Integration
- Informed by:
design-lead,ui-composition - Feeds into:
design-builder,design-system-alignment