agentleFS
egregore-labsegregore-labs/egregore/.claude/skills/dark-mode/SKILL.md

dark-mode

Skill293 starsChanged 11 days agoMITView on GitHub

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.

5 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If a renderer emits style="color:#15212e", theming loses: CSS can re-theme a value only when the rendered value is itself a variable …

    line 31
  2. Very specific:

    Tokens: use the role tokens from contract.roleTokens: --paper --paper-2 --card, --ink --ink-soft --ink-faint, --line --line-soft, --t1 --t2 …

    line 38
  3. Very specific:

    Status colour: read meaning from the tone tokens, never from --t1..--t3 positions.

    line 39
  4. Distinctive:

    No hex or resolved color constant in any render path that emits inline styles.

    line 85
  5. Very specific:

    Every var(--x) the page uses is defined for both members of its pair (for sovereign: ledger and bedrock).

    line 86

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.