OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add ilikescience/design-tokens-skill --skill design-tokens
Expert in design tokens using the DTCG specification. Use this skill when users ask about design tokens, DTCG format, token validation, formatting, transformation, color spaces (sRGB, Display P3, OKLCH), references and aliasing, resolvers, theming with modifiers/contexts, multi-platform design systems, accessibility, or working with tools like jq, jsonata, and terrazzo. Helps with token file creation, resolver configuration, structure, naming conventions, and best practices.
npx skills add ilikescience/design-tokens-skill --skill design-tokens
Expert guidance for working with design tokens following the Design Tokens Community Group (DTCG) specification.
| Topic | Reference |
|---|---|
| Token types, structure, validation | reference/format.md |
| Color spaces, components, alpha, common mistakes | reference/color.md |
| Sets, modifiers, resolution order | reference/resolver.md |
| jq, JSONata, Figma export, Terrazzo config | reference/tools.md |
| Common patterns and examples | examples/use-cases.md |
Getting Started: See Getting Started Guides for step-by-step workflows.
Based on the latest DTCG Draft Community Group Reports:
A token is a JSON object with $value. Special properties use $ prefix:
Atomic: color, dimension, fontFamily, fontWeight, duration, cubicBezier, number
Composite: strokeStyle, border, shadow, gradient, typography, transition
See reference/format.md for complete type definitions.
Colors use structured objects (not hex strings):
Supported spaces: srgb, display-p3, oklch, oklab, hsl, hwb, lab, lch, and more. See reference/color.md.
Two syntaxes supported:
"{path.to.token}"$ref) - Property-level access: {"$ref": "#/path/to/$value/property"}Token reference example:
JSON Pointer example (accessing array elements):
See reference/format.md for complete reference syntax details.
Groups organize tokens. $type on a group applies to all children:
Resolvers manage tokens across contexts (themes, platforms, densities):
See reference/resolver.md for complete documentation.
Starting point: Existing CSS custom properties
Step 1: Create primitives.tokens.json
Step 2: Create semantic.tokens.json with references
Conversion tips:
37/255 = 0.145)hex propertyStep 1: Install dependencies
Step 2: Create token files with mode extensions
tokens/themes/light.tokens.json:
tokens/themes/dark.tokens.json:
Step 3: Create terrazzo.config.mjs
Step 4: Build and use
In your HTML:
Step 1: Export from Figma
figma-export.jsonStep 2: Validate the export
Step 3: Add mode extensions if needed
If Figma exported separate mode files, add $extensions.mode:
Step 4: Add hex fallbacks (if missing)
Figma exports sRGB components but may omit hex:
Step 5: Configure Terrazzo
Create terrazzo.config.mjs pointing to your imported files and build.
Common Figma export issues:
$type on groups - add type inheritanceStep 1: Define structure
Organize into layers:
Step 2: Create primitives
Step 3: Create semantic tokens
Step 4: Validate
Check for:
$type{, }, . or start with $Step 5: Test with tools
Step 1: Organize files
Step 2: Create resolver
Step 3: Define theme modifier
Step 4: Set resolution order
Step 5: Test
Step 1: JSON syntax
Step 2: Type declarations
Every token needs a resolvable $type (explicit or inherited from parent group).
Step 3: Value formats
| Type | Valid Format |
|---|---|
| color | {colorSpace, components, [alpha], [hex]} |
| dimension | `{value: number, unit: "px" |
| duration | `{value: number, unit: "ms" |
| cubicBezier | [P1x, P1y, P2x, P2y] where P1x, P2x ∈ [0,1] |
| fontWeight | 1-1000 or string ("normal", "bold", etc.) |
Step 4: References
{path.to.token} references must resolveStep 5: Naming
${, }, .Common conversions:
| From | To DTCG |
|---|---|
"#ff0000" | {colorSpace: "srgb", components: [1,0,0], hex: "#ff0000"} |
"16px" | {value: 16, unit: "px"} |
"$colors.primary" or {colors.primary} | "{colors.primary}" |
Terrazzo conversion:
color.brand.primary[category].[subcategory].[variant].[state]color.interactive.default not color.blue-500Use resolvers for themes (recommended over group extension):
Color contrast: Document contrast ratios in $extensions:
Reduced motion: Use resolver modifier:
.tokens or .tokens.json.resolver.json| Task | Approach |
|---|---|
| Format validation | Check against DTCG spec, use Terrazzo validate |
| Structure optimization | Organize into primitive → semantic → component layers |
| Alias resolution | Trace references, check for circular dependencies |
| Resolver configuration | Define sets, modifiers, resolution order |
| Theme implementation | Use resolver modifiers with context files |
| Multi-context builds | Generate outputs per theme/platform/density |
| Tool integration | Use jq for queries, Terrazzo for transforms |
| Migration | Convert colors to structured format, update references |
When helping with design tokens:
$value, $type, references$extensionsImportant: When asked about spec capabilities (what syntax is valid, what features exist), always read the relevant reference file first. Do not rely on assumptions or prior knowledge about the spec.
Always provide clear examples and explain reasoning behind recommendations.
{
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [1, 0, 0.5],
"alpha": 0.8,
"hex": "#ff0080"
}
}{
"color": {
"primary": {"$type": "color", "$value": {"colorSpace": "srgb", "components": [0, 0.4, 0.8]}}
},
"button": {
"background": {"$type": "color", "$value": "{color.primary}"}
}
}{
"blue": {
"$type": "color",
"$value": {"colorSpace": "okhsl", "components": [0.733, 0.8, 0.5]}
},
"blue-hue": {
"$type": "number",
"$ref": "#/blue/$value/components/0"
}
}{
"spacing": {
"$type": "dimension",
"sm": {"$value": {"value": 8, "unit": "px"}},
"md": {"$value": {"value": 16, "unit": "px"}},
"lg": {"$value": {"value": 24, "unit": "px"}}
}
}{
"name": "my-system",
"version": "2025.10",
"sets": {
"core": {"sources": [{"$ref": "tokens/base.json"}]}
},
"modifiers": {
"theme": {
"contexts": {
"light": [{"$ref": "themes/light.json"}],
"dark": [{"$ref": "themes/dark.json"}]
},
"default": "light"
}
},
"resolutionOrder": [
{"$ref": "#/sets/core"},
{"$ref": "#/modifiers/theme"}
]
}:root {
--color-primary: #2563eb;
--color-background: #ffffff;
--spacing-sm: 8px;
--spacing-md: 16px;
}{
"color": {
"primitive": {
"$type": "color",
"blue-500": {
"$value": { "colorSpace": "srgb", "components": [0.145, 0.388, 0.922], "hex": "#2563eb" }
},
"white": {
"$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" }
}
}
},
"spacing": {
"$type": "dimension",
"scale": {
"sm": { "$value": { "value": 8, "unit": "px" } },
"md": { "$value": { "value": 16, "unit": "px" } }
}
}
}{
"color": {
"interactive": {
"$type": "color",
"primary": { "$value": "{color.primitive.blue-500}" }
},
"background": {
"$type": "color",
"page": { "$value": "{color.primitive.white}" }
}
},
"spacing": {
"$type": "dimension",
"component": {
"padding": { "$value": "{spacing.scale.sm}" },
"gap": { "$value": "{spacing.scale.md}" }
}
}
}npm install -D @terrazzo/cli @terrazzo/plugin-css{
"$extensions": { "mode": "light" },
"color": {
"background": {
"$type": "color",
"page": { "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" } }
},
"text": {
"$type": "color",
"primary": { "$value": { "colorSpace": "srgb", "components": [0.07, 0.07, 0.07], "hex": "#121212" } }
}
}
}{
"$extensions": { "mode": "dark" },
"color": {
"background": {
"$type": "color",
"page": { "$value": { "colorSpace": "srgb", "components": [0.07, 0.07, 0.07], "hex": "#121212" } }
},
"text": {
"$type": "color",
"primary": { "$value": { "colorSpace": "srgb", "components": [0.95, 0.95, 0.95], "hex": "#f2f2f2" } }
}
}
}import { defineConfig } from "@terrazzo/cli";
import pluginCSS from "@terrazzo/plugin-css";
export default defineConfig({
tokens: [
"./tokens/primitives.tokens.json",
"./tokens/themes/light.tokens.json",
"./tokens/themes/dark.tokens.json"
],
outDir: "./dist/",
plugins: [
pluginCSS({
filename: "tokens.css",
modeSelectors: [
{ mode: "light", selectors: [":root", "[data-theme='light']"] },
{ mode: "dark", selectors: ["[data-theme='dark']", "@media (prefers-color-scheme: dark)"] }
]
})
]
});npx terrazzo build<html data-theme="light"><!-- or "dark" --># Check JSON is valid
jq '.' figma-export.json > /dev/null && echo "Valid JSON"
# List all token paths
jq -r 'paths(has("$value")) | join(".")' figma-export.json# Add mode to light theme file
jq '. + {"$extensions": {"mode": "light"}}' light.json > light.tokens.json# Quick check if hex values exist
jq '.. | objects | select(.colorSpace == "srgb") | select(.hex == null)' figma-export.jsonToken File Creation:
- [ ] Step 1: Define file structure (primitives → semantic → components)
- [ ] Step 2: Create primitive tokens with explicit types
- [ ] Step 3: Create semantic tokens referencing primitives
- [ ] Step 4: Validate structure and references
- [ ] Step 5: Test with target tools (Terrazzo, etc.)tokens/
├── primitives.tokens.json # Raw values (colors, spacing scales)
├── semantic.tokens.json # Purpose-driven aliases
└── components.tokens.json # Component-specific tokens{
"color": {
"primitive": {
"$type": "color",
"blue": {
"500": {"$value": {"colorSpace": "srgb", "components": [0.15, 0.39, 0.92], "hex": "#2563eb"}}
}
}
}
}{
"color": {
"interactive": {
"$type": "color",
"default": {"$value": "{color.primitive.blue.500}"}
}
}
}terrazzo validate tokens.json
terrazzo build --input tokens.json --output test.css --format cssResolver Setup:
- [ ] Step 1: Organize token files by concern
- [ ] Step 2: Create resolver.json with version and sets
- [ ] Step 3: Define theme modifier with contexts
- [ ] Step 4: Configure resolution order
- [ ] Step 5: Test with different inputstokens/
├── resolver.json
├── base.tokens.json
└── themes/
├── light.tokens.json
└── dark.tokens.json{
"name": "my-design-system",
"version": "2025.10",
"sets": {
"foundation": {
"sources": [{"$ref": "base.tokens.json"}]
}
}
}{
"modifiers": {
"theme": {
"contexts": {
"light": [{"$ref": "themes/light.tokens.json"}],
"dark": [{"$ref": "themes/dark.tokens.json"}]
},
"default": "light"
}
}
}{
"resolutionOrder": [
{"$ref": "#/sets/foundation"},
{"$ref": "#/modifiers/theme"}
]
}terrazzo build --resolver resolver.json --output light.css
terrazzo build --resolver resolver.json --input theme=dark --output dark.cssValidation Checklist:
- [ ] Step 1: Check JSON syntax
- [ ] Step 2: Verify type declarations
- [ ] Step 3: Validate value formats
- [ ] Step 4: Check reference resolution
- [ ] Step 5: Verify naming constraintsjq '.' tokens.json > /dev/null && echo "Valid JSON"Migration Workflow:
- [ ] Step 1: Export existing tokens to JSON
- [ ] Step 2: Map types to DTCG equivalents
- [ ] Step 3: Convert color values to structured format
- [ ] Step 4: Update reference syntax
- [ ] Step 5: Validate and testterrazzo convert --from style-dictionary --to dtcg input.json output.tokens.json{
"$extensions": {
"com.example.a11y": {"contrastRatio": 7.5, "wcagLevel": "AA"}
}
}{
"modifiers": {
"motion": {
"contexts": {
"full": [{"$ref": "motion/full.json"}],
"reduced": [{"$ref": "motion/reduced.json"}]
},
"default": "full"
}
}
}