@krizaka/ui 3.22.0 → 3.23.0

package/registry/settings-layout.json

@@ -2,8 +2,8 @@
   "name": "settings-layout",
   "type": "primitive",
   "title": "Settings layout",
-  "summary": "Settings: the sections on the side (a row of chips that scrolls on a phone) and the current section's forms, each a titled card with its own save.",
-  "description": "Settings: the sections on the side (a row of chips that scrolls on a phone) and the current section's forms, each a titled card with its own save.",
+  "summary": "Settings: the sections on the side (a row of chips that scrolls on a phone) and the current section's forms, as titled cards with their own save or, flat, as hairline-divided rows (`SettingsRow`).",
+  "description": "Settings: the sections on the side (a row of chips that scrolls on a phone) and the current section's forms, as titled cards with their own save or, flat, as hairline-divided rows (`SettingsRow`).",
   "status": "beta",
   "deprecated": null,
   "category": "layouts",
@@ -36,6 +36,8 @@
     }
   ],
   "bestPractices": [
+    "Prefer `variant=\"flat\"` and `SettingsRow` for a product's settings: a label and its help on the left, the control on the right, no card.",
+    "Keep support-only facts (an account id) in a last `Advanced` section, small and mono, never in the first screen.",
     "One save per section, at its foot: a change never waits for another.",
     "Sections as pages (`/settings/billing`) or as anchors of one long page (`#billing`).",
     "Say in the description what the section changes for the user."
@@ -54,7 +56,7 @@
   ],
   "web": {
     "entry": "@krizaka/ui/settings-layout",
-    "import": "import { SettingsLayout, SettingsSection } from \"@krizaka/ui/settings-layout\";",
+    "import": "import { SettingsLayout, SettingsSection, SettingsRow } from \"@krizaka/ui/settings-layout\";",
     "props": [
       {
         "component": "SettingsLayout",
@@ -94,12 +96,46 @@
             "default": null,
             "description": "The screen's title (`Settings`).",
             "required": false
+          },
+          {
+            "name": "variant",
+            "type": "\"flat\" | \"card\"",
+            "default": "card",
+            "description": "`card` (each form a titled card) or `flat` (one calm column of at most 45rem, rows divided by hairlines).",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "SettingsRow",
+        "description": "One setting: its label and help on the left, its control or value on the right. Put rows in a flat `SettingsSection`.",
+        "props": [
+          {
+            "name": "label",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What the setting is (`Username`).",
+            "required": true
+          },
+          {
+            "name": "description",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The help text under it, one sentence.",
+            "required": false
+          },
+          {
+            "name": "htmlFor",
+            "type": "string",
+            "default": null,
+            "description": "The id of the control, so the label names it (a `<label htmlFor>`). Leave out for a plain value.",
+            "required": false
           }
         ]
       },
       {
         "component": "SettingsSection",
-        "description": "A group of settings: a titled card with its fields and its own save.",
+        "description": "A group of settings: a titled card with its fields and its own save, or flat rows under a title.",
         "props": [
           {
             "name": "title",
@@ -121,6 +157,13 @@
             "default": null,
             "description": "At the foot: the section's own save (a Button), a note.",
             "required": false
+          },
+          {
+            "name": "variant",
+            "type": "\"flat\" | \"card\"",
+            "default": "card",
+            "description": "`card` (a titled card) or `flat` (no card: a title, then hairline-divided `SettingsRow`s).",
+            "required": false
           }
         ]
       }
@@ -137,6 +180,17 @@
         "module": "@krizaka/ui/registry/examples/settings-layout/account",
         "code": "import { Button } from \"@krizaka/ui/button\";\nimport { Field, Input, Select } from \"@krizaka/ui/field\";\nimport { SettingsLayout, SettingsSection } from \"@krizaka/ui/settings-layout\";\nimport { Switch } from \"@krizaka/ui/switch\";\n\nconst NAV = [\n  { id: \"profile\", label: \"Profile\", href: \"#profile\", current: true },\n  { id: \"notifications\", label: \"Notifications\", href: \"#notifications\" },\n  { id: \"payouts\", label: \"Payouts\", href: \"#payouts\" },\n  { id: \"security\", label: \"Security\", href: \"#security\" },\n];\n\n// TEMPLATE — account settings: the sections on the left (a row of chips that scrolls on a phone), each form a titled\n// card with its own save, so a change in one never waits for another.\nexport default function SettingsLayoutAccount() {\n  return (\n    <SettingsLayout className=\"w-full\" title=\"Settings\" description=\"Your profile, what we tell you and how you are paid.\" nav={NAV} navLabel=\"Settings sections\">\n      <SettingsSection\n        id=\"profile\"\n        title=\"Profile\"\n        description=\"What your fans see.\"\n        footer={<Button size=\"sm\" variant=\"primary\" shape=\"cut\">Save the profile</Button>}\n      >\n        <Field.Root>\n          <Field.Label htmlFor=\"settings-name\">Display name</Field.Label>\n          <Input id=\"settings-name\" defaultValue=\"Elena Varga\" />\n        </Field.Root>\n        <Field.Root>\n          <Field.Label htmlFor=\"settings-language\">Language</Field.Label>\n          <Select id=\"settings-language\" defaultValue=\"fr\">\n            <option value=\"en\">English</option>\n            <option value=\"fr\">Français</option>\n          </Select>\n        </Field.Root>\n      </SettingsSection>\n      <SettingsSection id=\"notifications\" title=\"Notifications\" description=\"Only what you ask for.\">\n        {[\n          { id: \"unlock\", label: \"A fan unlocks a video\", on: true },\n          { id: \"auction\", label: \"An auction ends\", on: true },\n          { id: \"weekly\", label: \"Weekly summary by email\", on: false },\n        ].map((n) => (\n          <div key={n.id} className=\"flex items-center justify-between gap-4 text-sm text-fg\">\n            <span id={`notify-${n.id}`}>{n.label}</span>\n            <Switch aria-labelledby={`notify-${n.id}`} defaultChecked={n.on} />\n          </div>\n        ))}\n      </SettingsSection>\n    </SettingsLayout>\n  );\n}\n"
       },
+      {
+        "name": "flat",
+        "title": "Calm settings",
+        "description": "The flat variant: one column of at most 45rem, each setting a row (label and help left, control right) divided by hairlines.",
+        "template": true,
+        "purpose": "operate",
+        "why": "A person scans the settings, finds the one to change and changes it in place, without cards competing for attention.",
+        "path": "examples/settings-layout/flat.tsx",
+        "module": "@krizaka/ui/registry/examples/settings-layout/flat",
+        "code": "import { Badge } from \"@krizaka/ui/badge\";\nimport { Button } from \"@krizaka/ui/button\";\nimport { Input } from \"@krizaka/ui/field\";\nimport { SettingsLayout, SettingsRow, SettingsSection } from \"@krizaka/ui/settings-layout\";\n\nconst NAV = [\n  { id: \"account\", label: \"Account\", href: \"/settings/account\", current: true },\n  { id: \"appearance\", label: \"Appearance\", href: \"/settings/appearance\" },\n  { id: \"integrations\", label: \"Integrations\", href: \"/settings/integrations\" },\n];\n\n// TEMPLATE — calm settings: sections on the left, one column of rows (label and help left, control right) divided by hairlines.\nexport default function SettingsLayoutFlat() {\n  return (\n    <SettingsLayout className=\"w-full\" variant=\"flat\" title=\"Settings\" nav={NAV} navLabel=\"Settings sections\">\n      <SettingsSection variant=\"flat\" id=\"account\" title=\"Account\" description=\"Who you are in this workspace.\">\n        <SettingsRow label=\"Username\" description=\"Shown to your team.\" htmlFor=\"flat-username\">\n          <Input id=\"flat-username\" defaultValue=\"oussama\" className=\"w-56\" />\n        </SettingsRow>\n        <SettingsRow label=\"Email\">oussama@krizaka.com</SettingsRow>\n        <SettingsRow label=\"Role\"><Badge>Admin</Badge></SettingsRow>\n      </SettingsSection>\n      <SettingsSection variant=\"flat\" title=\"Danger zone\">\n        <SettingsRow label=\"Sign out everywhere\" description=\"Ends every session on every device.\">\n          <Button size=\"sm\" variant=\"secondary\">Sign out</Button>\n        </SettingsRow>\n      </SettingsSection>\n    </SettingsLayout>\n  );\n}\n"
+      },
       {
         "name": "sections",
         "title": "One section per page",
@@ -151,19 +205,19 @@
   "files": [
     {
       "path": "meta.ts",
-      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"action-sheet\"\n  | \"activity-feed\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"chat\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"comparison-table\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"document-viewer\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"force-update-screen\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"genui\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"maintenance-screen\"\n  | \"map\"\n  | \"markdown\"\n  | \"meta-row\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-grid\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"splash-handoff\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"update-prompt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n *   component that answers there, when one does.\n */\nexport type Absence =\n  | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n  | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n  readonly web?: Absence;\n  readonly native?: Absence;\n  readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: string;\n    });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n  readonly parity: Parity;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"action-sheet\"\n  | \"activity-feed\"\n  | \"alert\"\n  | \"app-header\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"captcha\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"chat\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"comparison-table\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"docs-nav\"\n  | \"document-viewer\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"force-update-screen\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"genui\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"maintenance-screen\"\n  | \"map\"\n  | \"markdown\"\n  | \"meta-row\"\n  | \"waveform\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-grid\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"rail-nav\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"splash-handoff\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"update-prompt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n *   component that answers there, when one does.\n */\nexport type Absence =\n  | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n  | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n  readonly web?: Absence;\n  readonly native?: Absence;\n  readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: string;\n    });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n  readonly parity: Parity;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
     },
     {
       "path": "settings-layout/index.ts",
-      "content": "/** @krizaka/ui/settings-layout — `SettingsLayout` and `SettingsSection`: sections on the side, forms as titled cards. Server-safe. */\nexport { SettingsLayout, settingsLayout, type SettingsLayoutProps, type SettingsNavItem, SettingsSection, type SettingsSectionProps } from \"./settings-layout\";\n"
+      "content": "/** @krizaka/ui/settings-layout — `SettingsLayout`, `SettingsSection` and `SettingsRow`: sections on the side, forms as titled cards or flat rows. Server-safe. */\nexport { SettingsLayout, settingsLayout, type SettingsLayoutProps, type SettingsNavItem, SettingsRow, type SettingsRowProps, SettingsSection, type SettingsSectionProps } from \"./settings-layout\";\n"
     },
     {
       "path": "settings-layout/meta.ts",
-      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Settings layout\",\n  summary: \"Settings: the sections on the side (a row of chips that scrolls on a phone) and the current section's forms, each a titled card with its own save.\",\n  status: \"beta\",\n  category: \"layouts\",\n  platforms: \"web\",\n  parity: { native: { status: \"gap\", issue: \"krizaka/krizaka-ui#246\", reason: \"orazaka-mobile-client hand-rolls its settings rows and groups (src/ui/SettingsRow.tsx).\" }, desktop: \"web\" },\n  whenToUse: [\"Account, workspace and administration settings.\", \"Any long form that splits into independent groups.\"],\n  whenNotToUse: [\n    { when: \"For a step-by-step setup the user follows once.\", use: \"stepper\" },\n    { when: \"For one small form.\", use: \"field\" },\n  ],\n  bestPractices: [\"One save per section, at its foot: a change never waits for another.\", \"Sections as pages (`/settings/billing`) or as anchors of one long page (`#billing`).\", \"Say in the description what the section changes for the user.\"],\n  accessibility: {\n    keyboard: [],\n    notes: [\"The sections are a `nav` named by `navLabel`; the current one has `aria-current` (page or location).\", \"Each section is a `section` named by its `h2`.\"],\n  },\n  related: [\"field\", \"switch\", \"app-shell\"],\n  web: {\n    imports: [\"SettingsLayout\", \"SettingsSection\"],\n    examples: [\n      { name: \"account\", title: \"Account settings\", description: \"Profile and notifications, each with its own save; the sections as chips on a phone.\", template: true, purpose: \"operate\", why: \"A person changes one setting at a time, saves it at once and knows where each lives.\" },\n      { name: \"sections\", title: \"One section per page\", description: \"A workspace's settings, the current section marked.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Settings layout\",\n  summary: \"Settings: the sections on the side (a row of chips that scrolls on a phone) and the current section's forms, as titled cards with their own save or, flat, as hairline-divided rows (`SettingsRow`).\",\n  status: \"beta\",\n  category: \"layouts\",\n  platforms: \"web\",\n  parity: { native: { status: \"gap\", issue: \"krizaka/krizaka-ui#246\", reason: \"orazaka-mobile-client hand-rolls its settings rows and groups (src/ui/SettingsRow.tsx).\" }, desktop: \"web\" },\n  whenToUse: [\"Account, workspace and administration settings.\", \"Any long form that splits into independent groups.\"],\n  whenNotToUse: [\n    { when: \"For a step-by-step setup the user follows once.\", use: \"stepper\" },\n    { when: \"For one small form.\", use: \"field\" },\n  ],\n  bestPractices: [\"Prefer `variant=\\\"flat\\\"` and `SettingsRow` for a product's settings: a label and its help on the left, the control on the right, no card.\", \"Keep support-only facts (an account id) in a last `Advanced` section, small and mono, never in the first screen.\", \"One save per section, at its foot: a change never waits for another.\", \"Sections as pages (`/settings/billing`) or as anchors of one long page (`#billing`).\", \"Say in the description what the section changes for the user.\"],\n  accessibility: {\n    keyboard: [],\n    notes: [\"The sections are a `nav` named by `navLabel`; the current one has `aria-current` (page or location).\", \"Each section is a `section` named by its `h2`.\"],\n  },\n  related: [\"field\", \"switch\", \"app-shell\"],\n  web: {\n    imports: [\"SettingsLayout\", \"SettingsSection\", \"SettingsRow\"],\n    examples: [\n      { name: \"account\", title: \"Account settings\", description: \"Profile and notifications, each with its own save; the sections as chips on a phone.\", template: true, purpose: \"operate\", why: \"A person changes one setting at a time, saves it at once and knows where each lives.\" },\n      { name: \"flat\", title: \"Calm settings\", description: \"The flat variant: one column of at most 45rem, each setting a row (label and help left, control right) divided by hairlines.\", template: true, purpose: \"operate\", why: \"A person scans the settings, finds the one to change and changes it in place, without cards competing for attention.\" },\n      { name: \"sections\", title: \"One section per page\", description: \"A workspace's settings, the current section marked.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
     },
     {
       "path": "settings-layout/settings-layout.tsx",
-      "content": "// Server-safe. Settings, read from the products' account and administration screens: a list of sections on the left\n// (a row of chips that scrolls on a phone), the current section's forms on the right, each form a titled card with its\n// own save at the foot. The sections are links (one page each) or anchors (one long page).\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nexport const settingsLayout = tv({\n  slots: {\n    root: \"flex w-full flex-col gap-6\",\n    head: \"flex flex-col gap-1\",\n    title: \"font-display text-2xl font-extrabold tracking-tight text-fg\",\n    description: \"max-w-2xl text-sm text-fg-secondary\",\n    columns: \"grid grid-cols-1 gap-6 lg:grid-cols-[13rem_minmax(0,1fr)] lg:gap-10\",\n    nav: \"-mx-4 overflow-x-auto overflow-y-hidden px-4 py-1 -my-1 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden lg:mx-0 lg:overflow-visible lg:px-0 lg:py-0 lg:my-0\",\n    navList: \"flex w-max gap-2 lg:sticky lg:top-20 lg:w-auto lg:flex-col lg:gap-0.5\",\n    navLink:\n      \"flex h-9 items-center gap-2.5 whitespace-nowrap rounded-full border border-border-default bg-surface-1 px-3.5 text-sm font-medium text-fg-secondary no-underline \" +\n      \"hover:text-fg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring aria-[current]:border-accent aria-[current]:text-fg \" +\n      \"lg:rounded-lg lg:border-transparent lg:bg-transparent lg:px-3 lg:hover:bg-surface-2 lg:aria-[current]:bg-accent-soft [&>svg]:h-4 [&>svg]:w-4\",\n    content: \"flex min-w-0 flex-col gap-6\",\n    section: \"rounded-xl border border-border-default bg-surface-1\",\n    sectionHead: \"flex flex-col gap-1 px-5 pt-5\",\n    sectionTitle: \"text-base font-bold text-fg\",\n    sectionDescription: \"text-sm text-fg-secondary\",\n    sectionBody: \"flex flex-col gap-4 px-5 py-5\",\n    sectionFooter: \"flex flex-wrap items-center justify-end gap-2 border-t border-border-subtle bg-surface-2/40 px-5 py-3 rounded-b-xl\",\n  },\n});\nconst s = settingsLayout();\n\nexport interface SettingsNavItem {\n  /** Its id (the anchor of a section on one long page). */\n  id: string;\n  /** Its words. */\n  label: string;\n  /** Where it leads: a page (`/settings/billing`) or an anchor (`#billing`). */\n  href: string;\n  /** Its icon (a signature icon). */\n  icon?: React.ReactNode;\n  /** The section shown now: `aria-current`. */\n  current?: boolean;\n}\n\nexport type SettingsLayoutProps = Omit<React.ComponentProps<\"div\">, \"title\"> & {\n  /** The screen's title (`Settings`). */\n  title?: React.ReactNode;\n  /** One sentence under it. */\n  description?: React.ReactNode;\n  /** The sections. */\n  nav: readonly SettingsNavItem[];\n  /** The navigation's accessible name (`Settings sections`). */\n  navLabel: string;\n  /** The app's link component for the sections (Next's `Link`); an `<a>` otherwise. */\n  linkAs?: React.ElementType;\n  /** The current section's forms (`SettingsSection`). */\n  children: React.ReactNode;\n};\n\n/** A settings screen: sections on the left (chips on a phone), forms on the right. */\nexport function SettingsLayout({ title, description, nav, navLabel, linkAs: Link = \"a\", className, children, ...props }: SettingsLayoutProps) {\n  return (\n    <div className={s.root({ className })} {...props}>\n      {(title || description) && (\n        <div className={s.head()}>\n          {title && <h1 className={s.title()}>{title}</h1>}\n          {description && <p className={s.description()}>{description}</p>}\n        </div>\n      )}\n      <div className={s.columns()}>\n        <nav aria-label={navLabel} className={s.nav()}>\n          <ul className={s.navList()}>\n            {nav.map((item) => (\n              <li key={item.id}>\n                <Link href={item.href} className={s.navLink()} aria-current={item.current ? (item.href.startsWith(\"#\") ? \"location\" : \"page\") : undefined}>\n                  {item.icon}\n                  {item.label}\n                </Link>\n              </li>\n            ))}\n          </ul>\n        </nav>\n        <div className={s.content()}>{children}</div>\n      </div>\n    </div>\n  );\n}\n\nexport type SettingsSectionProps = Omit<React.ComponentProps<\"section\">, \"title\"> & {\n  /** The section's title: it names the region (and is its anchor's target when `id` is set). */\n  title: React.ReactNode;\n  /** What these settings change, in one sentence. */\n  description?: React.ReactNode;\n  /** At the foot: the section's own save (a Button), a note. */\n  footer?: React.ReactNode;\n  /** The fields. */\n  children: React.ReactNode;\n};\n\n/** A group of settings: a titled card with its fields and its own save. */\nexport function SettingsSection({ title, description, footer, id, className, children, ...props }: SettingsSectionProps) {\n  const auto = React.useId();\n  const titleId = `${id ?? auto}-title`;\n  return (\n    <section id={id} aria-labelledby={titleId} className={s.section({ className })} {...props}>\n      <div className={s.sectionHead()}>\n        <h2 id={titleId} className={s.sectionTitle()}>\n          {title}\n        </h2>\n        {description && <p className={s.sectionDescription()}>{description}</p>}\n      </div>\n      <div className={s.sectionBody()}>{children}</div>\n      {footer && <div className={s.sectionFooter()}>{footer}</div>}\n    </section>\n  );\n}\n"
+      "content": "// Server-safe. Settings, read from the products' account and administration screens: a list of sections on the left\n// (a row of chips that scrolls on a phone), the current section's forms on the right, each form a titled card with its\n// own save at the foot. The sections are links (one page each) or anchors (one long page).\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nexport const settingsLayout = tv({\n  slots: {\n    root: \"flex w-full flex-col gap-6\",\n    head: \"flex flex-col gap-1\",\n    title: \"font-display text-2xl font-extrabold tracking-tight text-fg\",\n    description: \"max-w-2xl text-sm text-fg-secondary\",\n    columns: \"grid grid-cols-1 gap-6 lg:grid-cols-[13rem_minmax(0,1fr)] lg:gap-10\",\n    nav: \"-mx-4 overflow-x-auto overflow-y-hidden px-4 py-1 -my-1 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden lg:mx-0 lg:overflow-visible lg:px-0 lg:py-0 lg:my-0\",\n    navList: \"flex w-max gap-2 lg:sticky lg:top-20 lg:w-auto lg:flex-col lg:gap-0.5\",\n    navLink:\n      \"flex h-9 items-center gap-2.5 whitespace-nowrap rounded-full border border-border-default bg-surface-1 px-3.5 text-sm font-medium text-fg-secondary no-underline \" +\n      \"hover:text-fg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring aria-[current]:border-accent aria-[current]:text-fg \" +\n      \"lg:rounded-lg lg:border-transparent lg:bg-transparent lg:px-3 lg:hover:bg-surface-2 lg:aria-[current]:bg-accent-soft [&>svg]:h-4 [&>svg]:w-4\",\n    content: \"flex min-w-0 flex-col gap-6\",\n    section: \"rounded-xl border border-border-default bg-surface-1\",\n    sectionHead: \"flex flex-col gap-1 px-5 pt-5\",\n    sectionTitle: \"text-base font-bold text-fg\",\n    sectionDescription: \"text-sm text-fg-secondary\",\n    sectionBody: \"flex flex-col gap-4 px-5 py-5\",\n    sectionFooter: \"flex flex-wrap items-center justify-end gap-2 border-t border-border-subtle bg-surface-2/40 px-5 py-3 rounded-b-xl\",\n    // The flat look: no card, hairline-divided rows (Linear / Vercel / GitHub settings).\n    rows: \"flex flex-col divide-y divide-border-subtle border-y border-border-subtle\",\n    row: \"flex flex-col gap-2 py-4 sm:flex-row sm:items-center sm:justify-between sm:gap-6\",\n    rowText: \"flex min-w-0 flex-col gap-0.5\",\n    rowLabel: \"text-sm font-medium text-fg\",\n    rowDescription: \"text-sm text-fg-secondary\",\n    rowControl: \"flex min-w-0 shrink-0 items-center gap-2 text-sm text-fg sm:max-w-[60%] sm:justify-end\",\n  },\n  variants: {\n    variant: {\n      card: {},\n      flat: {\n        content: \"max-w-[45rem] gap-10\",\n        section: \"rounded-none border-0 bg-transparent\",\n        sectionHead: \"gap-0.5 px-0 pb-3 pt-0\",\n        sectionBody: \"gap-0 px-0 py-0\",\n        sectionFooter: \"justify-start border-t-0 bg-transparent px-0 pb-0 pt-4\",\n      },\n    },\n  },\n  defaultVariants: { variant: \"card\" },\n});\n\nexport interface SettingsNavItem {\n  /** Its id (the anchor of a section on one long page). */\n  id: string;\n  /** Its words. */\n  label: string;\n  /** Where it leads: a page (`/settings/billing`) or an anchor (`#billing`). */\n  href: string;\n  /** Its icon (a signature icon). */\n  icon?: React.ReactNode;\n  /** The section shown now: `aria-current`. */\n  current?: boolean;\n}\n\nexport type SettingsLayoutProps = Omit<React.ComponentProps<\"div\">, \"title\"> & {\n  /** The screen's title (`Settings`). */\n  title?: React.ReactNode;\n  /** One sentence under it. */\n  description?: React.ReactNode;\n  /** The sections. */\n  nav: readonly SettingsNavItem[];\n  /** The navigation's accessible name (`Settings sections`). */\n  navLabel: string;\n  /** The app's link component for the sections (Next's `Link`); an `<a>` otherwise. */\n  linkAs?: React.ElementType;\n  /**\n   * `card` (each form a titled card) or `flat` (one calm column of at most 45rem, rows divided by hairlines).\n   * @default \"card\"\n   */\n  variant?: \"card\" | \"flat\";\n  /** The current section's forms (`SettingsSection`). */\n  children: React.ReactNode;\n};\n\n/** A settings screen: sections on the left (chips on a phone), forms on the right. */\nexport function SettingsLayout({ title, description, nav, navLabel, linkAs: Link = \"a\", variant = \"card\", className, children, ...props }: SettingsLayoutProps) {\n  const s = settingsLayout({ variant });\n  return (\n    <div className={s.root({ className })} {...props}>\n      {(title || description) && (\n        <div className={s.head()}>\n          {title && <h1 className={s.title()}>{title}</h1>}\n          {description && <p className={s.description()}>{description}</p>}\n        </div>\n      )}\n      <div className={s.columns()}>\n        <nav aria-label={navLabel} className={s.nav()}>\n          <ul className={s.navList()}>\n            {nav.map((item) => (\n              <li key={item.id}>\n                <Link href={item.href} className={s.navLink()} aria-current={item.current ? (item.href.startsWith(\"#\") ? \"location\" : \"page\") : undefined}>\n                  {item.icon}\n                  {item.label}\n                </Link>\n              </li>\n            ))}\n          </ul>\n        </nav>\n        <div className={s.content()}>{children}</div>\n      </div>\n    </div>\n  );\n}\n\nexport type SettingsSectionProps = Omit<React.ComponentProps<\"section\">, \"title\"> & {\n  /** The section's title: it names the region (and is its anchor's target when `id` is set). */\n  title: React.ReactNode;\n  /** What these settings change, in one sentence. */\n  description?: React.ReactNode;\n  /** At the foot: the section's own save (a Button), a note. */\n  footer?: React.ReactNode;\n  /**\n   * `card` (a titled card) or `flat` (no card: a title, then hairline-divided `SettingsRow`s).\n   * @default \"card\"\n   */\n  variant?: \"card\" | \"flat\";\n  /** The fields (or, flat, the `SettingsRow`s). */\n  children: React.ReactNode;\n};\n\n/** A group of settings: a titled card with its fields and its own save, or flat rows under a title. */\nexport function SettingsSection({ title, description, footer, variant = \"card\", id, className, children, ...props }: SettingsSectionProps) {\n  const s = settingsLayout({ variant });\n  const auto = React.useId();\n  const titleId = `${id ?? auto}-title`;\n  return (\n    <section id={id} aria-labelledby={titleId} className={s.section({ className })} {...props}>\n      <div className={s.sectionHead()}>\n        <h2 id={titleId} className={s.sectionTitle()}>\n          {title}\n        </h2>\n        {description && <p className={s.sectionDescription()}>{description}</p>}\n      </div>\n      <div className={variant === \"flat\" ? s.rows() : s.sectionBody()} data-settings-rows={variant === \"flat\" ? \"\" : undefined}>\n        {children}\n      </div>\n      {footer && <div className={s.sectionFooter()}>{footer}</div>}\n    </section>\n  );\n}\n\nexport type SettingsRowProps = Omit<React.ComponentProps<\"div\">, \"title\"> & {\n  /** What the setting is (`Username`). */\n  label: React.ReactNode;\n  /** The help text under it, one sentence. */\n  description?: React.ReactNode;\n  /** The id of the control, so the label names it (a `<label htmlFor>`). Leave out for a plain value. */\n  htmlFor?: string;\n  /** The control or the value, on the right (stacked under the label on a phone). */\n  children?: React.ReactNode;\n};\n\n/** One setting: its label and help on the left, its control or value on the right. Put rows in a flat `SettingsSection`. */\nexport function SettingsRow({ label, description, htmlFor, className, children, ...props }: SettingsRowProps) {\n  const s = settingsLayout();\n  const Label = htmlFor ? \"label\" : \"span\";\n  return (\n    <div className={s.row({ className })} {...props}>\n      <div className={s.rowText()}>\n        <Label className={s.rowLabel()} {...(htmlFor ? { htmlFor } : {})}>\n          {label}\n        </Label>\n        {description && <span className={s.rowDescription()}>{description}</span>}\n      </div>\n      {children !== undefined && <div className={s.rowControl()}>{children}</div>}\n    </div>\n  );\n}\n"
     }
   ],
   "dependencies": [
@@ -213,12 +267,46 @@
           "default": null,
           "description": "The screen's title (`Settings`).",
           "required": false
+        },
+        {
+          "name": "variant",
+          "type": "\"flat\" | \"card\"",
+          "default": "card",
+          "description": "`card` (each form a titled card) or `flat` (one calm column of at most 45rem, rows divided by hairlines).",
+          "required": false
+        }
+      ]
+    },
+    {
+      "component": "SettingsRow",
+      "description": "One setting: its label and help on the left, its control or value on the right. Put rows in a flat `SettingsSection`.",
+      "props": [
+        {
+          "name": "label",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What the setting is (`Username`).",
+          "required": true
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "default": null,
+          "description": "The help text under it, one sentence.",
+          "required": false
+        },
+        {
+          "name": "htmlFor",
+          "type": "string",
+          "default": null,
+          "description": "The id of the control, so the label names it (a `<label htmlFor>`). Leave out for a plain value.",
+          "required": false
         }
       ]
     },
     {
       "component": "SettingsSection",
-      "description": "A group of settings: a titled card with its fields and its own save.",
+      "description": "A group of settings: a titled card with its fields and its own save, or flat rows under a title.",
       "props": [
         {
           "name": "title",
@@ -240,6 +328,13 @@
           "default": null,
           "description": "At the foot: the section's own save (a Button), a note.",
           "required": false
+        },
+        {
+          "name": "variant",
+          "type": "\"flat\" | \"card\"",
+          "default": "card",
+          "description": "`card` (a titled card) or `flat` (no card: a title, then hairline-divided `SettingsRow`s).",
+          "required": false
         }
       ]
     }

package/registry/showcase.json

@@ -307,7 +307,7 @@
   "files": [
     {
       "path": "meta.ts",
-      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"action-sheet\"\n  | \"activity-feed\"\n  | \"alert\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"chat\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"comparison-table\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"document-viewer\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"force-update-screen\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"genui\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"maintenance-screen\"\n  | \"map\"\n  | \"markdown\"\n  | \"meta-row\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-grid\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"splash-handoff\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"update-prompt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n *   component that answers there, when one does.\n */\nexport type Absence =\n  | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n  | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n  readonly web?: Absence;\n  readonly native?: Absence;\n  readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: string;\n    });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n  readonly parity: Parity;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
+      "content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n  | \"achievement\"\n  | \"action-bar\"\n  | \"action-sheet\"\n  | \"activity-feed\"\n  | \"alert\"\n  | \"app-header\"\n  | \"app-shell\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"auth-layout\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"captcha\"\n  | \"card\"\n  | \"card-grid\"\n  | \"catalogue-page\"\n  | \"changelog-page\"\n  | \"chat\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"choice-grid\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"comparison-table\"\n  | \"command\"\n  | \"component-page\"\n  | \"confirm-button\"\n  | \"contact-page\"\n  | \"continue-prompt\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"dashboard-layout\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"description-list\"\n  | \"detail-layout\"\n  | \"dialog\"\n  | \"docs-article-page\"\n  | \"docs-hub-page\"\n  | \"docs-layout\"\n  | \"docs-nav\"\n  | \"document-viewer\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"error-page\"\n  | \"fab\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"force-update-screen\"\n  | \"form\"\n  | \"gallery-page\"\n  | \"genui\"\n  | \"glow-card\"\n  | \"goal-gauge\"\n  | \"header\"\n  | \"how-it-works-page\"\n  | \"image-cropper\"\n  | \"image-viewer\"\n  | \"iso\"\n  | \"kanban\"\n  | \"kbd\"\n  | \"landing-page\"\n  | \"landscape\"\n  | \"legal-page\"\n  | \"link-card\"\n  | \"list\"\n  | \"loader\"\n  | \"longform-page\"\n  | \"maintenance-screen\"\n  | \"map\"\n  | \"markdown\"\n  | \"meta-row\"\n  | \"waveform\"\n  | \"marketing-layout\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"match-dialog\"\n  | \"media-capture\"\n  | \"media-grid\"\n  | \"media-picker\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"onboarding\"\n  | \"otp-input\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"permission-prompt\"\n  | \"photo-grid\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"pricing-page\"\n  | \"product-page\"\n  | \"profile-card\"\n  | \"progress\"\n  | \"promise-card\"\n  | \"pull-to-refresh\"\n  | \"radio-group\"\n  | \"rail-nav\"\n  | \"recipes\"\n  | \"screen\"\n  | \"scroll-stage\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"settings-layout\"\n  | \"showcase\"\n  | \"step-showcase\"\n  | \"site-footer\"\n  | \"sites\"\n  | \"skeleton\"\n  | \"skip-link\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"splash-handoff\"\n  | \"split-view\"\n  | \"stage-banner\"\n  | \"stat\"\n  | \"status-page\"\n  | \"step-progress\"\n  | \"stepper\"\n  | \"swipe-deck\"\n  | \"swipeable-row\"\n  | \"switch\"\n  | \"tab-bar\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"tag-selector\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"tree-view\"\n  | \"txt\"\n  | \"update-prompt\"\n  | \"verified-badge\"\n  | \"vertical-video\"\n  | \"video-player\"\n  | \"video-trimmer\"\n  | \"virtual\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n *   component that answers there, when one does.\n */\nexport type Absence =\n  | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n  | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n  readonly web?: Absence;\n  readonly native?: Absence;\n  readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n  /** The version that deprecated it (`3.6.0`). */\n  readonly since: string;\n  /** The major that removes it (`4.0.0`). */\n  readonly removedIn: string;\n  /** What replaces it, when a component does. */\n  readonly use?: ComponentName;\n  /** Why it goes: no product uses it, no planned work needs it. */\n  readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n  convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n  explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n  show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n  act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n  operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n  converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n  recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n  /** The file name, kebab-case (`primary`, `icon-button`). */\n  readonly name: string;\n  /** A short title (`Primary`, `Icon button`). */\n  readonly title: string;\n  /** One or two sentences: when this variant is the right one. */\n  readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n  | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n  | (ExampleBase & {\n      /**\n       * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n       * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n       */\n      readonly template: true;\n      /** The intent that groups it: why you need this block. */\n      readonly purpose: TemplatePurpose;\n      /** Why this layout: the user goal it serves, in one sentence. */\n      readonly why: string;\n    });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n  /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n  readonly imports: readonly string[];\n  /** The examples, in reading order; the first one is the component's preview. */\n  readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  /** Required for, and only for, a `deprecated` component. */\n  readonly deprecated?: Deprecation;\n  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\n  /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n  readonly parity: Parity;\n  /** When to reach for it: concrete situations, one per item. */\n  readonly whenToUse: readonly string[];\n  /** When not to — and what to use instead (`use`), when another component is the answer. */\n  readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n  /** How to use it well: wording, placement, composition. */\n  readonly bestPractices: readonly string[];\n  readonly accessibility: {\n    /** The keyboard, when it does more than Tab and Enter. */\n    readonly keyboard: readonly KeyboardInteraction[];\n    /** Roles, names and announcements: what the component does, what the app must provide. */\n    readonly notes: readonly string[];\n  };\n  /** The components a reader of this page should know about. */\n  readonly related: readonly ComponentName[];\n  readonly web?: PlatformDocs;\n  readonly native?: NativeDocs;\n}\n"
     },
     {
       "path": "showcase/index.ts",