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
- dresar/ui-skill-2045their own version, first seen Nov 16, 2026
- ArnavPuri/designskillstheir own version, first seen Nov 1, 2026
- Marvellbrazil/my-agentic-skillstheir own version, first seen Oct 17, 2026
- YepAPI/skillstheir own version, first seen Apr 12, 2026
- dylantarre/design-system-skillstheir own version, first seen Dec 30, 2025
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- dylantarre/design-system-skills★ 50same name
- ArnavPuri/designskills★ 17same name
- YepAPI/skills★ 8same name
- Marvellbrazil/my-agentic-skills★ 4same name
- dresar/ui-skill-2045★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository50 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- activitySkill
- announceSkill
- archiveSkill
- branchSkill
- checkupSkill
- commitSkill
- contributeSkill
- create-skillSkill
- dashboardSkill
- deep-reflectSkill
- delete-userSkill
- emissarySkill
- envSkill
- handoffSkill
- harvestSkill
- ingest-corpusSkill
- ingest-notionSkill
- ingestSkill
- ingest-user-interviewSkill
- inviteSkill
- issueSkill
- meetingSkill
- meSkill
- noteSkill
- notion-connectSkill
- onboardingSkill
- prSkill
- pullSkill
- pushSkill
- questSkill
- recordsSkill
- reflectSkill
- review-prSkill
- saveSkill
- slack-connectSkill
- summonSkill
- sync-reposSkill
- telegram-connectSkill
- telemetrySkill
- testSkill
- the-spiralSkill
- tui-designSkill
- tutorialSkill
- updateSkill
- viewSkill
- visual-explainSkill
- wrapSkill
- preview-designSkill
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
- Very specific: line 31
If a renderer emits style="color:#15212e", theming loses: CSS can re-theme a value only when the rendered value is itself a variable …
- Very specific: line 38
Tokens: use the role tokens from contract.roleTokens: --paper --paper-2 --card, --ink --ink-soft --ink-faint, --line --line-soft, --t1 --t2 …
- Very specific: line 39
Status colour: read meaning from the tone tokens, never from --t1..--t3 positions.
- Distinctive: line 85
No hex or resolved color constant in any render path that emits inline styles.
- Very specific: line 86
Every var(--x) the page uses is defined for both members of its pair (for sovereign: ledger and bedrock).
“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.
Files
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.
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
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.

