Skip to content

Worked example: tutorial

Generated by skills/document-author with type=tutorial. Demonstrates the canonical Diátaxis tutorial format.

---
title: Build your first design token set
description: Learn the design-ai workflow by generating, customizing, and exporting a complete design token set in 15 minutes.
type: tutorial
audience: New users — designers or front-end developers familiar with their design system but new to design-ai
last_updated: 2026.05.08
---

# Build your first design token set

> Time: 15 minutes · Audience: New to design-ai

In this tutorial you'll generate a fintech-flavored color palette, customize it for your brand, and export it as Tailwind v4 + shadcn-ui tokens.

## What you'll build

By the end you'll have:
- A `tokens/source.json` with your brand palette
- A `src/styles/tokens.css` with CSS custom properties
- A working `palette.preview.html` you can open in a browser to verify

## Prerequisites

- Node 20+
- A terminal
- A brand color (or a mood — we'll pick one if you don't have one)

## Step 1 — Clone design-ai

```bash
git clone https://github.com/your-org/design-ai
cd design-ai

You should see knowledge/, skills/, examples/ — the design-ai system layout.

Step 2 — Generate a palette

Run the palette-from-brand command in your AI agent (Claude Code, Codex, or paste into a chat):

/palette-from-brand "B2C Korean fintech, calming + youthful, teal seed #0D9488"

The agent reads skills/color-palette/PLAYBOOK.md and generates a full palette spec at examples/my-palette.md.

Open it. You should see: - An 11-step ramp (50–950) for primary, accent, and neutrals - Light + dark mode semantic aliases - A WCAG contrast matrix - Code blocks for Tailwind v4 / shadcn-ui / Style Dictionary

ℹ Note: if your contrast matrix shows ✗ for any pair, the palette needs adjustment. The agent should flag this.

Step 3 — Visually verify

Generate the HTML preview:

python3 tools/preview/render-tokens.py examples/my-palette.md

Open examples/my-palette.preview.html. You'll see: - Token swatches (light + dark) - Live Button/Input/Alert/Card with your tokens - A theme toggle at the top

Click the theme toggle. The whole preview switches. If anything looks wrong (low-contrast text, washed-out buttons), revise via /iterate.

Step 4 — Export to Style Dictionary

Save the JSON code block from your palette doc to tokens/source.json:

# Copy the JSON block from examples/my-palette.md → tokens/source.json

Install Style Dictionary:

npm init -y
npm install -D style-dictionary

Create style-dictionary.config.json:

{
  "source": ["tokens/source.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "src/styles/",
      "files": [
        { "destination": "tokens.css", "format": "css/variables" }
      ]
    }
  }
}

Build:

npx style-dictionary build

You should see src/styles/tokens.css with your tokens as CSS custom properties.

Step 5 — Use the tokens

Reference them in any CSS:

.my-button {
  background: var(--color-primary-default);
  color: var(--color-on-primary);
  padding: var(--space-md);
  border-radius: var(--radius-md);
}

The button now uses your brand-derived tokens.

What's next

You generated tokens. Now:

If you got stuck, check docs/USING.md for agent-specific setup. ```

Why this is a good tutorial example

  • Time + audience stated up top — sets expectations.
  • "What you'll build" with concrete deliverables — motivates.
  • Numbered steps — easy to follow.
  • Each step has visible outcome ("you should see…") — confirms progress.
  • Callout for warning when contrast fails.
  • What's next section — bridges to next learning.
  • No throat-clearing. Tutorials are encouraging but direct.

Cite knowledge/patterns/information-architecture.md for the canonical tutorial structure.

Cross-reference