@nanisoft/prism-llms 0.4.0 → 0.5.0

package/dist/md/blocks/process-rail-01.md

@@ -0,0 +1,106 @@
+# ProcessRail01
+
+A process drawn as a rail: two, three or four steps on one line, each with an ordinal, a name and one caption.
+
+```tsx
+import { ProcessRail01 } from '@nanisoft/prism-ui/blocks/process-rail-01'
+```
+
+## Overview
+
+ProcessRail01 draws a process as a rail: the steps of a pipeline, in order, on
+one line, each with an ordinal, a name and one caption.
+
+All four NaniSoft sites compose this section, and each one drew it by hand with
+the same three parts: an ordinal per step, a name, and one caption per step,
+separated by hairlines with a label on the last one. This is that section once,
+with the ordinal and the separation owned here rather than by four sets of site
+CSS.
+
+**The rail admits four steps and refuses five, in the type.** `steps` is a tuple
+union rather than an array, so a fifth element is a compile error and not a fifth
+column. The reason is that a rail is a claim about a sequence, and a rail that
+quietly dropped a step to fit a width would be a diagram of a process that is not
+the process. Four is the number every one of the four sites actually states; a
+longer process is a different shape and earns its own Block.
+
+## Guidelines
+
+### When to use
+
+Use ProcessRail01 for a process with two to four steps where each step is one
+name and one line: a data path, a build pipeline, a review loop.
+
+Use it when the order is the point. A set of independent features is a
+`FeatureGrid01`, and a set of stages that do not run in sequence is a set.
+
+### When not to use
+
+Do not use it for a process of five or more steps. It will not compile. That is
+the design: a rail this wide stops reading as a line, and a longer process wants a
+numbered list, which is a `Prose` and not a rail.
+
+Do not use it for two steps that are really a before and an after. A rail with
+two columns is two columns, and `NoteGrid01` says the same thing with less
+ceremony.
+
+### Best practices
+
+- Keep each caption to about twelve words. A caption that wraps under its step and
+  the row stops reading as a line; the detail belongs above the rail in
+  `description`.
+- Pass `finalLabel` only when the rail genuinely ends in a state worth naming.
+  "serving", "merged" and "verified" are claims; a rail that has not finished
+  should say nothing.
+- Leave `title` out when the rail is composed under a heading the page already
+  owns.
+
+### Content guidelines
+
+- Name a step the way you would name it in conversation: a verb or a short noun
+  phrase, not a sentence.
+- Write the caption as what happens, not as why it matters. The why belongs in
+  `description`.
+- Do not number the steps yourself. The ordinal is rendered from the position, so
+  a list that carries its own numbers can disagree with its own order after a
+  sort.
+
+**Four steps on one line, with the label on the last one.**
+
+```tsx
+import { ProcessRail01 } from '@nanisoft/prism-ui/blocks/process-rail-01'
+
+/** Four steps on one line, with the label on the last one. */
+export default function ProcessRail01Demo() {
+  return (
+    <ProcessRail01
+      headingLevel="h3"
+      eyebrow="Preview"
+      title="The data path"
+      description="One line about the whole path, above the rail rather than inside it."
+      finalLabel="serving"
+      steps={[
+        { name: 'Collect', description: 'The whole surface, every minute.' },
+        { name: 'Conform', description: 'One timestamp, one symbol form.' },
+        { name: 'Verify', description: 'The column list held by test.' },
+        { name: 'Serve', description: 'One queryable view.' },
+      ]}
+    />
+  )
+}
+```
+
+## Props
+
+**`eyebrow`** `string` · optional · default: — — Optional label above the section title. See the No-Default-Eyebrow Rule.
+**`title`** `string` · optional · default: — — The section title. Omit it for a rail that is composed under its own heading.
+**`description`** `string` · optional · default: — — One or two sentences under the title.
+**`finalLabel`** `string` · optional · default: — — The label on the last step, for a rail that ends in a state worth naming: "serving", "merged", "verified". Omit it when the last step needs no label, which is the honest state for a rail that has not finished.
+**`steps`** `ProcessRail01Steps` · required · default: — — The steps, in the order the process runs. Two, three or four; a fifth is a type error. See `ProcessRail01Steps`.
+**`headingLevel`** `HeadingLevel` · optional · default: — — Heading level for the section title. See `HeadingLevel`.
+
+## Composition
+
+**`exports`** `ProcessRail01` — the public runtime names this Block promises
+**`source`** `packages/ui/src/blocks/process-rail-01/index.tsx` — the file this Block is defined in
+**`dependencies`** `Section` — the public Prism exports this item composes

package/dist/md/blocks/product-grid-01.md

@@ -0,0 +1,113 @@
+# ProductGrid01
+
+A set of products as hairline rows: a two-part ProductMark, a name, one tagline and a destination per row.
+
+```tsx
+import { ProductGrid01 } from '@nanisoft/prism-ui/blocks/product-grid-01'
+```
+
+## Overview
+
+ProductGrid01 is a set of products as a stack of hairline rows: a two-part mark, a
+name, one tagline and a destination per row.
+
+All four NaniSoft sites publish this section, and each one drew it by hand with
+the same three parts in the same order: a colour mark for the product, the
+product's name, and one line about what it is, on a hairline row with the whole
+row a link. Each site also resolved the mark's ink in JavaScript from the live
+mode, which is the part that is a second source of truth.
+
+**The mark is two parts, and it is `ProductMark`.** The ring is `brand-ink` and
+the core is the product's own `primary`, with the name in the brand ink beside it.
+That split is settled by a measurement rather than by taste: a pastel brand value
+is a fill and never text, so the core may be `primary` and the name may not, and a
+*filled* mark on a light card measures under the threshold a mark has to clear, so
+the mark is a hairline ring around the fill rather than a disc of it.
+
+## Guidelines
+
+### When to use
+
+Use ProductGrid01 where the reader's question is "which of these should I open".
+That is a family of products, a set of integrations, a set of sibling sites.
+
+Use it when each member is one line long. A member that needs a paragraph is a
+`FeatureGrid01` card, and a paragraph in a row makes the row a column of
+paragraphs.
+
+### When not to use
+
+Do not use it for a set of things that are not navigable. A grid of capabilities
+is a `FeatureGrid01`; there is nothing to click, and a row that pretends to be a
+link teaches a reader that everything on a page is.
+
+Do not use it for two members. Two products side by side is a hero with two
+things in it, and a hairline list of two is a list.
+
+### Best practices
+
+- Order the rows by how likely a reader is to want each one. Order is a claim and
+  it is yours.
+- Pass `newTab` per row rather than globally. Prism does not decide what counts as
+  external, and a same-site link that opens a tab is a reader who has lost the
+  page.
+- Leave `pack` off the one member that has no pack of its own. That member wears
+  the spectrum.
+- Use one mark size across the grid. The grid passes one size to every mark, so a
+  mixed set is not reachable from here.
+
+### Content guidelines
+
+- Keep a tagline to one line. It is what a reader scans.
+- Write the tagline as what the product is, not as what it does for the reader.
+- Use the product's own name, in the case it uses everywhere else.
+
+**Two members, one wearing a pack and one wearing the spectrum.**
+
+```tsx
+import { ProductGrid01 } from '@nanisoft/prism-ui/blocks/product-grid-01'
+
+/** Two members, one wearing a pack and one wearing the spectrum. */
+export default function ProductGrid01Demo() {
+  return (
+    <ProductGrid01
+      headingLevel="h3"
+      eyebrow="Preview"
+      title="Built on one platform"
+      description="One line about the set, above the rows rather than inside one."
+      caption="The company root has no pack of its own, so its mark wears the spectrum."
+      products={[
+        {
+          id: 'nexus',
+          name: 'Nexus',
+          pack: 'lavender',
+          tagline: 'The agent factory: an issue in, a reviewed change out.',
+          href: '#nexus',
+        },
+        { id: 'www', name: 'NaniSoft', tagline: 'The company behind the platform.', href: '#www' },
+      ]}
+    />
+  )
+}
+```
+
+## Props
+
+**`eyebrow`** `string` · optional · default: — — Optional label above the section title. See the No-Default-Eyebrow Rule.
+**`title`** `string` · optional · default: — — The section title. Omit it for a grid composed under its own heading.
+**`description`** `string` · optional · default: — — One or two sentences under the title.
+**`products`** `readonly ProductGrid01Product[]` · required · default: — — The products, in the order a reader should meet them. Order is the caller's because it is a claim about which product matters first.
+**`caption`** `string` · optional · default: — — The line under the grid, for the sentence that qualifies it: what the set does not include, or where to read more.
+**`headingLevel`** `HeadingLevel` · optional · default: — — Heading level for the section title. See `HeadingLevel`.
+**`id`** `string` · required · default: — — The product's key within the set. Carried on the markup as `data-product` through `ProductMark`, so a test can name one product rather than the first one, and two products in one document are individually addressable.
+**`name`** `string` · required · default: — — The product's own name, which is the second part of its mark. It is the anchor of the row and the first thing a reader reads.
+**`pack`** `ProductMarkProps['pack']` · optional · default: — — The product's pack, which is the hue of the mark's core. Omit it, or pass `null`, for the one member of a set that has no pack of its own: that member wears the full spectrum rather than a colourless mark.
+**`tagline`** `string` · required · default: — — One line about what the product is.
+**`href`** `string` · required · default: — — Where the row goes. Rendered as a native anchor's `href`, so the row is a link with the browser's own affordances rather than a click handler.
+**`newTab`** `boolean` · optional · default: — — Opens the destination in a new browsing context, which defaults the link relationship to `noopener noreferrer`. Prism does not decide what counts as external, so the caller declares it.
+
+## Composition
+
+**`exports`** `ProductGrid01` — the public runtime names this Block promises
+**`source`** `packages/ui/src/blocks/product-grid-01/index.tsx` — the file this Block is defined in
+**`dependencies`** `ProductMark, Section` — the public Prism exports this item composes

package/dist/md/blocks/settings-panel-01.md

@@ -0,0 +1,148 @@
+# SettingsPanel01
+
+A settings form grouped into sections of text, select and switch fields.
+
+```tsx
+import { SettingsPanel01 } from '@nanisoft/prism-ui/blocks/settings-panel-01'
+```
+
+## Overview
+
+SettingsPanel01 is a settings form grouped into named sections. The card holds
+the title and description, each section holds a heading and its fields, and the
+footer holds the save and cancel controls, with a rule between sections.
+
+The block composes these components:
+
+| Part | Component | Role |
+| --- | --- | --- |
+| Surface | Card, Separator | the panel and the rule between sections |
+| Fields | Field, Input, Textarea | labelled text controls |
+| Choices | Select, Switch | one-of-many and on-or-off fields |
+| Footer | Button | the save and secondary actions |
+
+A field is a small object that describes one control: its `kind`, its label, an
+optional description and its value handlers. The block owns no values and no
+copy. Omitting `submitLabel` renders no footer, the right shape for a read-only
+view.
+
+## Guidelines
+
+### When to use
+
+Use SettingsPanel01 when a screen changes several settings that share one save.
+It works when the groups are stable and a reader scans them top to bottom.
+
+### When not to use
+
+Do not use it for a single setting. One field in a card is a heavier frame than
+the choice deserves; put the control in the page.
+
+Do not use it when each change should apply immediately with no save. A switch
+inside a saved form reads as applied; use standalone switches with their own
+handler instead.
+
+### Best practices
+
+- Give every field a stable `id`, so the label is linked to the control.
+- Keep one save per panel. A mixed model, where some fields save and others do
+  not, makes the footer's promise unclear.
+- Put the consequential choice first in its section, so a reader does not hunt
+  for the setting that matters most.
+- Disable the submit control while a save is in flight.
+
+### Content guidelines
+
+- A section title is one or two words in sentence case: "General",
+  "Notifications".
+- A field label is a short noun phrase and does not end in a colon.
+
+**A grouped settings form with text, select and switch fields.**
+
+```tsx
+'use client'
+
+import { SettingsPanel01 } from '@nanisoft/prism-ui/blocks/settings-panel-01'
+
+/** A grouped settings form with text, select and switch fields. */
+export default function SettingsPanel01Demo() {
+  return (
+    <SettingsPanel01
+      title="Workspace settings"
+      description="Manage how this workspace behaves for everyone on the team."
+      submitLabel="Save changes"
+      secondaryAction={{ label: 'Cancel' }}
+      sections={[
+        {
+          id: 'general',
+          title: 'General',
+          description: 'Shown to everyone you collaborate with.',
+          fields: [
+            {
+              kind: 'text',
+              id: 'workspace-name',
+              label: 'Workspace name',
+              defaultValue: 'Northwind',
+            },
+            {
+              kind: 'textarea',
+              id: 'workspace-description',
+              label: 'Description',
+              placeholder: 'What does this workspace do?',
+              rows: 3,
+            },
+            {
+              kind: 'select',
+              id: 'workspace-region',
+              label: 'Data region',
+              placeholder: 'Choose a region',
+              defaultValue: 'eu-west',
+              options: [
+                { label: 'Europe West', value: 'eu-west' },
+                { label: 'US East', value: 'us-east' },
+              ],
+            },
+          ],
+        },
+        {
+          id: 'notifications',
+          title: 'Notifications',
+          fields: [
+            {
+              kind: 'switch',
+              id: 'weekly-digest',
+              label: 'Weekly digest',
+              description: 'A summary of activity every Monday.',
+              defaultChecked: true,
+            },
+            {
+              kind: 'switch',
+              id: 'mention-alerts',
+              label: 'Mention alerts',
+              description: 'Notify me when someone mentions my name.',
+            },
+          ],
+        },
+      ]}
+    />
+  )
+}
+```
+
+## Props
+
+**`title`** `string` · required · default: —
+**`description`** `string` · optional · default: —
+**`sections`** `SettingsPanelSection[]` · required · default: — — The settings groups, each rendered with a heading and its own fields.
+**`submitLabel`** `string` · optional · default: — — The submit button label. Omit to render no footer.
+**`onSubmit`** `(event: FormEvent<HTMLFormElement>) => void` · optional · default: —
+**`secondaryAction`** `{ label: string; onClick?: () => void; }` · optional · default: — — A secondary control, such as Cancel.
+**`footer`** `ReactNode` · optional · default: — — Extra content in the footer, e.g. a status note.
+**`label`** `string` · required · default: —
+**`onClick`** `() => void` · optional · default: —
+
+## Composition
+
+**`exports`** `SettingsPanel01` — the public runtime names this Block promises
+**`source`** `packages/ui/src/blocks/settings-panel-01/index.tsx` — the file this Block is defined in
+**`dependencies`** `Button, Card, Field, Input, Select, Separator, Switch, Textarea` — the public Prism exports this item composes

package/dist/md/blocks/site-footer.md

@@ -1,19 +1,111 @@
 # SiteFooter
 
-Prism block — full documentation pending.
+The block at the foot of a product site: a brand lockup, grouped destinations, the links that leave the site and a slot for the legal line.
 
-```ts
-import { SiteFooter } from '@nanisoft/prism-ui/blocks';
+```tsx
+import { SiteFooter } from '@nanisoft/prism-ui/blocks/site-footer'
 ```
 
-`SiteFooter` is a Prism block. Full documentation is pending — the prism MCP answers API questions in the meantime (`get_item_props`, `get_item_source`).
+## Overview
+
+SiteFooter is the block at the foot of a product site: a brand lockup, grouped
+destinations, the links that leave the site, and an optional slot for the legal
+line.
+
+All four NaniSoft sites compose this exact footer in their root layout, and each
+one wrote its own column model, its own mark and its own current-page treatment.
+
+Every string is a prop and the block ships none. There is no site name, no
+copyright, no year, no "built with" line and no default column: a footer that
+hardcoded any of them would hand every consumer a claim about a product that is
+not theirs and a year that was not this one.
+
+## Guidelines
+
+### When to use
+
+Use SiteFooter as the chrome at the foot of a whole product site, in the root
+layout, below the main region.
+
+Use it wherever there are destinations a reader might otherwise not find: the
+documentation, the blog, the repository, the company site.
+
+### When not to use
+
+Do not use it inside an application screen. `AppShell01` owns a signed-in shell
+and its own foot.
+
+Do not use it for a single link. A footer with one destination is a link with a
+large margin around it.
+
+### Best practices
+
+- Group by what the links are, and name each group. Each column is its own
+  navigation region named by its title, so a reader navigating by landmark reaches
+  "Documentation" rather than one anonymous list of links.
+- The columns collapse to one column on a narrow viewport, and a footer read as
+  three unreadable columns on a phone is three columns nobody reads. Group what
+  belongs together before you split it into columns.
+- **Links that leave the site open in a new tab by default**, because a link that
+  leaves and comes back is a reader who has lost the page they were on. Pass
+  `newTab={false}` on one link to override it: Prism does not decide which
+  destinations are external, so the per-link prop wins.
+- Put a social icon in `icon`. It is `aria-hidden`, so the label is announced once
+  rather than twice.
+- Use `legal` for the copyright, the licence or the version. It is a slot because
+  every one of those is a fact about a specific product and about the year it was
+  published, and a block that held a year would be a block that went stale.
+
+### Content guidelines
+
+- Keep a link label to one or two words. A footer is scanned.
+- Name a column after what the links in it are, not after where they live.
+- Keep the social labels the same words a reader would use for the destination.
+
+**The site chrome: a brand lockup, grouped destinations, a social link and a legal slot.**
+
+```tsx
+import { SiteFooter } from '@nanisoft/prism-ui/blocks/site-footer'
+
+/** The site chrome: a brand lockup, grouped destinations, a social link and a legal slot. */
+export default function SiteFooterDemo() {
+  return (
+    <SiteFooter
+      product={{ id: 'nexus', name: 'Nexus', pack: 'lavender' }}
+      columns={[
+        {
+          title: 'Site',
+          links: [
+            { label: 'Landing', href: '#landing' },
+            { label: 'Docs', href: '#docs' },
+            { label: 'Blog', href: '#blog' },
+          ],
+        },
+        {
+          title: 'Elsewhere',
+          links: [
+            { label: 'GitHub', href: '#github' },
+            { label: 'nanisoft.com', href: '#company', newTab: true },
+          ],
+        },
+      ]}
+      social={[{ label: 'GitHub', href: '#github' }]}
+      legal={<span>2026 NaniSoft. One design language, five sites.</span>}
+    />
+  )
+}
+```
 
 ## Props
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `site` | PrismProductId | — | The site's registry id — marks the current product in the grid. |
-| `columns` (optional) | readonly SiteFooterColumn[] | — | Site-declared link columns, rendered beside the product grid. |
-| `social` (optional) | readonly SiteFooterSocialLink[] | — | Social links with app-supplied icons. |
-| `legal` (optional) | ReactNode | — | Overrides the default "© NaniSoft" line. |
-| `className` (optional) | string | — | — |
+**`product`** `Pick<ProductMarkProps, 'id' | 'name' | 'pack'>` · required · default: — — The product this footer belongs to: the id, name and pack its `ProductMark` is drawn from. The footer renders the mark rather than taking a slot, because the brand lockup is the one part of a footer that is never product-specific and every consumer would otherwise reimplement it.
+**`columns`** `readonly SiteFooterColumn[]` · optional · default: — — The groups of destinations: the sections of this site, its documentation, and anywhere else the site sends a reader. Omit it for a footer that carries only the brand lockup.
+**`social`** `readonly SiteFooterSocial[]` · optional · default: — — The links that leave the site. A `ReactNode` icon is drawn beside each label and hidden from assistive technology, so a screen reader announces the label once.
+**`legal`** `ReactNode` · optional · default: — — A slot for the line at the foot of the footer: a copyright, a licence, a version, a legal link. A slot rather than a prop, because every one of those is a fact about a specific product and about the year it was published, and a Block that held a year would be a Block that went stale.
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Component. Changing a Prism-owned visual property from here is prohibited.
+
+## Composition
+
+**`exports`** `SiteFooter` — the public runtime names this Block promises
+**`source`** `packages/ui/src/blocks/site-footer/index.tsx` — the file this Block is defined in
+**`dependencies`** `ProductMark` — the public Prism exports this item composes

package/dist/md/blocks/site-header.md

@@ -1,19 +1,119 @@
 # SiteHeader
 
-Prism block — full documentation pending.
+The bar at the top of a product site: a brand lockup, an optional product switcher, the site navigation and a slot for application controls.
 
-```ts
-import { SiteHeader } from '@nanisoft/prism-ui/blocks';
+```tsx
+import { SiteHeader } from '@nanisoft/prism-ui/blocks/site-header'
 ```
 
-`SiteHeader` is a Prism block. Full documentation is pending — the prism MCP answers API questions in the meantime (`get_item_props`, `get_item_source`).
+## Overview
+
+SiteHeader is the bar at the top of a product site: a brand lockup, an optional
+product switcher, the site's own navigation, and a slot for the controls your
+product owns.
+
+All four NaniSoft sites compose this exact bar in their root layout, and each one
+wrote its own: the mark in one place, the switcher in a popover in another, the
+navigation in a third, and each wrote the focus and current-page wiring separately.
+
+It is a Block and not a Component because it is a region of a page rather than a
+control: it composes a `ProductMark`, a `ProductSwitcher` and a set of links, and
+it owns the bar they sit in.
+
+**There is no product directory in this package.** The product is passed as the
+three facts its mark is drawn from rather than as an id this package would have to
+resolve. That is the same answer `ProductMark` gives, and for the same reason: a
+consumer that composes a set of its own products composes the header too.
+
+## Guidelines
+
+### When to use
+
+Use SiteHeader as the chrome around a whole product site. One header per site, in
+the root layout, above the main region.
+
+Use it on the landing page and on every documentation and blog page alike. A
+header that changes between sections of one site is two sites' worth of chrome.
+
+### When not to use
+
+Do not use it inside an application screen. `AppShell01` is that: a rail, a top
+bar and a mobile sheet, for signed-in state rather than for a public site.
+
+Do not use it for a product site's in-page navigation. That is a `Tabs` or a
+`Breadcrumb`.
+
+### Best practices
+
+- Pass `product`, and pass `products` only when the site is one of several. A set
+  of one renders one mark, so pass nothing rather than a switcher with a single
+  member.
+- Mark the current page with `current` on the one link whose destination is the
+  current route. The header marks it with `aria-current="page"`; it does not colour
+  it, because a colour is not a state a screen reader can read.
+- `navLabel` and `productsLabel` are required, because they are words a reader
+  hears. A Block that ships no copy ships no reader-facing copy either, so the name
+  of your own landmarks is yours to pass.
+- Put interactive controls in `actions`. It is a slot rather than a prop, because
+  an account menu, a sign-in link and a mode toggle are all application state and
+  none of them is a fact a header can be told.
+- Use `sticky` only where the page scrolls. A sticky header on a page with no
+  scroll costs the reader a strip of viewport for nothing.
+- The bar is one flex row that wraps. The switcher and the navigation wrap onto a
+  second line rather than overflowing, so a narrow viewport gets a taller header
+  and never a clipped one.
+
+### Content guidelines
+
+- Keep a nav label to one word. It is a bar.
+- Use each product's own name in the lockup, in the case it uses everywhere else.
+- Order the nav by how often a reader goes there, not alphabetically.
+
+**The site chrome: a brand lockup, the product set, the site nav and a slot.**
+
+```tsx
+import { SiteHeader } from '@nanisoft/prism-ui/blocks/site-header'
+
+/** The site chrome: a brand lockup, the product set, the site nav and a slot. */
+export default function SiteHeaderDemo() {
+  return (
+    <SiteHeader
+      product={{ id: 'nexus', name: 'Nexus', pack: 'lavender' }}
+      navLabel="Site"
+      productsLabel="Products"
+      products={[
+        { id: 'nexus', name: 'Nexus', pack: 'lavender', href: '#nexus' },
+        { id: 'atlas', name: 'Atlas', pack: 'mint', href: '#atlas' },
+        { id: 'alphalens', name: 'AlphaLens', pack: 'blush', href: '#alphalens' },
+      ]}
+      nav={[
+        { label: 'Docs', href: '#docs' },
+        { label: 'Blog', href: '#blog' },
+        { label: 'About', href: '#about', current: true },
+      ]}
+      actions={<span className="text-muted-foreground text-xs">A control you own</span>}
+    />
+  )
+}
+```
 
 ## Props
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `site` | PrismProductId | — | The site's registry id — identity is static and known at build time. |
-| `nav` (optional) | readonly PrismNavLink[] | — | Lean site nav, rendered between the brand and the actions. |
-| `cta` (optional) | ReactNode | — | Right-pinned call to action, before the switcher. |
-| `sticky` (optional) | boolean | — | Sticky by default; pass false to pin the header static. |
-| `className` (optional) | string | — | — |
+**`product`** `Pick<ProductMarkProps, 'id' | 'name' | 'pack'>` · required · default: — — The product this header belongs to: the id, name and pack its `ProductMark` is drawn from. The header renders the mark itself rather than a slot, because a header whose brand lockup is a slot is a header every consumer has to reimplement, and that is the one part of a site header that is never product-specific.
+**`products`** `readonly SwitcherProduct[]` · optional · default: — — The set of products to move between, rendered as a `ProductSwitcher` between the mark and the navigation. Omit it on a site that is the only product, and pass it on a site that is one of several. A set of one renders one mark, so pass nothing rather than a switcher with a single member.
+**`nav`** `readonly SiteHeaderLink[]` · optional · default: — — The header's own destinations: the sections of this site. Omit it for a header that carries only the brand lockup.
+**`navLabel`** `string` · required · default: — — The accessible name of the site navigation, which is also the visible word a screen reader announces before the list. It is required rather than defaulted because it is a word a reader hears, and a Block that ships no copy ships no reader-facing copy either. A header that defaulted this would put its own name on every consumer's site navigation, and "Site" is right for a company site and wrong for a product that has a docs section it wants called something else.
+**`productsLabel`** `string` · optional · default: — — The accessible name of the product switcher. Required whenever `products` is passed, for the same reason `navLabel` is: it is a word a reader hears, and a Block that ships no copy ships none of those either. Omit it and the switcher takes the site navigation's name, which is right when the two are the same set of places and wrong when they are not.
+**`actions`** `ReactNode` · optional · default: — — A slot for the controls a product owns on the right: an account menu, a sign in link, a mode toggle, a theme picker. A slot rather than a prop, because every one of those is application state and none of them is a fact a header can be told.
+**`sticky`** `boolean` · optional · default: — — Keeps the header at the top of the viewport as the page scrolls. Off by default, because a sticky header is a decision about a page rather than about a header, and a header that is sticky on a page with no scroll costs the reader a strip of their viewport.
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Component. Changing a Prism-owned visual property from here is prohibited.
+**`label`** `string` · required · default: — — The text of the link.
+**`href`** `string` · required · default: — — Where the link goes.
+**`current`** `boolean` · optional · default: — — Marks this link as the page the reader is on. Set it on the one link whose destination is the current route; leave it off every other link.
+**`newTab`** `boolean` · optional · default: — — Opens the destination in a new browsing context, which defaults the link relationship to `noopener noreferrer`. Prism does not decide what counts as external: a cross-origin destination is not by itself a reason to open a tab.
+
+## Composition
+
+**`exports`** `SiteHeader` — the public runtime names this Block promises
+**`source`** `packages/ui/src/blocks/site-header/index.tsx` — the file this Block is defined in
+**`dependencies`** `ProductMark, ProductSwitcher` — the public Prism exports this item composes