@hraness/design-kit 0.31.1

package/PALETTES.md

@@ -0,0 +1,90 @@
+# Semantic palettes
+
+Applications can opt into Paper, Catppuccin, Gruvbox, Rosé Pine, or Tokyo Night, with light, dark, and system appearance. Catppuccin dark is the default. Existing `DesignThemeProvider` consumers keep their existing appearance behavior until they opt in.
+
+## Install and render
+
+Install the explicit UI peer and import `@hraness/design-kit/styles.css` once for the full design system. Applications with their own fonts and reset can import `@hraness/design-kit/palettes.css` for the palette CSS and compiled compositions alone. Do not import both entries.
+
+Render the initial document with `data-palette="catppuccin"`, `data-theme="dark"`, and the class returned by `getDesignPaletteTheme("catppuccin", "dark")`. This gives the page a complete palette before JavaScript runs.
+
+Bundle an application-owned browser entry that calls `initDesignPalette()` from `@hraness/design-kit/browser`. Load that bundle as a same-origin, synchronous external script in the document head. It applies the saved preference before the page paints. It does not require inline scripts, inline styles, or a weaker content security policy.
+
+Wrap React content in `DesignPaletteProvider` and retain one `ThemeMenuButton` as the final header action. The provider adopts the document's existing controller. The menu exposes separate Theme and Appearance radio groups. `useDesignPalette()` provides the preference and its resolved light or dark mode.
+
+A product can use the browser controller without React. Its snapshot, subscription, and `setPreference` methods support native controls. Initialization is explicit; importing the browser package does not change the document or register listeners.
+
+## Product defaults and static pages
+
+Choose a default for the product family, then pass the same `defaultPreference`
+to the head bootstrap and `DesignPaletteProvider`. For example,
+`{ palette: "gruvbox", mode: "system" }` gives a writing suite a warm default
+while preserving a visitor's saved choice. Keep browser theme-color metadata
+aligned with the chosen palette and use `ThemeColorSync` for later changes.
+
+For a system-first document, render `data-palette="gruvbox"` without a
+`data-theme` attribute. The generated CSS uses `light-dark()` before JavaScript,
+including when scripting is disabled. A concrete `data-theme="light"` or
+`data-theme="dark"` takes precedence. Static palette islands use the same two
+attributes; React portals retain their complete generated class.
+
+The full and minimal foundations include this behavior. Static sites with an
+existing stylesheet can import `@hraness/design-kit/palette-bridge.css`; it
+includes `palette-system.css` and maps the raw values onto the semantic roles.
+The narrower `palette-system.css` export contains only raw palette values and
+color-scheme, for build pipelines that already supply their own role mapping.
+Neither stylesheet needs a browser script or an animation runtime.
+
+Plain reading surfaces inherit the selected palette through their existing
+`--plain-*` roles. Put `data-palette` on the document, a containing element, or
+the `.plain-site` surface itself. A nested boundary resolves its own palette
+and appearance, including inside a neutral dark document. Standalone and
+compiled foundations use the same precedence; products need no additional
+color overrides.
+
+## Preferences and embedded views
+
+The controller stores only `{ "palette": "catppuccin", "mode": "dark" }` under `hraness-design-palette-v1` in the current origin's local storage. It supports all five palette identifiers and `light`, `dark`, or `system`. Invalid or inaccessible storage falls back to Catppuccin dark. Storage events synchronize other tabs, and system mode follows operating-system appearance changes.
+
+Use `forcedPreference` for an embedded example or fixed preview in its own document. A document has one palette controller; conflicting nested providers are rejected. Forced providers do not persist preferences or adopt the parent document's controller. Each document still needs its initial attributes and compiled palette class. The host owns any propagation between iframe documents.
+
+Portalled controls receive the resolved palette class through the shared portal theme context. React portal roots retain the complete generated palette class and resolved `data-theme` value. Authored static islands can use the attribute-only system contract described above. Color selection never changes typography, layout, or application data.
+
+## StyleX and semantic roles
+
+`src/palettes.ts` owns the source colors and their application adaptations. `bun run generate:palettes` writes the static system palette sheet and ten complete `stylex.createTheme` recipes against one `stylex.defineVars` contract in `src/palette-tokens.stylex.ts`. The build verifies that the generated source is current, then compiles the recipes with runtime CSS injection disabled.
+
+The global CSS boundary maps existing `--primary`, `--danger`, `--warning`, `--success`, surface, text, focus, and `--ui-*` roles to the compiled `--hraness-palette-*` properties. Product CSS and shared controls consume the same values. Use semantic roles for meaning; keep text or an icon with each status so color is not its only cue.
+
+Compiler adopters that own their typography import `@hraness/design-kit/compiler-palettes.css`. It includes the portable UI foundation and semantic palette bridge, without webfonts, marketing styles, or standalone atomic recipes. It supports the palette controller, `DesignPaletteMenuButton`, and portable UI primitives. Full design-kit compositions use `compiler-foundation.css`, which includes that minimal foundation plus the package's typography and presentation styles.
+
+Both routes register the UI and design-kit manifests and link one finalized cross-package stylesheet after the foundation. The manifest binds `compiler-palettes.css`; the full foundation imports it once. Do not also load the standalone `palettes.css`, `styles.css`, or `stylex.css` entries.
+
+This uses StyleX's documented [variable contract](https://stylexjs.com/docs/api/javascript/defineVars/) and [compiled theme classes](https://stylexjs.com/docs/learn/theming/creating-themes/). Applications consuming the precompiled package do not need another StyleX compiler configuration.
+
+## Sources and contrast
+
+| Theme | Light source | Dark source |
+| --- | --- | --- |
+| [Catppuccin](https://catppuccin.com/palette/) | Latte | Mocha |
+| [Gruvbox](https://github.com/morhetz/gruvbox/blob/master/colors/gruvbox.vim) | Light | Dark |
+| [Rosé Pine](https://rosepinetheme.com/palette/) | Dawn | Rosé Pine |
+| [Tokyo Night](https://github.com/folke/tokyonight.nvim/tree/main/extras/lua) | Day | Night |
+
+These are interface adaptations of the upstream palettes. Backgrounds retain their source values. Text and control colors move toward black or white when necessary for readability across the background, surface, raised surface, and hover surface. Body text reaches 7:1, secondary text and semantic text reach at least 4.5:1, and control boundaries reach at least 3:1. Filled semantic actions also have a tested foreground pair. Subtle separators are decorative and do not serve as the sole boundary of an interactive control.
+
+The recipe tests cover every supported color pair. Browser coverage checks actual inheritance, theme switching, storage, and overlays. Forced-colors mode uses system colors. Components remain responsible for appropriate labels, keyboard behavior, and focus visibility.
+
+## Paper as a product default
+
+Paper uses warm neutral backgrounds and one blue action color. Its source
+backgrounds and typography follow the shared studio visual reference;
+foreground, status, and control colors use the same readability adaptation
+as the other palettes. Use `defaultPreference={{ palette: "paper", mode: "system" }}`
+on both the bootstrap and `DesignPaletteProvider`. Existing saved palette
+preferences win; `legacyStorageKey` migrates an existing light, dark, or system
+choice. The package default remains Catppuccin dark.
+
+The [portable Paper stylesheet](PAPER_THEME.md) is generated from these same
+palette values. It supplies typography and marketing tokens to named-palette
+consumers while a non-Paper palette retains its selected colors.

package/PAPER_THEME.md

@@ -0,0 +1,128 @@
+# Paper theme
+
+Paper shares warm neutral surfaces, Nebula Sans typography, a compact heading
+scale, and blue actions across marketing sites and application defaults.
+The CSS is generated from the `paper` semantic palette and shared marketing header paint.
+Products retain their content, layout, functionality, and saved appearance.
+
+## Portable CSS contract 1
+
+Load `@hraness/design-kit/paper-theme.css` after existing theme styles, then set
+`data-hraness-theme="paper"` on the document root or a complete subtree:
+
+```html
+<html data-hraness-theme="paper" data-theme="light">
+```
+
+The export has no imports, font requests, reset, JavaScript, layout recipes,
+or dependency on React, UI, or a StyleX compiler. It uses standard CSS
+`light-dark()`, supported by Chrome 123+, Firefox 120+, and Safari 17.5+.
+Use the compiled palette route for applications whose existing CSS pipeline
+does not preserve this function. A root without `data-theme`, or with
+`data-theme="system"`, follows the operating system. Explicit `light` or
+`dark` wins; a nested boundary without a mode inherits its ancestor's
+`color-scheme`. Existing appearance controllers continue to own preferences.
+
+The stylesheet declares semantic product roles (`--background`, `--foreground`,
+`--surface`, `--surface-raised`, `--muted`, `--line`, `--control-border`,
+`--primary`, status and inverse pairs), the corresponding `--ui-*` roles,
+`--plain-*` publication aliases, and `--hraness-site-accent` with its foreground.
+Control boundaries and secondary text are contrast adapted; subtle grid lines
+remain decorative. Forced colors use system surface, text, and action colors. The `--plain-link`
+alias uses `LinkText`; primary actions and focus retain `Highlight`.
+Product CSS decides where to paint these roles, with one shared header correction.
+The opted-in `.hraness-marketing-header` receives the same paint as current
+marketing headers in `components.hraness-design-kit.legacy`. It retains the
+82% surface tint and 14px blur, with separate standard and WebKit feature
+queries so CSS optimization preserves both browser paths. An opaque surface
+applies when neither path is supported, reduced transparency is preferred, or
+forced colors are active. This rule changes paint only; header layout,
+positioning, and interactions remain owned by the component. Loading a fresh
+snapshot after an older marketing stylesheet applies the correction without
+changing the installed component or compiler versions.
+
+`--font-text`, `--font-heading`, and `--font-sans` use Nebula Sans with system
+fallbacks. Code remains system monospace. Load the existing licensed font
+assets separately, or keep an application's own font through later overrides.
+The snapshot has no hidden font download.
+
+Marketing roles inherit an 80rem measure, responsive gutter, restrained radii,
+and shared rhythm. The optional size tokens are:
+
+| Token | Default |
+| --- | --- |
+| `--hraness-paper-heading-size` | `clamp(1.75rem, 3vw, 2.375rem)` |
+| `--hraness-paper-section-heading-size` | `var(--hraness-type-h2-size, clamp(1.75rem, 1.45rem + .9vw, 2.125rem))`: the shared h2 size, never below 1.75rem |
+| `--hraness-paper-summary-size` | `1rem` |
+| `--hraness-paper-heading-leading` | `1.15` |
+| `--hraness-paper-heading-tracking` | `-.035em` |
+
+Current `ProductHero` and narrative section recipes read the size tokens with
+their existing sizes as fallbacks. `ProductHero.eyebrow` is optional, so compact
+pages can omit the extra label. Older pinned component versions can bind their
+documented heading classes to these tokens in a small product-owned adapter.
+The theme does not rewrite grids, navigation, mobile breakpoints, or app state.
+If a publication stylesheet redeclares variables on a descendant, explicitly
+opt that boundary in as well. Keep local exceptions in a separate stylesheet
+after the snapshot.
+
+## Palette-aware applications
+
+The existing palette catalog now includes `paper`; its global default remains
+Catppuccin dark. A product may choose Paper and System as its own default:
+
+```tsx
+<DesignPaletteProvider
+  defaultPreference={{ palette: "paper", mode: "system" }}
+  legacyStorageKey="product-appearance"
+>
+  {children}
+</DesignPaletteProvider>
+```
+
+Use the same options in `initDesignPalette` before the first paint and render
+the initial Paper class from `getDesignPaletteTheme("paper", "light")` with
+the corresponding initial attributes. A saved named palette takes precedence;
+a valid legacy Light, Dark, or System preference migrates without changing its
+mode. Do not use `forcedPreference` for an application's default.
+
+When the Paper CSS boundary also has a non-Paper `data-palette`, the portable
+stylesheet leaves its colors to the selected palette. Typography and rhythm
+remain shared. Complete nested palette islands and portalled controls still
+follow the existing [palette contract](PALETTES.md).
+
+## Independent snapshots
+
+Products may keep their current UI and compiler releases and vendor the exact
+CSS file under `vendor/hraness-paper`. From a reviewed design-kit checkout:
+
+```sh
+bun scripts/paper-theme-snapshot.ts --write /path/to/product/vendor/hraness-paper --source-commit FULL_40_CHARACTER_COMMIT
+bun scripts/paper-theme-snapshot.ts --check /path/to/product/vendor/hraness-paper
+```
+
+The installer reads `src/paper-theme.css` and `LICENSE` from that Git commit,
+not from the working tree. It writes `paper-theme.css`, `LICENSE`, and
+`provenance.json`, recording the repository, full source commit, public export,
+contract version, source paths, and SHA-256 hashes of both artifacts. A missing
+commit or unowned destination file fails. Existing snapshots must verify before
+an intentional upgrade. The checker reads only the three local files and
+detects edits to either artifact; it does not contact a service or update them.
+Consumer checks can implement that small hash contract in their own runtime.
+
+Contract 1 keeps existing semantic meanings and selectors stable. Additive
+tokens and compatible paint corrections do not require a coordinated upgrade. A breaking token or selector
+change requires a new contract and an explicit migration. Pin the package or
+source commit independently in every product; upgrade and validate each on its
+own schedule. Do not use sibling paths, mutable branches, or runtime CSS CDNs.
+
+## Evidence
+
+`src/palettes.test.ts` verifies every Paper text, control, and status contrast
+pair. `src/browser/design-palette.test.ts` covers saved choices and legacy
+appearance migration. `scripts/paper-theme-browser.ts` renders the standalone
+gallery at desktop and phone sizes, checks light/dark islands, system mode,
+palette isolation, marketing token inheritance, real native controls, optimized
+header blur, opaque capability fallback, reduced transparency, and forced colors. `src/paper-theme.test.ts` verifies generated CSS and snapshot
+integrity. The public `DesignSystemGallery` includes Paper specimens; load
+`paper-theme.css` alongside the gallery stylesheet to display them.