Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
Guides building and reviewing design tokens, theming systems, dark mode implementation, CSS custom properties, and theme switching using three-tier model, purpose-based naming, and DTCG spec.
npx claudepluginhub oborchers/fractional-cto --plugin saas-design-principlesHow this skill is triggered — by the user, by Claude, or both
Slash command
/saas-design-principles:design-tokensThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
The industry has converged on a three-tier token architecture. Adopting it correctly means theme switching requires only toggling a class — no component re-renders, no complex logic.
Implements CSS design token architecture for scalable themes, including primitive/semantic/component tokens, light/dark mode switching, and Tailwind/framework integration.
Guides phased setup of design token systems: discovers brand/tech constraints, explains primitive/semantic two-tier model, creates CSS custom properties, Tailwind configs, spacing scales, color semantics.
Use when asked to define a design token system, create tokens, document tokens, set up CSS custom properties, build a Tailwind token config, establish a spacing scale, define color semantics, or bridge design decisions to code. Examples: "set up design tokens", "define our token system", "create CSS variables for the design system", "document our color tokens", "establish a spacing scale".
Share bugs, ideas, or general feedback.
The industry has converged on a three-tier token architecture. Adopting it correctly means theme switching requires only toggling a class — no component re-renders, no complex logic.
Raw values. The palette.
Examples: #3B82F6, 16px, 600
Purpose-driven aliases. The meaning layer.
Examples: --color-text-primary, --color-bg-surface, --spacing-md
Scoped references. The component layer.
Examples: --button-bg, --card-border-radius, --input-border-color
Name tokens by purpose, not appearance.
| Bad (appearance) | Good (purpose) |
|---|---|
--color-white | --color-bg-surface |
--color-blue-500 | --color-action-primary |
--font-large | --font-heading |
--color-gray-200 | --color-border-default |
--color-bg-surface works in both light and dark mode. --color-white becomes meaningless the moment themes change.
Use CSS custom properties with a class toggle on the root element. CSS variables cascade down, automatically updating every component without re-rendering the component tree.
Implementation pattern:
.dark (or [data-theme="dark"]) selector<html> to switch themesUse the hybrid approach:
prefers-color-schemelocalStoragedata-theme attribute on <html>Consider Twitter's three-option model for apps where users spend long sessions:
The DTCG released the first stable specification (2025.10), backed by Adobe, Amazon, Google, Figma, Shopify, and others. Adopting the DTCG JSON format future-proofs token architecture for cross-platform tooling and design-to-code pipelines.
Working implementations in examples/:
examples/three-tier-tokens.md — Complete CSS custom property system: primitives, semantics, component tokens, and DTCG JSON formatexamples/dark-mode-toggle.md — Hybrid theme switching with system detection, localStorage persistence, and framework-specific togglesWhen reviewing or building a token/theming system:
--white, --blue-500)prefers-color-schemelocalStoragedata-theme attribute on <html>