# Dark mode

How dark mode works in Frakment and how to wire it per framework.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

Frakment ships dark mode through CSS variables. Every token has a light and dark value. Toggling the `.dark` class on `<html>` swaps the entire palette, no JavaScript required at the component level.

This page covers the CSS layer. Framework guides cover how to toggle the class on load without a flash.

## How it works [#how-it-works]

Every token in `theme.css` has two values:

```css title="theme.css"
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --muted: oklch(0.97 0 0);
  --border: oklch(0.92 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --border: oklch(1 0 0 / 10%);
}
```

`@custom-variant dark (&:is(.dark *))` registers the `dark:` Tailwind variant. It activates whenever a `.dark` ancestor exists, so components can scope overrides locally:

```tsx
<div className="bg-background dark:bg-muted">
```

## Toggle the class [#toggle-the-class]

Add or remove `dark` on the `<html>` element. Any of these works:

- **`next-themes`** - handles persistence, system preference, and FOUC
- **A manual script** - reads `localStorage` and sets the class before hydration
- **A cookie** - server-readable, no flash on first paint

The framework guides below cover each path.

## Framework guides [#framework-guides]

<div className="mt-8 grid gap-4 sm:grid-cols-2 sm:gap-6">

<LinkedCard href="/docs/guides/dark-mode/next">
<BrandIcon />

<p className="mt-2 font-medium">Next.js</p>
</LinkedCard>

<LinkedCard href="/docs/guides/dark-mode/vite">
<BrandIcon />

<p className="mt-2 font-medium">Vite</p>
</LinkedCard>

<LinkedCard href="/docs/guides/dark-mode/astro">
<BrandIcon />

<p className="mt-2 font-medium">Astro</p>
</LinkedCard>

<LinkedCard href="/docs/guides/dark-mode/remix">
<BrandIcon />

<p className="mt-2 font-medium">Remix</p>
</LinkedCard>

</div>

## System preference [#system-preference]

Respect the OS setting on first load with `prefers-color-scheme`:

```css title="globals.css"
@media (prefers-color-scheme: dark) {
  :root:not(.light) {
    /* dark tokens */
  }
}
```

`next-themes` and the framework guides handle this automatically. Only add the media query if you do not use a theme library.

## Per-section theming [#per-section-theming]

Force a section to stay light or dark regardless of the page theme:

```tsx
<div className="light bg-background text-foreground">
  {/* always light */}
</div>

<div className="dark bg-background text-foreground">
  {/* always dark */}
</div>
```

The `dark` class on any ancestor activates the `dark:` variant for its subtree. The `light` class removes `.dark` from that subtree.

## Accessibility [#accessibility]

- **Do not toggle on scroll.** Users set their preference once.
- **Respect the OS preference on first visit.** All guides start with `system`.
- **Contrast is guaranteed at the token level.** `foreground` and `background` meet WCAG AA in both modes.
- **Animate the swap only on explicit toggle.** Use `disableTransitionOnChange` from `next-themes`.

## Next [#next]

- [Theming](/docs/guides/theming) - token reference
- [Next.js dark mode](/docs/guides/dark-mode/next) - App Router setup
- [Components](/docs/components) - browse the catalog