@k8ordo/color-scheme
v3.0.0
Published
The colour-scheme axis of an application, owned: the visitor's light / dark / system preference, kept in localStorage, resolved against the system, put on <html> before the first paint and kept there.
Maintainers
Readme
@k8ordo/color-scheme
The colour-scheme axis of an application, owned. The visitor's preference —
light, dark, or nothing, which follows the default (the system unless told
otherwise) — lives in localStorage through @k8ordo/state; one rule resolves
it against prefers-color-scheme; the result is the dark class on <html>,
put there by an inline script before the first paint and kept there after
hydration. A script in <head> and a provider do that; a hook reads it. @k8ordo/ui's
tokens read the class; Tailwind's dark: does too once the stylesheet declares
@custom-variant dark (&:where(.dark, .dark *)); — @k8ordo/ui/tailwind.css
already does.
Like every k8ordo package it assumes React 19 and Server Components, uses only what has reached Baseline newly available, and ships no polyfills or legacy fallbacks.
- Documentation: https://ordo.k8o.me/color-scheme
- Design guide: docs/GUIDE.md — shipped inside this package
Installation
npm install @k8ordo/color-scheme @k8ordo/state zod
# or
pnpm add @k8ordo/color-scheme @k8ordo/state zodPeer Dependencies
| Package | Version | Required | Needed for |
| --------------- | ------- | -------- | ------------------------------------------ |
| @k8ordo/state | ^3.0.0 | yes | where the preference lives (localStorage) |
| react | ≥19.3.0 | yes | the provider and the hook |
| zod | ^4.6.6 | yes | the one-field schema @k8ordo/state reads |
| typescript | ≥7.0.0 | optional | the shipped type declarations |
| @types/react | ≥19.3.0 | optional | the shipped type declarations |
Quick Start
The script goes in the root layout's <head>, and the provider inside
<body>, around everything. @k8ordo/framework writes the script ahead of
every stylesheet, which it has to be for the first paint to be right:
// src/routes/layout.tsx — a Server Component
import { ColorSchemeProvider, ColorSchemeScript } from '@k8ordo/color-scheme';
export default function RootLayout({ children }) {
return (
<html suppressHydrationWarning>
<head>
<ColorSchemeScript />
</head>
<body>
<ColorSchemeProvider>{children}</ColorSchemeProvider>
</body>
</html>
);
}A switcher reads and writes the preference:
'use client';
import { useColorScheme } from '@k8ordo/color-scheme';
export function SchemeSwitcher() {
const { scheme, setPreference } = useColorScheme();
return (
<button
onClick={() => setPreference(scheme === 'dark' ? 'light' : 'dark')}
type="button"
>
{scheme === 'dark' ? 'light mode' : 'dark mode'}
</button>
);
}scheme is what is on screen; preference is what the visitor asked for
('system' when nothing is stored); setPreference('system') stores none, so
the provider's default applies again. That default is the system unless told
otherwise: defaultPreference="dark" on both <ColorSchemeScript> and
<ColorSchemeProvider> starts every visitor dark until they choose.
The browser's own UI — the address bar, the status bar — follows the same
scheme once the script is given the colours: it writes the
<meta name="theme-color"> itself, and the provider keeps them in step.
<ColorSchemeScript themeColor={{ light: '#ffffff', dark: '#18181b' }} />AI Agent Documentation
The docs ship inside the package, so an agent always reads the exact version you installed — there is no snapshot to copy or re-sync on upgrade.
Point your agent at them once by pasting this into your project's CLAUDE.md /
AGENTS.md:
Use `@k8ordo/color-scheme` for light and dark mode. Before touching the
colour scheme, read `node_modules/@k8ordo/color-scheme/docs/GUIDE.md`. One
`<ColorSchemeScript />` goes in the root layout's `<head>` and one
`<ColorSchemeProvider>` wraps everything inside its `<body>`, with
`suppressHydrationWarning` on `<html>`; components read and change the
scheme through `useColorScheme()`. Never toggle the `dark` class, query
`prefers-color-scheme` for the scheme, or write the stored preference
yourself — the provider owns all three, and `setPreference` is the one way in.What each surface gives an agent:
| Surface | Where |
| -------------------------- | ------------------------------------------------- |
| Design guide (entry point) | node_modules/@k8ordo/color-scheme/docs/GUIDE.md |
| Docs index for LLMs | docs/llms.txt · https://ordo.k8o.me/llms.txt |
| Markdown twin on the web | https://ordo.k8o.me/color-scheme/docs/GUIDE.md |
License
MIT License - see LICENSE for details.
