Skip to content

egregore-labs/egregore / .claude/skills/dark-mode

dark-mode

Verified

Use 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 /view render; 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.json holds every palette pair and its theme tokens. The default pair is registry.routing.defaultPair, currently sovereign (ledger light, bedrock dark: cool stone with verdigris and steel accents). Use another registered pair only when the content matches that pair's semantics.useWhen and 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, --accent and the rest). Never copy its values into a page and never edit it by hand; npm run build in packages/design-system regenerates it from the registry.
  • Without the design package: public and downstream instances do not carry packages/design-system. The same files ship vendored in egregore-artifacts, both in a checked-out packages/egregore-artifacts and in the installed package: lib/vendor/design-system/themes/registry.json and lib/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 --t3 with their -bg washes, the tone tokens --ok --note --warn --critical --neutral with their -bg washes, --series-1 to --series-5 with --chart-grid --chart-axis for charts, and --grain --shadow.
  • Status colour: read meaning from the tone tokens, never from --t1..--t3 positions. The meaning is the same in every pair: --ok decided or done, --note aside or context, --warn owed or gated, --critical blocked or at risk, --neutral background 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>:

AttributeValueRole
data-themeresolved theme id, e.g. ledger or bedrockthe only CSS selector
data-theme-pairpair id, e.g. sovereignnames the family; never a CSS selector
data-theme-modeauto, light or darkthe reader's choice
  • Persist only the mode. Resolve it through the pair: auto follows prefers-color-scheme, with the local clock as the fallback, and the result writes the pair's light or dark member into data-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

PatternWhy It BreaksInstead
style={{ color: palette.ink }} with a JS constantSSR resolves the constant to a fixed hex, so the theme cannot override itstyle={{ color: 'var(--ink)' }} or a class
background: white on cardsThe card stays white in a dark themebackground: var(--card)
border: 1px solid rgba(0, 0, 0, 0.08)A light-only value inside a themeable componentvar(--line) or var(--line-soft)
[data-theme="dark"] overrides or .dark-* classesTheme ids are names like bedrock, and role tokens already flip per resolved themeStyle with role tokens; add no per-mode overrides
Selecting on data-theme-pairThe pair names the family; it is not a selectorUse role tokens, or [data-theme="<theme id>"] when one theme needs its own rule
opacity: 0.5 on colored textContrast changes unpredictably between themesvar(--ink-soft) or var(--ink-faint)
@media (prefers-color-scheme: dark) as the only mechanismNo manual override and no persistenceThe three-state mode above
Theme state on body or a wrapper divPortals, overlays and shells fall out of syncThe three attributes on <html>
Restoring the saved mode after the page rendersA flash of the wrong themeA 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 the dark: variant for theme colors.
  • Email HTML: the one context where @media (prefers-color-scheme: dark) with !important is correct. Build no JS toggle, and optimize for legibility over parity.

Pre-Ship Checklist

  1. No hex or resolved color constant in any render path that emits inline styles.
  2. Every var(--x) the page uses is defined for both members of its pair (for sovereign: ledger and bedrock).
  3. <html> carries all three attributes, and the mode is restored in <head> before paint.
  4. The toggle cycles light → auto → dark; the choice survives a reload where storage works, and nothing throws where it does not.
  5. Print and phone-width layouts still work.
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall