oborchers/design-tokens
saas-design-principles/skills/design-tokens/SKILL.md
This skill should be used when the user is building or reviewing theming systems, design tokens, dark mode implementation, CSS custom properties, color naming conventions, or theme switching architecture. Covers the three-tier token model (primitive/semantic/component), purpose-based naming, and the DTCG specification.
$ install --global
skillsauthnpx skillsauth add oborchers/fractional-cto design-tokensInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 13, 2026, 6:51 AM152.6s3 files scanned
SKILL.md
- name:
- design-tokens
- description:
- This skill should be used when the user is building or reviewing theming systems, design tokens, dark mode implementation, CSS custom properties, color naming conventions, or theme switching architecture. Covers the three-tier token model (primitive/semantic/component), purpose-based naming, and the DTCG specification.
- version:
- 1.0.0
Design Tokens Make Theming a Non-Event
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.
Three-Tier Token Architecture
Tier 1: Primitive Tokens
Raw values. The palette.
Examples: #3B82F6, 16px, 600
Tier 2: Semantic Tokens
Purpose-driven aliases. The meaning layer.
Examples: --color-text-primary, --color-bg-surface, --spacing-md
Tier 3: Component Tokens
Scoped references. The component layer.
Examples: --button-bg, --card-border-radius, --input-border-color
The Critical Naming Rule
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.
Theme Switching Architecture
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:
- Define semantic tokens as CSS custom properties
- Override values in a
.dark(or[data-theme="dark"]) selector - Toggle the class/attribute on
<html>to switch themes - No JavaScript re-renders needed
Dark Mode Implementation
Use the hybrid approach:
- Detect system preference with
prefers-color-scheme - Allow manual override via a toggle
- Store the preference in
localStorage - Apply via a
data-themeattribute on<html>
Consider Twitter's three-option model for apps where users spend long sessions:
- Default (light)
- Dim (reduced contrast dark)
- Lights Out (true black)
W3C Design Tokens Community Group
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.
Examples
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 toggles
Review Checklist
When reviewing or building a token/theming system:
- [ ] Three-tier architecture: primitive, semantic, component tokens
- [ ] All tokens named by purpose, not appearance
- [ ] No color names in token identifiers (no
--white,--blue-500) - [ ] Theme switching uses CSS custom properties with class/attribute toggle
- [ ] No component re-renders required for theme switching
- [ ] Dark mode detects system preference via
prefers-color-scheme - [ ] Manual theme override stored in
localStorage - [ ] Theme applied via
data-themeattribute on<html> - [ ] Long-session apps consider a three-option model (light/dim/dark)
- [ ] DTCG JSON format considered for token definitions
Related Skills
oborchers/using-planning-tools
tools
VerifiedTrustedCommunity
This skill should be used when the user invokes any /plan-* command from the planning-tools plugin (/plan-context, /plan-master, /plan-open-questions, /plan-verify, /plan-tick, /plan-progress, /plan-delete), asks how Claude Code's plan files work, asks where plans are stored, asks to author or audit a multi-phase master planning document, asks how to walk through a plan's Open Questions interactively, asks how to write progress entries, or mentions ~/.claude/plans/ or .claude/planning-tools.local.md. Provides the index of planning-tools commands, the master-plan workflow lifecycle, the v0.3.0+ list-shape mandate (phases and questions as headings + bulleted scope items, never tables), the v0.3.2+ plain-bullet shape (no `- [ ]` checkboxes — heading emoji is the sole tick signal), the progress-entry methodology, and the mechanics of Claude Code's plan-mode file storage.
15SKILL.mdUpdated May 13, 2026
oborchers/plan-verification-checklist
testing
VerifiedTrustedCommunity
This skill should be used by the plan-verifier agent and the /plan-verify command to audit a drafted master plan against a fixed checklist. Covers universal-core completeness, the v0.3.0+ no-tables-for-phases-or-questions rule, trigger-based section-coverage gaps, phase actionability (heading + per-phase TL;DR + bulleted scope + exit criteria), the v0.3.1+ per-phase TL;DR requirement, the v0.3.2+ plain-bullet scope shape (legacy `- [ ]`/`- [x]` accepted silently), the v0.3.3+ context-block shape (plan-level `**TL;DR:**` + bulleted metadata, legacy `>` blockquote accepted silently), integer phase numbering enforcement, dependency traceability, citation resolution, callout/evidence convention compliance, Open Questions placement, and the one-PR-per-master-plan rule. Single-owner of the audit checklist.
15SKILL.mdUpdated May 13, 2026
oborchers/master-plan-methodology
tools
VerifiedTrustedCommunity
This skill should be used when authoring, reviewing, or modifying a multi-phase master planning document via the planning-tools plugin (especially the /plan-master and /plan-verify commands). Codifies the universal core sections, trigger-based optional sections, integer-only phase numbering, Open Questions placement, one-PR-per-plan rule, status conventions, evidence attribution, callouts, cross-reference formats, the v0.3.0 list-shape mandate (phases and questions are heading + bulleted list, never markdown tables), the v0.3.1 per-phase TL;DR requirement (1–3 sentence what/why summary under each phase heading for glance-ability), the v0.3.2 plain-bullet scope shape (`- <action>` items, no `- [ ]` checkboxes — the phase status emoji is the sole tick signal), and the v0.3.3 context-block shape (a plan-level `**TL;DR:**` + a bulleted metadata list instead of a `>` blockquote; legacy blockquote blocks accepted silently). Project-agnostic — no ticket-prefix or plan-type taxonomy.
15SKILL.mdUpdated May 13, 2026
oborchers/whitespace-density
testing
VerifiedTrustedCommunity
This skill should be used when the user is adjusting spacing, padding, margins, content density, section gaps, vertical rhythm, or separation between elements. Also applies when reviewing whether a design feels cramped or too sparse, choosing between borders and whitespace for separation, or defining a spacing system. Covers the 4px/8px spacing system, macro vs micro whitespace, content density spectrum, separation techniques (whitespace > background shifts > borders), and vertical rhythm.
12SKILL.mdUpdated May 22, 2026