egregore-labs/egregore / .claude/skills/dark-mode
dark-mode
VerifiedUse when authoring or modifying browser-rendered visual output: HTML, CSS, React SSR, artifact templates, markdown renderers, design tokens, themes, or composed pages. Do not invoke for an ordinary /view render—the checked-in renderer already owns its theme contract. The load-bearing rule is that theme-sensitive colors must be emitted as `var(--token)`, never resolved inline hex; the colors themselves come from the design system registry.
Dark Mode
Voice Complex
This skill governs browser visual rendering: theme tokens and theme behavior. It carries no palette; every color comes from the design system.
Shared aesthetic: voice-bedrock (.claude/rules/voice-bedrock.md).
For pair routing, component profiles, or adding a pair: packages/design-system/skill/SKILL.md.
For terminal rendering: tui-design skill.
For product copy in rendered pages: product-voice skill.
For prose content in rendered pages: egregore-voice skill.
When to invoke
User says: "dark mode", "theme toggle", "color system", "card surface", "make this work in dark mode", or any request to generate or modify browser-rendered visual output (HTML, CSS, React SSR, Egregore artifacts, design tokens).
Not this:
- An ordinary deterministic
/viewrender; the checked-in renderer already owns and tests its theme contract - TUI terminal output; use
tui-design - Plain markdown files that do not render styled HTML
- Backend or CLI code with no visual surface
The rule
If a renderer emits style="color:#15212e", theming loses: CSS can re-theme a value only when the rendered value is itself a variable reference. Every theme-sensitive color, in a stylesheet or an inline style prop, is var(--token) at the render site.
Where colors come from
- Registry:
packages/design-system/themes/registry.jsonholds every palette pair and its theme tokens. The default pair isregistry.routing.defaultPair, currentlysovereign(ledgerlight,bedrockdark: cool stone with verdigris and steel accents). Use another registered pair only when the content matches that pair'ssemantics.useWhenand you can state the reason. - CSS: inline the committed, generated
packages/design-system/dist/egregore-design.css. It defines each theme as a[data-theme="<theme id>"]block plus legacy aliases (--bg,--text,--accentand the rest). Never copy its values into a page and never edit it by hand;npm run buildinpackages/design-systemregenerates it from the registry. - Without the design package: public and downstream instances do not carry
packages/design-system. The same files ship vendored inegregore-artifacts, both in a checked-outpackages/egregore-artifactsand in the installed package:lib/vendor/design-system/themes/registry.jsonandlib/vendor/design-system/dist/egregore-design.css. - Tokens: use the role tokens from
contract.roleTokens:--paper --paper-2 --card,--ink --ink-soft --ink-faint,--line --line-soft,--t1 --t2 --t3with their-bgwashes, the tone tokens--ok --note --warn --critical --neutralwith their-bgwashes,--series-1to--series-5with--chart-grid --chart-axisfor charts, and--grain --shadow. - Status colour: read meaning from the tone tokens, never from
--t1..--t3positions. The meaning is the same in every pair:--okdecided or done,--noteaside or context,--warnowed or gated,--criticalblocked or at risk,--neutralbackground or later. - No local palette: a page or a skill never defines its own theme colors. If the role tokens do not cover a color you need, that is a registry change; see the design system skill.
Highlights
No side stripes: a coloured bar down one side of a box is retired in every render. Mark reading emphasis with a marker under the words (.eg-mark), a label in the margin (.eg-margin holding an .eg-label) or a quote with a hanging opening mark (.eg-quote). Mark status with a quiet panel (.eg-panel) whose .eg-label carries the tone's shape (● ok, ◆ note, ▲ warn, ■ critical, ○ neutral), so the state reads without colour and in both themes. A selected item gets weight plus a filled shape, never a stripe. The classes are RECIPE_CSS in packages/egregore-artifacts/lib/recipe.js, which the kit's shell injects into every render; the design system skill has the full rule.
The theme contract
The kit's renderers set three attributes on <html>:
| Attribute | Value | Role |
|---|---|---|
data-theme | resolved theme id, e.g. ledger or bedrock | the only CSS selector |
data-theme-pair | pair id, e.g. sovereign | names the family; never a CSS selector |
data-theme-mode | auto, light or dark | the reader's choice |
- Persist only the mode. Resolve it through the pair:
autofollowsprefers-color-scheme, with the local clock as the fallback, and the result writes the pair's light or dark member intodata-theme. - Resolve before paint, in a blocking
<head>script. - Storage can throw in sandboxed and private pages: wrap every read and write in try/catch and keep the mode in memory.
- Reference implementation: the theme script in
packages/egregore-artifacts/lib/shell.js(a three-state toggle,light → auto → dark). Reuse its structure; do not write a second engine.
Anti-Patterns
| Pattern | Why It Breaks | Instead |
|---|---|---|
style={{ color: palette.ink }} with a JS constant | SSR resolves the constant to a fixed hex, so the theme cannot override it | style={{ color: 'var(--ink)' }} or a class |
background: white on cards | The card stays white in a dark theme | background: var(--card) |
border: 1px solid rgba(0, 0, 0, 0.08) | A light-only value inside a themeable component | var(--line) or var(--line-soft) |
[data-theme="dark"] overrides or .dark-* classes | Theme ids are names like bedrock, and role tokens already flip per resolved theme | Style with role tokens; add no per-mode overrides |
Selecting on data-theme-pair | The pair names the family; it is not a selector | Use role tokens, or [data-theme="<theme id>"] when one theme needs its own rule |
opacity: 0.5 on colored text | Contrast changes unpredictably between themes | var(--ink-soft) or var(--ink-faint) |
@media (prefers-color-scheme: dark) as the only mechanism | No manual override and no persistence | The three-state mode above |
Theme state on body or a wrapper div | Portals, overlays and shells fall out of sync | The three attributes on <html> |
| Restoring the saved mode after the page renders | A flash of the wrong theme | A blocking <head> script |
Context Modes
- Egregore artifacts (
packages/egregore-artifacts): the shell inlines the design CSS, bridges legacy chrome names onto role tokens, and runs the theme script. Component code uses role tokens only. - Python pages (
api/):api/design_system.py(design_head,html_attrs,bridge_css) reads the same dist CSS and registry as static files. - Standalone HTML: inline the dist CSS, set the three attributes on
<html>, and add the<head>theme script. - Tailwind: map utilities to role-token variables (for example
ink: 'var(--ink)'); do not use thedark:variant for theme colors. - Email HTML: the one context where
@media (prefers-color-scheme: dark)with!importantis correct. Build no JS toggle, and optimize for legibility over parity.
Pre-Ship Checklist
- No hex or resolved color constant in any render path that emits inline styles.
- Every
var(--x)the page uses is defined for both members of its pair (forsovereign:ledgerandbedrock). <html>carries all three attributes, and the mode is restored in<head>before paint.- The toggle cycles
light → auto → dark; the choice survives a reload where storage works, and nothing throws where it does not. - Print and phone-width layouts still work.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |