OpenParable
Skip to content
← Back to skills

Token Architecture

Design
token-architecture

Token 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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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-alignment identifies 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: 0ms for 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