🗿 Unholy Design Tokens - A Practical Guide to Design Tokens (Without the Fluff)

See Figma

A brutally clear, developer-friendly design token system using Style Dictionary.

This project is a playground to try to simplify the concept of design tokens and provide a practical framework for implementing and customize them using Style Dictionary.

🏠 Understanding Design Tokens through a House

To represent the concept of design tokens, you can use the following analogies:

→ House-Building Analogy (practical approach)

Goals:

• Avoid abstraction and provide a short and practical definition of design tokens.
• Propose a clear structure for organizing design tokens.
• Clarify who owns what between Designers and Developers regarding token levels

📁 Repository Structure

/
├─ README.md                ← you're here
├─ ANALOGY_HOUSE.md         ← build a house analogy for design tokens
├─ ANALOGY_I18NEXT.md       ← analogy applied to translations
├─ WHY_THIS_EXISTS.md       ← motivation behind the repo
│
└─ src/
    └─ tokens/
        ├─ README.md                    ← token system overview
        ├─ 1-primitives/                ← raw values (colors, spacing…)
        ├─ 2-semantic/                  ← meaningful roles
        ├─ 3-intent/                    ← purpose/state
        ├─ 4-cube/                      ← layout primitives
        └─ component/                   ← per-component token mapping

🗂 Token source

Tokens live here:
👉 src/tokens

📘 Explanations

• ❓ Why this repo exists → WHY_THIS_EXISTS.md
• ⚙️ Style Dictionary pipeline → STYLE_DICTIONARY.md
• i18n analogy → ANALOGY_I18NEXT.md
• 🏠 House-building analogy → ANALOGY_HOUSE.md

Use the package

A) Local dev (TS, no install)

pnpm exec tsx bin/build-tokens.ts ../../lib

B) Local project (compiled CLI)

pnpm exec build-tokens ../../lib

C) As a dependency in another repo

pnpm add style-dictionary-example-complete
pnpm exec build-tokens ./tokens

D) One-off usage

npx style-dictionary-example-complete ./tokens