@hadoku/themes 0.0.0-stage → 5.12.16

package/THEME_USAGE_GUIDE.md

@@ -0,0 +1,308 @@
+# Theme Usage Guide — which token do I use?
+
+**This is the doc for _using_ colors.** For authoring a new theme's palette, see
+[`THEME_CREATION_GUIDE.md`](./THEME_CREATION_GUIDE.md). For the accessibility
+contracts, see [`docs/THEME_SYSTEM_RULES.md`](../docs/THEME_SYSTEM_RULES.md).
+
+## The mental model, in one line
+
+**A token names a semantic role, not a hue. Light/dark is automatic — never
+branch on theme mode.**
+
+There are 18 themes. `--color-success` is sky blue in one and gold in another.
+Pick the token that matches what the element _means_; the theme decides the color.
+
+---
+
+## Decision table
+
+`<f>` is one of `primary` · `success` · `warning` · `danger` · `neutral`.
+
+| You're styling…                  | Use                                                              |
+| -------------------------------- | ---------------------------------------------------------------- |
+| Filled / primary button          | `bg-<f>` + `text-on-<f>`                                         |
+| …its gradient or pressed state   | `bg-<f>-dark` (still pair with `text-on-<f>`)                    |
+| Tint badge, chip, banner, alert  | `bg-<f>-bg` + `text-on-<f>-bg`                                   |
+| Ghost button / row hover tint    | `hover:bg-<f>-hover`                                             |
+| Body text                        | `text-text`                                                      |
+| Secondary / muted text           | `text-text-secondary` → `text-text-tertiary` → `text-text-muted` |
+| Page background                  | `bg-bg`                                                          |
+| Card / panel surface             | `bg-bg-card`                                                     |
+| Inset or alternate surface       | `bg-bg-alt`                                                      |
+| Neutral row/button hover surface | `bg-bg-hover`                                                    |
+| Modal scrim                      | `bg-bg-overlay`                                                  |
+| Border / divider                 | `border-border`                                                  |
+| Subtle divider                   | `border-border-light`                                            |
+
+### The one rule people get wrong
+
+`--color-<f>` and `--color-<f>-bg` are **different surfaces with different text
+colors.** They are not interchangeable.
+
+```
+bg-<f>       (solid fill)  →  text-on-<f>
+bg-<f>-bg    (faint tint)  →  text-on-<f>-bg     ← NOT text-<f>
+```
+
+Using `text-<f>` on `bg-<f>-bg` fails WCAG AA in 62 of 90 theme/family
+combinations. That pairing is why badges kept turning up unreadable.
+
+### The same rule, one step further out
+
+A fill colour is not a text colour **on any surface**, not just on its own tint.
+`text-<f>` with no background at all lands on the page or a card, and that pair
+was validated by nothing: `check-contrast` checks `on-<f>` over `<f>`, so
+accent-over-surface passed by never being looked at.
+
+```
+text-<f>  with no background   →  lands on bg / bg-card   ← unvalidated, usually fails
+```
+
+Measured against `--color-bg`: `--color-primary` clears the 3:1 large-text floor
+in only 12 of 18 themes (izakaya-light 1.92, nature-light 2.15, ocean-light 2.28,
+lavender-light 2.53, pink-light 2.56, strawberry-light 2.61). `--color-danger`
+misses AA on a card in 11 of 18. This shipped in `.app-header__title` and reached
+every consuming app at once.
+
+Text on a surface is `text-text` (8.87–17.58 across all 18) or
+`text-text-secondary`. To carry an accent, either pair `bg-<f>-bg` with
+`text-on-<f>-bg`, or move the accent off the glyph entirely — a border, rule, or
+underline is unconstrained by text contrast. `check-usage` gates this, in CSS
+and as Tailwind classes in markup (`text-danger` with no `bg-danger` fill).
+
+---
+
+## Complete token list
+
+Every token below is defined in **all 18 themes**. Nothing else exists — if a
+name isn't here, it isn't a token.
+
+### Semantic families
+
+| family    | fill              | gradient/pressed       | tint surface         | hover overlay           | text on fill         | text on tint            |
+| --------- | ----------------- | ---------------------- | -------------------- | ----------------------- | -------------------- | ----------------------- |
+| `primary` | `--color-primary` | `--color-primary-dark` | `--color-primary-bg` | `--color-primary-hover` | `--color-on-primary` | `--color-on-primary-bg` |
+| `success` | `--color-success` | `--color-success-dark` | `--color-success-bg` | `--color-success-hover` | `--color-on-success` | `--color-on-success-bg` |
+| `warning` | `--color-warning` | `--color-warning-dark` | `--color-warning-bg` | `--color-warning-hover` | `--color-on-warning` | `--color-on-warning-bg` |
+| `danger`  | `--color-danger`  | `--color-danger-dark`  | `--color-danger-bg`  | `--color-danger-hover`  | `--color-on-danger`  | `--color-on-danger-bg`  |
+| `neutral` | `--color-neutral` | `--color-neutral-dark` | `--color-neutral-bg` | `--color-neutral-hover` | `--color-on-neutral` | `--color-on-neutral-bg` |
+
+The table is a **rectangle on purpose.** Every family has exactly the same six
+tokens, so the symmetric guess is always the right one.
+
+### Structural
+
+| role            | token                    | AA-safe for text?     |
+| --------------- | ------------------------ | --------------------- |
+| body text       | `--color-text`           | ✅ all 18 themes      |
+| secondary text  | `--color-text-secondary` | ✅ all 18 themes      |
+| tertiary text   | `--color-text-tertiary`  | ⚠️ fails in 5 themes  |
+| muted text      | `--color-text-muted`     | ⚠️ fails in 14 themes |
+| border          | `--color-border`         | —                     |
+| subtle border   | `--color-border-light`   | —                     |
+| page background | `--color-bg`             | —                     |
+| card surface    | `--color-bg-card`        | —                     |
+| alt surface     | `--color-bg-alt`         | —                     |
+| hover surface   | `--color-bg-hover`       | —                     |
+| modal scrim     | `--color-bg-overlay`     | —                     |
+
+> **`-tertiary` and `-muted` are decorative-only.** Measured against
+> `bg`/`bg-card`/`bg-alt` in all 18 themes, `-tertiary` drops below 4.5:1 in 5
+> and `-muted` in 14. Use them for de-emphasised ornament (placeholder glyphs,
+> disabled states — WCAG exempts inactive controls). **Any text a user must
+> read gets `--color-text` or `--color-text-secondary`**, both of which clear
+> AA on every surface in every theme. `check-contrast.mjs` gates those two and
+> deliberately does not gate the other two.
+
+**41 tokens total.** Non-color tokens (spacing, radius, shadows, type) use the
+`--hdk-*` prefix — see [`README.md`](./README.md).
+
+---
+
+## Anti-patterns — hard rules
+
+| ❌ Never                                                                    | ✅ Instead                      | Why                                                                                                           |
+| --------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `text-white`, `color: #fff` on a filled button                              | `text-on-<f>`                   | `--color-<f>` is light in many themes; white-on-light is invisible                                            |
+| `var(--color-x, #hex)`                                                      | `var(--color-x)`                | A fallback renders the hardcoded value, so a wrong token looks right in light mode and breaks in the other 17 |
+| `text-<f>` on `bg-<f>-bg`                                                   | `text-on-<f>-bg`                | Fails AA in 62/90 theme×family combinations                                                                   |
+| `[data-theme='dark'] .foo { color: … }`                                     | one token, no branch            | Tokens already switch per theme; branching double-applies                                                     |
+| Inventing `--color-<f>-light` / `-lighter` / `-darker` / `--color-muted-bg` | the six canonical family tokens | Removed in v3.0.0 — see [`THEME_GRAVEYARD.md`](./THEME_GRAVEYARD.md)                                          |
+| `--color-<f>` as body text                                                  | `--color-text`                  | Solid fills are for backgrounds; §4 of the rules doc                                                          |
+| `@import "@wolffm/themes/style.css" layer(base)`                            | import it **unlayered**         | Layering it makes every color resolve to nothing                                                              |
+
+---
+
+## Icons
+
+Icons are part of the theme contract, not each app's business. Raw emoji were the old
+answer and they are retired: the same codepoint renders differently on every platform,
+and no CSS can fix it. The package ships **78 vendored line icons** (artwork from
+[Lucide](https://lucide.dev), ISC — see `LICENSE-lucide`) behind an enforced allowlist.
+
+**Reference icons by name. Never inline your own SVG, and never add an emoji.**
+
+### Three consumption paths
+
+```tsx
+// React, in an app that also uses the theming stack
+import { Icon } from '@wolffm/themes'
+;<Icon name="popcorn" />
+;<Icon name="popcorn" variant="tint" family="warning" />
+```
+
+```tsx
+// React, icons only — same component, none of the theming stack.
+// The root barrel re-exports useTheme, which imports @wolffm/prefs-client
+// and zod. If all you want is glyphs, take them from here instead.
+import { Icon } from '@wolffm/themes/icons/react'
+```
+
+```astro
+---
+// Astro / Qwik / plain HTML — no client JS, CSP-safe
+import { getIconSvg, getIconTileClass } from '@wolffm/themes/icons'
+---
+<span set:html={getIconSvg('popcorn')} />
+<span class={getIconTileClass('warning', 'tint')} set:html={getIconSvg('popcorn')} />
+```
+
+Both paths render byte-identical geometry — that is asserted in `e2e/icons.spec.ts`.
+
+Import the stylesheet **unlayered**, next to `style.css`:
+
+```css
+@import '@wolffm/themes/style.css';
+@import '@wolffm/themes/icons.css';
+```
+
+### Colour: bare glyphs inherit, accents go on the tile
+
+A bare icon inherits `currentColor`, so it is exactly as legible as the text beside it
+and carries no contrast obligation of its own. **That is the default, and usually the
+right answer.**
+
+Do **not** paint the glyph with an accent token. Measured across all 18 themes on both
+`--color-bg-card` and `--color-bg`, a bare `--color-warning` glyph misses the WCAG
+1.4.11 non-text minimum of 3:1 in 8 of 36 combinations (light 2.15, ocean-light 1.92,
+pink-light 1.67); every other family fails somewhere too, and `--color-<f>-dark` does
+not rescue it. This is the same accent-as-text anti-pattern listed above, and
+`check:contrast` does **not** cover it — it validates `on-<f>` over `<f>`, never an
+accent over a surface.
+
+When you want the accent, put it on the tile. Both treatments pass 3:1 in 18/18 themes
+for all five families, because they reuse pairings the system already guarantees:
+
+| Variant  | Background       | Glyph               | Contrast                      |
+| -------- | ---------------- | ------------------- | ----------------------------- |
+| `bare`   | — (inherits)     | `currentColor`      | matches its text, always safe |
+| `accent` | — (inherits)     | `--color-<f>`       | **yours to own** — see below  |
+| `tint`   | `--color-<f>-bg` | `--color-on-<f>-bg` | 3:1 in 18/18 themes           |
+| `filled` | `--color-<f>`    | `--color-on-<f>`    | 3:1 in 18/18 themes           |
+
+**How you colour an icon is your call; where the colour comes from is not.** Every
+variant resolves through family tokens, and no raw colour can travel through this
+API — so an icon cannot drift from the theme.
+
+Two cases, both first-class:
+
+```tsx
+// Inline in a button — inherit, so the icon matches the button's own text in
+// every theme with no extra thought.
+<button className="pill-btn"><Icon name="plus" /> Add</button>
+
+// Its own element, deliberately a different colour from the surrounding text.
+<Icon name="warning" variant="accent" family="danger" />
+```
+
+`accent` is opt-in rather than default because contrast moves to you when you use
+it: a bare accent glyph clears 3:1 on a card or page surface in 28 of 36
+theme/surface combinations for `warning`. That is fine when you know the surface —
+an accent glyph on a tinted row, or beside a label you have checked — and wrong as
+a blanket default. When the accent must be safe everywhere, use a tile.
+
+Framework-free gets the same control:
+
+```js
+getIconSvg('warning', { family: 'danger' }) // accent glyph
+getIconSvg('plus') // inherits
+```
+
+### The set
+
+| Name           | Name          | Name         | Name          | Name         | Name           |
+| -------------- | ------------- | ------------ | ------------- | ------------ | -------------- |
+| `activity`     | `antenna`     | `arrow-left` | `arrow-right` | `book`       | `briefcase`    |
+| `broom`        | `calendar`    | `camera`     | `chat`        | `check`      | `chevron-down` |
+| `circle`       | `clapper`     | `clipboard`  | `clock`       | `close`      | `compass`      |
+| `crop`         | `crown`       | `desktop`    | `document`    | `download`   | `edit`         |
+| `error`        | `eye`         | `fire`       | `folder`      | `gear`       | `handshake`    |
+| `helping-hand` | `home`        | `hourglass`  | `image`       | `inbox`      | `info`         |
+| `link`         | `lock`        | `magnifier`  | `mail`        | `masks`      | `minus`        |
+| `music`        | `note`        | `package`    | `palette`     | `panel-left` | `panel-right`  |
+| `paste`        | `play`        | `plus`       | `popcorn`     | `printer`    | `redo`         |
+| `refresh`      | `robot`       | `scissors`   | `shuffle`     | `skull`      | `sleep`        |
+| `sparkles`     | `star`        | `stop`       | `thumbs-down` | `thumbs-up`  | `trash`        |
+| `trophy`       | `undo`        | `upload`     | `user`        | `videotape`  | `volume-high`  |
+| `volume-low`   | `volume-mute` | `wand`       | `warning`     | `wave`       | `wrench`       |
+
+### See them all
+
+`pnpm run gallery` (in hadoku-task) serves a live page at
+`http://localhost:5200/dev/gallery/index.html`: every icon, the real
+`<HadokuThemePicker>` to sweep all 18 themes, variant/family/size controls, the
+React-vs-string comparison, and the icons sitting in real app chrome. It is the
+fastest way to check a new icon before committing it.
+
+### Adding an icon
+
+1. Add `"name": "lucide-slug"` to `themes/src/icons/sources.json`.
+2. `pnpm run generate:icons` — fails loudly if the slug is not in lucide.
+3. Commit the regenerated `registry.generated.ts`.
+
+### Verify it
+
+```sh
+node node_modules/@wolffm/themes/scripts/check-icons.mjs ./src
+```
+
+Fails on raw emoji in an icon position and on icon names not in the registry. The name
+check matters most outside TypeScript — Astro templates and JSON catalogues never see
+the `IconName` union, so a typo there renders nothing at all, silently.
+
+---
+
+## Setup
+
+```css
+@import '@wolffm/themes/style.css'; /* 1. tokens — MUST be unlayered */
+@import 'tailwindcss'; /* 2. Tailwind */
+@import '@wolffm/themes/tailwind-colors.css'; /* 3. the color mapping */
+```
+
+That's the whole integration. **Do not hand-write an `@theme` color block** —
+`tailwind-colors.css` maps all 41 tokens, and a local copy is exactly the
+drift this package exists to prevent.
+
+Not using Tailwind? Import step 1 only and use `var(--color-*)` directly.
+
+### Why step 1 must stay unlayered
+
+Tailwind emits each `@theme` entry into `@layer theme` as `:root { --x: var(--x) }`
+— self-referential, and invalid on its own. It resolves only because
+`style.css` declares the same properties **outside** any cascade layer, and
+unlayered declarations win. Put it in a layer and all 41 colors silently
+become `transparent`.
+
+---
+
+## Verify it
+
+```sh
+node node_modules/@wolffm/themes/scripts/check-usage.mjs ./src
+```
+
+Fails the build on: unknown tokens, Tailwind classes with no matching token,
+`var()` fallbacks, and layered imports of `style.css`. Wire it into `lint` and
+pre-commit — an unmapped class produces **no CSS rule at all**, so neither
+typecheck nor build will ever catch it for you.

package/dist/HadokuThemeRoot.d.ts

@@ -0,0 +1,53 @@
+/**
+ * HadokuThemeRoot — the single thing a hadoku app mounts to get the platform's
+ * theming and the locked header.
+ *
+ * Wrap the app root once:
+ *
+ * ```tsx
+ * import { HadokuThemeRoot } from '@wolffm/themes'
+ *
+ * export function mount(el: HTMLElement) {
+ *   createRoot(el).render(
+ *     <HadokuThemeRoot>
+ *       <App />
+ *     </HadokuThemeRoot>
+ *   )
+ * }
+ * ```
+ *
+ * That is the entire integration. `<AppHeader>` then renders the shared theme
+ * picker and the shared settings gear from this context — an app does not pass
+ * them, cannot substitute them, and no longer needs a local `useTheme`,
+ * `themePrefs` or `themeConfig` module.
+ *
+ * WHY THE CONTEXT LIVES HERE TOO
+ * -------------------------------
+ * It did not always. The context was defined in task-ui-components (where
+ * AppHeader consumes it) and only FILLED here, because this package used to
+ * import the theme icons from there and the reverse import would have closed a
+ * cycle.
+ *
+ * A context defined in one package and provided from another only works while
+ * exactly one copy of the defining module exists across every install tree,
+ * bundle and import map that touches it. That held until it didn't: on
+ * 2026-08-05 three apps threw "No <HadokuThemeRoot> above this component" with
+ * the provider plainly mounted, because a second copy of task-ui-components
+ * meant a second createContext() — provider filling one, consumer reading the
+ * other.
+ *
+ * Moving the icons here reversed the arrow, so the context now ships beside the
+ * provider that fills it, in the package every app already resolves through the
+ * parent's import map.
+ */
+import React, { type RefObject } from 'react';
+export interface HadokuThemeRootProps {
+    children: React.ReactNode;
+    /** Theme forced by a parent shell (the portfolio passes its resolved theme
+     *  into micro-frontend mounts). Omit for a standalone app. */
+    theme?: string;
+    /** Mirror `data-theme` onto this container as well as <html> — needed when
+     *  the app mounts into a subtree rather than owning the document. */
+    containerRef?: RefObject<HTMLElement | null>;
+}
+export declare function HadokuThemeRoot({ children, theme: propsTheme, containerRef }: HadokuThemeRootProps): React.JSX.Element;

package/dist/HadokuThemeRoot.js

@@ -0,0 +1,66 @@
+/**
+ * HadokuThemeRoot — the single thing a hadoku app mounts to get the platform's
+ * theming and the locked header.
+ *
+ * Wrap the app root once:
+ *
+ * ```tsx
+ * import { HadokuThemeRoot } from '@wolffm/themes'
+ *
+ * export function mount(el: HTMLElement) {
+ *   createRoot(el).render(
+ *     <HadokuThemeRoot>
+ *       <App />
+ *     </HadokuThemeRoot>
+ *   )
+ * }
+ * ```
+ *
+ * That is the entire integration. `<AppHeader>` then renders the shared theme
+ * picker and the shared settings gear from this context — an app does not pass
+ * them, cannot substitute them, and no longer needs a local `useTheme`,
+ * `themePrefs` or `themeConfig` module.
+ *
+ * WHY THE CONTEXT LIVES HERE TOO
+ * -------------------------------
+ * It did not always. The context was defined in task-ui-components (where
+ * AppHeader consumes it) and only FILLED here, because this package used to
+ * import the theme icons from there and the reverse import would have closed a
+ * cycle.
+ *
+ * A context defined in one package and provided from another only works while
+ * exactly one copy of the defining module exists across every install tree,
+ * bundle and import map that touches it. That held until it didn't: on
+ * 2026-08-05 three apps threw "No <HadokuThemeRoot> above this component" with
+ * the provider plainly mounted, because a second copy of task-ui-components
+ * meant a second createContext() — provider filling one, consumer reading the
+ * other.
+ *
+ * Moving the icons here reversed the arrow, so the context now ships beside the
+ * provider that fills it, in the package every app already resolves through the
+ * parent's import map.
+ */
+import React, { useMemo } from 'react';
+import { HadokuThemeProvider } from './themeContext.js';
+import { useTheme } from './useTheme.js';
+import { THEME_ICON_MAP } from './metadata.js';
+/** Resolve a theme name to its icon. Central so the picker's toggle button
+ *  looks identical in every app — this used to be a per-app arrow function,
+ *  and one app had a debug logger inside it. */
+function getThemeIcon(theme) {
+    const Icon = THEME_ICON_MAP[theme];
+    return Icon ? React.createElement(Icon, null) : null;
+}
+export function HadokuThemeRoot({ children, theme: propsTheme, containerRef }) {
+    const t = useTheme({ propsTheme, containerRef });
+    const value = useMemo(() => ({
+        theme: t.theme,
+        setTheme: t.setTheme,
+        themeFamilies: t.themeFamilies,
+        getThemeIcon,
+        isDarkTheme: t.isDarkTheme,
+        isThemeReady: t.isThemeReady,
+        isInitialThemeLoad: t.isInitialThemeLoad
+    }), [t.theme, t.setTheme, t.themeFamilies, t.isDarkTheme, t.isThemeReady, t.isInitialThemeLoad]);
+    return React.createElement(HadokuThemeProvider, { value: value }, children);
+}

package/dist/ThemeIcons.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Theme-family icons — one per theme pair in THEME_FAMILIES.
+ *
+ * These lived in @wolffm/task-ui-components, which is why @wolffm/themes had to
+ * import from it, which is why the dependency arrow ran themes -> ui-components,
+ * which is why HadokuThemeContext could not be defined next to the provider that
+ * fills it. That split is what let a duplicated ui-components module produce two
+ * distinct React contexts and take three apps down on 2026-08-05.
+ *
+ * They belong here: they are theme metadata, they are consumed by THEME_FAMILIES
+ * a few lines away, and they depend on nothing but React. Moving them reverses
+ * the arrow and lets the context live with its provider.
+ *
+ * UI chrome (SettingsIcon, TagIcon) and the fallback shapes stay in
+ * task-ui-components — those belong to the components that draw them.
+ */
+import React from 'react';
+export declare const SunIcon: () => React.JSX.Element;
+export declare const MoonIcon: () => React.JSX.Element;
+export declare const StrawberryIcon: () => React.JSX.Element;
+export declare const WaveIcon: () => React.JSX.Element;
+export declare const ZapIcon: () => React.JSX.Element;
+export declare const CoffeeIcon: () => React.JSX.Element;
+export declare const FlowerIcon: () => React.JSX.Element;
+export declare const HeartIcon: () => React.JSX.Element;
+export declare const LeafIcon: () => React.JSX.Element;
+export declare const LanternIcon: () => React.JSX.Element;
+/**
+ * Generic/Fallback icons for custom themes without specific icons
+ * These provide visual differentiation when using the ThemePicker with custom themes
+ */

package/dist/ThemeIcons.js

@@ -0,0 +1,91 @@
+/**
+ * Theme-family icons — one per theme pair in THEME_FAMILIES.
+ *
+ * These lived in @wolffm/task-ui-components, which is why @wolffm/themes had to
+ * import from it, which is why the dependency arrow ran themes -> ui-components,
+ * which is why HadokuThemeContext could not be defined next to the provider that
+ * fills it. That split is what let a duplicated ui-components module produce two
+ * distinct React contexts and take three apps down on 2026-08-05.
+ *
+ * They belong here: they are theme metadata, they are consumed by THEME_FAMILIES
+ * a few lines away, and they depend on nothing but React. Moving them reverses
+ * the arrow and lets the context live with its provider.
+ *
+ * UI chrome (SettingsIcon, TagIcon) and the fallback shapes stay in
+ * task-ui-components — those belong to the components that draw them.
+ */
+import React from 'react';
+/** Shared SVG attributes. Duplicated from task-ui-components' icon file rather
+ *  than imported: this package must not depend on that one — that dependency is
+ *  the whole reason the icons moved. Seventeen lines of constants is the right
+ *  price for a one-way graph. */
+const iconProps = {
+    width: 20,
+    height: 20,
+    viewBox: '0 0 24 24',
+    fill: 'none',
+    stroke: 'currentColor',
+    strokeWidth: 2,
+    strokeLinecap: 'round',
+    strokeLinejoin: 'round'
+};
+export const SunIcon = () => (React.createElement("svg", { ...iconProps },
+    React.createElement("circle", { cx: "12", cy: "12", r: "5" }),
+    React.createElement("line", { x1: "12", y1: "1", x2: "12", y2: "3" }),
+    React.createElement("line", { x1: "12", y1: "21", x2: "12", y2: "23" }),
+    React.createElement("line", { x1: "4.22", y1: "4.22", x2: "5.64", y2: "5.64" }),
+    React.createElement("line", { x1: "18.36", y1: "18.36", x2: "19.78", y2: "19.78" }),
+    React.createElement("line", { x1: "1", y1: "12", x2: "3", y2: "12" }),
+    React.createElement("line", { x1: "21", y1: "12", x2: "23", y2: "12" }),
+    React.createElement("line", { x1: "4.22", y1: "19.78", x2: "5.64", y2: "18.36" }),
+    React.createElement("line", { x1: "18.36", y1: "5.64", x2: "19.78", y2: "4.22" })));
+export const MoonIcon = () => (React.createElement("svg", { ...iconProps },
+    React.createElement("path", { d: "M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" })));
+export const StrawberryIcon = () => (React.createElement("svg", { ...iconProps },
+    React.createElement("path", { d: "M12 21 C12 21 6.5 15 6.5 11 C6.5 8.5 8 7 10 7 C11 7 12 7.5 12 7.5 C12 7.5 13 7 14 7 C16 7 17.5 8.5 17.5 11 C17.5 15 12 21 12 21 Z", fill: "currentColor" }),
+    React.createElement("path", { d: "M9.5 7.5 L9 5 L11 5.5 Z", fill: "currentColor" }),
+    React.createElement("path", { d: "M14.5 7.5 L15 5 L13 5.5 Z", fill: "currentColor" }),
+    React.createElement("path", { d: "M12 7.5 L12 4 L12 5", stroke: "currentColor", strokeWidth: "1.5", fill: "none" }),
+    React.createElement("line", { x1: "10", y1: "10", x2: "10", y2: "11", stroke: "currentColor", strokeWidth: "1", opacity: "0.4" }),
+    React.createElement("line", { x1: "14", y1: "10", x2: "14", y2: "11", stroke: "currentColor", strokeWidth: "1", opacity: "0.4" }),
+    React.createElement("line", { x1: "9", y1: "13", x2: "9", y2: "14", stroke: "currentColor", strokeWidth: "1", opacity: "0.4" }),
+    React.createElement("line", { x1: "15", y1: "13", x2: "15", y2: "14", stroke: "currentColor", strokeWidth: "1", opacity: "0.4" }),
+    React.createElement("line", { x1: "11", y1: "16", x2: "11", y2: "17", stroke: "currentColor", strokeWidth: "1", opacity: "0.4" }),
+    React.createElement("line", { x1: "13", y1: "16", x2: "13", y2: "17", stroke: "currentColor", strokeWidth: "1", opacity: "0.4" })));
+export const WaveIcon = () => (React.createElement("svg", { ...iconProps },
+    React.createElement("path", { d: "M2 12c2-2 4-2 6 0s4 2 6 0 4-2 6 0" }),
+    React.createElement("path", { d: "M2 17c2-2 4-2 6 0s4 2 6 0 4-2 6 0" }),
+    React.createElement("path", { d: "M2 7c2-2 4-2 6 0s4 2 6 0 4-2 6 0" })));
+export const ZapIcon = () => (React.createElement("svg", { ...iconProps },
+    React.createElement("polygon", { points: "13 2 3 14 12 14 11 22 21 10 12 10 13 2" })));
+export const CoffeeIcon = () => (React.createElement("svg", { ...iconProps },
+    React.createElement("path", { d: "M18 8h1a4 4 0 0 1 0 8h-1" }),
+    React.createElement("path", { d: "M2 8h16v9a4 4 0 0 1-4 4H6a4 4 0 0 1-4-4V8z" }),
+    React.createElement("line", { x1: "6", y1: "1", x2: "6", y2: "4" }),
+    React.createElement("line", { x1: "10", y1: "1", x2: "10", y2: "4" }),
+    React.createElement("line", { x1: "14", y1: "1", x2: "14", y2: "4" })));
+export const FlowerIcon = () => (React.createElement("svg", { ...iconProps },
+    React.createElement("circle", { cx: "12", cy: "12", r: "2", fill: "currentColor" }),
+    React.createElement("circle", { cx: "12", cy: "6", r: "2.5", fill: "none", stroke: "currentColor", strokeWidth: "2" }),
+    React.createElement("circle", { cx: "18", cy: "10", r: "2.5", fill: "none", stroke: "currentColor", strokeWidth: "2" }),
+    React.createElement("circle", { cx: "16", cy: "16", r: "2.5", fill: "none", stroke: "currentColor", strokeWidth: "2" }),
+    React.createElement("circle", { cx: "8", cy: "16", r: "2.5", fill: "none", stroke: "currentColor", strokeWidth: "2" }),
+    React.createElement("circle", { cx: "6", cy: "10", r: "2.5", fill: "none", stroke: "currentColor", strokeWidth: "2" })));
+export const HeartIcon = () => (React.createElement("svg", { ...iconProps },
+    React.createElement("path", { d: "M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z", fill: "currentColor" })));
+export const LeafIcon = () => (React.createElement("svg", { ...iconProps },
+    React.createElement("path", { d: "M11 20A7 7 0 0 1 9.8 6.1C15.5 5 17 4.48 19 2c1 2 2 4.18 2 8 0 5.5-4.78 10-10 10Z", fill: "currentColor" }),
+    React.createElement("path", { d: "M2 21c0-3 1.85-5.36 5.08-6C9 14.5 11 14 11 20", stroke: "currentColor", strokeWidth: "2", fill: "none" }),
+    React.createElement("path", { d: "M11 8c3 2 5 4 7 7", stroke: "white", strokeWidth: "1.5", opacity: "0.4" })));
+export const LanternIcon = () => (React.createElement("svg", { ...iconProps },
+    React.createElement("path", { d: "M12 1.5v2" }),
+    React.createElement("path", { d: "M9 3.5h6" }),
+    React.createElement("path", { d: "M8.5 5.5h7c3 1.8 4.5 4 4.5 6.5s-1.5 4.7-4.5 6.5h-7C5.5 16.7 4 14.5 4 12s1.5-4.7 4.5-6.5z" }),
+    React.createElement("path", { d: "M5 9.5q7 1.6 14 0", strokeWidth: "1.5" }),
+    React.createElement("path", { d: "M5 14.5q7 -1.6 14 0", strokeWidth: "1.5" }),
+    React.createElement("path", { d: "M9 20.5h6" }),
+    React.createElement("path", { d: "M12 20.5v2" })));
+/**
+ * Generic/Fallback icons for custom themes without specific icons
+ * These provide visual differentiation when using the ThemePicker with custom themes
+ */

package/dist/effects.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-theme advanced effect map
+ *
+ * Declares which effect modifier each surface type uses for a given
+ * theme. Components that want to apply effects automatically (Path B
+ * — themed primitive components) read this map. Until then, consumers
+ * apply hdk-advanced-surface[--modifier] classes directly in JSX.
+ *
+ * To add an advanced contract to a theme:
+ *   1. Define --advanced-stop-* and --advanced-gradient in the theme's
+ *      [data-theme='X'] block in style.css
+ *   2. Add an entry to THEME_EFFECTS below
+ */
+import type { Theme } from './index';
+export type AdvancedEffect = 'shift' | 'cascade-rich' | 'sat-rich' | 'none';
+export interface ThemeEffectMap {
+    card: AdvancedEffect;
+    modal: AdvancedEffect;
+    button: AdvancedEffect;
+}
+export declare const THEME_EFFECTS: Partial<Record<Theme, ThemeEffectMap>>;
+/** True when the theme ships an advanced visual contract. */
+export declare function hasAdvanced(theme: string): boolean;
+/** Returns the effect map for a theme, or null if it has no advanced contract. */
+export declare function getThemeEffects(theme: string): ThemeEffectMap | null;

package/dist/effects.js

@@ -0,0 +1,25 @@
+/**
+ * Per-theme advanced effect map
+ *
+ * Declares which effect modifier each surface type uses for a given
+ * theme. Components that want to apply effects automatically (Path B
+ * — themed primitive components) read this map. Until then, consumers
+ * apply hdk-advanced-surface[--modifier] classes directly in JSX.
+ *
+ * To add an advanced contract to a theme:
+ *   1. Define --advanced-stop-* and --advanced-gradient in the theme's
+ *      [data-theme='X'] block in style.css
+ *   2. Add an entry to THEME_EFFECTS below
+ */
+export const THEME_EFFECTS = {
+    light: { card: 'shift', modal: 'none', button: 'none' },
+    'cyberpunk-dark': { card: 'cascade-rich', modal: 'none', button: 'none' }
+};
+/** True when the theme ships an advanced visual contract. */
+export function hasAdvanced(theme) {
+    return theme in THEME_EFFECTS;
+}
+/** Returns the effect map for a theme, or null if it has no advanced contract. */
+export function getThemeEffects(theme) {
+    return THEME_EFFECTS[theme] ?? null;
+}

package/dist/icons/Icon.d.ts

@@ -0,0 +1,36 @@
+/**
+ * React `<Icon>` — a thin wrapper over the string registry.
+ *
+ * The glyph is emitted as real JSX children rather than dangerouslySetInnerHTML: the
+ * markup is ours and build-time-generated, but React apps run under the same strict
+ * CSP as the frontpage, and parsing 78 vendored strings at runtime buys nothing when
+ * the shapes can be elements. So the paths are parsed once, lazily, per icon actually
+ * rendered — an app that uses six icons never touches the other seventy-two.
+ */
+import React from 'react';
+import type { IconName } from './registry.generated';
+import type { IconFamily, IconVariant } from './index';
+export interface IconProps {
+    name: IconName;
+    /** CSS length. Defaults to `1em` so the glyph scales with surrounding text. */
+    size?: string | number;
+    /**
+     * Which family token colours this icon. Applies to `accent` (the glyph itself)
+     * and to `tint`/`filled` (the tile). Ignored for `bare`, which inherits
+     * `currentColor` by design.
+     */
+    family?: IconFamily;
+    /** `bare` (default), `accent`, `tint`, or `filled` — see IconVariant. */
+    variant?: IconVariant;
+    /** Round the accent tile. No effect when `variant` is `bare`. */
+    round?: boolean;
+    /**
+     * Accessible name. Omit for decorative icons — those render `aria-hidden` so a
+     * screen reader does not announce a glyph that repeats an adjacent text label.
+     */
+    title?: string;
+    className?: string;
+    /** Stroke width in the 24x24 viewBox. Lucide's default is 2. */
+    strokeWidth?: number;
+}
+export declare const Icon: React.FC<IconProps>;