design-token-system-architect

Generates layered design token systems with CSS custom properties, Tailwind configuration, and dark mode support.

1|Updated May 4, 2026
One-click install
npx skills add https://github.com/Scardubu/SwarmXQ --skill design-token-system-architect-scardubu
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: design-token-system-architect
Source: https://github.com/Scardubu/SwarmXQ/tree/main/.ai/skills/design-token-system-architect
Command: npx skills add https://github.com/Scardubu/SwarmXQ --skill design-token-system-architect-scardubu

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Building a design system by hand often leads to inconsistent colors, hard-coded hex values scattered across components, and dark mode implementations that flash or break on server-rendered pages. This Skill produces a complete, layered token architecture so every color, spacing value, and shadow traces back to a single source of truth. ## Core Features & Use Cases - Three-Layer Token Architecture: Generates primitive, semantic, and component token layers as CSS custom properties, enforcing the rule that components never reference raw hex values. - Tailwind and shadcn/ui Integration: Produces a complete tailwind.config.ts mapping semantic tokens to Tailwind utilities, plus a globals.css mapping for shadcn/ui's expected CSS variables. - Dark Mode Without Flash: Implements a cookie-based data-theme strategy for Next.js that renders the correct theme on the server, avoiding the flash caused by prefers-color-scheme alone. - Use Case: A developer starting a fintech dashboard asks for a design system; the Skill outputs primitives.css, tokens.css with light and dark semantic tokens, a Tailwind v3 config, and a theme toggle hook, all passing contrast and consistency quality gates. ## Quick Start Ask the AI to design a token system for your app with Tailwind and dark mode support, mentioning your brand color and framework.

Frequently Asked Questions about design-token-system-architect

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I set up design tokens with Tailwind CSS?

Define tokens as CSS custom properties in a tokens.css file, then reference them in tailwind.config.ts using var(--token-name) values for colors, spacing, fonts, and shadows. This keeps Tailwind utilities synchronized with the token layer so dark mode swaps values automatically.

How do I implement dark mode in Next.js without a flash?

Use a data-theme attribute on the html element driven by a cookie read on the server, rather than prefers-color-scheme alone. The server renders the correct theme immediately, and a client hook toggles the attribute and updates the cookie.

What is the difference between primitive and semantic design tokens?

Primitive tokens hold raw values like hex colors and are never used in components directly. Semantic tokens are intent-based aliases such as color-text-primary that reference primitives, letting themes change meaning without touching component code.

Does this token system work with shadcn/ui?

Yes. The generated tokens map to shadcn/ui's expected CSS variable names such as --background, --foreground, --primary, and --ring in globals.css. Components receive tokens through this mapping rather than direct overrides.

Why should components never use hex values directly?

Hard-coded hex values break theming because they cannot be swapped per theme and create drift across the codebase. The layered rule requires components to reference component tokens, which alias semantic tokens, which alias primitives.

What contrast ratios should design tokens meet?

The quality gates require text-primary on surface-base to reach at least 7:1 contrast (WCAG AAA) and text-secondary at least 4.5:1 (AA). Dark mode must cover all six semantic categories: text, surface, border, status, interactive, and shadow.