ilikescience/design-tokens-skill
Overview
This skill is an expert assistant for working with design tokens following the Design Tokens Community Group (DTCG) specification. It helps create, validate, transform, and resolve tokens across color spaces, themes, and platforms. Use it to configure resolvers, format token files, and integrate with tools like jq, JSONata, Terrazzo, and Figma exports.
How this skill works
I inspect token JSON for correct DTCG structure, types, and value formats, including color objects, dimensions, durations, and composites. I locate and validate references/aliases, detect circular references, suggest resolver configuration for themes and modifiers, and provide concrete conversions (hex ↔ structured sRGB/OKLCH). I also outline Terrazzo and jq/JSONata workflows for validation, transformation, and build integration.
When to use it
- Converting CSS variables or other token formats to DTCG structured tokens
- Validating token files for type correctness, reference resolution, and naming constraints
- Configuring resolvers and theme modifiers (light/dark, high-contrast, reduced motion)
- Preparing token files for Terrazzo builds or Figma variable imports/cleanup
- Designing multi-platform systems with color space conversions and accessibility metadata
Best practices
- Organize tokens in layers: primitives → semantic → components for clarity and reuse
- Prefer semantic names over appearance; use lowercase and hyphens (category.subcategory.variant)
- Store colors as structured objects (colorSpace, components, optional alpha and hex fallback)
- Use resolver modifiers for theming rather than duplicating groups; declare clear resolutionOrder
- Add accessibility metadata (contrast ratios, reduced-motion contexts) in $extensions for tooling and audits
- Validate tokens with jq and Terrazzo; detect circular refs and missing $type early
Example use cases
- Convert a CSS custom-property palette to primitives.tokens.json and create semantic aliases referencing them
- Import Figma variables, add $extensions.mode for themes, add missing hex fallbacks, and run jq checks
- Create resolver.json with theme modifier contexts and build CSS outputs via Terrazzo for light and dark modes
- Trace and fix a broken alias chain using jq/JSONata to identify unresolved or circular references
- Migrate a Style Dictionary export: map types, convert color hex to structured sRGB, and validate with the DTCG rules
FAQ
Store structured components and include a hex fallback: $type: "color", $value: {colorSpace: "srgb", components: [...], alpha: ..., hex: "#rrggbb"}.
What common validation checks should I run before building?
Check JSON syntax, ensure every token has a resolvable $type, validate value formats per type, verify all references resolve, and detect circular or self-references.
