design-token
owl-listener/designer-skills
Define and organize design tokens for color, spacing, type, and elevation with systematic naming rules.
What is design-token?
An expert guide for establishing the token layer of a design system. Helps you define, organize, and document atomic design values—colors, spacing, typography, elevation, borders, and motion—across global, alias, and component tiers. Use this when building or refining your design token architecture.
- Define token categories: color, spacing, typography, elevation, border, and motion
- Organize tokens into three tiers: global (raw values), alias (semantic references), and component (scoped usage)
- Apply consistent naming conventions following {category}-{property}-{variant}-{state} pattern
- Document tokens with usage context and cross-platform mapping
- Support theming by maintaining abstract alias tokens
- Version tokens alongside your design system
How to install design-token
npx skills add https://github.com/owl-listener/designer-skills --skill design-tokenHow to use design-token
- 1.Install the skill via npx skills add https://github.com/owl-listener/designer-skills --skill design-token
- 2.Define your global tokens with raw values (e.g., color palette, base spacing unit)
- 3.Create semantic alias tokens that reference globals (e.g., color-action-primary, spacing-stack-md)
- 4.Establish component-level tokens scoped to specific UI elements
- 5.Document each token with its category, tier, naming pattern, and usage context
- 6.Version your token definitions alongside your design system updates
Use cases
- Establishing a new design system token layer from scratch
- Restructuring existing tokens into a hierarchical taxonomy
- Creating semantic color and spacing aliases for consistency
- Documenting token usage rules for design and engineering teams
- Preparing tokens for multi-platform or multi-brand implementation
- Design system leads
- Product designers building systematic foundations
- Design engineers implementing token infrastructure
- Teams standardizing visual consistency across products
design-token FAQ
Use design-token to define and organize your token architecture from scratch. Use design-token-audit (from designer-toolkit) to analyze and audit how existing tokens are being used in your codebase.
Alias tokens are semantic references to global values (e.g., color-action-primary references a specific blue). Component tokens are scoped to specific UI elements (e.g., button-color-primary). Aliases stay abstract for theming; component tokens are more specific.
Keep alias tokens abstract and semantic rather than tied to specific visual values. This allows you to swap underlying global tokens for different themes while maintaining the same alias references.
Use {category}-{property}-{variant}-{state}. For example: color-background-surface-hover or spacing-stack-lg. This creates predictable, hierarchical token names.
No. Always reference alias or component tokens in your components, never raw global values. This maintains consistency and makes theming possible.
Full instructions (SKILL.md)
Source of truth, from owl-listener/designer-skills.
name: design-token
description: Define and organise tokens for colour, spacing, type, and elevation with naming and usage rules. Use when establishing the token layer. For auditing existing usage use design-token-audit (designer-toolkit); for multi-brand mapping use theming-system.
Design Token
You are an expert in design token architecture and systematic design foundations.
What You Do
You help define, organize, and document design tokens — the atomic values that drive visual consistency. You understand token taxonomies, naming hierarchies, and cross-platform mapping.
Token Categories
- Color: Global palette, alias tokens (surface, text, border), component tokens
- Spacing: Base unit (4px/8px), scale (xs through 3xl), contextual (inset, stack, inline)
- Typography: Font families, size scale, weights, line heights
- Elevation: Shadow levels, z-index scale
- Border: Radius scale, width scale, style options
- Motion: Duration scale, easing functions
Token Tiers
- Global tokens — Raw values (e.g., blue-500: #3B82F6)
- Alias tokens — Semantic references (e.g., color-action-primary)
- Component tokens — Scoped usage (e.g., button-color-primary)
Naming Convention
Pattern: {category}-{property}-{variant}-{state}
Best Practices
- Start with global tokens, then create semantic aliases
- Never reference raw values in components
- Document each token with usage context
- Version tokens alongside your design system
- Support theming by keeping alias tokens abstract
Related skills
More from owl-listener/designer-skills and the wider catalog.
design-token-audit
Audit design token adoption and identify hard-coded values, gaps, and drift across your product.
diary-study-plan
Design longitudinal diary studies to capture user behavior over days or weeks.
documentation-template
Generate standardized documentation templates for design system components, patterns, and guidelines.
doherty-threshold
Keep system response under 400ms to preserve user flow and productivity.
empathy-map
Build Says, Thinks, Does, Feels maps to align teams around user understanding from research data.
error-handling-ux
Design error prevention, detection, and recovery across multi-flow products.