@hraness/design-kit 0.31.1

package/ARTICLE_COPY.md

@@ -0,0 +1,208 @@
+# Writing articles
+
+The article components (`MarketingArticle`, `ArticleIndex`, and the static `renderArticleHtml` functions) give every Hraness host the same article shape. This guide says what goes in each part and which posts a host may publish. `STYLE.md` still owns voice and conventions, and `MARKETING_COPY.md` owns the product-page slots.
+
+A reader arrives with one question. The title names it, the dek answers it in one sentence, and the body shows the evidence.
+
+## Parts of an article
+
+Limits are maximums. Count characters in the rendered text.
+
+| Part | Write | Limit | Avoid |
+| --- | --- | --- | --- |
+| `heading` | The question or the result, in sentence case with no period. | 70 characters | Clickbait, a question the article does not answer, and a colon followed by a second title. |
+| `dek` | One concrete claim, as a complete sentence, that a reader could check. | 200 characters | A summary of the article's sections, "In this post", and claims with no source in the body. |
+| `eyebrow` | The series or post type: "Technique", "Release", "Integration". | Three words | A tagline. |
+| `author` | The organization byline on every host: `{ kind: "organization", name: "Hraness" }`. | | A person's name on a post that person did not adopt. |
+| `provenance` | The drafting kind and the review on record. | | Omitting it on an AI-drafted post. |
+| `toc` | One entry per `h2`, only when the article has four or more. | Eight entries | Entries for `h3` headings. |
+| Body headings | Sentence case, each naming what the section shows. | 70 characters | Signpost headings such as "Overview", "Conclusion", or "Key takeaways". |
+| `ArticleSources` | Primary sources a reader can open, each with the date someone last checked the cited claim. | | Secondary summaries when the primary source is public. |
+| `ArticleRelatedProducts` | Siblings from the registered relations for this article, each shown with its mark, name, and one-line description. | Three items | Every product in the portfolio. |
+| `ArticleCallout` | A limit or warning the reader must see before acting. | One short paragraph | Decorative asides and restated body text. |
+
+## Post shapes
+
+### Introducing a product
+
+Title: "Introducing <product>". It lives on the product's own host, and each active product gets one. The reader's job is to decide whether to try it, so the admission record says `readerJob: "decide whether to try it"`.
+
+The post keeps five parts, written as beats:
+
+1. **What it is.** One plain sentence, then the problem it solves in the reader's terms, with one concrete case.
+2. **What it does today.** Only shipped behavior. One beat per surface or mode, and only when that beat has its own visual.
+3. **How it works and who it is for.** How it works in the reader's terms, then the reader who has the problem and who should use something else.
+4. **The vision.** Where the product is going and why, stated as intent, not as a shipped feature or a date.
+5. **Limits and status.** What it does not do yet, then the status sentence and how to get it.
+
+It explains the reason for the product. It does not repeat the feature grid on the home page. A paused product says so in the status sentence; a retired or legacy product gets no introduction.
+
+#### Beats
+
+A beat is one short section that makes one claim and shows one visual. Write 7 to 10 beats, about 40 to 60 words each, in this order:
+
+| Part | Beats | Write |
+| --- | --- | --- |
+| `what` | 1 | What the product does, stated plainly. No question, teaser, or "here's why". |
+| `does` | 1 or more | One surface or mode each, tied to one mockup state or clip. |
+| `how` | 1 | How it works, in the reader's terms. |
+| `who` | 1 | Who it is for, and who should use something else. |
+| `vision` | 1 | Where it is going, as intent. |
+| `limits` | 1 | What it does not do yet, once, at its true scope. |
+| `status` | 1 | The status label and how to get it. |
+
+- The hero holds the title, the registry `meta` as the dek, the status line from release data, and the film when there is one.
+- Each beat has a headline of 70 characters or fewer, in sentence case with no period, and a post of 250 characters or fewer that works on its own as one social post.
+- Social posts carry claims only. The `limits` beat, and any caveat, known gap, negative finding, audit or review line, or legally required disclaimer, stay in the launch post, the docs, and the site, and never reach a social post, the Show HN facts, or the Product Hunt fields. Every social post must still be true on its own: when a caveat is what keeps a beat's claim accurate, give the beat a `socialPost` that states a narrower claim accurately without it, or mark the beat `social: false`.
+- Each beat has exactly one visual, and no two beats share one. Alt text is 125 characters or fewer. A mockup is labelled as an illustration in its alt text and caption.
+- Render beats with `LaunchBeats` from `@hraness/design-kit/react`. Each beat gets a `#beat-<id>` anchor.
+- After the beats: "Go deeper" links named for the reader's next task, then the social kit, then sources and the drafting and review note.
+- Technical depth, comparisons with other products, and tables go in companion posts or `/compare` pages. Link them from the beat with `detailHref`.
+
+#### Launch data
+
+`@hraness/design-kit/launch` holds the shapes and checks. It has no React.
+
+```ts
+type LaunchBeat = {
+  id: string;              // lowercase slug, rendered as #beat-<id>
+  part: "what" | "does" | "how" | "who" | "vision" | "limits" | "status";
+  headline: string;        // may hold {fact} placeholders
+  post: string;            // may hold {fact} placeholders
+  visual:
+    | { kind: "mockup"; id: string; state: Record<string, string> }
+    | { kind: "clip"; scene: string }
+    | { kind: "diagram"; src: string };
+  alt: string;
+  facts?: string[];        // every placeholder key the beat uses
+  detailHref?: string;     // a companion post
+  socialPost?: string;     // social wording when `post` keeps a caveat; accurate on its own
+  social?: boolean;        // false keeps the beat in the launch post only
+};
+
+type LaunchFacts = Record<string, { value: string; source: string }>;
+
+type SocialKit = {
+  x: string[];
+  bluesky: string[];
+  threads: string[];
+  linkedin: string;
+  productHunt: { tagline: string; description: string; tags: string[] };
+  showHnFacts: string[];   // facts for a person to write from
+  sources: Record<string, string>;
+};
+```
+
+- **Facts.** Type every number once, in the product's `LaunchFacts` module, with its source: versions, sizes, rates, counts, and prices. The post, the social kit, film captions, and store listings all import it. `resolveLaunchBeats(beats, facts)` fills `{key}` placeholders and rejects a beat that types a digit by hand.
+- **Checks.** `assertLaunchBeats(beats)` checks the order, the counts, the limits, and the wording rules. `buildSocialKit(beats, messaging, release, canonicalUrl)` builds each channel's posts from the social beats (every beat except `limits` and beats marked `social: false`, using `socialPost` when a beat has one), the Product Hunt fields from portfolio messaging, and the status from the release record. `assertLaunchKit(beats, kit, options)` checks each channel's length. It also checks that only the last post links, that the last post carries the status and the canonical URL without tracking parameters, that nothing asks the reader to install before a public install exists, that no other product is named, and that no post or fact carries the text of a `limits` beat or a `social: false` beat.
+- **Social kit.** Build it only from an `indexable` post. A quarantined post has no social kit. Render it with `SocialKitPanel`, a closed `<details>` with a copy button and a character count per post. A person writes the Show HN post and the first Product Hunt comment; the kit gives them the facts.
+- **Words.** Social posts follow the rules below, plus: no hashtags, no emoji, and no thread markers such as "1/n".
+- **Admission.** A launch post passes the same admission gate as every other article. The launch helpers do not change it.
+
+### How one product uses another
+
+Title: "How <consumer> uses <provider>". It lives on the consumer's host.
+
+1. **The reader's problem.** The job the consumer's user is trying to get done.
+2. **What the provider does.** In plain words, for a reader who has never used it.
+3. **How the consumer uses it.** The code path, configuration, or data flow, from the consumer's side.
+4. **What that buys the user.** The concrete result a user of the consumer sees.
+5. **Limits.** What the integration does not cover, once, at its true scope.
+6. **Links.** The provider's home page and hub page, and the consumer's introduction.
+
+- Write one only for a relation registered in `@hraness/design-kit/portfolio` that has a reviewed `detail` sentence. The post expands that sentence; it does not claim more.
+- Outside its hub page, the provider's host adds at most one descriptive link to the post, and only after both pages are live.
+- When the relation changes or is removed, update or archive the post in the same change.
+
+### Provider hub page
+
+A provider may keep one page, such as "Built on <provider>", that lists the products using it. Each entry is the registered relation's own sentence and a link to the consumer's "How <consumer> uses <provider>" post when one exists. The hub is an index. It does not restate each post.
+
+### Technique posts in two halves
+
+A technique post teaches one method, such as property tests, model checking, or proofs. It lives on hraness.com, and a product host may carry a product-specific version that shows the technique inside that product.
+
+- **First half, for any reader.** Ground it in problems people already know, such as vibe-coded slop (software a model wrote quickly that looks finished and breaks on the second use) and fragile foundations (a product built on code nobody checked). Use one familiar failure ("It only breaks if you save, lose connection, then reopen"). Then describe the brighter alternative: what it is like when a whole class of that failure cannot happen. No code or notation in this half.
+- **Second half, how Hraness does it.** Show the method with durable examples: laws, invariants, and small code excerpts that still read correctly after a refactor. Cite the repository file that holds the real example. Avoid line numbers and file names that change often, and keep internal jargon to the one term the technique needs.
+- End on the last supported fact. State what the technique does not prove, once, at its true scope.
+
+## Titles and formulas
+
+- Keep titles to 70 characters or fewer. Most search results cut longer ones.
+- The fixed formulas "Introducing <product>" and "How <consumer> uses <provider>" are allowed. Every other title in a series needs its own wording.
+- Vary openings, closing sections, and headings across a series. Check the other posts before publishing: no repeated first sentence pattern, closing heading, closing checklist, or disclaimer paragraph.
+
+## Words and numbers
+
+- Follow `STYLE.md`. Do not use em dashes anywhere in the article, including the title, dek, captions, and alt text.
+- Do not use these words: delve, tapestry, testament, landscape (for a market), realm, seamless, seamlessly, robust (without the specific property), leverage (as a verb), unlock, empower, elevate, supercharge, game-changer, cutting-edge, revolutionize, harness (as a verb), journey (for a process), and "in today's world".
+- Keep internal vocabulary out of articles: admission, admitted, qualification, qualified, custody, settlement, receipt, attest, bounded, boundary, gate, lane, surface, projection, manifest, lease, and the other words `STYLE.md` lists under "Write for the reader, not the build". A technique post may define one of these once when it is the subject.
+- Do not invent numbers, benchmarks, quotes, customers, or dates. Every number has a source or a date in the text. Every quote has a named person who agreed to it.
+- Type each number once. Versions, sizes, rates, counts, and prices in a launch post come from the product's launch facts, not from the article text.
+- State product status once with one of the `STYLE.md` labels: In development, Preview, Beta, Latest release: vX.Y.Z, Paused, or Retired.
+
+## Dual-use products
+
+Some products can be pointed at other people's accounts or data: authenticated browser adapters, automated messaging, exposure scans, clipping tools, and media import. Articles about them:
+
+- describe the owner's own accounts and data, used with the owner's authorization;
+- show previews, confirmation steps, and consent before anything is sent or changed;
+- say what the product will not do;
+- never frame the product as scraping, impersonation, or outreach at scale.
+
+## Drafting and review note
+
+Every article states who drafted it and who reviewed it, visibly, on every host. The owner decided this on 2026-09-23, as relayed to the task that added this guide. It applies to articles only; other pages follow `STYLE.md`.
+
+- Render `ArticleProvenance`, or the `provenance` prop of `MarketingArticle`, from the admission record with `articleProvenanceFromAdmission()`. Do not type the sentence by hand.
+- An AI-drafted post from repository sources reads: "Drafted with AI from the source code and reviewed by <reviewer>."
+- Name the reviewer as it is. An AI reviewer has `reviewerType: "ai"` and a name that says it is AI, for example "Claude Opus 5.5 (claude-opus-5-5) editorial review". The sentence says "human" only when `reviewerType` is `human-editor`.
+- Keep `humanReview` null unless a person reviewed the article. Never describe AI review as human review.
+- The byline is "Hraness" on every host. Do not credit a person, including the owner, for an AI-drafted post. A person who later adopts a post may switch the byline to their own name; the drafting and review note stays.
+- A post with no review on record renders "It has not been reviewed yet." and stays quarantined.
+
+## Admission and indexing
+
+Every article URL has an `ArticleAdmission` record in its host's registry, checked by `assertArticleAdmissions()` in tests.
+
+- A new post starts `quarantined`: readable, `noindex`, and absent from the sitemap, feeds, `llms.txt`, and index lists.
+- It becomes `indexable` only when the record passes: six scores of 0 to 2 totalling at least 9 with no zero, a review with reviewer and `reviewerType`, at least one source with a check date, two observations that are not paraphrases of the sources, and at least one refresh trigger.
+- An independent, disclosed AI review can admit a post. Record it as `reviewerType: "ai"`. The validator rejects an AI reviewer name that does not say it is AI (for example by naming the model), and it rejects `reviewerType: "author"` for an indexable post, because the author cannot admit their own post.
+- `archived` keeps an old URL working without listing it.
+
+## Freshness
+
+- Every record has `reassessOn`, 28 to 56 days after `review.reviewedOn`. `articleAdmissionsDue(registry, today)` lists the records to look at again.
+- Render versions, release dates, and status labels from release data (`package.json`, a published release file, or the portfolio facts). Never type a version into an article body.
+- Each record names its refresh triggers: a release tag bump, a change to a relation's `detail`, a rename, or a change to the feature the post describes.
+- When a product is renamed, update article bodies, titles, and slugs (with redirects) in the same change as the rename.
+- When a feature an article describes changes, refresh the article or archive it. Update the `updated` date only when the content changed.
+
+## Interlinking
+
+- Add a link only when it is the reader's next useful action. Use a descriptive anchor.
+- Follow registered relations. Do not link every product to every other product.
+- No minimum link counts, reciprocal link swaps, or footer link farms.
+- Every article stands on its own. A reader who follows no link still gets the answer.
+- Link to another host only after both URLs are live.
+
+## Check before publishing
+
+Read the title, dek, and first paragraph aloud. Open every source and confirm the cited claim on the check date. Render the article at 1280px and 375px wide; code blocks scroll sideways and tables stay readable on a phone. Run `assertArticleAdmissions()` on the registry.
+
+## Block for product repositories
+
+Paste this block into the `AGENTS.md` of every product repository that publishes articles. Keep the markers so the block can be synced.
+
+```md
+<!-- hraness-articles:start -->
+## Articles
+
+- Take product names, one-liners, URLs, status, and relations from `@hraness/design-kit/portfolio`. Do not copy them into article text by hand.
+- Write "How <consumer> uses <provider>" only for a relation registered there with a `detail` sentence. Change the relation and the post in the same change.
+- Give every post an `ArticleAdmission` record with a `reassessOn` date 28 to 56 days after its review, and keep `assertArticleAdmissions()` in the tests.
+- Render versions, release dates, and status from release data. Never type a version into an article.
+- When a product is renamed, update article bodies, titles, and slugs in the same change. When a feature an article describes changes, refresh or archive the article.
+- Follow `ARTICLE_COPY.md` in `@hraness/design-kit` for article shapes, the drafting and review note, and interlinking.
+<!-- hraness-articles:end -->
+```

package/HERO_FIELDS.md

@@ -0,0 +1,55 @@
+# Hero fields
+
+Hero backdrops are retired. Since 0.23.0, marketing heroes follow the Quiet
+direction: a flat palette background, a sans heading, a short summary, one next
+step, and one real proof of the product right after the copy. Nothing moves,
+glows, or blurs behind the text.
+
+```tsx
+<ProductHero
+  eyebrow="Job runner"
+  heading="Run a job from your terminal, your code, or your agent"
+  headingId="title"
+  name="Relay"
+  summary="Relay runs the same job wherever you start it and writes a log you can read afterward."
+  actions={[{ href: "#install", label: "Install Relay" }]}
+  boundary="MIT license · macOS and Linux"
+  frame={<MarketingProofFrame title="relay run job-01">{terminalOutput}</MarketingProofFrame>}
+/>
+```
+
+Put real proof in `frame`: a terminal or code block, a static screenshot with
+`alt` text, or compact real output. It stays available to readers and
+assistive technology. Do not put a large interactive copy of the application in
+the hero.
+
+When the product has no single screen to capture, `frame` may hold one static
+mockup from `@hraness/design-kit/mockups`, or a `ModeShowcase` from
+`@hraness/design-kit/mockups/client` that lets the reader switch between a few
+states of the same illustration. Both need a caption that says the picture is
+an illustration; `ModeShowcase` throws without one. Mockups render as a single
+image with a text description, carry no headings, and are skipped by search
+snippets. Load `@hraness/design-kit/mockups.css` with them.
+
+## Retired features
+
+These names stay exported so existing code compiles. They do nothing visible,
+and their types are marked deprecated. Remove them when convenient.
+
+| Feature | Behavior since 0.23.0 |
+| --- | --- |
+| `ProductHero` `backdrop` prop | Ignored. `backdrop={false}`, artwork, and omission all render the same hero with no decorative layer. |
+| `HeroBackdrop` from `@hraness/design-kit/react` or `@hraness/design-kit/react/hero-backdrop` | Renders nothing, including its children. |
+| `attachHeroLight` from `@hraness/design-kit/browser` | Attaches no listeners, writes no styles, schedules no frames, and returns a disposer you can call any number of times. |
+| `--hraness-hero-light-x`, `--hraness-hero-light-y`, `--hraness-hero-drift-x`, `--hraness-hero-drift-y`, `--hraness-hero-proximity` | No longer written or read by any shared style. |
+| `data-hraness-hero-item` | No proximity effect. Product artwork marked with it no longer renders inside the hero. |
+| `.hraness-marketing-hero-backdrop` and its `__atmosphere` and `__light` children in hand-written HTML | Hidden with `display: none` by `product-marketing.css` and the compiler foundation, so old markup paints nothing and takes no space. |
+| `data-hraness-pattern="cells"`, `"weave"`, `"contour"`, `"mesh"` | Still valid; each renders exactly like `"none"`. See [Marketing preset](MARKETING_PRESET.md). |
+
+A product that still passes decorative artwork should delete it rather than
+recreate it in product CSS. Floating or blurred elements behind the heading make
+it harder to read, especially on phones.
+
+`ProductHero` stays available from the server entry and no longer crosses a
+client boundary. The `@hraness/design-kit/react/hero-backdrop` export remains a
+client module for compatibility.

package/ICONS.md

@@ -0,0 +1,56 @@
+# Icons
+
+`@hraness/design-kit/icons` is the shared vetted illustration and mark library
+for hraness.com surfaces. Every icon is generated as a member of a measured
+family — never alone — by Slopcamera, then admitted to the package by hash and
+metric bounds.
+
+## Using icons
+
+Two distributions ship from the same canonical artwork:
+
+```ts
+import { hranessIconMarkup, hranessIcons } from "@hraness/design-kit/icons";
+
+const html = hranessIconMarkup("shared/research"); // complete inline <svg>
+```
+
+or the raw file, for `<img>` sources and static builds:
+
+```ts
+import researchUrl from "@hraness/design-kit/icons/shared/research.svg";
+```
+
+Each asset carries `viewBox`, sanitized inner `body`, `ink`, `context`
+(`card` | `hero` | `inline`), `purpose` (`illustration` | `mark`), `set`, and
+`subject`.
+
+## Adding or regenerating a set
+
+Sets are authored in `src/icons/sets/<name>.json` and are also the exact input
+Slopcamera consumes:
+
+```sh
+slopcamera image icon --set src/icons/sets/sponge.json \
+  --output-dir artifacts/icons/sponge --candidates 2 --set-rounds 3
+```
+
+Copy the reviewed SVGs into `src/icons/<set>/` and the set receipt into
+`src/icons/receipts/`, then run:
+
+```sh
+bun run generate:icons   # measures artwork and rewrites manifest + module
+bun run check:icons      # CI form: verifies instead of writing
+bun test src/icons.test.ts
+```
+
+Admission is fail-closed: single ink, bounded bytes and vector detail,
+context-shaped density and stroke bands, and per-set family coherence
+(each illustration within ±45% coverage and ±50% stroke of its set median;
+marks are excluded from family coherence since they are product-authored).
+A manifest member without artwork is listed under `pending`, never silently
+omitted.
+
+Product marks are declared on a set's `marks` field: they are vetted and
+distributed through the same registry but are product-authored content that
+a `--set` regeneration run never rewrites.

package/LANTERN_MATERIAL.md

@@ -0,0 +1,60 @@
+# Lantern material
+
+Lantern adds luminous edges, palette-tinted selection states and restrained depth to the shared component system. It is independent of the selected palette, the Paper theme and editorial typography. The default application treatment is quiet. Glazing belongs at key transitions and on chrome with real content behind it.
+
+Opacity-only color mixes use sRGB so translucent surfaces keep the source color's hue. Blends between two colored paints use OKLCH. The native browser checks compare translucent paint with an independent RGB and alpha reference in both appearances.
+
+The complete `styles.css` and `compiler-foundation.css` entries include the material. For a selective import, load `@hraness/design-kit/lantern-material.css` after the existing foundation and palette styles, then set `data-hraness-material="lantern"` on the document or an explicit theme island. The stylesheet has no JavaScript, font, remote URL or inline-style dependency. Existing controls continue to own their semantics, dimensions, state and accessible names.
+
+| Hook | Purpose |
+| --- | --- |
+| `.hraness-material-pane` | Opaque, readable content plane. Optional `data-depth="raised"` or `"inset"` describes actual depth. |
+| `.hraness-material-chrome` | Diffused header or floating enclosure. It becomes opaque without backdrop support or when reduced transparency is requested. |
+| `.hraness-material-wall` | A flat palette plane behind an area. Its shaded faces, grain, patterns, and light washes are retired and no longer paint. It never filters or overlays descendants. |
+| `.hraness-material-control` | Plain HTML action adapter. A narrow edge leaves the established foreground/background pair and focus shadow intact. |
+| `.hraness-material-input` | Plain HTML field adapter: inset edge paint and a semantic caret. |
+| `.hraness-material-choice` | Plain HTML selection with a matched fill/text pair, driven by `aria-pressed`, `aria-selected` or React Aria's `data-selected`. |
+| `.hraness-material-terminal` | A quiet window enclosure; its `__bar` is decorative title chrome. |
+| `.hraness-material-code` | A theme-aware `pre` with intact source lines and horizontal overflow. Use `SyntaxCode` or framework-neutral `highlightCode` for syntax; give an overflowing example a keyboard focus target. |
+| `.hraness-material-rows` | An unruled readable collection. The product owns grouping, separators, and responsive structure. |
+| `.hraness-material-disclosure` | Native disclosure with a touch-sized summary and visible keyboard focus. |
+
+The wall and marketing fields accept `data-hraness-pattern="cells"`, `"weave"`, `"contour"`, `"mesh"` or `"none"` on their boundary for compatibility. Patterns are retired: every value paints the uninterrupted palette background, and the material-only snapshot needs no assets.
+
+Panes use a resting shadow by default. Raised panes use a broader lift, while inset panes use an inner shadow and a quieter fill. Their transparent borders preserve geometry; forced colors replaces those edges with `CanvasText`. Chrome uses a diffused shadow rather than a drawn divider. `--hraness-material-rest`, `--hraness-material-raised`, `--hraness-material-lift`, `--hraness-material-inset` and `--hraness-material-outline` are the shared depth roles. `--hraness-material-raised` is the small-control counterpart of the resting shadow. The UI adapters leave error borders and keyboard focus under the control's ownership.
+
+Material tokens resolve inside each marked island. Mark a nested theme island separately. A portalled overlay must carry the complete palette class/attributes, resolved light/dark mode and `data-hraness-material="lantern"` on its actual host (or inherit them from a corresponding wrapper). The marker and material hook can live on the same element. A material class alone cannot transport context across a portal.
+
+For `@hraness/ui` primitives, use the compiled `lanternControlStyles` exported from `@hraness/design-kit/react` through their existing `controlXstyle` prop. Use `edge` on actions, `inset` on a text field's control, and conditionally append `selected` for a real selected state. Do not apply the plain HTML classes to primitive wrappers or controls. The compiled recipes leave the primitive's focus outline, focus shadow, dimensions, error and disabled behavior intact. They work through either the standalone package stylesheet or the final compiler union.
+
+```tsx
+<Button
+  aria-pressed={selected}
+  controlXstyle={[lanternControlStyles.edge, selected && lanternControlStyles.selected]}
+  onPress={() => setSelected(!selected)}
+>
+  Personal only
+</Button>
+<TextField label="Find a note" controlXstyle={lanternControlStyles.inset} />
+```
+
+`ThemeMenuButton` and `ThemeToggle`'s menu presentation need no adapter. Inside a Lantern island the trigger rests on the material plane with a seam border and the raised shadow, warms on hover, sets into the inset shadow while pressed, and keeps its focus ring and outline. Its menu uses the material plane and lift, and the selected appearance uses the warm plane. The palette appearance menu that `ThemeMenuButton` renders inside `DesignPaletteProvider` follows the same rules. Outside Lantern every value falls back to the palette, so other products see no change. Forced colors removes the shadows and uses system colors; reduced motion removes the transition. The menu is portalled, so put `data-hraness-material="lantern"` on the document element (or the portal host) when the header is Lantern. Remove site CSS that restyles `.hraness-design-theme-toggle__trigger`, `.hraness-design-theme-toggle__popover`, or `.hraness-design-theme-toggle__item` for Lantern.
+
+`TopBar` accepts the chrome class with `surface="glass"`; the material binds its public background/backdrop tokens. Its `--hraness-design-top-bar-edge` token resolves to the material outline, including an explicit system-color edge in forced colors. The same class also supports a native header. Use sticky chrome only where content actually scrolls behind it.
+
+Older applications can vendor a five-file snapshot without upgrading their primitive peer graph:
+
+```sh
+bun scripts/lantern-material-snapshot.ts --write DEST --source-commit FULL_SHA
+node DEST/check.mjs DEST
+```
+
+Run the installer from an immutable design-kit checkout and supply its full commit. The snapshot contains CSS, license, a Node checker and declaration, and provenance. It has no fonts or bitmap dependencies. Keep its checker in the consuming application's normal validation gate.
+
+Keep body text on opaque planes. Use square modules for alignment and proportion without forcing content into square cards. Collections need a bounded readable measure, a clear grouping rule and progressive disclosure of secondary details. Availability, errors and consequential limits remain visible before a user acts. One section should have one clear primary next step.
+
+Warm material states do not replace success, warning, danger or keyboard-focus meaning. Reduced motion removes material transitions. Reduced transparency removes glazing. Forced colors replaces material paint with system colors and keeps selected states explicit.
+
+The architectural reference is Maison Hermès in Tokyo. RPBW describes textured translucent glass, curved corner blocks and a façade that shifts from cool daylight to warm interior illumination. Hermès describes a repeated square module extending into the flooring and shelving. These are principles of material and organization, not a license to cover every control with a façade image.
+
+Sources: [RPBW project](https://www.rpbw.com/project/maison-hermes), [Hermès: The magic of the squares](https://lanterne.hermes.com/en/secrets/secret2412/).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hraness/design-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MARKETING_COPY.md

@@ -0,0 +1,49 @@
+# Writing for the marketing components
+
+The product-marketing components give every Hraness site the same page shape. This guide says what each slot is for, so the shape does not also produce the same prose. `STYLE.md` still owns voice and conventions; this file covers the slots.
+
+A reader arrives asking "What is this, and is it for me?" Answer that in the hero, show evidence next, and keep build details for the documentation.
+
+## Slots
+
+Limits are maximums. Count characters in the rendered text.
+
+| Slot | Write | Limit | Avoid |
+| --- | --- | --- | --- |
+| `ProductHero` `heading` | One sentence that says what the reader can do with the product. | 60 characters | Verbless slogans ("All your subscriptions. One router."), lists of three verbs, and claims a competitor could publish unchanged. |
+| `ProductHero` `summary` | One or two sentences: what it is, who it is for, and the mechanism in the reader's words. | 240 characters | Stacking four mechanisms into one clause; "the first" or "the only" without a source. |
+| `eyebrow` | The product's category from the portfolio registry, or nothing. | Four words | A tagline or a second headline. |
+| `boundary` | Price or license, requirements, and release state, once and plainly: "Free and open source · Needs Rust 1.85 or newer · Latest release: v0.2.1". | 110 characters | Governance terms such as "verified release", "admitted", "qualified", or "source pilot". |
+| `notice` | Status only when it changes what the reader can do today. | One sentence | A second copy of the boundary, or caveats a reader cannot act on. |
+| `MarketingProofFrame` | Output a reader can reproduce with the current release. Put the capture date in `credit` and label a historical record as historical. Set `chrome` to `window`, `browser` (with the page's `url`), or `terminal` to match what was captured. | | Commands or flags the current release rejects; "Live qualification" as a label; a browser address the product does not serve. |
+| Mockups from `@hraness/design-kit/mockups` | An illustration of one state of the product, with a `describe` sentence that starts "Illustration of" and a caption that says it is an illustration. Invented names, handles, and addresses on reserved example domains. | `describe`: one sentence | Real people's names or handles, headings inside the picture, and a mockup presented as a screenshot. |
+| `MarketingDataTable` `caption` | The measurement's name: what was run, on what. | 70 characters | A verdict disguised as a caption. |
+| `MarketingDataTable` `meta`, `note` | The date, source, or sample size in `meta`; the caveat that bounds the claim in `note`. | `note`: 160 characters | Data that outlives its caveat, or a table presented as a guarantee. |
+| `MarketingDataTable` columns | Short unit-bearing labels. Numbers go in `numeric` columns; the first column names each row. | | Wide dumps that belong in documentation. |
+| `MarketingCodeBlock` | Commands and output a reader can copy and run on the current release. Keep lines inside about 32 characters on a phone. | | Prompts, placeholders, or output the release cannot produce. |
+| `MarketingPillars`, `MarketingPrimitives` | Two to four items. Labels name a thing or state a fact ("A log for every run"); each summary is one sentence. | Label: five words. Summary: 120 characters | Adjective triads ("Fast / Legible / Yours") and abstract nouns ("durable objects"). |
+| Section `heading` | Sentence case. A full sentence in the editorial preset may end with a period; other headings do not. | 70 characters | Slogans and headings that promise more than the section shows. |
+| `MarketingTrustBoundary` | What stays on the reader's machine, what is shared, and what the product will not do, each stated once on the page. | Four items | Authority, custody, admission, or lease vocabulary. |
+| `MarketingRelated` `role` | The sibling product's own one-line description from the portfolio registry. It is the only text the card shows, under the product's mark and name. | One line | A new description invented for this page. |
+| `MarketingRelated` `mark` | The sibling product's portfolio mark, such as a `relatedFor()` item's `mark`. | | Artwork the sibling does not use. |
+| `MarketingQuestionList` | Questions readers actually ask. The first sentence of each answer answers it. Generate any FAQ JSON-LD from the same array. | Eight questions | Questions written to deliver a talking point. |
+| `MarketingCallToAction` | The next concrete step. | Section heading limit | Decorative closers ("Give every job the same room to run in."). |
+
+## Plain-string props
+
+Most text props (`summary`, `detail`, `caption`, `boundary`, `role`) are plain strings and render as text. Backticks show up literally on the page. Name a command in prose there, or put code in a slot that accepts elements (`example`, `children`, `answer`).
+
+## Before and after
+
+These come from live Hraness pages.
+
+- "every turn lands on one eligible account, bounded, with custody proven at settlement." Better: "Each task runs on one of your accounts that is signed in, idle, and not at a known quota limit, and xcb keeps that account locked until the provider process exits."
+- "A policy over your transcripts, not a new editor." Better: "You decide when to compact and how."
+- "Current verified release v0.2.1." Better: "Latest release: v0.2.1."
+- "Automatic replies remain a separate choice, requiring a qualified agent, an enabled contact and global resume." Better: "Automatic replies stay off until you connect an AI account, turn them on for this contact, and resume the butler."
+
+## Check before publishing
+
+A launch post and its social posts are articles, not page slots. Write them as beats with `ARTICLE_COPY.md`.
+
+Read the hero and the first two sections aloud. Every command must run on the current release. Render the page at 1280px and 375px wide; monospace proof frames need to fit about 32 characters per line on a phone.

package/MARKETING_PRESET.md

@@ -0,0 +1,108 @@
+# Marketing preset contract 1 (Quiet)
+
+The separately imported `@hraness/design-kit/product-marketing-preset.css` export adds the Quiet marketing treatment to the existing product-marketing grammar: a sans display heading, a flat palette background, hairline rules, and a thin header. It shares Paper's `light-dark()` browser baseline: Chrome 123+, Firefox 120+, and Safari 17.5+. It does not replace Paper contract 1, reset the document, or change default component presentation. Import it after `styles.css` for standalone components, or beside `compiler-foundation.css` in a registered compiler graph. The published manifest binds the stylesheet. Bundle the font its CSS URL references along with it; the browser downloads it only for a product that opts in to it.
+
+```tsx
+import "@hraness/design-kit/product-marketing-preset.css";
+import { MarketingPage, MarketingField, ProductHero, MarketingSection } from "@hraness/design-kit/react/server";
+
+<MarketingPage preset="editorial">
+  <MarketingField>
+    <ProductHero name="Relay" heading="Run a job from your terminal, your code, or your agent" headingId="title"
+      summary="Relay runs the same job wherever you start it and writes a log you can read afterward." />
+  </MarketingField>
+  <MarketingSection heading="Install Relay and run your first job." headingId="next">
+    <p>Run <code>relay init</code>, then <code>relay run job-01</code> to write your first log.</p>
+  </MarketingSection>
+</MarketingPage>
+```
+
+Raw HTML and older components use `data-hraness-marketing-preset="editorial"` on their marketing ancestor and `.hraness-marketing-field` on the opening container. Existing semantic `hraness-marketing-*` hooks receive the same typography, spacing, and action tokens. A field may also be the hero itself. The field paints the flat palette background in document flow, with no texture, gradient, overlay, or filter, whatever the retired field tokens say. Product imagery and logos stay clean and full color; `.hraness-marketing-brand-mark` is an optional image hook. Existing product accent variables remain authoritative.
+
+`editorial` sets the display role to the `--font-text` face (normally Nebula Sans) at weight 550 with tight tracking and a fluid heading that opens at 2.375rem on phones. `minimal` uses the same face at weight 500, a compact heading scale, and a 40px header token. Neither preset uses a serif. The snapshot still vendors Instrument Serif 400 for a product that opts in explicitly with `--hraness-marketing-display-font: "Instrument Serif", Georgia, serif`; the browser downloads it only then. Nested scopes reset their own display and field tokens. Prefer independent header and main scopes when their presets differ.
+
+For a custom or older component header, add `class="hraness-marketing-header-surface"` to the header itself. This class explicitly opts in to paint without requiring a preset ancestor. Add `data-hraness-marketing-preset="minimal"` on the same element only when you also need its compact role tokens. This paint-only hook adds supported backdrop blur and opaque accessibility fallbacks without setting position, dimensions, or navigation layout. No wrapper is required around a sticky header. Unsupported filtering, reduced transparency, and forced colors retain opaque surfaces. Blur is allowed only here, on a sticky header with content scrolling behind it; cards and content never use blur or glass. Coarse pointers retain 48px action targets.
+
+## Phone header
+
+At 48rem and narrower, `MarketingSiteHeader` and the raw `.hraness-marketing-header__*` hooks use two rows. The first row holds the brand, the primary action, and the `trailing` appearance menu. The navigation takes the whole second row, reaches the screen edges, and scrolls sideways without a visible scrollbar. The brand, links, and header actions keep 44px targets (48px for coarse pointers in the preset). The navigation row never widens the header's intrinsic size, so the page does not overflow at 360px. Keep three to six short link labels; the header wraps to its measured height, so use `StickyOffsetSync` or `syncStickyOffset` when the header is sticky.
+
+## Palette and patterns
+
+The opening field and terminal proof inherit the active palette's foreground, muted, primary, background and surface colors. Existing product accent overrides remain available for actions.
+
+Patterns are retired. `MarketingPage` and `MarketingField` still accept the `pattern` prop, and `data-hraness-pattern` still accepts the same finite values in React markup, raw HTML, and immutable CSS snapshots, so existing markup keeps working. Every value paints the flat palette background:
+
+| Value | Since 0.23.0 |
+| --- | --- |
+| `cells`, `weave`, `contour`, `mesh` | Retired; renders exactly like `none` |
+| `none` and omission | The flat palette background |
+
+The grain and cell textures, the field gradient, the accent band's grid, and the terminal chrome gradient no longer paint. `--hraness-marketing-field-images` and `--hraness-marketing-field-size` remain defined for compatibility, but the field ignores them. The hero light inputs are no longer read.
+
+Editorial marketing uses the Nebula Sans display role at weight 550 with a fluid 2.375rem to 4.5rem opening heading and a 52-character summary measure. Minimal marketing uses the same face at weight 500 and a smaller fluid hierarchy. Application and embedded preview headings retain their own roles. Marketing cards, proof frames, and header chrome use hairline edges (`0 0 0 1px` of `--hraness-marketing-line`) instead of lifted shadows. Forced colors restores explicit system-color edges.
+
+## Sticky clearance and equal-height card rows
+
+A sticky `.hraness-marketing-header` or `.hraness-marketing-header-surface` publishes `--hraness-sticky-offset` on `html` and on `.hraness-marketing-page`. The token height is the fallback; `StickyOffsetSync` from `@hraness/design-kit/react` or `syncStickyOffset` from `@hraness/design-kit/browser` replaces it with the measured header border box when the chrome wraps. Attach the site header as a direct child of the page, then put the main landmark immediately after it:
+
+```tsx
+import { MarketingMain, MarketingPage, MarketingSiteHeader, StickyOffsetSync } from "@hraness/design-kit/react";
+
+<MarketingPage>
+  <MarketingSiteHeader brand="Relay" brandMark="/marks/relay.svg" links={[{ href: "#work", label: "Work" }]} />
+  <StickyOffsetSync />
+  <MarketingMain>
+    <div className="hraness-sticky-below-chrome" data-hraness-sticky>Index</div>
+    {children}
+  </MarketingMain>
+</MarketingPage>
+```
+
+Skip links should target `#main-content`. Hash targets and the main landmark use the offset as `scroll-margin`. Do not add a second padding gap while the header stays in flow. Use `clearance="pad"` or `data-hraness-clearance="pad"` only when the header is `data-position="fixed"`. The next sticky sibling must use `.hraness-sticky-below-chrome` or `data-hraness-sticky` (`inset-block-start: var(--hraness-sticky-offset)`), not `top: 0`. This is the same publish-on-ancestor pattern as `@hraness/ui` next-adopter sticky-offset sync, under the kit-owned `--hraness-sticky-offset` name.
+
+`.hraness-marketing-card-row` / `MarketingCardRow` stretches every direct child to the tallest item in the row. Meta sits in a reserved two-line block (`--hraness-marketing-card-meta-lines`, default 2). Titles wrap and are not clamped. Product-owned flex rows that `align-items: start` should switch to this hook so a longer blurb cannot stagger the row.
+
+`.hraness-marketing-card__art` / `MarketingCardArt` is the per-card media well. It clips overflow, isolates paint, and keeps backgrounds attached and originated on the well so a logo or art surface cannot run through the gutter as one bar. Pass `art` on `MarketingCard` or `MarketingCardItem`, or put the class on a well inside a `.hraness-marketing-card`. Each card is a containing block (`position: relative; isolation: isolate`). Do not place the well as a row sibling or give it `background-attachment: fixed`.
+
+## Tokens for custom compositions
+
+| Role | Public tokens |
+| --- | --- |
+| Display | `--hraness-marketing-display-font`, `--hraness-marketing-display-weight` |
+| Hero heading | `--hraness-marketing-h1-size`, `--hraness-marketing-h1-leading`, `--hraness-marketing-h1-tracking` |
+| Section heading | `--hraness-marketing-h2-size`, `--hraness-marketing-h2-leading`, `--hraness-marketing-h2-tracking` |
+| Tier and proof heading | `--hraness-marketing-h3-size`, `--hraness-marketing-h3-leading` |
+| Layout | `--hraness-marketing-content-measure`, `--hraness-marketing-header-measure`, `--hraness-marketing-header-height`, `--hraness-marketing-gutter`, `--hraness-marketing-hero-space`, `--hraness-marketing-story-space` |
+| Field | `--hraness-marketing-field-ink`, `--hraness-marketing-field-muted`, `--hraness-marketing-link`. `--hraness-marketing-field-images` and `--hraness-marketing-field-size` are retired and ignored. |
+| Terminal proof | `--hraness-marketing-terminal-background`, `--hraness-marketing-terminal-ink`, `--hraness-marketing-terminal-muted`, `--hraness-marketing-terminal-command`, `--hraness-marketing-terminal-chrome`, `--hraness-marketing-terminal-shadow` |
+
+Map only owned marketing headings to these tokens. Do not restyle every descendant h2 inside product previews or authentication forms. Remove obsolete unlayered font, size, and role-token overrides when adopting the preset; unlayered author rules otherwise outrank the legacy component layer. Custom compiled recipes must read these variables rather than pin old values. The preset uses the existing marketing grammar for layout; importing only this preset does not supply every base component recipe.
+
+`MarketingSection.label` and collection labels are optional in current components. For older versions that require strings, pass an empty string only when the slot is redundant. The preset removes spacing for empty label/name/eyebrow elements; nonempty facts remain visible. Preserve factual positioning in an appropriate product-owned body or example slot.
+
+## Mockups
+
+`@hraness/design-kit/mockups` draws illustrations of chat, feeds, inboxes,
+articles, terminals, browsers, desktop windows, and phones in plain React with
+no StyleX. Its stylesheet, `@hraness/design-kit/mockups.css`, uses `hkm-`
+classes, reads the marketing tokens with fallbacks, sizes itself with container
+queries, and switches between light and dark on `[data-hkm-theme]`. Transitions
+start only after the reader first changes a state, and stop under reduced
+motion. `MarketingProofFrame` takes `chrome="window"`, `"browser"` with a `url`,
+or `"terminal"` for real captures.
+
+## Immutable snapshots for existing sites
+
+Keep the current component/UI versions when upgrading them would create unrelated migration work. Use the installer from a reviewed design-kit checkout at an exact full commit containing the preset:
+
+```sh
+bun scripts/product-marketing-snapshot.ts --write /path/to/site/vendor/hraness-marketing --source-commit FULL_40_CHARACTER_COMMIT
+node /path/to/site/vendor/hraness-marketing/check.mjs
+```
+
+Import `vendor/hraness-marketing/product-marketing-preset.css`. Keep the entire directory. The CSS references only `fonts/instrument-serif/instrument-serif-latin-400.woff2`, which loads only when a product opts in to that face. `marketing-assets/grain.svg` and `marketing-assets/cells.svg` stay in the inventory so an earlier snapshot upgrades in place, but the Quiet preset no longer references them. Reinstall from a 0.23.0 or later commit to get the Quiet preset; the same installer replaces a previously verified snapshot. The finite bundle also includes their licenses/provenance, a dependency-free Node/Bun `check.mjs` validator, and `provenance.json`, which binds every file to SHA-256 and a source commit. Check that manifest in the consumer gate. Installation reads Git object bytes, never a dirty working copy, and refuses changed, unowned, or symlinked destinations. An upgrade replaces only a previously verified snapshot. Run from a released immutable commit for production delivery; local candidate commits are for pre-release verification.
+
+The retained texture files come from `scripts/marketing-textures.ts`; its check verifies byte-identical deterministic SVGs. Instrument Serif retains its OFL license and upstream provenance. The existing Paper CSS snapshot remains separate and unchanged. Neither snapshot executes code at runtime or upgrades UI/compiler dependencies.
+
+For a build graph, import `checkMarketingSnapshot` from the vendored `check.mjs` and await it with the snapshot directory (default: the checker's directory). It returns the validated source identity and finite `files` record; each entry contains its source path and SHA-256. The included `check.d.mts` provides TypeScript declarations. Include those checked CSS, font, and SVG files in your build; validation does not copy or modify files.