Design tokens basics

Skill almasumdev/awesome-mobile-design-system-agent-skills/.github/skills/foundations/design-tokens-basics

Agent skills for building and maintaining mobile design systems, tokens, and component libraries.

Install

npx -y skills add almasumdev/awesome-mobile-design-system-agent-skills --skill design-tokens-basics

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

DTCG token schema, naming conventions, and reference/system/component layering. Use this when introducing or auditing a token set.

SKILL.md

4.5 KB, as published. Nobody here has run it

Design Tokens Basics

Instructions

Design tokens are the single source of truth for every visual and behavioral decision in the design system. Follow the W3C Design Tokens Community Group (DTCG) format and a strict three-layer model.

1. DTCG Schema Essentials

Tokens are JSON objects where every leaf has $value and $type. Groups may set a default $type that descendants inherit.

{
  "color": {
    "$type": "color",
    "brand": {
      "600": { "$value": "#4F46E5" },
      "700": { "$value": "#4338CA" }
    }
  },
  "space": {
    "$type": "dimension",
    "4":  { "$value": "4px" },
    "8":  { "$value": "8px" },
    "16": { "$value": "16px" }
  },
  "font": {
    "family": {
      "sans": { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] }
    }
  }
}

Supported $type values used in this system: color, dimension, fontFamily, fontWeight, number, duration, cubicBezier, shadow, typography, transition, strokeStyle.

2. Three-Layer Model

Reference (core): raw primitives. Never consumed by components directly.
- color.blue.500, space.8, font.size.16, radius.8.
System (semantic): intent-bearing aliases. This is the layer components consume.
- color.surface.default, color.action.primary.default, space.inset.md, text.body.md.
Component: component-scoped. Built by aliasing System tokens.
- button.primary.bg.default, card.surface.bg, field.border.focus.

3. Aliasing

Use DTCG alias syntax {group.name} in $value. The build resolves aliases; runtime never sees references.

{
  "color": {
    "action": {
      "primary": {
        "default": { "$value": "{color.brand.600}" },
        "hover":   { "$value": "{color.brand.700}" },
        "pressed": { "$value": "{color.brand.800}" }
      }
    }
  }
}

Rule: a token may alias only inward (component → system → reference). Never reference → system.

4. Naming Convention

Use dotted, lowercase, noun-first names. Keep segments short and semantic.

<category>.<role>.<property>.<state>
color.action.primary.bg.default
color.action.primary.fg.default
color.feedback.danger.bg.subtle

Do not encode platform, hex value, or implementation (color-ios-blue, space-8px-v2) in the name.

5. Token Categories

Every mobile design system should minimally define tokens for:

Category	Examples
color	`color.surface.`, `color.content.`, `color.action.*`
typography	`text.display.lg`, `text.body.md` (composite)
spacing	`space.inset.`, `space.stack.`, `space.inline.*`
radius	`radius.sm`, `radius.md`, `radius.pill`
elevation	`elevation.level1`, `elevation.level2` (shadow composite)
motion	`motion.duration.`, `motion.easing.`
border	`border.width.sm`, `border.style.default`

6. Metadata

DTCG allows $description, $deprecated, and $extensions. Use them.

{
  "color": {
    "action": {
      "primary": {
        "default": {
          "$value": "{color.brand.600}",
          "$description": "Default background for primary CTAs.",
          "$extensions": {
            "com.designsystem.contrastPair": "color.action.primary.fg.default"
          }
        }
      }
    }
  }
}

7. Anti-Patterns

Hex values inline in component code.
Semantic layer with color-in-the-name (color.blue-primary).
Component tokens aliasing reference tokens directly.
Token removal without a deprecation window.
One monster JSON file — split per category and per layer.

Checklist

Tokens validate as DTCG ($value + $type on every leaf).
Three layers exist as separate files/folders: reference/, system/, component/.
Components consume only system or component tokens.
Names are semantic, lowercase, dotted, no implementation details.
Every token has a $description or its intent is obvious from its name.
Deprecated tokens use $deprecated: true with a replacement hint.
A tokens/ lint step fails the build on broken aliases or layer violations.