@hraness/design-kit 0.31.1

package/README.md

@@ -0,0 +1,745 @@
+# hraness/design-kit
+
+React components and CSS for Hraness apps and product sites: application shells, marketing sections, charts, themes, effects, and syntax highlighting. Built on `@hraness/ui`.
+
+`@hraness/ui` supplies the accessible React Aria primitives: actions, form fields, overlays, collections, navigation, and basic surfaces. This package builds on them with application shells, loading and error pages, saved light and dark appearance, charts and instrument controls, haptics, decorative effects, server-side syntax highlighting, plain-site CSS, and a gallery you can run.
+
+## Install
+
+Pin a GitHub release tag:
+
+```json
+{
+  "dependencies": {
+    "@hraness/design-kit": "github:hraness/design-kit#v0.31.1",
+    "@hraness/ui": "github:hraness/ui#v0.5.17"
+  }
+}
+```
+
+`@hraness/ui` is an explicit peer dependency with the supported range
+`>=0.5.16 <0.6.0`; consumers should pin an immutable compatible release such as
+`v0.5.17` when using the stylesheet, React, or compiler-adopter entries. The peer is optional at
+installation so the framework-neutral root and syntax highlighter can be used
+on their own. React 18 or 19 and React DOM 18 or 19 are also peer dependencies.
+
+### Provider artwork notices
+
+Version 0.31.1 includes Charm's complete license and copyright notices for the Crush HeartBit artwork in `vendor/provider-marks/CRUSH-LICENSE.md`. The package also retains the LobeHub MIT notice and identifies the exact Crush source commit.
+
+### Social posts carry claims only
+
+Version 0.31.0 keeps caveats out of the social kit. `buildSocialKit` skips the `limits` beat and any beat marked `social: false`, so their text stays in the launch post and never reaches X, Bluesky, Threads, LinkedIn, or the Show HN and Product Hunt fact sheet. A beat can carry a `socialPost`, a narrower wording that is accurate without the caveat its `post` keeps; `resolveLaunchBeats` fills its placeholders and the checks apply to it. `assertLaunchKit` now rejects a kit that carries a launch-post-only beat. New exports: `launchPostOnlyParts`, `isSocialBeat`, `socialBeats`, and `socialPostText`. Kits built from beats without a `limits` beat are unchanged.
+
+### Product names in the portfolio snapshot
+
+Version 0.30.3 refreshes the `@hraness/design-kit/portfolio` snapshot from the registry. Related-product cards now spell every product the way its own site does, including GhostGet, TextButler, SlopCamera, Soulscrape, Valhalla, and Excalibur (xcb), and names that were set in capitals, such as Stripe History and Lifecharts, now use their prose form. The snapshot adds icon.place, GhostGet Skills, System One Skills, and Pattern Language, with the current one-liners and relations. No export changes.
+
+### Narrow install tabs
+
+Version 0.30.2 keeps the narrow and stacked `PlatformInstall` layout in place when another package, such as `@hraness/site-footer`, compiles the same default atoms into a later cascade layer: the tab row and tabs now read their narrow and stacked values from private `--_hraness-platform-install-*` custom properties, so the tab row spans its column again and stacked tabs use their smaller label and padding. No prop or export changes. Version 0.30.1 keeps every `PlatformInstall` tab name whole in narrow columns. The component is now an inline-size container named `hraness-platform-install`, and its narrow rules follow the column it sits in rather than the viewport. At 30rem and below the tab row spans the column; at 17.5rem and below each mark stacks above its name, so macOS, Linux, and Windows stay whole down to a 200px tab row, such as a nested install panel on a 320px phone. No prop or export changes. Sites that mirror the hook classes in their own CSS should add `container: hraness-platform-install / inline-size` to `.hraness-platform-install`, move their narrow `.hraness-platform-install__tabs` and `__tab` rules from `@media (max-width: 30rem)` to `@container hraness-platform-install (max-width: 30rem)`, and copy the stacked `__tab` rule. Version 0.30.0 adds `site-shell.css` with `hraness-site-shell` and `hraness-site-shell__content` hooks. Short pages place their footer at the viewport bottom; long pages keep it below their content. Plain and marketing document bodies use the shared layout by default. Version 0.29.3 keeps selected install-tab labels and marks readable in forced-colors mode. Selected tabs preserve the paired system selection colors across their descendants, including hovered tabs.
+
+Version 0.29.2 keeps every `PlatformInstall` tab visible at 320 to 360px. Below 30rem the tab row spans its column, the tabs share its width and use tighter padding and a slightly smaller label, and a name is truncated only as a last resort, so the Windows tab no longer hides behind a sideways scroll. The component also defines each platform mark once as an SVG `<symbol>` and draws tabs and no-script labels by reference, which removes about 25 KB of repeated paths per instance. No prop or export changes. Sites that mirror the hook classes in their own CSS should copy the narrow rules for `.hraness-platform-install__tabs`, `__tab`, and the new `__tab-label`.
+
+### Forced-colors action labels
+
+Version 0.29.1 keeps marketing action labels readable with system button colors, including accent sections and hovered controls. Older consumers can load the standalone `@hraness/design-kit/marketing-forced-colors.css` after their existing marketing styles without changing normal appearance. Vendored copies must retain the exact released file and its provenance; local action color overrides must respect forced-colors mode.
+
+### Metallic brand marks
+
+`FoilMark` is available from both React entry points, including the server-safe
+`@hraness/design-kit/react/server`. Give it a transparent same-origin SVG (or a
+data URL); the exact artwork alpha carries the material and the original image
+remains underneath as a fallback. An optional `fallback` accepts the original
+inline vector for currentColor behavior. The mark is decorative unless `label`
+is supplied. Name its enclosing link once.
+
+React consumers load `@hraness/design-kit/components.css` or the complete
+`styles.css` entry. The raw marketing stylesheet alone styles authored HTML
+hooks; it does not contain the compiled React atoms.
+
+```tsx
+<MarketingSiteHeader brand="Relay" brandMark="/marks/relay.svg" links={[]} />
+<FoilMark src="/marks/relay.svg" size={44} />
+```
+
+Wordmarks and marks use contrast-bearing metal bands with a faint rainbow
+reflection, including before hydration and on touch devices. The existing
+`attachFoil` controller adds bounded pointer movement only when motion and
+forced-color preferences permit it. `--hraness-foil-reflection` defaults to
+`14%`; `--hraness-foil-image` can replace the shared text/mark paint. The
+spectrum image belongs to wordmarks and marks only: `.hraness-foil` and
+`[data-emphasis="primary"]` bordered surfaces keep a flat fill under one
+theme-aware monochrome edge, black on light and white on dark, overridable
+through `--hraness-foil-edge`. A blocked inline
+mask style or unsupported masks retain the original image. Cross-origin masks
+require the asset server's CORS permission; prefer local assets. Forced colors
+remove the overlay entirely.
+
+### Provider and agent marks
+
+`providerMarks` (root entry) is the shared registry of coding-agent and
+model-vendor identities: display name, aliases, accent color, monochrome
+glyph, and vendor-colored artwork where the source publishes one. `providerMark()`
+resolves any display name or alias by folded lowercase-alphanumeric match, so
+"Claude Code", `claude-code`, and `claudecode` land on the same mark.
+
+```tsx
+import { providerMark } from "@hraness/design-kit";
+import { ProviderMark, ProviderMarkChip } from "@hraness/design-kit/react";
+
+<ProviderMark mark="claudecode" size={40} />
+<ProviderMark mark="crush" tone="solid" size={40} />
+<ProviderMarkChip mark="goose" />
+```
+
+`ProviderMark` renders an accent-tinted tile by default, a saturated brand
+tile with `tone="solid"`, or the bare glyph with `tone="plain"`. Identity
+artwork comes from vendored sources (`vendor/provider-marks/`, LobeHub
+icons 1.95.1 plus the Crush and Aider marks documented in its UPSTREAM.md);
+marks without published color art keep a retinted glyph, and unknown names
+fall back to a neutral monogram tile rather than invented artwork. In forced
+colors the artwork yields to a system-color glyph or monogram. Non-React
+consumers can build data URIs with `providerMarkGlyphDataUri` and
+`providerMarkArtDataUri`.
+
+### Install commands for each platform
+
+`PlatformInstall` (`@hraness/design-kit/react`) shows one tab per operating
+system with that platform's mark, its install command, and a Copy button.
+Every CLI site should use it for install commands so they look and behave
+the same.
+
+```tsx
+import { PlatformBadges, PlatformInstall } from "@hraness/design-kit/react";
+
+<PlatformInstall
+  platforms={[
+    {
+      id: "macos",
+      command: "brew install hraness/tap/relay",
+      shell: "Terminal",
+      note: "Apple silicon and Intel",
+      alternatives: [{ label: "npm", command: "npm install --global relay" }],
+    },
+    {
+      id: "linux",
+      command: "curl -fsSL https://relay.example/install.sh | sh",
+      shell: "Terminal",
+      note: "x86_64 and ARM64, glibc 2.34+",
+    },
+    {
+      id: "windows",
+      unavailable: true,
+      unavailableNote: "No native build yet. Relay runs in WSL2.",
+      command: "curl -fsSL https://relay.example/install.sh | sh",
+      shell: "WSL2 terminal",
+    },
+  ]}
+/>
+
+<PlatformBadges platforms={["macos", "linux", { id: "windows", note: "via WSL2" }]} />
+```
+
+The server render selects `defaultPlatform` (the first platform when
+omitted). After hydration the component selects the visitor's operating
+system when it is listed; pass `detect={false}` to keep the default. The tabs
+follow the ARIA tab pattern: arrow keys, Home, and End move between
+platforms. Copy writes the exact command, shows "Copied", and announces the
+result to screen readers; when the clipboard is blocked it selects the
+command and says so. Long commands scroll inside their box, not the page.
+Below 30rem the tab row spans its column and the tabs tighten, so macOS,
+Linux, and Windows fit side by side at 320px without scrolling; a name is
+truncated only when a longer platform list cannot fit. Each platform mark is
+defined once per component as an SVG `<symbol>` and drawn by reference, so
+the markup does not repeat the paths. Non-React sites that render the hook
+classes should mirror the narrow rules on `.hraness-platform-install__tabs`,
+`.hraness-platform-install__tab`, and `.hraness-platform-install__tab-label`.
+Without JavaScript the tab row and Copy buttons hide and every platform's
+commands show in order under their names. The component uses no inline
+script or style, so it works under a strict content security policy.
+
+`PlatformIcon` draws the Apple logo, Tux, or the Windows window in
+`currentColor`, and a neutral terminal glyph for other ids. It is decorative
+unless you pass `label`. `PlatformBadges` is a compact "Runs on" row for
+heroes and footers; both are server-safe and also ship from
+`@hraness/design-kit/react/server`. The root entry exports `platformLabel`,
+`platformMark` (raw SVG paths for non-React sites), `detectPlatform`, and
+`matchDetectedPlatform`. The Apple and Linux marks come from Simple Icons (CC0); see
+`vendor/platform-marks/UPSTREAM.md`.
+
+## Load the presentation layer
+
+Import the complete stylesheet once after Tailwind, if the application uses it:
+
+```css
+@import "tailwindcss";
+@import "@hraness/design-kit/styles.css";
+```
+
+The complete stylesheet composes the token, reset, legacy component, and extracted StyleX layers from `@hraness/ui` before applying design-kit presentation. It keeps `base` below `components`, then freezes UI `legacy.base`, legacy, and priority1 through priority7 before the design-kit legacy and priority1-through-priority8 inventory. The design-kit manifest currently maps eight raw-priority buckets to those eight serialized ranks. Rank 1 begins with generated raw-priority-0 keyframes, so its keyframes and custom-property atoms are unlayered and `priority1` is reserved in the prelude; the remaining atomic output occupies the exact `priority2` through `priority8` blocks. Migrated declarations therefore win according to package ownership and StyleX priority without relying on import timing. Nebula Sans is the default proportional text and heading face, while explicit code and mono roles keep the system monospace stack. Package-owned atomic component presentation is authored in colocated `*.stylex.ts` files and compiled into deterministic `dist/stylex.css` with runtime injection disabled. `styles.css` reaches that local artifact once through `components.css`, so the public narrow component entry and the complete entry carry the same component recipes. Generated atomic class names are declaration hashes that may repeat across package layers; they are internal and do not identify package ownership. Use documented stable classes only when a composition exposes one. The notice retains logical block-axis inset and border declarations through canonical dashed StyleX properties. Its minimum height remains physical; the horizontal LTR and RTL compiler canary does not establish complete vertical-writing-mode parity.
+
+Applications that compile local StyleX declarations register both `@hraness/ui/stylex-manifest.json` and `@hraness/design-kit/stylex-manifest.json` with the build tools from `@hraness/ui/stylex-build`. Import `@hraness/design-kit/compiler-foundation.css` for full design-kit compositions, or `@hraness/design-kit/compiler-palettes.css` for palettes, the appearance menu, and portable controls with application-owned typography. The minimal entry supplies the UI foundation and palette bridge without webfonts or marketing styles; the full entry includes it transitively. Neither route imports precompiled StyleX recipes. The finalizer unions the raw UI, design-kit, and application rules and serializes them once into `components.hraness-stylex`, after every package's legacy layers. Generation plans and completion records use schema 2 and bind the exact union policy; package manifests remain schema 1 and bind the minimal foundation. Start a fresh generation when upgrading the union policy. Every HTML or SSR entry links that finalized stylesheet after its foundation stylesheet. Do not combine this route with either package's `styles.css` or `stylex.css`.
+
+Package authors use `createStylexTransformCollector` and `serializeStylexPackageRules` from `@hraness/ui/stylex-build` to publish externalized JavaScript, independently usable package CSS under a distinct `components.*` namespace, and a manifest that binds the raw rules, runtime files, standalone CSS, and compiler foundation. Final applications consume those manifests rather than concatenating independently serialized package stylesheets.
+
+Import narrower layers when the application does not need the full presentation system:
+
+```css
+@import "@hraness/design-kit/tokens.css";
+@import "@hraness/design-kit/charts.css";
+@import "@hraness/design-kit/effects.css";
+@import "@hraness/design-kit/syntax-highlighting.css";
+```
+
+`site-shell.css` keeps the footer at the viewport bottom on short pages and below content on long pages. Import it and add `hraness-site-shell` to the root containing the header, `main`, and footer as direct children:
+
+```html
+<body class="hraness-site-shell">
+  <header>…</header>
+  <main>…</main>
+  <footer>…</footer>
+</body>
+```
+
+For React apps with a root wrapper, put the class on that wrapper instead. If the content is a grid or another wrapper around `main`, add `hraness-site-shell__content` to that direct child so it fills the available height. Keep the content’s width and maximum measure in your page styles. The shell fills the dynamic viewport with a `vh` fallback. Multiple footer rows stay together in normal document flow. `body.plain-site` and `body.hraness-marketing-page` include this layout by default; nested theme and marketing examples opt in with `hraness-site-shell`. The standalone stylesheet has no dependencies and can accompany older design-kit styles.
+
+`plain-site.css` provides a compact site shell. `plain-publication.css` adds sourced article, citation, table, callout, and related-reading structure. `reading.css` carries the shared long-form scale on `.hraness-prose` for docs and guide surfaces outside the publication shell; the same `--hraness-type-*` tokens size the publication article, and `data-hraness-reading-face="serif"` adapts the scale to serif display faces.
+
+### Heading type from the shared foundation
+
+`typography.css` (included in `styles.css` and `compiler-foundation.css`, or importable as `@hraness/design-kit/typography.css`) owns the heading scale for every site. Site CSS should not set a heading's size or face. A heading at level N reads three tokens:
+
+```css
+.my-section h3 {
+  font-family: var(--hraness-type-h3-font);
+  font-size: var(--hraness-type-h3-size);
+  font-weight: var(--hraness-type-h3-weight);
+}
+```
+
+h1 and h2 use the display face (`--hraness-type-heading-font`, which follows `--hraness-marketing-display-font`). h3 and h4 use the text face (`--hraness-type-subheading-font`). The display face is used only at `--hraness-type-display-min` (1.75rem) or larger, and h2 never scales below it. Both marketing presets set the display face to Nebula Sans, so the floor mainly protects a product that opts in to a condensed serif, which is unreadable at card and label sizes. Choose the level by a heading's role in the page, not by the size you want: a heading that should look small is an h3 or h4, set in the text face.
+
+## Share the Paper theme
+
+`paper-theme.css` is a separate, zero-import CSS contract for warm neutral light
+and dark surfaces, Nebula Sans font roles, and compact marketing typography.
+Opt in with `data-hraness-theme="paper"` after the existing stylesheets. It can
+be adopted from an immutable package release or as a verified CSS snapshot
+without upgrading UI, React, or a StyleX compiler. Existing layouts and
+appearance choices remain product-owned. See [Paper theme](PAPER_THEME.md) for
+installation, compatibility, snapshot verification, and preference migration.
+
+## Add Lantern material
+
+Lantern gives opaque reading surfaces a luminous perimeter and selected controls a warm, matched fill and text color. Glass is reserved for chrome with scrolling content behind it. The selected palette, existing focus indicators and product layout remain authoritative.
+
+Set `data-hraness-material="lantern"` on a themed host and apply the documented surface hooks. Complete stylesheets include the material; selective and older consumers can import a verified CSS snapshot. React primitives use the compiled `lanternControlStyles` through their existing `controlXstyle` prop. `ThemeMenuButton` picks up the material by itself: raised at rest, inset while pressed, with a Lantern menu.
+
+See the [material contract and examples](LANTERN_MATERIAL.md) for palette islands, portal hosts, accessibility fallbacks and the immutable installer. The gallery demonstrates light and dark workspaces with working search, selection and disclosures.
+
+## Explain a technical product
+
+`product-marketing.css` is an opt-in narrative grammar for technical product
+sites. It gives every Hraness product one typeface, one measured type scale,
+sentence-case labels, hairline chrome, soft radii, and one accent color, so the
+portfolio reads as one studio's work. The roles are a sticky site header, a main landmark that clears that header,
+equal-height product card rows, an outcome-led hero with an optional product
+frame, a row of pillars, an install panel, an ordered flow, fact and stat strips,
+narrative sections, numbered primitives, interface and trust cards, attributed
+quotes, pricing, native questions, a maker section, a closing call to action,
+and an in-flow site footer. The classes own
+responsive structure and semantics-facing presentation.
+
+When a page also mounts the shared network footer from `@hraness/site-footer`,
+render it directly after the marketing footer: the grammar joins the pair into
+one band instead of two stacked bars. The product row's bottom space collapses
+to a compact gap, and the network row's content follows the marketing measure
+and gutter through the footer's documented `--hraness-site-footer-measure`
+seam, so both registers share one column. Products bind the
+`--hraness-marketing-*` roles to their own content and set one accent:
+
+```css
+@import "@hraness/design-kit/styles.css";
+
+.hraness-marketing-page {
+  --hraness-site-accent: oklch(0.55 0.21 262);
+  --hraness-site-accent-ink: #ffffff;
+}
+```
+
+Static sites may render the documented classes directly. React sites can use
+the server-safe compositions from either React entry:
+
+```tsx
+import {
+  MarketingCallToAction,
+  MarketingMain,
+  MarketingPage,
+  MarketingPillars,
+  MarketingProofFrame,
+  MarketingSiteHeader,
+  ProductHero,
+} from "@hraness/design-kit/react/server";
+
+<MarketingPage>
+  <MarketingSiteHeader
+    action={{ href: "#install", label: "Install Relay" }}
+    brand="Relay"
+    links={[{ href: "#how", label: "How it works" }, { href: "#pricing", label: "Pricing" }]}
+  />
+  <MarketingMain>
+  <ProductHero
+    actions={[
+      { href: "#install", label: "Install Relay" },
+      { href: "#how", label: "See how it works" },
+    ]}
+    boundary="Free for local use on macOS and Linux · version 1.2.3"
+    example="Ask your agent to run the nightly job and show you the log."
+    eyebrow="A reference developer tool"
+    frame={(
+      <MarketingProofFrame caption="The log written by the example job." credit="Captured 5 September 2026" title="relay run job-01">
+        <img alt="Relay printing a run log in a terminal" src="/relay-log.png" />
+      </MarketingProofFrame>
+    )}
+    heading="Run a job from your terminal, your code, or your agent"
+    headingId="relay-title"
+    name="Relay"
+    summary="Relay runs the same job wherever you start it and writes a log you can read afterward: inputs, outputs, and how long it took."
+  />
+  <MarketingPillars
+    ariaLabel="Relay in three points"
+    columns={3}
+    pillars={[
+      { label: "No hosted service", summary: "Jobs run on your machine and never wait on a server." },
+      { label: "A log for every run", summary: "Open it to see what went in, what came out, and when." },
+      { label: "Your files stay put", summary: "Source files and credentials never leave your machine." },
+    ]}
+  />
+  <MarketingCallToAction
+    actions={[{ href: "#install", label: "Install Relay" }]}
+    footnote="Free for local use on macOS and Linux."
+    heading="Start with one job"
+    headingId="cta-title"
+  />
+  </MarketingMain>
+</MarketingPage>
+```
+
+A sticky `MarketingSiteHeader` publishes `--hraness-sticky-offset` on the
+page and on `html`, so siblings inherit it. Wrap page content in
+`MarketingMain` (`id="main-content"`) so skip links and hash targets use that
+offset as scroll-margin. Do not add extra padding when the header stays in
+flow; pass `clearance="pad"` only for a `data-position="fixed"` header. The
+next sticky strip should use `.hraness-sticky-below-chrome` or
+`data-hraness-sticky` instead of `top: 0`. When the header wraps, render
+`StickyOffsetSync` once from `@hraness/design-kit/react` or call
+`syncStickyOffset` from `@hraness/design-kit/browser` to replace the token
+fallback with the measured border box. `MarketingCardRow` stretches every
+direct child to the tallest item in the row and reserves a two-line meta
+block; titles wrap and are not clamped. `MarketingCardArt` /
+`.hraness-marketing-card__art` clips each card's logo or media well so
+background paint cannot bleed through the gutter.
+
+`tone="accent"` on the hero or the call to action paints that role edge to
+edge in the product accent. `layout="split"` or `"split-reverse"` on a
+section places its heading group beside its body. `MarketingQuoteGrid` and
+`MarketingPillars` render nothing for an empty list, so a site adds quotes
+only when it has real, attributed ones.
+
+For a policy with `style-src-attr 'none'`, set `columns` to `1`, `2`, `3`, or
+`4` on `MarketingFacts`, `MarketingPillars`, and `MarketingStatStrip`. Set
+`factsColumns` on `ProductHero` for its nested facts. These finite choices use
+compiled recipes and emit no inline column style. Below 48rem, facts and stats
+still use two columns and pillars use one. Omitting the prop preserves the
+existing item-count custom property, including its inline style and arbitrary
+collection length. Use the compiled standalone stylesheet or the finalized
+compiler-adopter stylesheet with the finite choices.
+
+`MarketingNotice` renders one status or alert line — a redirect confirmation, a
+failed action — on the content edge of the page column, with `tone` set to
+`info`, `success`, or `error`. Errors use `role="alert"`; the other tones use
+`role="status"`. Signed-in account pages inside `MarketingSiteHeader` compose
+`MarketingMain`, `MarketingNotice`, `MarketingStatStrip`, and `MarketingSection`
+so every block shares the header's measure and gutter; they do not add
+full-bleed banners or cards nested inside sections.
+
+`ProductHero.notice` renders product-owned content after the boundary text in
+the hero's copy group. `MarketingInstallPanel.note` renders after its heading,
+before the separate command group. Both accept React nodes without adding a
+wrapper. Omit them to preserve the existing markup. `MarketingMaker.linkClassName`
+adds a caller class to its listed links only; it does not style biography links.
+
+Use `MarketingSectionLabel` for a native paragraph with the same label recipe
+as `MarketingSection`. Its default preserves the existing label presentation;
+`size="body"` selects the compiled 1rem variant. Override
+`--hraness-marketing-example-measure` in a product stylesheet to change only
+the hero example's maximum inline size. When absent, it uses
+`--hraness-marketing-copy-measure`; the summary's measure is unchanged.
+
+Homepage copy on this grammar follows [`STYLE.md`](STYLE.md) and
+[`MARKETING_COPY.md`](MARKETING_COPY.md), which gives each slot its job and its
+length limit. The headline states what the reader can do, in sentence case with
+no period. The summary says what the product is, who it is for, and the one
+thing it does differently. The `example` is a concrete request a reader could
+make. State the release status once, plainly, in `boundary`, and keep each other
+limit beside the feature it limits. A full-sentence section heading in the
+editorial preset may end with a period; other headings do not. Words such as
+"bounded", "exact", "authority", "custody", "immutable", and "inspectable" stay
+out of the hero and leads. Every number has a date or a source, and no quote
+appears without an attributed author who agreed to it.
+
+Import only the grammar when a site owns its reset and tokens:
+
+```css
+@import "@hraness/design-kit/product-marketing.css";
+```
+
+The components render complete server HTML and add no clipboard, animation, or
+analytics runtime. A
+product may enhance a command with its own accessible copy control while
+keeping selectable text as the fallback.
+
+## Publish articles
+
+The article layer renders long-form posts with a title, a one-sentence dek, a byline, published and updated dates, a visible drafting and review note, an optional contents list, sources, and related products. React and static sites get identical markup, styled by `plain-publication.css` (included in `styles.css`). The body keeps a 68ch measure, and the contents list moves beside it on wide screens. [`ARTICLE_COPY.md`](ARTICLE_COPY.md) gives the article shapes and the rules for provenance, freshness, and links.
+
+```tsx
+import {
+  ArticleSources,
+  MarketingArticle,
+} from "@hraness/design-kit/react/server";
+import { articleProvenanceFromAdmission } from "@hraness/design-kit";
+
+<MarketingArticle
+  author={{ kind: "organization", name: "Hraness" }}
+  dek="Relay replays a failed webhook from the stored request body."
+  eyebrow="Technique"
+  heading="Replaying webhooks without breaking signatures"
+  provenance={articleProvenanceFromAdmission(admission)}
+  published="2026-09-10"
+  toc={[{ href: "#approach", label: "The approach" }]}
+  after={<ArticleSources sources={sources} />}
+>
+  {body}
+</MarketingArticle>
+```
+
+`ArticleIndex` lists posts, `ArticleCallout` marks a note, limit, or warning, and `ArticleRelatedProducts` wraps `MarketingRelated`. Static site builders import `renderArticleHtml`, `renderArticleIndexHtml`, `renderArticleSourcesHtml`, `renderArticleCalloutHtml`, and `renderArticleRelatedHtml` from the framework-neutral root and load `@hraness/design-kit/plain-publication.css` after `plain-site.css`. Text arguments are escaped; `bodyHtml` and `afterHtml` take HTML the site already rendered.
+
+Each host keeps an `ArticleAdmission` record per article and checks the registry in a test:
+
+```ts
+import { assertArticleAdmissions } from "@hraness/design-kit";
+
+assertArticleAdmissions(registry);
+```
+
+A record passes when its six 0 to 2 scores total at least 9 with no zero. An `indexable` record also needs a review with a reviewer type, dated sources, two observations, and a refresh trigger, and every reviewed record needs `reassessOn` 28 to 56 days after the review. The provenance sentence says "human" only for a human editor's review.
+
+### Write a launch post
+
+An "Introducing" post is a column of 7 to 10 beats. Each beat makes one claim, shows one visual, and doubles as one social post, except the `limits` beat and beats marked `social: false`, which stay in the post. Keep the numbers in one facts module and build the posts from the beats:
+
+```tsx
+import { assertLaunchKit, buildSocialKit, resolveLaunchBeats } from "@hraness/design-kit/launch";
+import { LaunchBeats, SocialKitPanel } from "@hraness/design-kit/react";
+
+const beats = resolveLaunchBeats(draftBeats, launchFacts);
+const kit = buildSocialKit(beats, portfolioMessaging, { status: "Preview" }, canonicalUrl);
+assertLaunchKit(beats, kit, { status: "Preview", publicInstall: false, canonicalUrl });
+
+<LaunchBeats beats={beats} renderVisual={(beat) => <Visual beat={beat} />} />
+<SocialKitPanel kit={kit} />
+```
+
+Draw the visuals with `@hraness/design-kit/mockups` and load `@hraness/design-kit/mockups.css`. Build the social kit only once the post is `indexable`. Product tests can run the checks from `@hraness/design-kit/testing`, such as `blogConformance` for the blog and `assertRoleImgWithLabel` for each mockup. See [ARTICLE_COPY.md](ARTICLE_COPY.md) for the beat rules.
+
+Hraness product sites run the whole launch with the `product-launch` agent skill: mockups, the post, the social kit, the launch film, and comparison pages. It also lists the checks to run before you publish.
+
+### Share product facts
+
+`@hraness/design-kit/portfolio` holds the public facts about Hraness products: each product's name, one-liner, canonical URL, status, and other names, plus the registered relations between products. It is a snapshot generated from one commit of the portfolio registry, recorded in `portfolioProvenance`, and it renders nothing.
+
+```tsx
+import { ArticleRelatedProducts } from "@hraness/design-kit/react/server";
+import { product, relatedFor, usesPairs } from "@hraness/design-kit/portfolio";
+
+const textbutler = product("message-like-me");
+
+<ArticleRelatedProducts headingId="related" items={relatedFor("message-like-me")} />;
+
+for (const { relation, source, target } of usesPairs()) {
+  console.log(source.name, relation.label, target.name, relation.detail);
+}
+```
+
+`relatedFor(id)` returns one card per related product, and only for relations with a written detail sentence. Each item carries the product's `mark` (the portfolio artwork hraness.com shows, as a `data:image/svg+xml` URL) and its one-line `role`; the cards show the mark, name, and role, as on the hraness.com project index. The relation's `relationship` sentence stays on the item for articles that quote it. `usesPairs()` lists the integration relations that have one. Static sites read the same data from `@hraness/design-kit/portfolio.json`. Pin `portfolioDigest` in a test so an upgrade that changes the facts shows up in review.
+
+## Use application compositions
+
+```tsx
+import { Button, Icon, ViewportFrame } from "@hraness/ui";
+import {
+  AppShell,
+  NavigationRail,
+  PageCanvas,
+  RailItem,
+  RailSection,
+  TopBar,
+} from "@hraness/design-kit/react";
+import { DashboardSquare01Icon } from "@hugeicons/core-free-icons";
+
+export function Workspace() {
+  const rail = (
+    <NavigationRail>
+      <RailSection title="Workspace">
+        <RailItem
+          href="/"
+          icon={<Icon icon={DashboardSquare01Icon} />}
+          isActive
+          label="Overview"
+        />
+      </RailSection>
+    </NavigationRail>
+  );
+
+  return (
+    <ViewportFrame>
+      <AppShell rail={rail} topBar={<TopBar title="Workspace" />}>
+        <PageCanvas>
+          <Button variant="primary">Create project</Button>
+        </PageCanvas>
+      </AppShell>
+    </ViewportFrame>
+  );
+}
+```
+
+Connect routing with `RouterProvider` from `@hraness/ui`. Design-kit rail links use that public router context and intent-prefetch contract.
+
+`AnimatedRailStage` keeps the surrounding shell mounted while one keyed route stage enters and exits through `AnimatePresence` in wait mode. The public `stageKey`, stable class, `data-stage-key`, and caller-last `className` contracts remain unchanged. Its logical minimum and reduced-motion fallback are delivered through extracted StyleX classes. Reduced motion keeps content visible, removes translation and duration from the motion recipe, and forces any Motion-authored transform and transition off in CSS.
+
+`ChatMessage` keeps its article, finite `data-role`, optional avatar, header, and action slots, and caller-last root class while its grid, logical minimum, and metadata-row presentation are delivered through extracted StyleX classes. `ChatComposer` remains a controlled native form composition with a multiline field and submit button. It always prevents native navigation, calls its callback only for an enabled, non-pending, nonblank value, and keeps native form attributes and inline styles caller-controlled. Its two-column layout collapses to one column at the existing compact breakpoint. Neither component exposes a public `xstyle` or ref seam.
+
+`TopBar`, `BottomBar`, `PageCanvas`, and `DockedFooter` keep their native header, footer, main, or div semantics while their product-neutral layout recipes are delivered through extracted StyleX classes. Their stable classes and data attributes remain available for semantic inspection, and native `className` and `style` props remain caller-controlled. `DockedFooter` continues to forward its root footer ref. Its `surface` value remains a stable data hook; only `TopBar` gives `glass` a visual treatment. Its 90% tint and 18px blur use feature detection; unsupported filtering, reduced transparency, and forced colors use an opaque surface.
+
+`DitherSurface` composes its product-neutral texture through the typed `ThemedSurface` seam from `@hraness/ui`. Its `density` is one of `coarse`, `fine`, or `medium`; the default medium texture uses `4px`, while coarse and fine set the literal public `--hraness-design-dither-size` property to `7px` and `3px`. A caller `xstyle` recipe is applied after the shared texture, and native `style` remains last for deliberate per-instance overrides. Forced-colors mode removes the decorative image without changing the surface's content, native element, tone, shape, or border.
+
+`PlaybackTransport` keeps one large primary command through idle, pending, and playing states. Give the toolbar exactly one of `aria-label` or `aria-labelledby`; the command changes its accessible label, glyph, busy state, and play or stop callback without changing its stable button hook. Its wrapping toolbar recipe and exact `1.5rem` logical glyph and spinner dimensions are delivered through extracted StyleX classes. The existing root `className`, button id, keyboard-shortcut, button-ref, and trailing-control seams remain available.
+
+`Fader` keeps the full React Aria single-value slider contract while defaulting to a vertical, default-density control with a hidden accessible label and output. Its default and compact dimensions, horizontal variant, label row, rails, thumb, and focus-visible state are delivered through extracted StyleX classes. The two decorative rail nodes are inert and keep the logical geometry that the former pseudo selectors provided without expanding the package layer range. Existing root and input refs, visible label and accessory, output, caller `className`, native slider props, and native `style` overrides remain available. Native styles may override the public `--hraness-design-fader-*` properties for a deliberate per-instance size.
+
+## Show status pages
+
+`RouteNotFoundPage`, `RouteErrorPage`, and `GlobalErrorDocument` render one shared page for missing addresses and recoverable errors: the product's main action, a "Did you mean" link to the closest known page, up to three places to start, and a decorative glyph drawn as dots that react to the pointer. Static sites render the same markup with `renderStatusPageHtml` and enhance it with `attachStatusPage` from `@hraness/design-kit/browser`. [`STATUS_PAGES.md`](STATUS_PAGES.md) says what to put in each slot.
+
+```tsx
+<RouteNotFoundPage
+  siteName="Sponge"
+  primaryAction={{ href: "/start", label: "Start your library" }}
+  next={[{ href: "/docs", label: "Docs", description: "Connect Claude, ChatGPT, or any MCP client." }]}
+  routes={knownPages}
+  agentIndexHref="/llms.txt"
+/>
+```
+
+## Use charts and syntax
+
+Charts own responsive geometry, exact-value accessibility, reduced motion, and forced-color behavior. Applications own data, labels, units, and categorical colors.
+
+```tsx
+import { BarListChart, SyntaxCode } from "@hraness/design-kit/react";
+
+<BarListChart
+  aria-label="Requests by region"
+  data={[
+    { id: "north", label: "North", value: 72 },
+    { id: "south", label: "South", value: 48 },
+  ]}
+/>
+
+<pre>
+  <SyntaxCode code={'const ready = true;'} />
+</pre>
+```
+
+`SyntaxCode` and `highlightCode(code)` choose a language for recognizable code when the language is omitted. The deterministic rules recognize JSON objects and arrays, common package and Git commands, and distinctive TypeScript, Markdown, HTML, and CSS syntax. Prose and uncertain input stay plain text. Pass a language or Markdown fence hint to keep an explicit choice. Rust, TOML, YAML, Lean, and TLA+ use explicit language hints and keep comments and multiline strings intact; unsupported hints and `language="text"` remain plain text. Blocks longer than 131,072 characters also remain escaped plain text.
+
+The framework-neutral highlighter is available from `@hraness/design-kit/syntax-highlighting`. For sites that disallow inline styles, call `highlightCode(code, "typescript", { styles: "classes" })` or pass `styles="classes"` to `SyntaxCode`. Import `syntax-highlighting.css` when using the highlighter alone; the complete stylesheet, compiler foundation, and narrow `product-marketing.css` entry include it. The default style mode remains unchanged; both modes share the same theme colors and preserve source line breaks. Markdown renderers should pass each literal code block and its fence hint to this shared highlighter. Stylesheets do not tokenize raw `<pre><code>` markup.
+Server components can import `SyntaxCode`, deterministic procedural effects, and
+static surfaces from `@hraness/design-kit/react/server` without crossing the
+client boundary used by the interactive React barrel.
+
+## Foil cards and decks
+
+`FoilCardSurface` adds deterministic material paint behind semantic card
+content. Use `renderMode="static"` for image capture and other motionless
+surfaces. Interactive cards work on their own; a collection should be wrapped
+once in `FoilCardDeck`, which delegates pointer and focus interaction through a
+single controller and keeps geometry cached for the active descendant.
+
+```tsx
+import { FoilCardDeck, FoilCardSurface } from "@hraness/design-kit/react";
+
+<FoilCardDeck aria-label="Reference cards" className="card-grid">
+  {records.map((record) => (
+    <FoilCardSurface
+      intensity="standard"
+      key={record.id}
+      ornament="circuit"
+      preset="aurora"
+      renderMode="interactive"
+      seed={record.id}
+    >
+      <article>{record.label}</article>
+    </FoilCardSurface>
+  ))}
+</FoilCardDeck>
+```
+
+The optional `ornament` is one of `none`, `corners`, `rails`, `circuit`,
+`radial`, or `facets`. It affects edge paint only, so product content remains
+legible. Set `--foil-card-radius` on a surface or deck descendant to match a
+product-owned card radius. Fine-pointer movement activates directional
+diffraction; keyboard focus gets a motionless material cue. Touch, reduced
+motion, and forced-colors modes keep ordinary semantic content intact, and no
+inactive card receives `will-change`.
+
+## Semantic palettes
+
+Opt into Catppuccin, Gruvbox, Rosé Pine, or Tokyo Night in light or dark mode. `DesignPaletteProvider` and the existing `ThemeMenuButton` provide one appearance menu, with Catppuccin dark as the default. The shared controller supports external bootstrap scripts and strict content security policies. See [palette installation, semantic roles, and sources](./PALETTES.md).
+
+## Appearance and fonts
+
+Wrap browser applications with `DesignThemeProvider` and render
+`ThemeMenuButton` as the final action in the product header. It exposes one
+icon-only trigger and a Light, Dark, or System menu with the same presentation
+across products. The first visit defaults to System and follows the device
+preference. Explicit Light, Dark, and System choices persist under a versioned
+Hraness-neutral key. Server-rendered document roots may use Light as a safe
+concrete baseline while the blocking appearance bootstrap resolves the stored
+or System preference before paint.
+
+Show a timestamp with `RelativeTime` from `@hraness/design-kit/react`. It
+renders `<time>` with the ISO instant in `dateTime`, the local date and time in
+`title`, and relative text such as "5 minutes ago" or "in 23 hours". Pass `now`
+to render the same text on the server and during hydration. After mount it
+follows the browser clock and refreshes as often as the shown unit can change.
+Set `refreshInterval` to a fixed number of milliseconds, or to `"off"` to keep
+`now`. Framework-neutral code can call `formatRelativeTime(value, { now,
+locale, numeric })` from the package root. Both throw on an invalid date instead
+of printing "Invalid Date".
+
+`ThemeColorSync` leaves adaptive media-qualified server tags in control until a
+concrete Light or Dark preference resolves. It then owns one active browser
+chrome color, temporarily neutralizes competing same-name tags, and restores
+their exact media conditions after the final synchronized owner unmounts.
+
+Use `GlobalErrorDocument` for a Next root `global-error` boundary. It remains
+control-free because the normal product header is unavailable. Its System
+default emits adaptive Light and Dark `theme-color` metadata plus a
+`light dark` `color-scheme` before hydration, then follows the same stored
+preference as the application. Products with their own canvas colors pass the
+same palette once:
+
+```tsx
+<GlobalErrorDocument
+  darkColor="#101419"
+  error={error}
+  lightColor="#f4efe7"
+  reset={reset}
+/>
+```
+
+An explicitly fixed `theme="light"` or `theme="dark"` emits one matching,
+unqualified `theme-color` and a fixed `color-scheme` without mounting the
+preference provider.
+
+Static HTML products use the same composition without a client framework:
+
+```ts
+import { installAppearanceMenus } from "@hraness/design-kit/browser";
+
+installAppearanceMenus({
+  darkThemeColor: "#09090d",
+  lightThemeColor: "#f7f3ea",
+  storageKey: "product-appearance",
+});
+```
+
+Load `@hraness/design-kit/appearance-menu.css`, render one progressive
+`[data-hraness-appearance-menu]` composition as the final header action, and
+bundle the installer into a small blocking local script. The installer applies
+the stored or System preference before the stylesheet loads, synchronizes
+browser chrome, and supplies the same icon, menu, keyboard, focus, and storage
+contract as the React control. Importing the browser module has no side effects.
+
+Nebula Sans is bundled under the SIL Open Font License and loads through `tokens.css` for ordinary text and headings. Explicit serif treatments remain product-owned, and code and mono roles keep the system monospace stack. Geist Mono remains available as an optional display face:
+
+Content Security Policies must allow same-origin font assets with `font-src 'self'`.
+Bundlers configured to inline font assets also require `data:` in that directive.
+
+```css
+@import "@hraness/design-kit/fonts.css";
+
+:root {
+  --font-heading: var(--font-geist-mono);
+}
+```
+
+Applications may override semantic roles in a local stylesheet after the design-kit import. Keep deliberate serif and monospace treatments explicit so they are not absorbed into the proportional default. The public package contains no restricted font assets or metric overrides.
+
+Generated artwork can import `nebulaSansSocialFonts` from
+`@hraness/design-kit/fonts/nebula-sans/social`. It returns the official Book and
+Bold OTF payloads without a remote request or runtime filesystem lookup, ready
+for an `ImageResponse` `fonts` option.
+
+## Migrating Jelly surfaces
+
+The Jelly surface API, stylesheet export, and browser runtime have been removed.
+Replace `JellySurface` wrappers with the appropriate native or `@hraness/ui`
+primitive. Apply the [shared material roles](./LANTERN_MATERIAL.md) to that
+semantic element when it needs a surface treatment. Keep labels, refs, disabled
+and pending behavior, keyboard interaction, and portal ownership on the
+primitive. Remove imports of `@hraness/design-kit/jelly.css` and any direct
+Jelly runtime integration. `DesignThemeProvider` continues to manage appearance
+and portal themes without loading a decorative control runtime.
+
+The EvilCharts license and adaptation provenance remain under `vendor/evilcharts`.
+
+## Gallery
+
+`DesignSystemGallery` is an executable, product-neutral reference for the package boundary. Mount it in a development route and import `design-gallery.css` through the complete stylesheet. The gallery exercises Chat message slots, controlled composer submission, compact responsive layout, extracted class delivery, and caller-last classes alongside the other public compositions.
+
+## Development
+
+Provision the pinned test browser with `bun run browser:install` after installing dependencies. Browser checks use that Playwright revision by default. `CHROMIUM_EXECUTABLE_PATH` (or `CHROME_PATH`) may select an explicitly provisioned Chrome for Testing executable. Invalid overrides fail; checks never fall back to an installed personal browser. Each check reports the selected executable and version.
+
+Use Bun 1.3.14:
+
+```sh
+bun install --frozen-lockfile
+bun run browser:install
+bun run check
+```
+
+The stable dependency pair for this release is `@hraness/ui` `v0.5.17` with `@hraness/design-kit` `v0.31.1`. Version 0.31.0 keeps the `limits` beat and beats marked `social: false` out of the social kit and adds `socialPost` for social wording that stands without a caveat. Version 0.30.3 refreshes the portfolio snapshot so related-product cards use each product's own spelling, such as GhostGet and TextButler. Version 0.30.2 keeps the narrow and stacked install-tab layout when another package compiles the same atoms into a later cascade layer. Version 0.30.1 keeps every PlatformInstall tab name whole in columns down to 200px by stacking each mark above its name, using a container query on the component. Version 0.30.0 adds `site-shell.css`, which keeps short-page footers at the viewport bottom. Version 0.29.3 preserves readable selected install tabs in forced colors. Version 0.29.2 keeps all three PlatformInstall tabs visible at 320 to 360px and draws each platform mark once per component. Version 0.29.1 keeps marketing action labels readable in forced colors. Version 0.29.0 adds `PlatformInstall`, one install block for every CLI site: a tab per operating system with its mark, the install command with a Copy button that announces the result, optional alternative commands such as npm or Homebrew, and a note for platforms without a native build. After hydration it selects the visitor's operating system; without JavaScript every command shows. It also adds `PlatformIcon` (Apple, Tux, and Windows marks in `currentColor`) and a `PlatformBadges` "Runs on" row, plus `platformLabel`, `platformMark`, `detectPlatform`, and `matchDetectedPlatform` at the package root. See [Install commands for each platform](#install-commands-for-each-platform). No existing export changes. Version 0.28.0 adds the launch kit. `@hraness/design-kit/mockups` draws labelled illustrations of chat, feeds, inboxes, articles, terminals, browsers, desktop windows, menu bars, and phones in server-safe plain React with no StyleX or React Aria, styled by `@hraness/design-kit/mockups.css`; each renders as one image with a text description and no headings. `@hraness/design-kit/mockups/client` adds `ModeShowcase`, `FitToWidth`, and `StepThrough`. `@hraness/design-kit/launch`, with no React, holds the `LaunchBeat`, `LaunchFacts`, and `SocialKit` shapes with `resolveLaunchBeats`, `buildSocialKit`, and `assertLaunchKit`. `@hraness/design-kit/testing` gives product repositories `blogConformance`, `renderMatrix`, `assertNoHeadings`, `assertRoleImgWithLabel`, and `assertFakeHandles`. The React entries add `ArticleFigure`, `ArticleVideo` with `articleVideoJsonLd`, `ArticleTable`, `ArticleBarChart`, `ComparisonTable`, `LaunchBeats`, and `SocialKitPanel`, and `MarketingProofFrame` takes `chrome` (`window`, `browser` with `url`, or `terminal`). [ARTICLE_COPY.md](ARTICLE_COPY.md) now writes "Introducing a product" as beats; the admission rules are unchanged. No existing export changes. Version 0.27.0 adds explicit Rust, TOML, YAML, Lean, and TLA+ code highlighting, including nested comments and multiline strings. The existing highlighter API and stylesheet remain the shared entry points; unsupported languages still render as escaped text. Version 0.26.0 adds `MarketingNotice` and the raw `.hraness-marketing-notice` class: one status or alert line (`info`, `success`, or `error`) that sits on the content edge of the page column instead of spanning the window. Errors are announced as alerts and other tones as status. Signed-in account pages that render inside `MarketingSiteHeader` should compose `MarketingMain`, `MarketingNotice`, `MarketingStatStrip`, and `MarketingSection` so every block shares the header's measure and gutter, rather than hand-rolled full-bleed banners and nested cards. Version 0.25.0 moves bordered foil surfaces off the spectrum: `.hraness-foil` and `[data-emphasis="primary"]` actions keep their flat surface fill under one theme-aware monochrome edge — black on light, white on dark, overridable through the new `--hraness-foil-edge` token — while the metallic spectrum stays on wordmarks and marks. The foil material contract advances to version 3: `surfaceImage` and `surfaceBackgroundClip` are replaced by `surfaceFill`, `edge`, `edgeDark`, and `edgeColor`. Reinstall any vendored marketing snapshot from the 0.25.0 commit. Version 0.24.0 joins a marketing footer directly followed by the shared `@hraness/site-footer` network footer into one band: the product row's bottom space collapses to a compact gap and the network row's content follows the marketing measure and gutter through `--hraness-site-footer-measure`, so product links and the organization row share one column instead of reading as two stacked bars. Mount the network footer directly after `MarketingSiteFooter`; no prop or markup change is needed inside either landmark. Version 0.23.0 moves marketing pages to the Quiet direction described in [DESIGN.md](DESIGN.md). `ProductHero` no longer renders a backdrop, `HeroBackdrop` renders nothing, and `attachHeroLight` is an inert disposer; their names and props stay so existing code compiles and are marked deprecated. The `cells`, `weave`, `contour`, and `mesh` patterns render as `none`, and marketing fields and Lantern walls paint the flat palette background. Both marketing presets use Nebula Sans for display headings (editorial at weight 550); Instrument Serif stays vendored for explicit opt-in only. Hero eyebrows are plain labels, the accent band loses its grid, and cards and header chrome use hairline edges instead of lifted shadows. On phones `MarketingSiteHeader` keeps the brand, primary action, and appearance menu on one row and moves the links to a second row that scrolls sideways, with 44px targets. To migrate, delete `backdrop` artwork, `HeroBackdrop`, `attachHeroLight`, pattern values, and product CSS that recreated textures or serif headings, then reinstall any vendored marketing snapshot from the 0.23.0 commit. Version 0.22.2 restores the canonical roughday mark — the rain-cloud artwork pinned by the portfolio registry — after the mark slot briefly carried a stray illustration. Version 0.22.1 completes the icon library with the roughday inline chip family (65 admitted assets, no pending members). Version 0.22.0 adds the `./icons` surface: 62 vetted single-ink assets across ten sets — a shared illustration family, product illustration families, and the product marks, each admitted through a measured gate (single ink, bounded aspect, coverage, stroke, paths, bytes) and per-set family coherence, distributed as a typed registry module (`hranessIcons`, `hranessIcon`, `hranessIconMarkup`, `hranessIconsForSet`) and as canonical `./icons/<set>/<slug>.svg` files for image consumers. See [ICONS.md](ICONS.md). Version 0.21.1 accepts status-page `routes` straight from a sitemap: long titles are shortened for the "Did you mean" line and unusable entries are dropped instead of failing the render. Version 0.21.0 replaces the 404 and route-error pages with one shared status page: the product's main action, a "Did you mean" link to the closest known page, at most three next links with one-line descriptions, an optional line for AI agents, and a glyph drawn as dots that gather, move away from the pointer, and settle. `RouteNotFoundPage`, `RouteErrorPage`, and `GlobalErrorDocument` render it; `renderStatusPageHtml` and `attachStatusPage` bring the same page to static sites; `status-page.css` ships in `styles.css` and `compiler-foundation.css`. The default copy changes to "We can’t find that page". See [STATUS_PAGES.md](STATUS_PAGES.md). Version 0.20.0 gives `ThemeMenuButton` the Lantern material: under `data-hraness-material="lantern"` its trigger is raised at rest and inset while pressed, and its menu uses the material plane, lift and warm selection, with no new props. Sites can delete their local Lantern CSS for the appearance menu. It also adds `formatRelativeTime` at the package root and a hydration-safe `RelativeTime` component in `@hraness/design-kit/react`. Version 0.19.0 redraws related-product cards as the hraness.com project cards: each shows the product's mark, its name, and its one-line `role` at reading size, and no longer renders the `relationship` sentence (the prop stays accepted and is deprecated). `MarketingRelatedProduct` and the static `ArticleRelatedLink` take a `mark`, and every `@hraness/design-kit/portfolio` product and `relatedFor()` item now carries its portfolio mark as an inert `data:image/svg+xml` URL. Related-tier and proof headings move to the new `--hraness-marketing-h3-size` token, so the editorial display face never renders below 1.75rem. `typography.css` gains per-level heading tokens (`--hraness-type-h1-font` through `--hraness-type-h4-font`, the matching `-weight` tokens, `--hraness-type-subheading-font`, and `--hraness-type-display-min`). h3 and h4 in `.hraness-prose` and publication articles now use the text face, and the h2 floor rises to 1.75rem. Version 0.18.3 adds the Sponge and Wordcell runtime relations to Oh to the `@hraness/design-kit/portfolio` snapshot, so related-product cards on all three sites can link them. Version 0.18.2 refreshes the `@hraness/design-kit/portfolio` snapshot from the registry: the public ghostget.com entry, updated Gobstopper and xcb naming and descriptions, and the current sibling-product relations for related-product cards. Version 0.18.1 adds the Perplexity mark and a dependency-free `@hraness/design-kit/provider-marks` leaf entry (`providerMark`, `providerMarks`, `providerMarkFallback`, `providerMarkGlyphDataUri`, `providerMarkArtDataUri`, `providerMarkOnAccent`, `providerMarkMonogram`) so packages such as `@hraness/ui` can consume the registry without pulling the marketing surface. Version 0.18.0 adds the shared provider-mark registry: `providerMarks`, `providerMark()` alias resolution, `ProviderMark`/`ProviderMarkChip` accent-tinted tile components on both React entry points, vendored agent and vendor artwork from LobeHub icons 1.95.1 plus documented Crush and Aider marks, monogram fallbacks for uncovered names, and data-URI helpers for CSS-mask consumers. See `vendor/provider-marks/UPSTREAM.md` for asset provenance. Version 0.17.2 carries the canonical portfolio messaging record per product (`names`, `category`, `tagline`, `short`, `meta`, `medium`, `long`, and hero copy) in the `/portfolio` snapshot. Version 0.17.1 lets Next.js apps that compile dependencies with Babel build the article layer: its link check no longer uses a Unicode property escape that Babel cannot rewrite, and it rejects the same control characters and whitespace as before. Version 0.17.0 adds the article layer: server-safe `MarketingArticle`, byline, provenance, sources, callout, related-product, and index components, a matching static HTML renderer for sites without React, long-form article styles in `plain-publication.css`, and the `ArticleAdmission` rubric with `assertArticleAdmissions()`. It also adds `@hraness/design-kit/portfolio`, a snapshot of public product names, one-liners, links, and relations for related-product cards and "How X uses Y" posts. See [ARTICLE_COPY.md](ARTICLE_COPY.md). Version 0.16.4 keeps native appearance-menu labels usable inside keyboard-focusable page landmarks, including mouse and touch selection. Version 0.16.3 keeps decorative hero backgrounds hidden in forced colors and reduced transparency when other packages load their styles afterward. Version 0.16.2 preserves palette hues in translucent headers, material surfaces, and decorative highlights. Version 0.16.1 keeps plain reading pages and nested compiled surfaces in their selected palette, including system appearance without JavaScript. Version 0.16.0 adds a shared bounded hero light, product-owned backdrop slots, five Lantern patterns, palette-derived soft surfaces, and responsive typography across marketing and reading layouts. Static sites can use the palette bridge for system appearance before JavaScript. See [HERO_FIELDS.md](HERO_FIELDS.md), [LANTERN_MATERIAL.md](LANTERN_MATERIAL.md), and [MARKETING_PRESET.md](MARKETING_PRESET.md). Version 0.15.0 lets `MarketingRelated` present labeled tiers of sibling products: a `groups` collection renders each tier under its own heading with an accessible card-row label, while the flat `items` shape stays available for a single group. Version 0.14.0 adds `MarketingRelated`, a collection section that presents sibling products as linked cards, each framed by its relationship to the featured product. Version 0.13.0 publishes `--hraness-sticky-offset` from sticky marketing chrome, gives `MarketingMain` and the next sticky sibling a clearance contract, stretches marketing card rows to the tallest item with a reserved two-line meta block, and clips per-card art wells so a logo surface cannot paint through the gutter. Version 0.12.0 replaces pointer-driven gradient rotation with a steady material and a moving light: the spectrum and its 115deg direction stay fixed while `--hraness-foil-x`/`--hraness-foil-y` highlights travel across each lockup, and marketing footers can opt into the same icon-plus-wordmark foil as the site header with `brandMark`. Version 0.11.1 preserves visible metallic marks when another package repeats a generic hidden atom in a later CSS layer. React consumers load `components.css` or `styles.css`; the raw marketing entry supports authored HTML hooks. Version 0.11 adds server-rendered `FoilMark` artwork and metallic text with subtle rainbow reflections, including a shared header mark seam and original-artwork fallbacks. Version 0.10.1 adds conservative server syntax defaults, includes their styles in the narrow marketing entry, and pins the icon dependency to preserve fresh Linux installs. Version 0.10 adds the shared foil contract: `.hraness-foil` surfaces and `.hraness-foil-text` wordmarks render a pointer-following metallic spectrum from the `--hraness-foil-*` custom properties, applied by default to marketing header brands and primary actions. The `attachFoil` browser export drives the bounded `x`/`y`/`angle` inputs with damped easing, reduced-motion and forced-color fallbacks, and no style injection; the same spectrum feeds `@hraness/site-footer` signup controls. Dark appearances use a deeper palette so the sheen stays visible. Version 0.8 removes Jelly's optional API, stylesheet, vendor runtime and theme-provider side effect. Migrate direct Jelly surfaces to native shared primitives before upgrading. Lantern now uses softer directional depth and shaded faces; the marketing preset adds individually shaded static cells, theme-aware terminal colors and window chrome. Code blocks retain source lines and follow the active palette. Paper preferences, semantic palettes, and compiler identity stay stable. Compiler adopters must regenerate their finalized stylesheet with the new package manifest.
+
+The complete check runs linting, typechecking, production builds, an installed-package smoke test, deterministic examples, property tests, server rendering, vendor-integrity checks, and headless Chromium regressions. The browser gate verifies responsive shell ownership, extracted AnimatedRailStage, Fader, layout-surface, and playback-transport delivery, reduced-motion stage fallback, Fader keyboard and focus behavior, forced-color behavior, keyboard-operable appearance, browser-chrome synchronization across opposing device and saved preferences, global-error static metadata and runtime lifecycle, accessible title and copy, deterministic procedural layers, viewport containment, and the absence of the excluded canvas effect. Set `CHROMIUM_EXECUTABLE_PATH` when Chromium or Chrome is installed outside the standard macOS and Linux paths.
+
+Global CSS remains the boundary for tokens, resets, document grammar, cross-component layout, accessibility media rules, and audited vendor fallbacks. A new overlapping compiled style family from another package requires a layer-order compatibility gate against that package's released artifact before adoption.
+
+Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request. Report suspected vulnerabilities as described in [SECURITY.md](./SECURITY.md).
+
+## License
+
+MIT. Vendored Nebula Sans, Geist Mono, and other upstream artifacts retain their own included license and provenance files.
+
+### Shared editorial marketing preset
+
+Import `@hraness/design-kit/product-marketing-preset.css` after your existing marketing styles, then opt in with `<MarketingPage preset="editorial">`. The editorial preset sets one large Nebula Sans heading at weight 550 on the flat palette background, with hairline rules and a thin header whose links move to their own scrolling row on phones. `preset="minimal"` uses a more compact sans hierarchy. Hero backdrops, patterns, and textures are retired; see [Hero fields](HERO_FIELDS.md). Product accents and copy remain product-owned.
+
+[Writing for the marketing components](MARKETING_COPY.md) says what each slot is for and which copy patterns to avoid.
+
+[Marketing preset contract](MARKETING_PRESET.md) documents the native HTML hooks, shared tokens, paint-only header hook, and immutable CSS/font/asset snapshots for consumers that retain an older component release. The preset leaves application UI outside its explicit scope untouched.