design-tokens-and-naming

Use when defining, naming, mapping, or exporting primitive, semantic, and component design tokens for colour, type, space, radius, elevation, motion, themes, or brands. Use component-library-architecture for component APIs and design-handoff-and-dev-spec for screen delivery.

仓库: peterbamuhigire/design-system-skills
最近来源活动: 2026年7月13日 08:02
检测到的 SKILL.md 语言: 英语
星标: 3
分支: 1

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

返回搜索返回安装

09-…/dark-mode-and-theming

Artefact or context	Source	Required?	Why
Approved colour, type, space, radius, elevation, and motion decisions	Upstream design skills	yes	Tokens encode rather than invent decisions
Theme, brand, density, and platform axes	Product architecture	yes	Determines semantic remapping boundaries
Consumer inventory and export targets	Repositories and platform owners	yes	Prevents unusable or colliding contracts

Separate the three tiers before naming anything. A token system that conflates them is the structural cause of drift.
- Primitive (a.k.a. global/option) tokens — raw, context-free values: the full colour ramps, the type sizes, the space scale. Named by what they are, never where they're used: color.blue.500, space.4, font.size.300. Components must NEVER reference these directly.
- Semantic (a.k.a. alias/system) tokens — role names that point at primitives and carry intent: color.text.default, color.surface.raised, color.action.primary.bg, space.inset.md. This is the only tier a theme (dark, brand) re-points. It is the contract.
- Component tokens — the most specific tier, scoped to one component, pointing at semantic tokens: button.primary.bg, card.padding, input.border.focus. They exist so a single component can be retuned without touching the shared semantic layer. Each tier references only the tier above it: component → semantic → primitive → literal value. Never let a component reach past semantic to a primitive — that is the single most common failure and it silently breaks theming. See references/token-tiers-and-naming.md.
Set one naming convention and hold it. Use a consistent, hierarchical namespace.category.concept.property.variant.state shape (drop segments that don't apply), lower-kebab or dot-delimited, no abbreviations that aren't in a stated glossary. Decide plural-vs-singular, and decide your scale unit names (100–900 numeric, or xs…3xl t-shirt) once. A name must say its tier: a reader should tell a primitive from a semantic token by the name alone. Banned names: anything that bakes a literal value into a role (color.text.blue), positional cruft (color.box-2), or a primitive masquerading as a role.
Make semantic tokens the theming seam — never the primitives. Light/dark, each brand, and each density mode are expressed by re-pointing the semantic layer at different primitives. Components and their tokens stay byte-identical across themes; only the alias targets change. This is what lets one component set serve N brands and both modes. For the dark remap, do NOT invert lightness — dark surfaces want lower chroma and a near-dark grey carrying the brand hue, accents usually lighten and slightly desaturate; re-run the contrast gate for the dark roles independently (doctrine colour rule; 02-…/color-system-and-palette workflow). See examples/semantic-mapping.md.
Encode colour primitives in OKLCH, not hex. Author the ramps in OKLCH (oklch(L C H)): lightness is perceptual so ramp steps are actually even, hue stays put while you adjust chroma, and generating a dark variant or a sibling brand is a controlled L/C move rather than eyeballed hex-twiddling. Keep a hex fallback for legacy/email targets in the same token. This is the perceptual-uniformity rule from the colour system, carried into the token layer.
Hold every themed semantic pair to the WCAG gate as a token-level invariant. A token set is a promise that any sanctioned foreground/surface pairing passes: body/small text ≥ 4.5:1, large text (≥24px or ≥18.66px bold) and meaningful UI/icons/focus ≥ 3:1 (doctrine/references/wcag-2.2-criteria.md, WCAG 1.4.3/1.4.11). Verify the pairs in each theme — light passing does not imply dark passing. Record the results next to the tokens; a token that can produce a failing pair is a bug, not a style choice.
Tokenise type, space, radius, elevation, and motion too — not just colour. Type sizes off a real ratio (≥1.25; doctrine type-scale-and-spacing.md), space as multiples of one unit (4 or 8px), a small radius set, an elevation set (shadow tokens that also remap for dark, where elevation reads as lighter surface + lower-chroma shadow), and motion duration/easing tokens. One rhythm, named once, is what separates "designed" from "assembled."
Choose the export topology, then generate. Single source of truth = the tier'd token file (JSON, ideally aligned to the W3C Design Tokens $value/$type format). Transform out to: CSS custom properties (semantic tokens become :root / [data-theme="dark"] / [data-brand] vars), a JSON consumed by app code, a Tailwind theme, and native platforms — via Style Dictionary so all targets derive from one source and cannot drift. See references/token-export-formats.md and examples/tokens.json.
Document references, not values. The handoff is the semantic role map and the alias graph, so engineering wires components to roles. A spec that lists hexes per component instead of role names has already lost the plot. Hand the wired tokens to 09-…/component-library-architecture and 09-…/design-handoff-and-dev-spec.
Treat Apple materials as platform aliases, not primitives. Liquid Glass, vibrancy, system backgrounds, SF Symbols rendering modes, and app icon variants should be named as semantic platform roles with fallbacks. Do not hardcode a fake glass color or shadow token and call it Liquid Glass; the platform material remains owned by the OS.

Condition	Action	Wrong-choice failure
One product and one theme	Keep three tiers but avoid speculative brand/platform aliases	Premature abstraction makes tokens harder to use
Dark mode or multiple brands are confirmed	Remap semantic roles; do not fork primitive/component contracts	Theme copies drift and components bypass intent
Existing code uses raw values	Inventory usage, define aliases, and migrate incrementally	A big-bang rename breaks consumers and destroys traceability
Platform-owned material has no portable equivalent	Use a semantic platform alias with documented fallback	A fake literal token impersonates native behaviour

Artefact	Consumer	Evidence and acceptance condition
Three-tier token source and naming contract	Component and theme skills	Primitive, semantic, and component boundaries are machine-readable and documented
Theme/brand maps and platform exports	Product repositories	Contrast and schema checks pass for each supported transform or are marked unverified
Migration map	Engineering owners	Existing values and aliases have a staged compatibility path