Quieto Tokens
An open source CLI and MCP server that turns a handful of design decisions into a production-ready, multi-platform token system — accessible by default.
The problem I wanted to solve with this project
The Quieto Design System gave me a cohesive set of tokens and components I could reuse across projects. But every time I started something new, I was still spending hours manually wiring up the same foundational layer: picking color ramps, building spacing scales, and threading semantic references through primitives. Worse, when I wanted to hand that system to someone else — or use it in a native app alongside a web project — the output was locked to CSS custom properties and a single Figma file.
I needed a tool that could generate the entire token foundation from a few inputs, enforce accessibility constraints automatically, and output artifacts for whatever platform I was targeting — CSS, Figma, iOS, Android — without me maintaining parallel files by hand.
What Quieto Tokens does
Quieto Tokens is a CLI that walks you through creating a complete three-tier design token system. You provide a brand color, a spacing unit, and a typography feel. It generates DTCG-aligned JSON source files and platform-specific builds via Style Dictionary v4.
The tool produces three tiers of tokens:
- Primitive tokens — the raw values: 10-step color ramps, spacing scales, type scales. Every color step is WCAG AA compliant, enforced structurally by @quieto/engine.
- Semantic tokens — UI-meaningful assignments that reference primitives. color.background.primary, spacing.md, typography.body. These are where theming lives — light and dark modes are generated from a single yes/no question.
- Component tokens — tier-3 tokens for specific UI elements. button.primary.color.background.hover references semantics, so theming cascades automatically.
The CLI supports two modes. Quick start asks three to four questions and generates everything. Advanced mode gives full control over individual hue ramps, spacing steps, font families, sizes, weights, and line heights.
Building for evolution, not just generation
A token system that can only be created once isn't very useful. I built several commands to support the full lifecycle:
quieto-tokens update lets you change one category — say, swap your brand color — without regenerating everything. It shows a terminal diff of what changed, including cascade effects on semantic tokens, before you commit.
quieto-tokens add extends the system with new categories (shadow, border, animation) without touching your existing color, spacing, or typography files.
quieto-tokens component generates tier-3 component tokens interactively. You define variants, properties, states, and pick from your semantic tokens to assign values.
quieto-tokens inspect analyzes the health of your token system: orphaned primitives, broken references, naming violations, and WCAG contrast checks for paired semantic color tokens.
quieto-tokens migrate scans a codebase for hardcoded hex colors and dimensions that match your tokens, with an apply mode that does exact-match replacements and backs up every file it touches.
Every command supports `--dry-run`, and every successful write appends to a `TOKENS_CHANGELOG.md` so you have a tool-level audit trail alongside Git history.
Multi-platform output
One of the core goals was eliminating the "now port it" step. The CLI outputs:
- CSS custom properties — primitives, semantics, and per-theme layers
- DTCG JSON — interoperable source files for the design token ecosystem
- Figma Variables / Tokens Studio JSON — nested, theme-aware, ready to import
- iOS Swift — UIColor constants, SwiftUI Color extensions, CGFloat spacing, font constants
- Android — XML resources with values-night/ for dark mode, or Jetpack Compose Kotlin with Material3 ColorScheme bridges
All from the same `quieto.config.json`. Change a value, re-run, and every platform updates together.
The AI layer: Skills and MCP
As I was building the CLI, I was using Claude Code as my primary development environment. I realized the CLI's interactive prompts mapped naturally to conversational workflows — so I wrote Claude Code Skills that wrap each command into a slash-command experience. /design-token-init scaffolds a system through conversation. /design-token-audit runs a health check. /design-token-migrate scans your stylesheets. These are published as a standalone package (@quieto/skills) that you can install into any project.
I then took it further with an MCP server (@quieto/mcp) that exposes the core engine as tools for any LLM. It's hosted on Cloudflare Workers at quieto.dev/sse — no install required. You can generate color ramps, check WCAG contrast, map semantic tokens, and generate full light/dark theme collections, all from Claude Code, Claude Desktop, or Cursor. The MCP server uses the same @quieto/engine color math that powers the CLI, so the outputs are identical.
Technical decisions
TypeScript end to end. The CLI, engine, skills, and MCP server are all TypeScript. The CLI uses tsup for bundling and vitest for testing. The MCP server runs on Cloudflare Workers.
DTCG alignment. Every JSON source file follows the Design Tokens Community Group format. This was a deliberate bet on interoperability — as the DTCG spec matures and more tools adopt it, Quieto-generated tokens should work without translation.
Accessibility as a structural guarantee. Color ramps aren't just "intended" to be accessible — the engine enforces WCAG AA compliance mathematically during generation. You can't produce a non-compliant ramp. The inspect command verifies this across your full semantic layer after the fact.
Config as source of truth. quieto.config.json stores every answer you gave during setup. Re-running the CLI loads your previous answers so you only change what's different. Generated files carry a $metadata.doNotEdit banner — the config is the thing you version-control and modify, the outputs are derived.
Links
- quieto-tokens on GitHub
- quieto-skills on GitHub
- quieto-mcp on GitHub
- MCP server (live)
All repositories are open source under the MIT license.