@d4gger/design-system 2.7.0

package/dist/docs/theme-guide.md

@@ -0,0 +1,648 @@
+# Theme Guide
+
+This guide covers the package's theme system: `ThemeProvider`, `useTheme`,
+the `Theme` component for local scope overrides, the persisted theme
+preference, the accent, gray, density, scaling, radius, and panel
+background dimensions, and the SSR guidance for avoiding hydration
+mismatches when the stored preference is read after mount.
+
+The general consumer entry point is
+[consumer-guide.md](./consumer-guide.md). The canonical per-component
+specs are [theme.md](./theme.md),
+[theme-provider.md](./theme-provider.md), and
+[font-provider.md](./font-provider.md).
+
+## Theme dimensions
+
+The theme system is built around a fixed set of dimensions. Every
+dimension is exposed as a prop on `ThemeProvider` and `Theme`, and
+persisted in `localStorage` when used through `ThemeProvider`.
+
+| Dimension | Values | Default | Source of truth |
+|---|---|---|---|
+| `mode` | `light` \| `dark` \| `system` | `system` | `ThemeProvider.defaultTheme` |
+| `appearance` | `light` \| `dark` \| `inherit` | `inherit` | `Theme.appearance` (one render) |
+| `accentColor` | `amber` \| `silver` \| `bronze` | `amber` | `DESIGN.md` accent identity |
+| `grayColor` | `auto` \| `neutral` | `auto` | Gray family |
+| `radius` | `none` \| `sm` \| `md` \| `lg` \| `full` | `md` | Border radius preset |
+| `panelBackground` | `solid` \| `translucent` | `translucent` | Panel background treatment |
+| `density` | `comfortable` \| `compact` | `comfortable` | Density mode |
+| `scaling` | `90` \| `95` \| `100` \| `105` \| `110` | `100` | UI scaling step |
+| `surface` | `theme` \| `transparent` | `theme` | Whether the wrapper paints a surface |
+
+`Theme` resolves every dimension through the same cascade: the prop on
+the local `Theme` wins, then the inherited `ThemeContext` (from a
+parent `Theme` or `ThemeProvider`), then the
+`DEFAULT_THEME_CONTEXT_VALUE` constant.
+
+`ThemeProvider` writes the full data-attribute contract to
+`document.documentElement` and `document.body` (plus `colorScheme`) and
+mirrors the value to the `ThemeContext` so nested `Theme` wrappers
+inherit it.
+
+## ThemeProvider: persisted theme preference
+
+`ThemeProvider` stores the full theme object (mode plus the six
+dimensions) in `localStorage`. On mount, it reads the stored object
+back through a `useLayoutEffect` and updates state so the
+SSR-rendered HTML matches the initial client render.
+
+```tsx
+import { ThemeProvider } from '@d4gger/design-system'
+
+function App() {
+  return (
+    <ThemeProvider
+      defaultTheme="system"
+      storageKey="dsx-theme"
+      accentColor="amber"
+      density="comfortable"
+      grayColor="auto"
+      panelBackground="translucent"
+      radius="md"
+      scaling="100"
+    >
+      <Root />
+    </ThemeProvider>
+  )
+}
+```
+
+`storageKey` is required. Two apps in the same domain need different
+keys to avoid clobbering each other. The full object is stored as
+JSON, so older entries that only contain `{ mode }` are merged with the
+defaults rather than overwritten.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `defaultTheme` | `'light' \| 'dark' \| 'system'` | `'system'` | Initial mode when no stored value is present. |
+| `storageKey` | `string` | (required) | The localStorage key. |
+| `accentColor` | `'amber' \| 'silver' \| 'bronze'` | `'amber'` | Initial accent when no stored value is present. |
+| `density` | `'comfortable' \| 'compact'` | `'comfortable'` | Initial density. |
+| `grayColor` | `'auto' \| 'neutral'` | `'auto'` | Initial gray family. |
+| `mode` | (controlled, use the `mode` prop on `Theme` instead) | n/a | `ThemeProvider` does not accept a `mode` prop. The mode is read from storage on mount and updated through `useTheme`. |
+| `panelBackground` | `'solid' \| 'translucent'` | `'translucent'` | Initial panel background. |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` | Initial radius preset. |
+| `scaling` | `'90' \| '95' \| '100' \| '105' \| '110'` | `'100'` | Initial scaling. |
+
+The `mode` prop is intentionally not exposed on `ThemeProvider`; the
+mode flows through `useTheme().setTheme` so the value round-trips
+through `localStorage`. To control the mode from a server-rendered
+context, use the SSR guidance below.
+
+## useTheme: reading and switching
+
+`useTheme` returns the `ThemeContext` value from `ThemeProvider` plus
+the setters. It throws when called outside a `ThemeProvider`.
+
+```tsx
+import { useTheme } from '@d4gger/design-system'
+
+function ThemeToggle() {
+  const { resolvedTheme, setTheme } = useTheme()
+
+  return (
+    <IconButton
+      aria-label={`Switch to ${resolvedTheme === 'dark' ? 'light' : 'dark'} mode`}
+      onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}
+    >
+      <Icon name={resolvedTheme === 'dark' ? 'sun' : 'moon'} />
+    </IconButton>
+  )
+}
+```
+
+The hook returns the following fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `theme` | `'light' \| 'dark' \| 'system'` | The current preference (may be `'system'`). |
+| `resolvedTheme` | `'light' \| 'dark'` | The active mode. `'system'` resolves to the OS preference. |
+| `setTheme` | `Dispatch<SetStateAction<ThemePreference>>` | Set the preference; persists to `localStorage`. |
+| `accentColor` | `ThemeAccentColor` | Current accent. |
+| `setAccentColor` | `(value: ThemeAccentColor) => void` | Set the accent. |
+| `density` | `'comfortable' \| 'compact'` | Current density. |
+| `setDensity` | `(value: DensityMode) => void` | Set the density. |
+| `grayColor` | `ThemeGrayColor` | Current gray family. |
+| `setGrayColor` | `(value: ThemeGrayColor) => void` | Set the gray family. |
+| `panelBackground` | `ThemePanelBackground` | Current panel background. |
+| `setPanelBackground` | `(value: ThemePanelBackground) => void` | Set the panel background. |
+| `radius` | `ThemeRadius` | Current radius preset. |
+| `setRadius` | `(value: ThemeRadius) => void` | Set the radius. |
+| `scaling` | `ThemeScaling` | Current scaling. |
+| `setScaling` | `(value: ThemeScaling) => void` | Set the scaling. |
+| `mode` | `'light' \| 'dark' \| 'system'` | Alias of `theme` for cross-component readability. |
+| `setMode` | `Dispatch<SetStateAction<ThemePreference>>` | Alias of `setTheme`. |
+
+`setTheme` accepts a function (`setTheme((prev) => prev === 'dark' ? 'light' : 'dark')`)
+so toggling is one line.
+
+## Theme: local scope override
+
+`Theme` writes the same data-attribute contract as `ThemeProvider` to
+its host element (default `div`) and provides a `ThemeContext` for
+nested descendants. It does not persist anything. Use it to scope a
+subtree to a different accent, radius, density, or appearance without
+touching the user's global preference.
+
+```tsx
+import { Theme } from '@d4gger/design-system'
+
+function Showcase() {
+  return (
+    <Theme accentColor="silver" density="compact" radius="full">
+      <Card>
+        <Card.Content>Scoped theme for this card.</Card.Content>
+      </Card>
+    </Theme>
+  )
+}
+```
+
+`Theme` also accepts `applyToDocument` to mirror the resolved
+attributes to `html` and `body`. Use this for a single-page app where
+you want the document to reflect the theme without persisting it.
+
+```tsx
+<Theme accentColor="amber" mode="dark" applyToDocument>
+  <Root />
+</Theme>
+```
+
+The `appearance` prop overrides `mode` for a single render and accepts
+`inherit` to keep the inherited or document `data-dsx-theme` value.
+`appearance="inherit"` is the right choice when you want to override
+accent, density, or radius locally without disturbing the appearance.
+
+```tsx
+<Theme appearance="inherit" accentColor="bronze" radius="lg">
+  <Card>...</Card>
+</Theme>
+```
+
+`surface` toggles whether the wrapper paints a surface. With
+`surface="theme"` the wrapper paints `var(--dsx-color-surface)` and
+writes `data-has-background="true"`. With `surface="transparent"` the
+wrapper is invisible and `data-has-background` is omitted.
+
+`Theme` is polymorphic. Pass `as="section"` or `as="main"` to swap the
+host element, or `asChild` to render the attributes through a
+consumer's element.
+
+## Accent, gray, density, scaling, panel background
+
+### Accent color
+
+Three accents carry the brand identity. `amber` is the gold-dominant
+default, `silver` is the cool secondary, and `bronze` is the warm
+tertiary. Mix them deliberately; never combine more than one accent in
+a single view.
+
+```tsx
+<Theme accentColor="amber">...</Theme>
+<Theme accentColor="silver">...</Theme>
+<Theme accentColor="bronze">...</Theme>
+```
+
+### Gray color
+
+`auto` selects the gray family based on the active accent (the gray
+takes on a slight tint from the accent). `neutral` selects a
+brand-neutral gray for pages that need a less branded look.
+
+```tsx
+<Theme grayColor="auto">...</Theme>
+<Theme grayColor="neutral">...</Theme>
+```
+
+### Density
+
+`comfortable` is the default spacing for form controls, buttons, and
+list rows. `compact` reduces the spacing for dense tables or
+information-heavy layouts.
+
+```tsx
+<Theme density="comfortable">...</Theme>
+<Theme density="compact">...</Theme>
+```
+
+Density maps through `var(--dsx-density-{mode}-{controlHeight,padding})`
+and adjusts the relevant control and padding tokens across the
+package.
+
+### Scaling
+
+Scaling adjusts the UI scale across the whole tree. The values
+`90`, `95`, `100`, `105`, `110` map to `90%`, `95%`, `100%`, `105%`,
+`110%` of the base font size. Use it for accessibility-driven UI
+scaling, not for breakpoints.
+
+```tsx
+<Theme scaling="100">...</Theme>
+<Theme scaling="110">...</Theme>
+```
+
+When no scaling is resolved, the `data-dsx-scaling` attribute is
+removed from the document entirely; the token layer treats the missing
+attribute as the default `100%` scale.
+
+### Panel background
+
+`solid` paints the surface through a flat color. `translucent` enables
+the glass treatment for floating panels. Use `translucent` for dialogs
+and popovers that benefit from a hint of the underlying content;
+prefer `solid` for cards and structured surfaces.
+
+```tsx
+<Theme panelBackground="solid">...</Theme>
+<Theme panelBackground="translucent">...</Theme>
+```
+
+## Code examples
+
+### Mode toggle
+
+```tsx
+import { useTheme, IconButton, Icon } from '@d4gger/design-system'
+
+export function ModeToggle() {
+  const { resolvedTheme, setTheme } = useTheme()
+  const next = resolvedTheme === 'dark' ? 'light' : 'dark'
+
+  return (
+    <IconButton
+      aria-label={`Switch to ${next} mode`}
+      onClick={() => setTheme(next)}
+    >
+      <Icon name={resolvedTheme === 'dark' ? 'sun' : 'moon'} />
+    </IconButton>
+  )
+}
+```
+
+### Accent color switch
+
+```tsx
+import { useTheme, SegmentedControl } from '@d4gger/design-system'
+import type { ThemeAccentColor } from '@d4gger/design-system'
+
+const accents: ThemeAccentColor[] = ['amber', 'silver', 'bronze']
+
+export function AccentSwitch() {
+  const { accentColor, setAccentColor } = useTheme()
+
+  return (
+    <SegmentedControl
+      value={accentColor}
+      onValueChange={setAccentColor}
+      options={accents.map((value) => ({ value, label: value }))}
+      aria-label="Accent color"
+    />
+  )
+}
+```
+
+### Density and scaling panel
+
+```tsx
+import { useTheme, Field, SegmentedControl } from '@d4gger/design-system'
+
+export function DensityAndScaling() {
+  const { density, setDensity, scaling, setScaling } = useTheme()
+
+  return (
+    <Stack gap="md">
+      <Field label="Density">
+        <SegmentedControl
+          value={density}
+          onValueChange={setDensity}
+          options={[
+            { value: 'comfortable', label: 'Comfortable' },
+            { value: 'compact', label: 'Compact' },
+          ]}
+        />
+      </Field>
+      <Field label="UI scale">
+        <SegmentedControl
+          value={scaling}
+          onValueChange={setScaling}
+          options={['90', '95', '100', '105', '110'].map((value) => ({
+            value,
+            label: `${value}%`,
+          }))}
+        />
+      </Field>
+    </Stack>
+  )
+}
+```
+
+### Local scope override with `Theme`
+
+```tsx
+import { Theme, Card, DataList, Badge } from '@d4gger/design-system'
+
+function PlanShowcase() {
+  return (
+    <Theme accentColor="silver" radius="full" appearance="inherit">
+      <Card variant="default" size="md">
+        <Card.Header>
+          <Card.Title>Enterprise</Card.Title>
+        </Card.Header>
+        <Card.Content>
+          <DataList aria-label="Plan details">
+            <DataList.Item text="Bandwidth" metadata="Unlimited" />
+            <DataList.Item text="Locations" metadata="62 countries" />
+            <DataList.Item
+              text="Support"
+              metadata="24/7"
+              badge={<Badge>Priority</Badge>}
+            />
+          </DataList>
+        </Card.Content>
+      </Card>
+    </Theme>
+  )
+}
+```
+
+## ThemeProvider SSR guidance
+
+`ThemeProvider` reads the stored theme from `localStorage` in a
+`useLayoutEffect` after mount. The SSR pass renders the default
+mode (the one passed as `defaultTheme`), then the client takes over
+and applies the stored value. This split is intentional: the server
+has no access to `localStorage`, so it cannot render the user's
+stored preference.
+
+The split is hydration-safe for the document because the data
+attributes are written to `document.documentElement` after the initial
+client render, not during it. The split is not hydration-safe for
+components that read the resolved theme during the initial render,
+because the server and the client disagree on the active mode during
+the first paint. There are four patterns for resolving this gap.
+
+### Solution 1: render with `defaultTheme="system"` and apply in `useEffect`
+
+The simplest approach. `defaultTheme="system"` resolves to `light` on
+the server (the system-theme helper returns `light` when `window` is
+undefined) and to the OS preference on the client. The first client
+paint matches the server paint, then a `useEffect` flips the document
+attributes to the stored value.
+
+```tsx
+'use client'
+import { ThemeProvider, Theme } from '@d4gger/design-system'
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider defaultTheme="system" storageKey="dsx-theme">
+      {children}
+    </ThemeProvider>
+  )
+}
+```
+
+Use this when the first paint of a small flash of light or dark
+mode is acceptable. Most product surfaces accept the flash; the
+`useLayoutEffect` in `ThemeProvider` runs before the browser paints,
+so the document attributes are correct by the time the user sees
+anything.
+
+### Solution 2: `suppressHydrationWarning` on the html element
+
+React's `suppressHydrationWarning` attribute tells React to skip the
+hydration check for the element's children and attributes. Apply it
+to the `<html>` element so React does not warn when the client and
+server disagree on `class` or `data-dsx-theme` during the first
+paint.
+
+```tsx
+// app/layout.tsx (Next.js App Router)
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+
+The attributes still mismatch; the warning is just suppressed. Pair
+this with one of the other solutions so the document is actually
+correct, not just quiet.
+
+### Solution 3: inline script to set the class before React hydrates (next-themes pattern)
+
+The `next-themes` pattern. A small inline script runs in the
+document `<head>` before React hydrates. The script reads the stored
+value from `localStorage` (or the cookie), resolves the system theme
+through `matchMedia`, and writes the matching `class` and
+`data-dsx-theme` attribute to `<html>`. By the time React hydrates,
+the document already matches the user's stored preference.
+
+```tsx
+// app/layout.tsx (Next.js App Router)
+const themeScript = `
+(function() {
+  try {
+    var stored = JSON.parse(localStorage.getItem('dsx-theme') || '{}');
+    var mode = stored.mode || 'system';
+    var resolved = mode;
+    if (mode === 'system') {
+      resolved = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    }
+    var root = document.documentElement;
+    root.setAttribute('data-dsx-theme', resolved);
+    root.setAttribute('data-dsx-density', stored.density || 'comfortable');
+    root.setAttribute('data-accent-color', stored.accentColor || 'amber');
+    root.setAttribute('data-gray-color', stored.grayColor || 'auto');
+    root.setAttribute('data-radius', stored.radius || 'md');
+    root.setAttribute('data-panel-background', stored.panelBackground || 'translucent');
+    if (stored.scaling) root.setAttribute('data-dsx-scaling', stored.scaling);
+    root.style.colorScheme = resolved;
+  } catch (e) {}
+})();
+`.trim()
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeScript }} />
+      </head>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+
+The script must run synchronously before React hydrates. Place it in
+`<head>` so the browser parses and executes it during the initial
+HTML parse, before it parses `<body>`. The `dangerouslySetInnerHTML`
+escape is safe because the script content is static.
+
+Pair the inline script with a `ThemeProvider` mounted with
+`defaultTheme="system"`. The `useLayoutEffect` in `ThemeProvider` runs
+after hydration; by then, the inline script has already set the
+document attributes, so the layout effect's snapshot/restore cycle is
+a no-op for the theme attributes (it still runs to ensure parity).
+
+### Solution 4: cookie-based server-side theme detection
+
+When the user has been seen before, persist the theme to a cookie on
+the server. The server reads the cookie, renders the matching theme
+attributes on `<html>`, and the client hydrates without a mismatch.
+
+```tsx
+// app/layout.tsx (Next.js App Router)
+import { cookies } from 'next/headers'
+
+function readThemeFromCookies() {
+  const cookieStore = cookies()
+  const value = cookieStore.get('dsx-theme')?.value
+  if (!value) return null
+  try {
+    return JSON.parse(value) as {
+      mode?: 'light' | 'dark' | 'system'
+      accentColor?: 'amber' | 'silver' | 'bronze'
+      density?: 'comfortable' | 'compact'
+      radius?: 'none' | 'sm' | 'md' | 'lg' | 'full'
+      panelBackground?: 'solid' | 'translucent'
+      grayColor?: 'auto' | 'neutral'
+      scaling?: '90' | '95' | '100' | '105' | '110'
+    }
+  } catch {
+    return null
+  }
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const stored = readThemeFromCookies()
+  const mode = stored?.mode ?? 'system'
+  const accent = stored?.accentColor ?? 'amber'
+  const density = stored?.density ?? 'comfortable'
+
+  return (
+    <html lang="en" data-dsx-theme={mode} data-accent-color={accent} data-dsx-density={density} suppressHydrationWarning>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+The client-side `ThemeProvider` must write the same cookie on every
+change so the server-side render is consistent on the next request.
+
+```tsx
+'use client'
+import { useTheme } from '@d4gger/design-system'
+import { useEffect } from 'react'
+
+export function ThemeCookieSync() {
+  const { theme, accentColor, density, grayColor, radius, panelBackground, scaling } = useTheme()
+
+  useEffect(() => {
+    const payload = JSON.stringify({ theme, accentColor, density, grayColor, radius, panelBackground, scaling })
+    document.cookie = `dsx-theme=${encodeURIComponent(payload)}; path=/; max-age=31536000; samesite=lax`
+  }, [theme, accentColor, density, grayColor, radius, panelBackground, scaling])
+
+  return null
+}
+```
+
+This pattern is the most consistent (no flash, no mismatch warning)
+but it requires a cookie write on every change and a cookie read on
+every server render. The cookie is small (under 200 bytes), and the
+`Path=/` plus `SameSite=Lax` defaults are safe for a single-domain
+app.
+
+### Pages Router (Next.js)
+
+The Pages Router pattern is similar. The inline script lives in
+`_document.tsx`; the cookie-based pattern uses `getServerSideProps`
+or `getInitialProps` on the page.
+
+```tsx
+// pages/_document.tsx
+import { Html, Head, Main, NextScript } from 'next/document'
+
+const themeScript = `
+(function() {
+  try {
+    var stored = JSON.parse(localStorage.getItem('dsx-theme') || '{}');
+    var mode = stored.mode || 'system';
+    var resolved = mode;
+    if (mode === 'system') {
+      resolved = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    }
+    var root = document.documentElement;
+    root.setAttribute('data-dsx-theme', resolved);
+    root.setAttribute('data-dsx-density', stored.density || 'comfortable');
+    root.setAttribute('data-accent-color', stored.accentColor || 'amber');
+    root.setAttribute('data-gray-color', stored.grayColor || 'auto');
+    root.setAttribute('data-radius', stored.radius || 'md');
+    root.setAttribute('data-panel-background', stored.panelBackground || 'translucent');
+    if (stored.scaling) root.setAttribute('data-dsx-scaling', stored.scaling);
+    root.style.colorScheme = resolved;
+  } catch (e) {}
+})();
+`.trim()
+
+export default function Document() {
+  return (
+    <Html lang="en" suppressHydrationWarning>
+      <Head>
+        <script dangerouslySetInnerHTML={{ __html: themeScript }} />
+      </Head>
+      <body>
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  )
+}
+```
+
+For cookie-based detection on the Pages Router, write the theme
+cookie from the client and read it through `getServerSideProps`:
+
+```tsx
+// pages/_app.tsx
+import type { GetServerSideProps, AppProps } from 'next/app'
+import { ThemeProvider } from '@d4gger/design-system'
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <ThemeProvider defaultTheme="system" storageKey="dsx-theme">
+      <Component {...pageProps} />
+    </ThemeProvider>
+  )
+}
+```
+
+The cookie read happens at the page level rather than the layout
+level on the Pages Router, because `_document.tsx` does not have
+access to `req` or `cookies()`. Use the inline script pattern when
+you need the document attributes set before the first paint.
+
+## Decision guide
+
+| Need | Pattern |
+|---|---|
+| No SSR, single-page app | None needed. `ThemeProvider` is sufficient. |
+| SSR with a tolerable flash | Solution 1: `defaultTheme="system"` and `suppressHydrationWarning`. |
+| SSR with no flash, no cookie | Solution 3: inline script in `<head>`. |
+| SSR with the most consistent render | Solution 4: cookie-based server detection. |
+| Hybrid (cookie + inline script) | Cookie read on the server, inline script as a fallback for clients that arrive without the cookie. |
+
+The hybrid pattern is the most robust: the server reads the cookie and
+writes the theme attributes to `<html>`. The inline script handles
+clients that arrive without the cookie (the first visit, the post-clear
+visit, or the visit from a browser that blocks third-party cookies).
+Both paths converge on the same document state, so the first paint is
+always correct.