themelia-ui 2.0.1 → 3.1.0

package/.agents/skills/themelia-ui/references/theming.md

@@ -1,163 +1,228 @@
 # Theming
 
-A theme author sets the **global contract** and stops. Most rebrands begin with the palette,
-semantic-colour, radius and shadow seeds in the default theme; the contract also includes
-the public type, spacing, motion, focus and layering controls.
-`src/styles/TOKENS.md` (`node_modules/themelia-ui/src/styles/TOKENS.md`) lists every name and the current counts.
+The theme is about eighty variables, declared once at `:root` in `src/styles/theme/`. Each
+colour holds both modes as `light-dark(light, dark)`, and every length, shadow, tint and
+duration comes as a pair. Components derive everything else where they use it, so a value
+you set anywhere reaches every component below it. `src/styles/TOKENS.md` (`node_modules/themelia-ui/src/styles/TOKENS.md`)
+names the variable for each role.
 
-The component-token layer is plumbing, not the theming surface: most of it is a `var()` off
-the contract, and the rest is geometry no theme would touch.
-Override component tokens only where a family reference names one as an extension point.
+## Setting a theme
 
-## Editing a running app
+Set the variables you change on `:root`. A colour takes a `light-dark()` pair, or one value
+for both modes:
 
-`ThemeTweaker` (`themelia-ui/features/theme-tweaker`) lets people change appearance, accent
-colour, density, corners and font while the app runs, and exports CSS theme values and
-provider configuration separately. Mount it as a floating button, a full-page route, or both.
+```css
+:root {
+  --primary: light-dark(oklch(0.55 0.19 250), oklch(0.72 0.14 250));
+  --primary-foreground: light-dark(oklch(0.985 0 0), oklch(0.2 0.03 250));
+  --radius: 0.75rem;
+  --radius-sm: 0.375rem;
+  --font-sans: "Your interface font", sans-serif;
+}
+```
 
-The application owns the theme and provider state, above its router:
+That one block reaches every region, including popups portalled to `<body>` and a dark
+region inside a light page: nothing below `:root` declares a colour again.
+
+The same values work on any element, for a region of their own:
+
+```css
+.marketing {
+  --primary: oklch(0.6 0.2 30);
+}
+```
 
-- Keep `useAppliedTheme` mounted there with `target="document"` and `manageModeClass={false}`.
-- Give the root `UIProvider` the shared config and `themeToStyle(theme)`.
-- Render the controlled editor with `apply={false}`.
+A provider takes them as config and writes them on its own element:
 
-This keeps document portals and the provider scope in sync, and theme application does not
-depend on whether the panel is open. Persist valid config separately from unfinished field
-input, so typing a partial locale cannot break the app.
+```tsx fragment — shape only, not a program
+<UIProvider config={{ theme: { colors: { primary: "light-dark(#2563eb, #60a5fa)" } } }}>
+```
 
-## Setting a theme
+Colours passed this way reach the provider's subtree. A popup portalled to `<body>` leaves
+that subtree; render it into the provider with `UIPortalHost` (see
+[Provider and scoping](provider-and-scoping.md#portals-and-scopes)), or set the value on
+`:root` instead.
 
-Declare the contract's names wherever you want them to apply. Which selector reaches a
-component depends on the kind of name.
+## Ready-made themes
 
-A **raw input** — `--radius`, a font stack, a palette primitive — is declared once at
-`:root` and inherits everywhere. `--primary` resolves through `--brand-600` in light and
-`--brand-350` in dark, so a rebrand sets the primitives and every semantic follows:
+Four themes ship with the kit, each a style rather than a colour: Soft (large corners,
+diffuse shadows, comfortable spacing), Sharp (square corners, hairlines, no shadows), Dense
+(compact spacing and small corners, for data) and Editorial (serif headings on warm paper, a
+step larger type). Each is a `ThemePreset`: a `label`, a `description`, and the provider
+`config` it sets. That config reaches past colour to radii, shadows and border weight, density,
+typography, motion and component defaults, such as the card surface. Every theme's colours
+hold WCAG AA contrast in both modes, as the kit's own do.
 
-```css
-:root {
-  --brand-600: oklch(0.55 0.19 250);
-  --brand-350: oklch(0.72 0.14 250);
-  --radius: 1rem;
-  --radius-sm: 0.5rem;
-}
+```tsx fragment — shape only, not a program
+import { themes } from "themelia-ui/theming"
+
+<UIProvider config={themes.sharp.config}>
 ```
 
-A **semantic** — `--primary`, `--background`, `--border` — re-derives at every scope
-boundary, and the provider's own element is one. Set on `:root` alone, it is re-declared at
-that element and no component sees it. Pass it through the provider, which writes it on the
-boundary itself:
+Switching themes is handing the provider another theme's config. Keep the choice in state,
+and wrap the application in `UIPortalHost`, so menus and popovers, which portal to `<body>`,
+take the theme too:
 
 ```tsx fragment — shape only, not a program
-<UIProvider config={{ theme: { colors: { primary: "oklch(0.55 0.19 250)" } } }}>
+const [name, setName] = useState<ThemeName>("soft")
+
+<UIProvider config={themes[name].config}>
+  <UIPortalHost>
+    <App onThemeChange={setName} />
+  </UIPortalHost>
+</UIProvider>
 ```
 
-or declare it at the boundaries, in the list the package itself uses:
+A nested provider themes one region the same way. Settings of your own go beside a theme's:
+`config={{ ...themes.dense.config, formatting: { locale: "de-DE" } }}`.
 
-```css
-:root, [data-ui-scope], [data-density], [data-theme], .light, .dark {
-  --primary: oklch(0.55 0.19 250);
+A theme of your own is the same shape. Start from one of these and change what you need:
+
+```tsx fragment — shape only, not a program
+const brand: ThemePreset = {
+  label: "Brand",
+  description: "Our product's look.",
+  config: {
+    ...themes.sharp.config,
+    density: "comfortable",
+    theme: {
+      ...themes.sharp.config.theme,
+      colors: {
+        ...themes.sharp.config.theme?.colors,
+        primary: "light-dark(oklch(0.5 0.19 15), oklch(0.76 0.13 15))",
+        "primary-foreground": "light-dark(oklch(0.985 0 0), oklch(0.2 0.05 15))",
+      },
+    },
+  },
 }
 ```
 
-For a subtree, use a scope boundary rather than a bare element — see
-[Provider and scoping](provider-and-scoping.md#scope--tokens-only). Derived tokens resolve
-**where they are declared**, so a variable set on an element that is not a boundary is set
-and never read.
+A square theme should set `defaults.card.surface` to `"card"`: the default `framed` surface is
+a band that follows the corner, and with no corner to follow it reads as a box in a box. Write
+a zero radius as `0px`: the kit subtracts lengths from the radii, and `calc()` cannot subtract
+a length from a bare `0`. Write no shadow as `0 0 transparent`, not `none`: a popup lists
+`--shadow-lg` after its hairline, and `none` cannot stand in a list, so the popup would lose
+its edge.
+
+To edit a theme's colours and variables visually, load them into the theme editor with
+`themeFromConfig(themes.soft.config.theme)` from `themelia-ui/features/theme-tweaker`; the
+editor exports the result as CSS or provider config.
 
 ## Start with the shared controls
 
-Most layout adjustments need only the surface insets, row insets, spacing factor, font
-family, and the two radii. These controls follow the component's role rather than its
-feature name:
+Most adjustments need only these, and they follow a component's role rather than its name:
 
 ```css
 :root {
-  --surface-x: 1.25rem;
-  --surface-y: 1rem;
-  --row-x: 0.75rem;
-  --row-y: 0.5rem;
-  --font-sans: "Your interface font", sans-serif;
-  --radius: 0.75rem;    /* containers */
-  --radius-sm: 0.375rem; /* what sits inside them — set both, nothing derives it */
+  --padding: 1.25rem;      /* container insets: cards, dialogs, sheets, popovers */
+  --padding-sm: 0.625rem;  /* item insets: rows, cells, chips, fields */
+  --gap: 1.25rem;          /* between groups: fields, cards, sections */
+  --gap-sm: 0.625rem;      /* inside a group: icon and label, title and description */
+  --control-height: 2.25rem;
+  --radius: 0.75rem;       /* containers */
+  --radius-sm: 0.375rem;   /* what sits inside them; nothing derives one from the other */
 }
 ```
 
+- A nested corner is the container's radius less its inset, computed where it is used, so
+  menus and option lists keep their rows concentric at any radius.
+- A density preset sets the four lengths and the two control heights on its region (see
+  [Scale and density](#scale-and-density)); a value you set on `:root` applies where no preset
+  is in effect.
+
 **Fonts.** The kit ships Geist for text and Geist Mono for code and identifiers (SIL OFL 1.1),
 as variable-weight woff2 files beside `core.css`, one per script. A browser downloads a file
 only when text in that script renders in that family, so a theme that sets `--font-sans` and
-`--font-mono` to its own fonts downloads none of them.
+`--font-mono` to its own fonts downloads none of them. `--font-heading` is unset by default,
+and headings fall back to the interface font.
 
-- Cards, framed ContentBlocks and overlay bodies share the surface X/Y insets.
-- Overlay headers and footers use the same horizontal inset and 75% of the vertical inset;
-  the header adds a small optical inset above its title.
-- Menus and option lists inset their rows by `--space-md`, the difference between the two
-  radii, so rows sit concentric.
-- Dark mode inherits the chosen fonts.
-
-Compose title/description regions with CardHeader, ContentBlock or OverlayHeader; action
-regions with CardFooter or OverlayFooter; and label/value facts with MetadataList. These
+Compose title and description regions with CardHeader, ContentBlock or OverlayHeader, action
+regions with CardFooter or OverlayFooter, and label/value facts with MetadataList. These
 components own their spacing, so the application does not reproduce it.
 
-`--content-block-p` and `--overlay-region-p` remain supported for local exceptions. Leave
-them unset when the surface should follow the theme.
-
-## Scale
-
-Three factors, and no per-family ones:
+## Scale and density
 
-| Factor | Multiplies |
-|---|---|
-| `--scale` | everything; the other two default to it |
-| `--density-scale` | spacing, control heights and row rhythm, rounded to whole pixels |
-| `--text-scale` | the type scale, control labels included |
+Controls take two sizes, `default` and `sm`. A denser or roomier region is a scope instead,
+so everything inside it moves together:
 
-Setting `--scale` alone moves the whole system. `UIProvider`'s `typography.scale` sets
-`--text-scale` for a scope without changing its geometry.
-`src/styles/FACTORS.md` (`node_modules/themelia-ui/src/styles/FACTORS.md`) is the authority.
+| Setting | Moves |
+| --- | --- |
+| `density` | the four lengths and the two control heights; type keeps its size |
+| `scale` | the same, the two icon sizes, and type |
+| `typography.scale` | type alone, through `--text-scale` |
 
-Named `density` presets set only `--density-scale`, so compact and comfortable regions
-change spacing, control heights and row rhythm without resizing readable type. Controls are
-34, 30 and 24px at the default and 32, 28 and 23px under `compact`. Use explicit `scale`
-when the entire scoped UI should move together.
+```tsx fragment — shape only, not a program
+<UIProvider config={{ density: "compact" }}>
+<UIProvider config={{ scale: 1.125 }}>
+<UIProvider config={{ typography: { scale: 0.875 } }}>
+```
 
-All three are raw inputs: set them on `:root`, with a `density` preset, or on a boundary such
-as [`Scope`](provider-and-scoping.md#scope--tokens-only). On a plain nested element nothing
-re-derives from them.
+The provider computes `scale` in JavaScript and writes the lengths themselves, rounded to
+whole pixels, so no length is multiplied twice. A density preset also works without a
+provider: any element can carry `data-density="compact"` or `"comfortable"`.
 
-A single family cannot be scaled on its own; scale a region with a scope instead. A
-family-shaped token name is not a tuning seam. Use the three public factors rather than
-reconstructing component calculations.
+A preset sets its lengths on the region. To change a length under one preset, set it for
+that preset: `[data-density="compact"] { --padding: 0.625rem; }`.
 
 ## Dark mode
 
-Three signals, all answered:
+Colours switch through `color-scheme`, which the kit sets from three signals: a `.dark` or
+`.light` class, `data-theme="dark"` or `"light"`, and, with neither, the operating system's
+preference. Each colour's `light-dark()` pair resolves on the element that paints it, so a
+dark region inside a light page needs only `data-theme="dark"` (or a nested provider with
+`colorScheme: "dark"`) on its container, and a light island inside a dark page the same.
 
-```css
-.dark { … }
-[data-theme="dark"] { … }
-@media (prefers-color-scheme: dark) { … }
-```
+A value of your own switches the same way: write `light-dark()` in the value, never a rule
+under `.dark` or `@media (prefers-color-scheme: dark)`, which would miss a dark region inside
+a light page.
 
-A dark-only override should answer all three: an app that toggles a class and an app that
-sets an attribute are both normal, and honouring only one leaves the other half-themed.
+## Editing a theme at runtime
 
-A bare token boundary nested under an explicit dark ancestor — a `Scope`, a `data-density`
-region, a nested provider on the default `system` scheme — re-derives the dark values. An
-explicit light island inside a dark tree keeps its own boundary light, but a bare boundary
-inside that island re-derives dark again; give it its own `data-theme`, or use `UIScope`,
-which writes the resolved scheme on each boundary it renders.
-`src/styles/SCOPES.md` (`node_modules/themelia-ui/src/styles/SCOPES.md`) shows the selectors.
+`ThemeTweaker` (`themelia-ui/features/theme-tweaker`) lets people change appearance, accent
+colour, density, corners and font while the app runs, and exports CSS theme values and
+provider configuration separately. Mount it as a floating button, a full-page route, or both.
+The exported stylesheet is one `:root` block in which each colour it changed is a
+`light-dark()` pair.
 
-In CSS Modules, `.dark` is hashed like any other class. Write a dark rule as
-`:global(.dark)`, or it matches nothing and the theme silently does not apply.
+The application owns the theme and provider state, above its router:
 
-## Runtime theming
+- `useAppliedTheme`, mounted there with `target: "document"` and `manageModeClass: false`,
+  applies the theme whether or not the editor is open.
+- The root `UIProvider` takes the same config and `themeToStyle(theme)`.
+- The editor is controlled, with `apply={false}`.
+
+```tsx compile
+import { useRef, useState, type ReactNode } from "react"
+import { UIProvider, type UIConfig } from "themelia-ui/ui-provider"
+import {
+  ThemeTweaker, createTheme, themeToStyle, useAppliedTheme, type ThemeDefinition,
+} from "themelia-ui/features/theme-tweaker"
+
+export function ThemedApp({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState<ThemeDefinition>(() => createTheme())
+  const [config, setConfig] = useState<UIConfig>({ colorScheme: "system" })
+  const selfRef = useRef<HTMLDivElement>(null)
+  useAppliedTheme({ theme, target: "document", selfRef, apply: true, manageModeClass: false })
+
+  return (
+    <UIProvider config={config} style={themeToStyle(theme)}>
+      {children}
+      <ThemeTweaker
+        value={theme}
+        onValueChange={setTheme}
+        config={config}
+        onConfigChange={setConfig}
+        apply={false}
+      />
+    </UIProvider>
+  )
+}
+```
 
-`features/theme-tweaker` edits CSS theme values and provider defaults at runtime. Connect
-`onConfigChange` to application state and pass valid configuration to the provider; mounted
-descendants update without a remount. Use its export callbacks to persist the result in
-your application. See [runtime provider configuration](provider-and-scoping.md#updating-defaults-at-runtime).
+Mounted descendants update without a remount. Persist valid configuration apart from
+unfinished field input, so a half-typed locale cannot break the app, and use the export
+callbacks to save the result. See
+[runtime provider configuration](provider-and-scoping.md#updating-defaults-at-runtime).
 
 ## Synthesising a theme in code
 
@@ -171,8 +236,11 @@ const overrides = deriveThemePalette({ primary: "#3b82f6" })
 // { "--primary": "#3b82f6", "--primary-foreground": "oklch(0.18 0.01 260)", … }
 ```
 
-The derived values stay CSS — `color-mix(in oklch, var(--primary) 10%, var(--background))`
-rather than a computed literal — so they keep following the tokens they derive from.
+The keys are theme variables, so write them on `:root` or pass them to a `Scope`'s `vars`.
+The derived values stay CSS (`color-mix(in oklch, var(--primary) 10%, var(--background))`
+rather than a computed literal), so they keep following the variables they derive from.
+Derive one set for each mode and pair them, as the ThemeTweaker does, when the two should
+differ.
 
 `readableForeground(background)` **measures** WCAG contrast against both candidates and
 returns the better one, with the ratio and whether it clears AA:
@@ -189,64 +257,61 @@ Both functions are also re-exported from `features/theme-tweaker`.
 
 ## Design tokens (DTCG)
 
-`themelia-ui/tokens.json` is the contract in [W3C DTCG][dtcg] format, for Figma and
-tools like Style Dictionary. Colours are OKLCH objects with a `hex` fallback:
+`themelia-ui/tokens.json` is the theme in [W3C DTCG][dtcg] format, for Figma and tools like
+Style Dictionary. Each colour is a token in `theme.light` and one in `theme.dark`; every other
+variable is written once in `theme.light` and aliased from `theme.dark`. Colours are OKLCH
+objects with a `hex` fallback:
 
 ```json
-{ "$value": { "colorSpace": "oklch", "components": [0.45, 0.124, 167.35], "hex": "#00785f" } }
+{ "$value": { "colorSpace": "oklch", "components": [0.45, 0.124, 167.35], "hex": "#006a47" } }
 ```
 
-Two kinds of value are deliberately absent, each named in its own `$extensions`:
-
-- **Mixed colours.** `--destructive-accent` and the inverse steps are `color-mix()` over
-  other tokens; DTCG has no type for a mix, and resolving one would bake one theme's value in.
-- **Shadows.** Each is a multi-layer shadow whose colour is a `color-mix`; resolving it
-  would bake one theme's ink in.
-
-Every `$type`, value and `{reference}` in the file is validated, and no dark token aliases
-a skipped light token.
+Shadows, durations, the easing curve and the font stacks carry their DTCG types. The two tint
+strengths are percentages, which DTCG cannot express, and the unset font roles have no value;
+the file lists them under its `$extensions`.
 
 [dtcg]: https://www.designtokens.org/TR/drafts/format/
 
 ## Tailwind CSS v4
 
 The kit ships no Tailwind and needs none. If your application already uses Tailwind v4,
-import the bridge and its utilities resolve against this contract:
+import the bridge after Tailwind, and its utilities resolve against the theme:
 
 ```css
 @import "tailwindcss";
-@import "themelia-ui/core.css";
 @import "themelia-ui/tailwind.css";
 ```
 
-`bg-primary` is `var(--primary)`, `rounded-sm` is the kit's inner radius, `p-md` is
-`var(--space-md)`, `text-sm` is `calc(0.875rem * var(--text-scale, var(--scale)))`. The
-container radius has no named utility — `rounded` stays Tailwind's own — so write
-`rounded-(--radius)`. Every utility reads the token **at the element**, so a `.dark`
-subtree, a `[data-density="compact"]` scope, a nested `UIProvider` and a provider's
-`theme.radiusSm` or `typography.fonts` all move Tailwind's output the way they move the
-kit's own.
-
-**Import it even if you never write a kit-token utility.** Both projects descend from
-shadcn, so custom-property names collide — `--radius-sm` and `--radius-pill`, `--text-xs`
-through `--text-2xl`, `--shadow-*`, `--font-sans/serif/mono`, `--leading-*`, `--ease-*`.
-Tailwind emits its defaults onto `:root` inside `@layer theme`; when the kit is imported
-first, that layer sits **above** the kit's `tokens` layer. Without the bridge, Tailwind
-wins every shared name, among them:
+The kit's own CSS arrives with its components. Do not `@import` `themelia-ui/style.css` or
+`themelia-ui/core.css` here as well: that inlines a second copy.
+
+`bg-primary` is `var(--primary)`, `rounded` is the container radius and `rounded-sm` the
+item radius, `p-padding` and `gap-gap-sm` are the kit's lengths, and `text-sm` is
+`calc(0.875rem * var(--text-scale))`, which follows the type factor as Text does. Every
+utility reads the variable **at the element**, so a dark region, a `[data-density="compact"]`
+scope, a nested `UIProvider` and a provider's `theme.radiusSm` or `typography.fonts` all move
+Tailwind's output the way they move the kit's own.
+
+**Import the bridge even if you never write a kit utility.** Both projects descend from
+shadcn, so custom-property names collide: `--radius`, `--radius-sm`, `--shadow`,
+`--shadow-lg`, `--text-xs` through `--text-2xl` and the font stacks. Tailwind emits its
+defaults onto `:root` inside `@layer theme`, and depending on the order your application
+imports its CSS, that layer can sit above the kit's `tokens` layer. Without the bridge,
+Tailwind can win every shared name:
 
 | what | kit | Tailwind takes it to |
 | --- | --- | --- |
-| `--radius-sm` | `0.5rem` — the kit's inner radius | `0.25rem` |
-| `--text-sm` | `calc(0.875rem * var(--text-scale, var(--scale)))` | `0.875rem` — **scoped type scaling stops working** |
+| `--radius-sm` | `0.5rem`, the kit's item radius | `0.25rem` |
+| `--shadow-lg` | the kit's floating shadow | Tailwind's `shadow-lg` |
 | `--font-sans` | Geist first | Tailwind's system stack |
-| `--animate-pulse` | `cubic-bezier(0.4, 0, 0.2, 1)` | `cubic-bezier(0.4, 0, 0.6, 1)` |
 
-The symptom is a slightly wrong radius and a density control that stops working, not an
-error. The bridge restates those names with the kit's own definitions, so Tailwind's
-override becomes a no-op. It is generated from the same public tokens.
+The symptom is a slightly wrong radius or shadow, not an error. The bridge restates those
+names with the kit's own values, so Tailwind's override becomes a no-op in either order. It is
+generated from the theme. The kit declares nothing in Tailwind's `--animate-*` namespace, so
+`animate-spin` and its neighbours stay Tailwind's own.
 
-The bridge is two theme declarations and nothing else: no rules and no utilities, and
-Tailwind drops every key no utility uses, so it costs nothing you do not use. Keys that read
-a kit token or a formula are `@theme inline`, so they resolve at the element; the restated
-literals (the inner radius, font stacks, leading, easing) are a plain `@theme`, so their
-utilities read the variable and follow a theme that moves it.
+The bridge is theme declarations and nothing else: no rules and no utilities, and Tailwind
+drops every key no utility uses, so it costs nothing you do not use. Keys that read a kit
+variable or a formula are `@theme inline`, so they resolve at the element; the restated
+literals (the radii, shadows and font stacks) are a plain `@theme`, so their utilities read
+the variable and follow a theme that moves it.