@krizaka/ui 2.0.0-beta.4 → 2.0.0-beta.6

package/registry/tabs.json

@@ -1,12 +1,126 @@
 {
   "name": "tabs",
   "type": "primitive",
-  "description": "`Tabs.Root/List/Trigger/Content` (variant underline · segmented · pills), `tabs` (the slots). Client (\"use client\").",
+  "title": "Tabs",
+  "summary": "Views of the same page, one at a time: underlined sections, a segmented switch or pills.",
+  "description": "Views of the same page, one at a time: underlined sections, a segmented switch or pills.",
+  "status": "beta",
+  "category": "navigation",
+  "platforms": "web",
+  "whenToUse": [
+    "To split a page into sections the user switches between without leaving it: videos, stories, about.",
+    "`variant=\"segmented\"` for a view switch (grid, list); `pills` for a feed's sections."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "For a filter that narrows a list.",
+      "use": "chip"
+    },
+    {
+      "when": "To go to other pages: use links in the navigation."
+    },
+    {
+      "when": "For a choice in a form.",
+      "use": "radio-group"
+    }
+  ],
+  "bestPractices": [
+    "Short labels of one or two words; the active one should be clear without colour.",
+    "Keep the URL in sync with the active tab when a tab is worth sharing."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Tab",
+        "action": "Moves to the active tab, then into its panel."
+      },
+      {
+        "keys": "Arrow keys / Home / End",
+        "action": "Move between tabs and activate them."
+      }
+    ],
+    "notes": [
+      "Radix Tabs: `tablist`, `tab` with `aria-selected` and `aria-controls`, `tabpanel`; name the list with `aria-label`.",
+      "A disabled tab is skipped."
+    ]
+  },
+  "related": [
+    "chip",
+    "segmented",
+    "radio-group"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/tabs",
+    "import": "import { Tabs } from \"@krizaka/ui/tabs\";",
+    "props": [
+      {
+        "component": "TabsRoot",
+        "description": "`value`/`defaultValue` + `onValueChange`, `orientation` (horizontal by default), `variant` for the list.",
+        "props": [
+          {
+            "name": "variant",
+            "type": "\"underline\" | \"segmented\" | \"pills\"",
+            "default": "underline",
+            "description": "underline (the sections of a page) · segmented (a view switch) · pills (a feed's sections).",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "TabsList",
+        "description": "The tabs. Name it (`aria-label`) when no heading says what it switches.",
+        "props": []
+      }
+    ],
+    "examples": [
+      {
+        "name": "underline",
+        "title": "Underline",
+        "description": "The sections of a page; a disabled tab is skipped.",
+        "path": "examples/tabs/underline.tsx",
+        "module": "@krizaka/ui/registry/examples/tabs/underline",
+        "code": "import { Tabs } from \"@krizaka/ui/tabs\";\n\nexport default function TabsUnderline() {\n  return (\n    <Tabs.Root defaultValue=\"videos\">\n      <Tabs.List aria-label=\"Profile\">\n        <Tabs.Trigger value=\"videos\">Videos</Tabs.Trigger>\n        <Tabs.Trigger value=\"stories\">Stories</Tabs.Trigger>\n        <Tabs.Trigger value=\"collections\">Collections</Tabs.Trigger>\n        <Tabs.Trigger value=\"about\" disabled>\n          About\n        </Tabs.Trigger>\n      </Tabs.List>\n      <Tabs.Content value=\"videos\" className=\"text-sm text-fg-secondary\">\n        Twelve videos, newest first.\n      </Tabs.Content>\n      <Tabs.Content value=\"stories\" className=\"text-sm text-fg-secondary\">\n        Stories of the last 24 hours.\n      </Tabs.Content>\n      <Tabs.Content value=\"collections\" className=\"text-sm text-fg-secondary\">\n        Three public collections.\n      </Tabs.Content>\n      <Tabs.Content value=\"about\" className=\"text-sm text-fg-secondary\">\n        About this channel.\n      </Tabs.Content>\n    </Tabs.Root>\n  );\n}\n"
+      },
+      {
+        "name": "segmented",
+        "title": "Segmented",
+        "description": "A view switch: equal segments in a track.",
+        "path": "examples/tabs/segmented.tsx",
+        "module": "@krizaka/ui/registry/examples/tabs/segmented",
+        "code": "import { Tabs } from \"@krizaka/ui/tabs\";\n\n// A view switch: equal segments in a track, the active one filled.\nexport default function TabsSegmented() {\n  return (\n    <Tabs.Root variant=\"segmented\" defaultValue=\"grid\">\n      <Tabs.List aria-label=\"View\">\n        <Tabs.Trigger value=\"grid\">Grid</Tabs.Trigger>\n        <Tabs.Trigger value=\"list\">List</Tabs.Trigger>\n        <Tabs.Trigger value=\"cinema\">Cinema</Tabs.Trigger>\n      </Tabs.List>\n      <Tabs.Content value=\"grid\" className=\"text-sm text-fg-secondary\">\n        Four columns of cards.\n      </Tabs.Content>\n      <Tabs.Content value=\"list\" className=\"text-sm text-fg-secondary\">\n        One line per video.\n      </Tabs.Content>\n      <Tabs.Content value=\"cinema\" className=\"text-sm text-fg-secondary\">\n        One large player per video.\n      </Tabs.Content>\n    </Tabs.Root>\n  );\n}\n"
+      },
+      {
+        "name": "pills",
+        "title": "Pills",
+        "description": "A feed's sections, scrolling sideways on a phone.",
+        "path": "examples/tabs/pills.tsx",
+        "module": "@krizaka/ui/registry/examples/tabs/pills",
+        "code": "import { Tabs } from \"@krizaka/ui/tabs\";\n\n// A feed's sections: pills that scroll sideways on a phone.\nexport default function TabsPills() {\n  return (\n    <Tabs.Root variant=\"pills\" defaultValue=\"videos\">\n      <Tabs.List aria-label=\"Profile\">\n        <Tabs.Trigger value=\"videos\">Videos</Tabs.Trigger>\n        <Tabs.Trigger value=\"stories\">Stories</Tabs.Trigger>\n        <Tabs.Trigger value=\"collections\">Collections</Tabs.Trigger>\n      </Tabs.List>\n      <Tabs.Content value=\"videos\" className=\"text-sm text-fg-secondary\">\n        Twelve videos, newest first.\n      </Tabs.Content>\n      <Tabs.Content value=\"stories\" className=\"text-sm text-fg-secondary\">\n        Stories of the last 24 hours.\n      </Tabs.Content>\n      <Tabs.Content value=\"collections\" className=\"text-sm text-fg-secondary\">\n        Three public collections.\n      </Tabs.Content>\n    </Tabs.Root>\n  );\n}\n"
+      },
+      {
+        "name": "vertical",
+        "title": "Vertical",
+        "description": "`orientation=\"vertical\"`: the list on the side.",
+        "path": "examples/tabs/vertical.tsx",
+        "module": "@krizaka/ui/registry/examples/tabs/vertical",
+        "code": "import { Tabs } from \"@krizaka/ui/tabs\";\n\n// `orientation=\"vertical\"`: up and down arrows, the list on the side.\nexport default function TabsVertical() {\n  return (\n    <Tabs.Root orientation=\"vertical\" defaultValue=\"videos\">\n      <Tabs.List aria-label=\"Profile\">\n        <Tabs.Trigger value=\"videos\">Videos</Tabs.Trigger>\n        <Tabs.Trigger value=\"stories\">Stories</Tabs.Trigger>\n        <Tabs.Trigger value=\"collections\">Collections</Tabs.Trigger>\n      </Tabs.List>\n      <Tabs.Content value=\"videos\" className=\"text-sm text-fg-secondary\">\n        Twelve videos, newest first.\n      </Tabs.Content>\n      <Tabs.Content value=\"stories\" className=\"text-sm text-fg-secondary\">\n        Stories of the last 24 hours.\n      </Tabs.Content>\n      <Tabs.Content value=\"collections\" className=\"text-sm text-fg-secondary\">\n        Three public collections.\n      </Tabs.Content>\n    </Tabs.Root>\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
   "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 krizaka.com renders as\n// /docs/ui/<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  | \"alert\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"cn\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"kbd\"\n  | \"page-header\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"switch\"\n  | \"tabs\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\";\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"layout\" | \"foundations\";\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 */\nexport interface Example {\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/** 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  /** 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  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\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": "tabs/index.ts",
       "content": "/** @krizaka/ui/tabs — `Tabs.Root/List/Trigger/Content` (variant underline · segmented · pills), `tabs` (the slots). Client (\"use client\"). */\nexport { Tabs, tabs, TabsContent, TabsList, TabsRoot, type TabsRootProps, TabsTrigger, type TabsVariants } from \"./tabs\";\n"
     },
+    {
+      "path": "tabs/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Tabs\",\n  summary: \"Views of the same page, one at a time: underlined sections, a segmented switch or pills.\",\n  status: \"beta\",\n  category: \"navigation\",\n  platforms: \"web\",\n  whenToUse: [\n    \"To split a page into sections the user switches between without leaving it: videos, stories, about.\",\n    \"`variant=\\\"segmented\\\"` for a view switch (grid, list); `pills` for a feed's sections.\",\n  ],\n  whenNotToUse: [\n    { when: \"For a filter that narrows a list.\", use: \"chip\" },\n    { when: \"To go to other pages: use links in the navigation.\" },\n    { when: \"For a choice in a form.\", use: \"radio-group\" },\n  ],\n  bestPractices: [\n    \"Short labels of one or two words; the active one should be clear without colour.\",\n    \"Keep the URL in sync with the active tab when a tab is worth sharing.\",\n  ],\n  accessibility: {\n    keyboard: [\n      { keys: \"Tab\", action: \"Moves to the active tab, then into its panel.\" },\n      { keys: \"Arrow keys / Home / End\", action: \"Move between tabs and activate them.\" },\n    ],\n    notes: [\n      \"Radix Tabs: `tablist`, `tab` with `aria-selected` and `aria-controls`, `tabpanel`; name the list with `aria-label`.\",\n      \"A disabled tab is skipped.\",\n    ],\n  },\n  related: [\"chip\", \"segmented\", \"radio-group\"],\n  web: {\n    imports: [\"Tabs\"],\n    examples: [\n      { name: \"underline\", title: \"Underline\", description: \"The sections of a page; a disabled tab is skipped.\" },\n      { name: \"segmented\", title: \"Segmented\", description: \"A view switch: equal segments in a track.\" },\n      { name: \"pills\", title: \"Pills\", description: \"A feed's sections, scrolling sideways on a phone.\" },\n      { name: \"vertical\", title: \"Vertical\", description: \"`orientation=\\\"vertical\\\"`: the list on the side.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
     {
       "path": "tabs/tabs.tsx",
       "content": "// Client (a context). Radix Tabs does the roles (tablist, tab, tabpanel), the aria-selected / aria-controls wiring,\n// the roving focus (arrows, Home, End) and automatic activation: this file only holds the three looks.\nimport { Tabs as TabsPrimitive } from \"radix-ui\";\nimport * as React from \"react\";\nimport { tv, type VariantProps } from \"tailwind-variants\";\n\nexport const tabs = tv({\n  slots: {\n    root: \"flex gap-4 data-[orientation=horizontal]:flex-col data-[orientation=vertical]:flex-row\",\n    list: \"flex shrink-0 data-[orientation=vertical]:flex-col\",\n    trigger:\n      \"inline-flex shrink-0 select-none items-center justify-center gap-2 whitespace-nowrap font-semibold transition-colors \" +\n      \"focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40\",\n    content: \"kz-fade min-w-0 flex-1 rounded-lg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring\",\n  },\n  variants: {\n    variant: {\n      /* The section of a page: a line under the list, the active tab underlined in the accent. */\n      underline: {\n        list: \"gap-1 border-border-default data-[orientation=horizontal]:border-b data-[orientation=vertical]:border-r\",\n        trigger:\n          \"relative rounded-md px-3 py-2.5 text-sm text-fg-secondary hover:text-fg data-[state=active]:text-fg \" +\n          \"after:absolute after:rounded-full after:bg-transparent data-[state=active]:after:bg-accent \" +\n          \"data-[orientation=horizontal]:after:inset-x-2 data-[orientation=horizontal]:after:-bottom-px data-[orientation=horizontal]:after:h-0.5 \" +\n          \"data-[orientation=vertical]:justify-start data-[orientation=vertical]:after:inset-y-1.5 data-[orientation=vertical]:after:-right-px data-[orientation=vertical]:after:w-0.5\",\n      },\n      /* A view switch: equal segments in a track, the active one filled. */\n      segmented: {\n        list: \"inline-grid auto-cols-fr grid-flow-col gap-1 self-start rounded-xl border border-border-default bg-surface-1 p-1 data-[orientation=vertical]:grid-flow-row\",\n        trigger:\n          \"min-h-8 rounded-lg px-3 py-1.5 text-xs text-fg-secondary hover:bg-surface-2 hover:text-fg \" +\n          \"data-[state=active]:bg-accent data-[state=active]:text-on-accent data-[state=active]:shadow-sm data-[state=active]:hover:bg-accent\",\n      },\n      /* Pills that scroll sideways on a phone: a feed's sections. */\n      pills: {\n        list: \"gap-1.5 overflow-x-auto overscroll-x-contain [scrollbar-width:none] data-[orientation=horizontal]:pb-1\",\n        trigger:\n          \"h-9 rounded-full border border-border-default bg-surface-1 px-4 text-xs text-fg-secondary hover:border-border-strong hover:text-fg \" +\n          \"data-[state=active]:border-accent data-[state=active]:bg-accent-soft data-[state=active]:text-fg\",\n      },\n    },\n  },\n  defaultVariants: { variant: \"underline\" },\n});\n\nexport type TabsVariants = VariantProps<typeof tabs>;\ntype Variant = NonNullable<TabsVariants[\"variant\"]>;\n\nconst VariantContext = React.createContext<Variant>(\"underline\");\n\nexport type TabsRootProps = React.ComponentProps<typeof TabsPrimitive.Root> & {\n  /** underline (the sections of a page) · segmented (a view switch) · pills (a feed's sections). */\n  variant?: TabsVariants[\"variant\"];\n};\n\n/** `value`/`defaultValue` + `onValueChange`, `orientation` (horizontal by default), `variant` for the list. */\nexport function TabsRoot({ variant = \"underline\", className, ...props }: TabsRootProps) {\n  return (\n    <VariantContext.Provider value={variant}>\n      <TabsPrimitive.Root data-variant={variant} className={tabs({ variant }).root({ className })} {...props} />\n    </VariantContext.Provider>\n  );\n}\n\n/** The tabs. Name it (`aria-label`) when no heading says what it switches. */\nexport function TabsList({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.List>) {\n  const variant = React.useContext(VariantContext);\n  return <TabsPrimitive.List data-variant={variant} className={tabs({ variant }).list({ className })} {...props} />;\n}\n\nexport function TabsTrigger({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Trigger>) {\n  const variant = React.useContext(VariantContext);\n  return <TabsPrimitive.Trigger className={tabs({ variant }).trigger({ className })} {...props} />;\n}\n\nexport function TabsContent({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Content>) {\n  return <TabsPrimitive.Content className={tabs().content({ className })} {...props} />;\n}\n\n/** `Tabs.Root/List/Trigger/Content` — `variant` underline · segmented · pills on the root. */\nexport const Tabs = { Root: TabsRoot, List: TabsList, Trigger: TabsTrigger, Content: TabsContent };\n"
@@ -18,8 +132,8 @@
   ],
   "registryDependencies": [],
   "demo": {
-    "path": "demos/tabs.tsx",
-    "content": "import { Tabs } from \"@krizaka/ui/tabs\";\n\nexport default function TabsDemo() {\n  return (\n    <Tabs.Root defaultValue=\"videos\">\n      <Tabs.List aria-label=\"Profile\">\n        <Tabs.Trigger value=\"videos\">Videos</Tabs.Trigger>\n        <Tabs.Trigger value=\"stories\">Stories</Tabs.Trigger>\n        <Tabs.Trigger value=\"collections\">Collections</Tabs.Trigger>\n        <Tabs.Trigger value=\"about\" disabled>\n          About\n        </Tabs.Trigger>\n      </Tabs.List>\n      <Tabs.Content value=\"videos\" className=\"text-sm text-fg-secondary\">\n        Twelve videos, newest first.\n      </Tabs.Content>\n      <Tabs.Content value=\"stories\" className=\"text-sm text-fg-secondary\">\n        Stories of the last 24 hours.\n      </Tabs.Content>\n      <Tabs.Content value=\"collections\" className=\"text-sm text-fg-secondary\">\n        Three public collections.\n      </Tabs.Content>\n      <Tabs.Content value=\"about\" className=\"text-sm text-fg-secondary\">\n        About this channel.\n      </Tabs.Content>\n    </Tabs.Root>\n  );\n}\n"
+    "path": "examples/tabs/underline.tsx",
+    "content": "import { Tabs } from \"@krizaka/ui/tabs\";\n\nexport default function TabsUnderline() {\n  return (\n    <Tabs.Root defaultValue=\"videos\">\n      <Tabs.List aria-label=\"Profile\">\n        <Tabs.Trigger value=\"videos\">Videos</Tabs.Trigger>\n        <Tabs.Trigger value=\"stories\">Stories</Tabs.Trigger>\n        <Tabs.Trigger value=\"collections\">Collections</Tabs.Trigger>\n        <Tabs.Trigger value=\"about\" disabled>\n          About\n        </Tabs.Trigger>\n      </Tabs.List>\n      <Tabs.Content value=\"videos\" className=\"text-sm text-fg-secondary\">\n        Twelve videos, newest first.\n      </Tabs.Content>\n      <Tabs.Content value=\"stories\" className=\"text-sm text-fg-secondary\">\n        Stories of the last 24 hours.\n      </Tabs.Content>\n      <Tabs.Content value=\"collections\" className=\"text-sm text-fg-secondary\">\n        Three public collections.\n      </Tabs.Content>\n      <Tabs.Content value=\"about\" className=\"text-sm text-fg-secondary\">\n        About this channel.\n      </Tabs.Content>\n    </Tabs.Root>\n  );\n}\n"
   },
   "props": [
     {

package/registry/theme.json

@@ -1,12 +1,198 @@
 {
   "name": "theme",
   "type": "primitive",
-  "description": "`ThemeScript`, `ThemeProvider`, `useTheme`, `ThemeToggle`. Client (\"use client\").",
+  "title": "Theme",
+  "summary": "Dark, light or the system's: `ThemeProvider`, `ThemeScript` against the flash, and `ThemeToggle`.",
+  "description": "Dark, light or the system's: `ThemeProvider`, `ThemeScript` against the flash, and `ThemeToggle`.",
+  "status": "stable",
+  "category": "foundations",
+  "platforms": "both",
+  "whenToUse": [
+    "Once per app, in the root layout: `ThemeScript` in `<head>`, `ThemeProvider` around the app.",
+    "`ThemeToggle` in the header or the settings, to cycle dark → light → system.",
+    "`useTheme()` to read or set the mode from your own control."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "To theme one area differently: put `.theme-light` or `.theme-dark` on the subtree instead."
+    },
+    {
+      "when": "To change a product's colours: override the `--kz-*` tokens in its design system."
+    }
+  ],
+  "bestPractices": [
+    "Put `<ThemeScript />` in `<head>` and `suppressHydrationWarning` on `<html>`: the right theme is applied before the first paint.",
+    "The choice is persisted as `kz-theme` and applied as `html.light`: every Krizaka app reads the same switch.",
+    "Check every screen in both themes."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Enter / Space",
+        "action": "The toggle cycles to the next mode."
+      }
+    ],
+    "notes": [
+      "`ThemeToggle` is a button named by `label` (translated); its icon shows the current mode.",
+      "`color-scheme` follows the theme, so native controls and scrollbars match."
+    ]
+  },
+  "related": [
+    "button",
+    "cn"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/theme",
+    "import": "import { ThemeProvider, ThemeScript, ThemeToggle, useTheme } from \"@krizaka/ui/theme\";",
+    "props": [
+      {
+        "component": "ThemeProvider",
+        "description": "",
+        "props": [
+          {
+            "name": "defaultMode",
+            "type": "Mode",
+            "default": "system",
+            "description": "The mode before anything is persisted.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "ThemeScript",
+        "description": "In <head>, before anything renders: applies the persisted mode and named theme, so the page never flashes.\n`nonce` for a strict Content-Security-Policy.",
+        "props": [
+          {
+            "name": "nonce",
+            "type": "string",
+            "default": null,
+            "description": "The nonce of a strict Content-Security-Policy (`script-src 'nonce-…'`).",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "ThemeToggle",
+        "description": "An icon button (styled as `IconButton`, without its Slot) that cycles dark → light → system. Needs a\n<ThemeProvider> above it. State: `data-mode`.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string | ((mode: Mode) => string)",
+            "default": null,
+            "description": "The accessible name — a string, or one per current mode (e.g. `(mode) => t(\"theme.\" + mode)`).",
+            "required": true
+          },
+          {
+            "name": "shape",
+            "type": "\"rounded\" | \"pill\"",
+            "default": "rounded",
+            "description": "rounded · pill.",
+            "required": false
+          },
+          {
+            "name": "variant",
+            "type": "\"danger\" | \"primary\" | \"secondary\" | \"outline\" | \"ghost\"",
+            "default": "ghost",
+            "description": "Any `Button` variant.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "toggle",
+        "title": "Toggle",
+        "description": "A ghost icon button in its provider.",
+        "path": "examples/theme/toggle.tsx",
+        "module": "@krizaka/ui/registry/examples/theme/toggle",
+        "code": "import { ThemeProvider, ThemeToggle } from \"@krizaka/ui/theme\";\n\nexport default function ThemeToggleExample() {\n  return (\n    <ThemeProvider>\n      <ThemeToggle label=\"Change the theme\" />\n    </ThemeProvider>\n  );\n}\n"
+      },
+      {
+        "name": "secondary",
+        "title": "Another look",
+        "description": "Any button variant and shape.",
+        "path": "examples/theme/secondary.tsx",
+        "module": "@krizaka/ui/registry/examples/theme/secondary",
+        "code": "import { ThemeProvider, ThemeToggle } from \"@krizaka/ui/theme\";\n\n// The toggle takes any button variant and shape.\nexport default function ThemeToggleSecondary() {\n  return (\n    <ThemeProvider>\n      <ThemeToggle label=\"Change the theme\" variant=\"secondary\" shape=\"pill\" />\n    </ThemeProvider>\n  );\n}\n"
+      }
+    ]
+  },
+  "native": {
+    "entry": "@krizaka/ui/native",
+    "import": "import { ThemeProvider, useTheme } from \"@krizaka/ui/native\";",
+    "differences": [
+      "`ThemeProvider` takes the product's colour roles (`overrides`) and fonts; there is no `ThemeScript` and no toggle.",
+      "`useTheme()` returns the resolved `theme` (colour roles), `scheme`, `radius` and `motion` for `StyleSheet`.",
+      "The mode is not persisted: the app stores it from `onModeChange`."
+    ],
+    "props": [
+      {
+        "component": "ThemeProvider",
+        "description": "Once, at the root of the app. Without it, `useTheme()` follows the system with the platform's roles.",
+        "props": [
+          {
+            "name": "defaultMode",
+            "type": "Mode",
+            "default": "system",
+            "description": "Uncontrolled: the mode before the user picks one. Default: follow the system.",
+            "required": false
+          },
+          {
+            "name": "fonts",
+            "type": "ThemeFonts",
+            "default": null,
+            "description": "Font families the app has loaded (`expo-font`…); absent: the system font.",
+            "required": false
+          },
+          {
+            "name": "mode",
+            "type": "Mode",
+            "default": null,
+            "description": "Controlled mode (with `onModeChange`).",
+            "required": false
+          },
+          {
+            "name": "onModeChange",
+            "type": "((mode: Mode) => void)",
+            "default": null,
+            "description": "Every change of mode — the app persists it (no storage dependency here).",
+            "required": false
+          },
+          {
+            "name": "overrides",
+            "type": "ThemeOverrides",
+            "default": null,
+            "description": "The product's roles over the platform's, per theme.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "provider",
+        "title": "Provider",
+        "description": "Once at the root; `useTheme()` reads the roles in any component.",
+        "path": "examples/theme/native/provider.tsx",
+        "module": "@krizaka/ui/registry/examples/theme/native/provider",
+        "code": "import { ThemeProvider, Txt, useTheme } from \"@krizaka/ui/native\";\nimport { View } from \"react-native\";\n\nfunction Screen() {\n  const { theme, scheme } = useTheme();\n  return (\n    <View style={{ backgroundColor: theme.surface1, padding: 16, borderRadius: 12 }}>\n      <Txt variant=\"title\">Every night, a new set.</Txt>\n      <Txt tone=\"secondary\">The {scheme} theme, from the system.</Txt>\n    </View>\n  );\n}\n\n// Once, at the root of the app: the roles of @krizaka/tokens, the system's scheme, a product's overrides.\nexport default function NativeThemeProvider() {\n  return (\n    <ThemeProvider defaultMode=\"system\">\n      <Screen />\n    </ThemeProvider>\n  );\n}\n"
+      }
+    ]
+  },
   "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 krizaka.com renders as\n// /docs/ui/<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  | \"alert\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"cn\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"kbd\"\n  | \"page-header\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"switch\"\n  | \"tabs\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\";\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"layout\" | \"foundations\";\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 */\nexport interface Example {\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/** 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  /** 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  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\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": "theme/index.ts",
       "content": "/** @krizaka/ui/theme — `ThemeScript`, `ThemeProvider`, `useTheme`, `ThemeToggle`. Client (\"use client\"). */\nexport {\n  type Mode,\n  type ThemeContextValue,\n  ThemeProvider,\n  type ThemeProviderProps,\n  ThemeScript,\n  ThemeToggle,\n  type ThemeToggleProps,\n  useTheme,\n} from \"./theme\";\n"
     },
+    {
+      "path": "theme/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Theme\",\n  summary: \"Dark, light or the system's: `ThemeProvider`, `ThemeScript` against the flash, and `ThemeToggle`.\",\n  status: \"stable\",\n  category: \"foundations\",\n  platforms: \"both\",\n  whenToUse: [\n    \"Once per app, in the root layout: `ThemeScript` in `<head>`, `ThemeProvider` around the app.\",\n    \"`ThemeToggle` in the header or the settings, to cycle dark → light → system.\",\n    \"`useTheme()` to read or set the mode from your own control.\",\n  ],\n  whenNotToUse: [\n    { when: \"To theme one area differently: put `.theme-light` or `.theme-dark` on the subtree instead.\" },\n    { when: \"To change a product's colours: override the `--kz-*` tokens in its design system.\" },\n  ],\n  bestPractices: [\n    \"Put `<ThemeScript />` in `<head>` and `suppressHydrationWarning` on `<html>`: the right theme is applied before the first paint.\",\n    \"The choice is persisted as `kz-theme` and applied as `html.light`: every Krizaka app reads the same switch.\",\n    \"Check every screen in both themes.\",\n  ],\n  accessibility: {\n    keyboard: [{ keys: \"Enter / Space\", action: \"The toggle cycles to the next mode.\" }],\n    notes: [\"`ThemeToggle` is a button named by `label` (translated); its icon shows the current mode.\", \"`color-scheme` follows the theme, so native controls and scrollbars match.\"],\n  },\n  related: [\"button\", \"cn\"],\n  web: {\n    imports: [\"ThemeProvider\", \"ThemeScript\", \"ThemeToggle\", \"useTheme\"],\n    examples: [\n      { name: \"toggle\", title: \"Toggle\", description: \"A ghost icon button in its provider.\" },\n      { name: \"secondary\", title: \"Another look\", description: \"Any button variant and shape.\" },\n    ],\n  },\n  native: {\n    imports: [\"ThemeProvider\", \"useTheme\"],\n    differences: [\n      \"`ThemeProvider` takes the product's colour roles (`overrides`) and fonts; there is no `ThemeScript` and no toggle.\",\n      \"`useTheme()` returns the resolved `theme` (colour roles), `scheme`, `radius` and `motion` for `StyleSheet`.\",\n      \"The mode is not persisted: the app stores it from `onModeChange`.\",\n    ],\n    examples: [{ name: \"provider\", title: \"Provider\", description: \"Once at the root; `useTheme()` reads the roles in any component.\" }],\n  },\n} satisfies ComponentMeta;\n"
+    },
     {
       "path": "theme/theme.tsx",
       "content": "// Client. ONE mechanism for the whole organisation: dark by default, `html.light` for light, `html.theme-<name>` for a\n// named theme, persisted in localStorage (`kz-theme` for the mode, `kz-theme-name` for the named theme).\nimport * as React from \"react\";\n\nimport { type ButtonVariants, buttonVariants } from \"../button/button\";\n\nexport type Mode = \"dark\" | \"light\" | \"system\";\n\nconst MODE_KEY = \"kz-theme\";\nconst NAME_KEY = \"kz-theme-name\";\nconst MODES: readonly Mode[] = [\"dark\", \"light\", \"system\"];\nconst DARK_QUERY = \"(prefers-color-scheme: dark)\";\n\nconst isMode = (value: unknown): value is Mode => MODES.includes(value as Mode);\n\n// Storage blocked (private mode, sandbox): the choice lives in memory for the page.\nconst memory = new Map<string, string>();\n\nfunction read(key: string): string | null {\n  try {\n    return localStorage.getItem(key);\n  } catch {\n    return memory.get(key) ?? null;\n  }\n}\n\nfunction write(key: string, value: string | null) {\n  if (value === null) memory.delete(key);\n  else memory.set(key, value);\n  try {\n    if (value === null) localStorage.removeItem(key);\n    else localStorage.setItem(key, value);\n  } catch {\n    // storage blocked: memory holds it\n  }\n}\n\n// The persisted choice is an external store: every provider and tab reads the same value, the server reads none.\nconst listeners = new Set<() => void>();\nconst notify = () => listeners.forEach((listener) => listener());\nfunction subscribe(listener: () => void) {\n  listeners.add(listener);\n  window.addEventListener(\"storage\", listener);\n  return () => {\n    listeners.delete(listener);\n    window.removeEventListener(\"storage\", listener);\n  };\n}\n\nfunction applyMode(mode: Mode) {\n  const dark = window.matchMedia(DARK_QUERY).matches;\n  document.documentElement.classList.toggle(\"light\", mode === \"light\" || (mode === \"system\" && !dark));\n}\n\nfunction applyName(previous: string | null, next: string | null) {\n  const classes = document.documentElement.classList;\n  if (previous) classes.remove(`theme-${previous}`);\n  if (next) classes.add(`theme-${next}`);\n}\n\n/**\n * In <head>, before anything renders: applies the persisted mode and named theme, so the page never flashes.\n * `nonce` for a strict Content-Security-Policy.\n */\nexport function ThemeScript({\n  nonce,\n}: {\n  /** The nonce of a strict Content-Security-Policy (`script-src 'nonce-…'`). */\n  nonce?: string;\n}) {\n  const js =\n    `(function(){try{var m=localStorage.getItem(\"${MODE_KEY}\")||\"system\";var n=localStorage.getItem(\"${NAME_KEY}\");` +\n    `var d=matchMedia(\"${DARK_QUERY}\").matches;var c=document.documentElement.classList;` +\n    `c.toggle(\"light\",m===\"light\"||(m===\"system\"&&!d));if(n)c.add(\"theme-\"+n)}catch(e){}})()`;\n  return <script nonce={nonce} dangerouslySetInnerHTML={{ __html: js }} />;\n}\n\nexport type ThemeContextValue = {\n  /** The chosen mode: dark, light or follow the system. */\n  mode: Mode;\n  setMode: (mode: Mode) => void;\n  /** The named theme (`html.theme-<name>`), or null. */\n  theme: string | null;\n  setTheme: (theme: string | null) => void;\n};\n\nconst ThemeContext = React.createContext<ThemeContextValue | null>(null);\n\nexport type ThemeProviderProps = {\n  children: React.ReactNode;\n  /** The mode before anything is persisted. */\n  defaultMode?: Mode;\n};\n\nexport function ThemeProvider({ children, defaultMode = \"system\" }: ThemeProviderProps) {\n  // Before hydration the server knows nothing persisted (ThemeScript has already applied it to <html>).\n  const stored = React.useSyncExternalStore(subscribe, () => read(MODE_KEY), () => null);\n  const mode: Mode = isMode(stored) ? stored : defaultMode;\n  const theme = React.useSyncExternalStore(subscribe, () => read(NAME_KEY), () => null);\n\n  // \"system\" follows the operating system while the page is open.\n  React.useEffect(() => {\n    if (mode !== \"system\") return;\n    const query = window.matchMedia(DARK_QUERY);\n    const onChange = () => applyMode(\"system\");\n    query.addEventListener?.(\"change\", onChange);\n    return () => query.removeEventListener?.(\"change\", onChange);\n  }, [mode]);\n\n  const setMode = React.useCallback((next: Mode) => {\n    write(MODE_KEY, next);\n    applyMode(next);\n    notify();\n  }, []);\n\n  const setTheme = React.useCallback((next: string | null) => {\n    applyName(read(NAME_KEY), next);\n    write(NAME_KEY, next);\n    notify();\n  }, []);\n\n  const value = React.useMemo(() => ({ mode, setMode, theme, setTheme }), [mode, setMode, theme, setTheme]);\n  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;\n}\n\nexport function useTheme(): ThemeContextValue {\n  const context = React.useContext(ThemeContext);\n  if (!context) throw new Error(\"useTheme: wrap the app in <ThemeProvider>\");\n  return context;\n}\n\nconst ICONS: Record<Mode, React.ReactNode> = {\n  dark: <path d=\"M20 14.5A8 8 0 0 1 9.5 4a8 8 0 1 0 10.5 10.5Z\" />,\n  light: (\n    <>\n      <circle cx=\"12\" cy=\"12\" r=\"4\" />\n      <path d=\"M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4\" />\n    </>\n  ),\n  system: (\n    <>\n      <rect x=\"3\" y=\"4\" width=\"18\" height=\"12\" rx=\"2\" />\n      <path d=\"M8 20h8M12 16v4\" />\n    </>\n  ),\n};\n\nexport type ThemeToggleProps = Omit<React.ComponentProps<\"button\">, \"onClick\" | \"children\"> &\n  Pick<ButtonVariants, \"variant\" | \"shape\"> & {\n    /** Any `Button` variant. */\n    variant?: ButtonVariants[\"variant\"];\n    /**\n     * rounded · pill.\n     * @default \"rounded\"\n     */\n    shape?: ButtonVariants[\"shape\"];\n    /** The accessible name — a string, or one per current mode (e.g. `(mode) => t(\"theme.\" + mode)`). */\n    label: string | ((mode: Mode) => string);\n  };\n\n/**\n * An icon button (styled as `IconButton`, without its Slot) that cycles dark → light → system. Needs a\n * <ThemeProvider> above it. State: `data-mode`.\n */\nexport function ThemeToggle({ label, variant = \"ghost\", shape, className, ...props }: ThemeToggleProps) {\n  const { mode, setMode } = useTheme();\n  const next = MODES[(MODES.indexOf(mode) + 1) % MODES.length] as Mode;\n  const name = typeof label === \"function\" ? label(mode) : label;\n  return (\n    <button\n      type=\"button\"\n      aria-label={name}\n      title={name}\n      data-mode={mode}\n      onClick={() => setMode(next)}\n      className={buttonVariants({ variant, shape, size: \"icon\", className })}\n      {...props}\n    >\n      <svg viewBox=\"0 0 24 24\" className=\"h-5 w-5\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" strokeLinecap=\"round\" strokeLinejoin=\"round\" aria-hidden>\n        {ICONS[mode]}\n      </svg>\n    </button>\n  );\n}\n"
@@ -17,8 +203,8 @@
     "button"
   ],
   "demo": {
-    "path": "demos/theme.tsx",
-    "content": "import { ThemeProvider, ThemeToggle } from \"@krizaka/ui/theme\";\n\nexport default function ThemeDemo() {\n  return (\n    <ThemeProvider>\n      <ThemeToggle label=\"Change the theme\" />\n    </ThemeProvider>\n  );\n}\n"
+    "path": "examples/theme/toggle.tsx",
+    "content": "import { ThemeProvider, ThemeToggle } from \"@krizaka/ui/theme\";\n\nexport default function ThemeToggleExample() {\n  return (\n    <ThemeProvider>\n      <ThemeToggle label=\"Change the theme\" />\n    </ThemeProvider>\n  );\n}\n"
   },
   "props": [
     {