---
slug: sample-dark-mode-toggle
title: Dark mode toggle
status: in-spec
risk: low
authors: [you@example.com]
created: 2026-04-01
updated: 2026-04-12
references: []
sample: true   # delete this file once you're done test-driving
---

# PRD — Dark mode toggle

> **This is a sample artifact** seeded by `fastpace init --sample`.
> It exists so the dashboard isn't empty when you run `fastpace ui` for
> the first time. Delete the whole `sample-*` set once you're done
> kicking the tires.

## Why

Users on the dashboard and docs pages have asked for a dark theme so
they can read late-night without their eyes melting. The infra is
already CSS-variable driven, so this is a small front-end-only change
with a clear UX win.

## Outcome

A persistent **toggle in the top nav** that switches the site between
the existing dark theme (current default) and a new light theme. The
choice persists across reloads via `localStorage`. Respects the
`prefers-color-scheme` system setting on first visit.

## Out of scope

- A third "auto" theme that switches based on time of day.
- Per-page theme overrides.
- Theming third-party embeds (Mermaid, code highlighters) — those keep
  their existing themes for now.

## Success metrics

- Toggle ships in <5 days of dev work.
- Theme choice survives a hard reload (no flash of wrong theme).
- 0 accessibility regressions (color contrast remains AA in light mode).

## Open questions

- Should the toggle be icon-only or have a label? *(Decided: icon-only,
  matching the GitHub link styling already in the nav.)*
- What color tokens does the marketing team want for light mode? *(Punt
  to ERD — pick neutral defaults, iterate.)*