@k8ordo/color-scheme 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Koki Sakano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @k8ordo/color-scheme
+
+The colour-scheme axis of an application, owned. The visitor's preference —
+light, dark, or nothing, which follows the system — 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. One provider does all
+of that; a hook reads it. `@k8ordo/ui`'s tokens, and Tailwind's own dark
+variant, read the class.
+
+Like every [k8ordo](https://ordo.k8o.me) 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](docs/GUIDE.md) — shipped inside this package
+
+## Installation
+
+```bash
+npm install @k8ordo/color-scheme @k8ordo/state zod
+# or
+pnpm add @k8ordo/color-scheme @k8ordo/state zod
+```
+
+## Peer Dependencies
+
+| Package         | Version | Needed for                                 |
+| --------------- | ------- | ------------------------------------------ |
+| `@k8ordo/state` | ≥0.2.0  | where the preference lives (localStorage)  |
+| `react`         | ≥19.3.0 | the provider and the hook                  |
+| `zod`           | ^4.4.3  | the one-field schema `@k8ordo/state` reads |
+| `typescript`    | ≥7.0.2  | the shipped type declarations (optional)   |
+
+## Quick Start
+
+The provider goes in the root layout, inside `<body>`, around everything. It
+renders the inline script itself, so nothing goes in `<head>`:
+
+```tsx
+// routes/layout.tsx — a Server Component
+import { ColorSchemeProvider } from '@k8ordo/color-scheme';
+
+export default function RootLayout({ children }) {
+  return (
+    <html suppressHydrationWarning>
+      <body>
+        <ColorSchemeProvider>{children}</ColorSchemeProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+A switcher reads and writes the preference:
+
+```tsx
+'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')` clears it.
+`<ColorSchemeProvider defaultPreference="dark">` starts every visitor dark
+until they choose.
+
+## AI Agent Documentation
+
+This package ships its documentation so an AI coding assistant reads the exact
+installed version:
+
+- `node_modules/@k8ordo/color-scheme/docs/GUIDE.md` — the design guide
+- `node_modules/@k8ordo/color-scheme/docs/llms.txt` — the index
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { ColorScheme, ColorSchemePreference, colorSchemeState } from "./scheme.mjs";
+import { ColorSchemeProvider, ColorSchemeProviderProps, UseColorScheme, useColorScheme } from "./provider.mjs";
+export { type ColorScheme, type ColorSchemePreference, ColorSchemeProvider, type ColorSchemeProviderProps, type UseColorScheme, colorSchemeState, useColorScheme };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { colorSchemeState } from "./scheme.mjs";
+import { ColorSchemeProvider, useColorScheme } from "./provider.mjs";
+export { ColorSchemeProvider, colorSchemeState, useColorScheme };

package/dist/provider.d.mts

@@ -0,0 +1,31 @@
+import { ColorScheme, ColorSchemePreference } from "./scheme.mjs";
+import { ReactNode } from "react";
+//#region src/provider.d.ts
+type UseColorScheme = {
+  /** What is on screen: the preference, or the system's answer. */
+  readonly scheme: ColorScheme;
+  /** What the visitor asked for; `'system'` when nothing is stored. */
+  readonly preference: ColorSchemePreference;
+  /** Stores a preference, or `'system'` to store none and follow it again. */
+  readonly setPreference: (preference: ColorSchemePreference) => void;
+};
+type ColorSchemeProviderProps = {
+  /**
+   * What applies while the visitor has chosen nothing. `'system'` follows
+   * `prefers-color-scheme`; a scheme starts every visitor there until they
+   * choose.
+   */
+  readonly defaultPreference?: ColorSchemePreference;
+  readonly children: ReactNode;
+};
+/**
+ * The one place the scheme is decided and written. Goes in the root
+ * layout, inside `<body>`, around everything: it renders the inline script
+ * that puts the class on `<html>` before the first paint, keeps the class
+ * in step afterwards, and hands `useColorScheme` what it reads.
+ */
+declare function ColorSchemeProvider({ defaultPreference, children }: ColorSchemeProviderProps): ReactNode;
+/** The visitor's colour scheme and a way to change it, from the provider above. */
+declare function useColorScheme(): UseColorScheme;
+//#endregion
+export { ColorSchemeProvider, ColorSchemeProviderProps, UseColorScheme, useColorScheme };

package/dist/provider.mjs

@@ -0,0 +1,58 @@
+"use client";
+import { DARK_CLASS, DARK_QUERY, colorSchemeState, resolve, scriptFor } from "./scheme.mjs";
+import { useAppState } from "@k8ordo/state";
+import { createContext, use, useCallback, useEffect, useMemo, useSyncExternalStore } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/provider.tsx
+const ColorSchemeContext = createContext(null);
+const subscribeSystem = (onChange) => {
+	const query = matchMedia(DARK_QUERY);
+	query.addEventListener("change", onChange);
+	return () => {
+		query.removeEventListener("change", onChange);
+	};
+};
+const readSystemDark = () => matchMedia(DARK_QUERY).matches;
+const serverSystemDark = () => false;
+const subscribeNever = () => () => {};
+const useReadsStore = () => useSyncExternalStore(subscribeNever, () => true, () => false);
+/**
+* The one place the scheme is decided and written. Goes in the root
+* layout, inside `<body>`, around everything: it renders the inline script
+* that puts the class on `<html>` before the first paint, keeps the class
+* in step afterwards, and hands `useColorScheme` what it reads.
+*/
+function ColorSchemeProvider({ defaultPreference = "system", children }) {
+	const [{ preference }, update] = useAppState(colorSchemeState);
+	const systemDark = useSyncExternalStore(subscribeSystem, readSystemDark, serverSystemDark);
+	const scheme = resolve(preference, defaultPreference, systemDark);
+	const readsStore = useReadsStore();
+	useEffect(() => {
+		if (!readsStore) return;
+		document.documentElement.classList.toggle(DARK_CLASS, scheme === "dark");
+	}, [readsStore, scheme]);
+	const setPreference = useCallback((next) => {
+		update({ preference: next === "system" ? void 0 : next });
+	}, [update]);
+	const value = useMemo(() => ({
+		scheme,
+		preference: preference ?? "system",
+		setPreference
+	}), [
+		scheme,
+		preference,
+		setPreference
+	]);
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("script", { children: scriptFor(defaultPreference) }), /* @__PURE__ */ jsx(ColorSchemeContext, {
+		value,
+		children
+	})] });
+}
+/** The visitor's colour scheme and a way to change it, from the provider above. */
+function useColorScheme() {
+	const value = use(ColorSchemeContext);
+	if (value === null) throw new Error("useColorScheme needs <ColorSchemeProvider> above it — put one in the root layout, inside <body>");
+	return value;
+}
+//#endregion
+export { ColorSchemeProvider, useColorScheme };

package/dist/scheme.d.mts

@@ -0,0 +1,36 @@
+import * as z from "zod/mini";
+//#region src/scheme.d.ts
+type ColorScheme = 'light' | 'dark';
+/** What the visitor asked for: a scheme, or to follow the system. */
+type ColorSchemePreference = ColorScheme | 'system';
+/**
+ * Where the preference lives: localStorage, under
+ * `k8ordo-state:color-scheme`. An absent `preference` is "nothing chosen",
+ * so a visitor who never chose is never pinned to what the system said on
+ * their first visit.
+ */
+declare const colorSchemeState: import("@k8ordo/state").LocalState<z.ZodMiniObject<{
+  preference: z.ZodMiniOptional<z.ZodMiniEnum<{
+    dark: "dark";
+    light: "light";
+  }>>;
+}, z.core.$strip>>;
+/** The media query the system answers through. */
+declare const DARK_QUERY = "(prefers-color-scheme: dark)";
+/** The class `@k8ordo/ui` — and Tailwind's own dark variant — read on `<html>`. */
+declare const DARK_CLASS = "dark";
+/**
+ * The one rule: what the visitor chose wins, then what the provider was
+ * told to start from, and `system` — the default's default — asks the
+ * system.
+ */
+declare const resolve: (preference: ColorScheme | undefined, defaultPreference: ColorSchemePreference, systemDark: boolean) => ColorScheme;
+/**
+ * The inline script the provider renders before its children: the rule
+ * above, run before the first paint. The schema does not run there, so the
+ * stored value is checked by hand and anything else reads as nothing
+ * chosen — the same salvage the store applies.
+ */
+declare const scriptFor: (defaultPreference: ColorSchemePreference) => string;
+//#endregion
+export { ColorScheme, ColorSchemePreference, DARK_CLASS, DARK_QUERY, colorSchemeState, resolve, scriptFor };

package/dist/scheme.mjs

@@ -0,0 +1,31 @@
+import { defineLocalState } from "@k8ordo/state";
+import * as z from "zod/mini";
+//#region src/scheme.ts
+/**
+* Where the preference lives: localStorage, under
+* `k8ordo-state:color-scheme`. An absent `preference` is "nothing chosen",
+* so a visitor who never chose is never pinned to what the system said on
+* their first visit.
+*/
+const colorSchemeState = defineLocalState("color-scheme", z.object({ preference: z.optional(z.enum(["light", "dark"])) }));
+/** The media query the system answers through. */
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+/** The class `@k8ordo/ui` — and Tailwind's own dark variant — read on `<html>`. */
+const DARK_CLASS = "dark";
+/**
+* The one rule: what the visitor chose wins, then what the provider was
+* told to start from, and `system` — the default's default — asks the
+* system.
+*/
+const resolve = (preference, defaultPreference, systemDark) => {
+	return preference ?? (defaultPreference === "system" ? void 0 : defaultPreference) ?? (systemDark ? "dark" : "light");
+};
+/**
+* The inline script the provider renders before its children: the rule
+* above, run before the first paint. The schema does not run there, so the
+* stored value is checked by hand and anything else reads as nothing
+* chosen — the same salvage the store applies.
+*/
+const scriptFor = (defaultPreference) => `(()=>{const s=${colorSchemeState.inlineRead()};const v=s&&s.preference;const p=v==="dark"||v==="light"?v:${JSON.stringify(defaultPreference)};if(p==="dark"||(p!=="light"&&matchMedia(${JSON.stringify(DARK_QUERY)}).matches))document.documentElement.classList.add(${JSON.stringify(DARK_CLASS)})})()`;
+//#endregion
+export { DARK_CLASS, DARK_QUERY, colorSchemeState, resolve, scriptFor };

package/docs/GUIDE.md

@@ -0,0 +1,130 @@
+# @k8ordo/color-scheme
+
+The colour-scheme axis of an application, owned.
+
+A visitor's colour scheme is three things that have to agree: what they
+asked for, what the system says, and what is on screen. This package keeps
+the first in localStorage (through `@k8ordo/state`), reads the second from
+`prefers-color-scheme`, and resolves both into the third — the `dark` class
+on `<html>`, which `@k8ordo/ui`'s tokens and Tailwind's own dark variant
+read. One provider does all of it: it renders the inline script that puts
+the class there before the first paint, keeps it right after hydration, and
+hands a hook what it reads.
+
+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.
+
+## What it does not own
+
+- **The colours.** Which colour `dark` means is the stylesheet's business —
+  `@k8ordo/ui`'s tokens, or any other that reads the class.
+- **Where the preference lives.** That is `@k8ordo/state`'s
+  `defineLocalState`; this package declares one and reads it, so the key
+  and the JSON envelope are never spelled here.
+- **A guess on the server.** No cookie, no header: a server render shows
+  the provider's default, and the inline script is what makes the first
+  paint right.
+
+## The shape of it
+
+```
+routes/layout.tsx   <body><ColorSchemeProvider>{children}</ColorSchemeProvider></body>
+                        │ renders <script> first → class on <html> before the first paint
+                        │ reads the store + the system → keeps the class in step
+components          useColorScheme() → { scheme, preference, setPreference }
+```
+
+## Setup
+
+The provider goes in the root layout — a Server Component — inside `<body>`
+and around everything, so the script it renders comes before anything the
+page paints:
+
+```tsx
+// routes/layout.tsx
+import { ColorSchemeProvider } from '@k8ordo/color-scheme';
+import type { ReactNode } from 'react';
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <ColorSchemeProvider>{children}</ColorSchemeProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+`suppressHydrationWarning` on `<html>`, because the script adds a class the
+server did not render — that difference is the point, not a mistake.
+
+Nothing else is required: the first paint is right, and a visitor who
+never chooses follows the system, in either direction, for as long as the
+page is open. To start every visitor somewhere other than the system, say
+so once: `<ColorSchemeProvider defaultPreference="dark">`.
+
+## Reading and changing it
+
+```tsx
+'use client';
+
+import { useColorScheme } from '@k8ordo/color-scheme';
+
+export function SchemeSwitcher() {
+  const { scheme, preference, setPreference } = useColorScheme();
+  return (
+    <select
+      onChange={(event) =>
+        setPreference(event.currentTarget.value as typeof preference)
+      }
+      value={preference}
+    >
+      <option value="system">system ({scheme})</option>
+      <option value="light">light</option>
+      <option value="dark">dark</option>
+    </select>
+  );
+}
+```
+
+| Member          | What it is                                                                |
+| --------------- | ------------------------------------------------------------------------- |
+| `scheme`        | `'light' \| 'dark'` — what is on screen.                                  |
+| `preference`    | `'light' \| 'dark' \| 'system'` — what the visitor asked for.             |
+| `setPreference` | Stores a preference; `'system'` stores none and follows the system again. |
+
+A toggle is `setPreference(scheme === 'dark' ? 'light' : 'dark')`. The hook
+reads the provider and touches nothing else, so a switcher and a preview
+agree because there is one provider deciding.
+
+`colorSchemeState` is the `defineLocalState` definition itself, exported for
+anything that wants the row without the hook — `useAppState(colorSchemeState)`,
+or `colorSchemeState.storageKey` in a test.
+
+## What it guarantees
+
+- **No flash.** The script runs before the first paint and reads the same
+  row the provider writes; a dark page loads dark.
+- **Nothing chosen follows the default, and the default follows the
+  system.** A visitor who never chose is never pinned to what the system
+  said on their first visit, and a row an older version wrote, or one that
+  is not JSON, reads as nothing chosen.
+- **The server renders the default**, and the provider corrects itself on
+  hydration without touching the document: the render that hydrates reads
+  the server's guesses and writes nothing, and the render that follows reads
+  the store and writes what the script already put there. Until then the
+  HTML shows the default — a switcher's icon, say — which is the one thing
+  no server can know; a component that must not show it even for a moment
+  says so with React's `use(browser())` under a `<Suspense>`.
+- **Tabs agree.** The preference propagates across tabs through the
+  `storage` event, as any `@k8ordo/state` local state does.
+
+## Testing
+
+Under a browser, `localStorage.clear()`, remove the class from
+`document.documentElement`, and `resetStateRegistry()` from `@k8ordo/state`
+between tests; render the hook under `<ColorSchemeProvider>` (a `wrapper`).
+A client-only mount also runs the script the provider renders — a script
+element React creates executes — which is idempotent with the effect.

package/docs/llms.txt

@@ -0,0 +1,37 @@
+# @k8ordo/color-scheme
+
+> The colour-scheme axis of an application, owned. The visitor's preference
+> — light, dark, or nothing, which follows the system — lives in
+> localStorage through `@k8ordo/state`; one rule resolves it against
+> `prefers-color-scheme`; the result is the `dark` class on `<html>` (what
+> `@k8ordo/ui` and Tailwind's dark variant read). `<ColorSchemeProvider>` in
+> the root layout renders the inline script that puts the class on before
+> the first paint and keeps it in step afterwards; `useColorScheme()` reads
+> it. The server renders the default.
+>
+> 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.
+
+When installed via npm, these docs live under `node_modules/@k8ordo/color-scheme/docs/`.
+
+## Guide
+
+- [Design Guide](GUIDE.md): what the package owns and does not (the class,
+  not the colours; the rule, not the storage), placing the provider in the
+  root layout, reading and changing the preference with the hook, what it
+  guarantees, and testing.
+
+## Entry point
+
+- `@k8ordo/color-scheme` — `<ColorSchemeProvider defaultPreference?>`
+  (client; goes inside `<body>` around everything) renders the inline
+  `<script>` that puts `dark` on `<html>` before the first paint from the
+  stored preference, the default (`'system'` unless told otherwise), or the
+  system, and keeps the class in step. `useColorScheme()` returns
+  `{ scheme, preference, setPreference }`: `scheme` is `'light' | 'dark'`
+  on screen, `preference` is `'light' | 'dark' | 'system'`, and
+  `setPreference('system')` clears the stored row. `colorSchemeState` is the
+  `@k8ordo/state` local definition itself (`k8ordo-state:color-scheme`).
+  Types: `ColorScheme`, `ColorSchemePreference`, `ColorSchemeProviderProps`,
+  `UseColorScheme`.

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@k8ordo/color-scheme",
+  "version": "0.1.0",
+  "description": "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.",
+  "keywords": [
+    "color-scheme",
+    "dark-mode",
+    "prefers-color-scheme",
+    "react",
+    "server-components",
+    "theme"
+  ],
+  "homepage": "https://ordo.k8o.me",
+  "bugs": {
+    "url": "https://github.com/k35o/k8ordo/issues"
+  },
+  "license": "MIT",
+  "author": "k8o <kosakanoki@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k35o/k8ordo.git"
+  },
+  "files": [
+    "dist/**",
+    "docs/**"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@k8ordo/state": "^0.2.0",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-react": "6.1.1",
+    "@vitest/browser-playwright": "5.0.0",
+    "publint": "0.3.24",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "7.0.2",
+    "vite": "8.2.2",
+    "vite-plus": "0.3.0",
+    "vitest": "5.0.0",
+    "vitest-browser-react": "2.3.0",
+    "zod": "4.5.4"
+  },
+  "peerDependencies": {
+    "@k8ordo/state": "^0.2.0",
+    "@types/react": ">=19.3.0",
+    "react": ">=19.3.0",
+    "typescript": ">=7.0.2",
+    "zod": "^4.4.3"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit",
+    "check": "vp check",
+    "check:write": "vp check --fix",
+    "check:package": "publint && attw --pack . --profile esm-only"
+  }
+}