Dark Theme

System-aware light/dark theming with a manual override, one hook for the whole app.

adds it to an existing project · no account needed

Currentas published in v1.5.1

The rule

This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.

Read colors through useTheme() / themeTokens[theme] — never hardcode a hex value in a component. A hardcoded #ffffff background is invisible in light mode and a solid white box in dark mode.
Three states, not two: light, dark, system. Default to system — overriding it should be something a user opts into, not the starting state.
The provider renders nothing (mobile) or nothing themed (web, via data-theme) until the stored preference loads. Do not remove that guard to "fix" a perceived flash — removing it reintroduces the flash it exists to prevent.
On web, toggle the theme via the data-theme attribute on <html>/documentElement, never a class — it is what [data-theme="dark"] selectors in CSS expect, and changing the mechanism silently breaks every rule written against it.

6 formats, one per tool

Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.

.cursor/rules/dark-theme.mdchand-written

---
description: Dark theme conventions
globs: ["src/theme/**/*.ts", "src/theme/**/*.tsx"]
alwaysApply: false
---

# Dark Theme

- Read colors through `useTheme()` / `themeTokens[theme]` — never hardcode a
  hex value in a component. A hardcoded `#ffffff` background is invisible in
  light mode and a solid white box in dark mode.
- Three states, not two: `light`, `dark`, `system`. Default to `system` —
  overriding it should be something a user opts into, not the starting state.
- The provider renders nothing (mobile) or nothing themed (web, via
  `data-theme`) until the stored preference loads. Do not remove that guard
  to "fix" a perceived flash — removing it reintroduces the flash it exists
  to prevent.
- On web, toggle the theme via the `data-theme` attribute on
  `<html>`/`documentElement`, never a class — it is what `[data-theme="dark"]`
  selectors in CSS expect, and changing the mechanism silently breaks every
  rule written against it.

Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.

What else this module writes

The rule is one file of several. Selecting Dark Theme contributes all of this too — merged with every other module you pick, with conflicts resolved rather than duplicated.

Dependencies

Depends on the rest of the stack — this module installs different packages depending on what else you select, so there is no single list to show.

Folders

src/theme/

Advisory history

Every time this rule turned out to be wrong, and what we did about it.

No corrections yet

This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.

Pro tells you the day a correction lands that affects a repo you actually have.

See what Pro adds →

Put this rule in a real project

The wizard picks the rest of the stack with you, writes all 6 formats, and leaves a manifest so check can tell you when any of it drifts.