@krizaka/ui 2.2.0 → 2.3.0

package/registry/skeleton.json

@@ -2,8 +2,8 @@
   "name": "skeleton",
   "type": "primitive",
   "title": "Skeleton",
-  "summary": "A placeholder the shape of what is loading: a line, a circle or a block.",
-  "description": "A placeholder the shape of what is loading: a line, a circle or a block.",
+  "summary": "A placeholder the shape of what is loading — lines, circles, blocks, or the real component turned into its own skeleton (`SkeletonShape`) — crossed by one reflection of the brand light.",
+  "description": "A placeholder the shape of what is loading — lines, circles, blocks, or the real component turned into its own skeleton (`SkeletonShape`) — crossed by one reflection of the brand light.",
   "status": "stable",
   "category": "feedback",
   "platforms": "both",
@@ -25,28 +25,32 @@
     }
   ],
   "bestPractices": [
-    "Compose the shapes like the content: an avatar circle, two lines, a media block.",
+    "Best: `SkeletonShape` around the real component with placeholder words — its exact layout, nothing to keep in sync.",
+    "Otherwise compose the shapes like the content: an avatar circle, two lines (`SkeletonText`), a media block.",
+    "Let `LoadingRegion` (`@krizaka/ui/loader`) decide when to show them: after a short delay, with words when the wait lasts.",
     "Show skeletons only after a short delay on fast connections, and never for more than a few seconds without a message."
   ],
   "accessibility": {
     "keyboard": [],
     "notes": [
       "Decorative and hidden from assistive technology: announce the wait elsewhere (`aria-busy` on the region, a `Spinner`).",
-      "The pulse stops under `prefers-reduced-motion`."
+      "`SkeletonShape` is also `inert`: the placeholder component can hold no focus.",
+      "The reflection stops under `prefers-reduced-motion`: the shapes rest, tinted."
     ]
   },
   "related": [
+    "loader",
     "spinner",
     "empty-state",
     "card"
   ],
   "web": {
     "entry": "@krizaka/ui/skeleton",
-    "import": "import { Skeleton } from \"@krizaka/ui/skeleton\";",
+    "import": "import { Skeleton, SkeletonText, SkeletonShape } from \"@krizaka/ui/skeleton\";",
     "props": [
       {
         "component": "Skeleton",
-        "description": "A pulsing shape the size of what is loading. Announce the wait elsewhere (aria-busy on the region, a Spinner).",
+        "description": "A shape the size of what is loading. Announce the wait elsewhere (`LoadingRegion` does it, with `aria-busy`).",
         "props": [
           {
             "name": "shape",
@@ -56,9 +60,43 @@
             "required": false
           }
         ]
+      },
+      {
+        "component": "SkeletonShape",
+        "description": "The skeleton of the real thing: render your component with placeholder data inside, and its text, images and icons\nbecome skeleton shapes in place — the exact layout, nothing to draw twice. Inert and hidden from assistive technology.",
+        "props": []
+      },
+      {
+        "component": "SkeletonText",
+        "description": "A paragraph on its way: `lines` lines, the last one shorter — like text that wraps.",
+        "props": [
+          {
+            "name": "lines",
+            "type": "number",
+            "default": "3",
+            "description": "How many lines.",
+            "required": false
+          }
+        ]
       }
     ],
     "examples": [
+      {
+        "name": "shape-of-content",
+        "title": "The shape of the content",
+        "description": "`SkeletonShape` around the real card with placeholder words, above the loaded card: the same layout.",
+        "path": "examples/skeleton/shape-of-content.tsx",
+        "module": "@krizaka/ui/registry/examples/skeleton/shape-of-content",
+        "code": "import { SkeletonShape } from \"@krizaka/ui/skeleton\";\n\nfunction CreatorCard({ name, line }: { name: string; line: string }) {\n  return (\n    <div className=\"flex items-center gap-3 rounded-xl border border-border-default bg-surface-1 p-4\">\n      <span data-skeleton aria-hidden className=\"h-10 w-10 shrink-0 rounded-full bg-accent-soft\" />\n      <div className=\"min-w-0\">\n        <p className=\"font-semibold text-fg\">{name}</p>\n        <p className=\"text-sm text-fg-secondary\">{line}</p>\n      </div>\n    </div>\n  );\n}\n\n// The skeleton of the real card: the same component with placeholder words, its text and media turned into shapes.\n// The layout is exact — nothing drawn twice, nothing jumps when the data arrives. `data-skeleton` marks any other shape.\nexport default function SkeletonShapeOfContent() {\n  return (\n    <div className=\"flex w-full max-w-sm flex-col gap-3\">\n      <SkeletonShape>\n        <CreatorCard name=\"Placeholder name\" line=\"Placeholder supporters line\" />\n      </SkeletonShape>\n      <CreatorCard name=\"Eric Moreau\" line=\"1,204 supporters · Paris\" />\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "paragraph",
+        "title": "A paragraph",
+        "description": "A title and `SkeletonText`: lines that wrap, one reflection across them all.",
+        "path": "examples/skeleton/paragraph.tsx",
+        "module": "@krizaka/ui/registry/examples/skeleton/paragraph",
+        "code": "import { Skeleton, SkeletonText } from \"@krizaka/ui/skeleton\";\n\n// An article on its way: a title, then `SkeletonText` — lines that wrap, the last one shorter. One reflection crosses\n// all of them together, like light across a page, rather than each one pulsing on its own.\nexport default function SkeletonParagraph() {\n  return (\n    <div className=\"flex w-full max-w-sm flex-col gap-3\">\n      <Skeleton className=\"h-5 w-2/3\" />\n      <SkeletonText lines={4} />\n    </div>\n  );\n}\n"
+      },
       {
         "name": "text",
         "title": "Text",
@@ -160,19 +198,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 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  | \"mascots\"\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"
+      "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  | \"chip-link\"\n  | \"cn\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"glow-card\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\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  | \"stepper\"\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": "skeleton/index.ts",
-      "content": "/** @krizaka/ui/skeleton — `Skeleton`, `skeletonVariants`. Server-safe. */\nexport { Skeleton, type SkeletonProps, skeletonVariants } from \"./skeleton\";\n"
+      "content": "/** @krizaka/ui/skeleton — `Skeleton`, `SkeletonText`, `SkeletonShape` (the skeleton of the real component), `skeletonVariants`. Server-safe. */\nexport { Skeleton, type SkeletonProps, SkeletonShape, type SkeletonShapeProps, SkeletonText, type SkeletonTextProps, skeletonVariants } from \"./skeleton\";\n"
     },
     {
       "path": "skeleton/meta.ts",
-      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Skeleton\",\n  summary: \"A placeholder the shape of what is loading: a line, a circle or a block.\",\n  status: \"stable\",\n  category: \"feedback\",\n  platforms: \"both\",\n  whenToUse: [\"While a list, a card or a profile loads, in its final layout: the page does not jump when it arrives.\"],\n  whenNotToUse: [\n    { when: \"For an action the user is waiting on (a save).\", use: \"spinner\" },\n    { when: \"When there is nothing to load.\", use: \"empty-state\" },\n    { when: \"For the progress of a task.\", use: \"progress\" },\n  ],\n  bestPractices: [\n    \"Compose the shapes like the content: an avatar circle, two lines, a media block.\",\n    \"Show skeletons only after a short delay on fast connections, and never for more than a few seconds without a message.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"Decorative and hidden from assistive technology: announce the wait elsewhere (`aria-busy` on the region, a `Spinner`).\",\n      \"The pulse stops under `prefers-reduced-motion`.\",\n    ],\n  },\n  related: [\"spinner\", \"empty-state\", \"card\"],\n  web: {\n    imports: [\"Skeleton\"],\n    examples: [\n      { name: \"text\", title: \"Text\", description: \"A line of text.\" },\n      { name: \"circle\", title: \"Circle\", description: \"An avatar.\" },\n      { name: \"rect\", title: \"Rect\", description: \"A media or a block.\" },\n      { name: \"composition\", title: \"Composition\", description: \"Shapes composed into a card being loaded.\" },\n    ],\n  },\n  native: {\n    imports: [\"Skeleton\"],\n    differences: [\"`width` and `height` are props (points or a percentage), not classes.\"],\n    examples: [{ name: \"shapes\", title: \"Shapes\", description: \"`text`, `circle` and `rect`, composed.\" }],\n  },\n} satisfies ComponentMeta;\n"
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Skeleton\",\n  summary:\n    \"A placeholder the shape of what is loading — lines, circles, blocks, or the real component turned into its own skeleton (`SkeletonShape`) — crossed by one reflection of the brand light.\",\n  status: \"stable\",\n  category: \"feedback\",\n  platforms: \"both\",\n  whenToUse: [\"While a list, a card or a profile loads, in its final layout: the page does not jump when it arrives.\"],\n  whenNotToUse: [\n    { when: \"For an action the user is waiting on (a save).\", use: \"spinner\" },\n    { when: \"When there is nothing to load.\", use: \"empty-state\" },\n    { when: \"For the progress of a task.\", use: \"progress\" },\n  ],\n  bestPractices: [\n    \"Best: `SkeletonShape` around the real component with placeholder words — its exact layout, nothing to keep in sync.\",\n    \"Otherwise compose the shapes like the content: an avatar circle, two lines (`SkeletonText`), a media block.\",\n    \"Let `LoadingRegion` (`@krizaka/ui/loader`) decide when to show them: after a short delay, with words when the wait lasts.\",\n    \"Show skeletons only after a short delay on fast connections, and never for more than a few seconds without a message.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"Decorative and hidden from assistive technology: announce the wait elsewhere (`aria-busy` on the region, a `Spinner`).\",\n      \"`SkeletonShape` is also `inert`: the placeholder component can hold no focus.\",\n      \"The reflection stops under `prefers-reduced-motion`: the shapes rest, tinted.\",\n    ],\n  },\n  related: [\"loader\", \"spinner\", \"empty-state\", \"card\"],\n  web: {\n    imports: [\"Skeleton\", \"SkeletonText\", \"SkeletonShape\"],\n    examples: [\n      { name: \"shape-of-content\", title: \"The shape of the content\", description: \"`SkeletonShape` around the real card with placeholder words, above the loaded card: the same layout.\" },\n      { name: \"paragraph\", title: \"A paragraph\", description: \"A title and `SkeletonText`: lines that wrap, one reflection across them all.\" },\n      { name: \"text\", title: \"Text\", description: \"A line of text.\" },\n      { name: \"circle\", title: \"Circle\", description: \"An avatar.\" },\n      { name: \"rect\", title: \"Rect\", description: \"A media or a block.\" },\n      { name: \"composition\", title: \"Composition\", description: \"Shapes composed into a card being loaded.\" },\n    ],\n  },\n  native: {\n    imports: [\"Skeleton\"],\n    differences: [\"`width` and `height` are props (points or a percentage), not classes.\"],\n    examples: [{ name: \"shapes\", title: \"Shapes\", description: \"`text`, `circle` and `rect`, composed.\" }],\n  },\n} satisfies ComponentMeta;\n"
     },
     {
       "path": "skeleton/skeleton.tsx",
-      "content": "// Server-safe. A placeholder for content on its way: decorative, so hidden from assistive technology.\nimport type * as React from \"react\";\nimport { tv, type VariantProps } from \"tailwind-variants\";\n\nexport const skeletonVariants = tv({\n  base: \"block bg-surface-3 motion-safe:animate-pulse\",\n  variants: {\n    shape: { text: \"h-3 w-full rounded-sm\", circle: \"aspect-square h-10 rounded-full\", rect: \"h-24 w-full rounded-lg\" },\n  },\n  defaultVariants: { shape: \"text\" },\n});\n\nexport type SkeletonProps = React.ComponentProps<\"span\"> & {\n  /**\n   * text (a line) · circle (an avatar; give it a height) · rect (a media; give it a height).\n   * @default \"text\"\n   */\n  shape?: VariantProps<typeof skeletonVariants>[\"shape\"];\n};\n\n/** A pulsing shape the size of what is loading. Announce the wait elsewhere (aria-busy on the region, a Spinner). */\nexport function Skeleton({ shape, className, ...props }: SkeletonProps) {\n  return <span aria-hidden data-shape={shape ?? \"text\"} className={skeletonVariants({ shape, className })} {...props} />;\n}\n"
+      "content": "// Server-safe. A placeholder for content on its way: decorative, so hidden from assistive technology. One reflection of\n// the brand light crosses every skeleton of the page together (`background-attachment: fixed`), instead of each one\n// pulsing on its own; under reduced motion they rest, tinted.\nimport type * as React from \"react\";\nimport { tv, type VariantProps } from \"tailwind-variants\";\n\nexport const skeletonVariants = tv({\n  base: \"kz-skeleton block bg-surface-3\",\n  variants: {\n    shape: { text: \"h-3 w-full rounded-sm\", circle: \"aspect-square h-10 rounded-full\", rect: \"h-24 w-full rounded-lg\" },\n  },\n  defaultVariants: { shape: \"text\" },\n});\n\nexport type SkeletonProps = React.ComponentProps<\"span\"> & {\n  /**\n   * text (a line) · circle (an avatar; give it a height) · rect (a media; give it a height).\n   * @default \"text\"\n   */\n  shape?: VariantProps<typeof skeletonVariants>[\"shape\"];\n};\n\n/** A shape the size of what is loading. Announce the wait elsewhere (`LoadingRegion` does it, with `aria-busy`). */\nexport function Skeleton({ shape, className, ...props }: SkeletonProps) {\n  return <span aria-hidden data-shape={shape ?? \"text\"} className={skeletonVariants({ shape, className })} {...props} />;\n}\n\nexport type SkeletonTextProps = React.ComponentProps<\"span\"> & {\n  /**\n   * How many lines.\n   * @default 3\n   */\n  lines?: number;\n};\n\n/** A paragraph on its way: `lines` lines, the last one shorter — like text that wraps. */\nexport function SkeletonText({ lines = 3, className, ...props }: SkeletonTextProps) {\n  return (\n    <span aria-hidden className={[\"flex w-full flex-col gap-2\", className].filter(Boolean).join(\" \")} {...props}>\n      {Array.from({ length: lines }, (_, i) => (\n        <Skeleton key={i} className={i === lines - 1 && lines > 1 ? \"w-3/5\" : undefined} />\n      ))}\n    </span>\n  );\n}\n\nexport type SkeletonShapeProps = React.ComponentProps<\"div\">;\n\n/**\n * The skeleton of the real thing: render your component with placeholder data inside, and its text, images and icons\n * become skeleton shapes in place — the exact layout, nothing to draw twice. Inert and hidden from assistive technology.\n */\nexport function SkeletonShape({ className, children, ...props }: SkeletonShapeProps) {\n  return (\n    <div aria-hidden inert className={[\"kz-skeleton-shape\", className].filter(Boolean).join(\" \")} {...props}>\n      {children}\n    </div>\n  );\n}\n"
     }
   ],
   "dependencies": [
@@ -180,13 +218,13 @@
   ],
   "registryDependencies": [],
   "demo": {
-    "path": "examples/skeleton/text.tsx",
-    "content": "import { Skeleton } from \"@krizaka/ui/skeleton\";\n\nexport default function SkeletonText() {\n  return <Skeleton />;\n}\n"
+    "path": "examples/skeleton/shape-of-content.tsx",
+    "content": "import { SkeletonShape } from \"@krizaka/ui/skeleton\";\n\nfunction CreatorCard({ name, line }: { name: string; line: string }) {\n  return (\n    <div className=\"flex items-center gap-3 rounded-xl border border-border-default bg-surface-1 p-4\">\n      <span data-skeleton aria-hidden className=\"h-10 w-10 shrink-0 rounded-full bg-accent-soft\" />\n      <div className=\"min-w-0\">\n        <p className=\"font-semibold text-fg\">{name}</p>\n        <p className=\"text-sm text-fg-secondary\">{line}</p>\n      </div>\n    </div>\n  );\n}\n\n// The skeleton of the real card: the same component with placeholder words, its text and media turned into shapes.\n// The layout is exact — nothing drawn twice, nothing jumps when the data arrives. `data-skeleton` marks any other shape.\nexport default function SkeletonShapeOfContent() {\n  return (\n    <div className=\"flex w-full max-w-sm flex-col gap-3\">\n      <SkeletonShape>\n        <CreatorCard name=\"Placeholder name\" line=\"Placeholder supporters line\" />\n      </SkeletonShape>\n      <CreatorCard name=\"Eric Moreau\" line=\"1,204 supporters · Paris\" />\n    </div>\n  );\n}\n"
   },
   "props": [
     {
       "component": "Skeleton",
-      "description": "A pulsing shape the size of what is loading. Announce the wait elsewhere (aria-busy on the region, a Spinner).",
+      "description": "A shape the size of what is loading. Announce the wait elsewhere (`LoadingRegion` does it, with `aria-busy`).",
       "props": [
         {
           "name": "shape",
@@ -196,6 +234,24 @@
           "required": false
         }
       ]
+    },
+    {
+      "component": "SkeletonShape",
+      "description": "The skeleton of the real thing: render your component with placeholder data inside, and its text, images and icons\nbecome skeleton shapes in place — the exact layout, nothing to draw twice. Inert and hidden from assistive technology.",
+      "props": []
+    },
+    {
+      "component": "SkeletonText",
+      "description": "A paragraph on its way: `lines` lines, the last one shorter — like text that wraps.",
+      "props": [
+        {
+          "name": "lines",
+          "type": "number",
+          "default": "3",
+          "description": "How many lines.",
+          "required": false
+        }
+      ]
     }
   ]
 }

package/registry/slider.json

@@ -171,7 +171,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 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  | \"mascots\"\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"
+      "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  | \"chip-link\"\n  | \"cn\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"glow-card\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\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  | \"stepper\"\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": "slider/index.ts",

package/registry/slot.json

@@ -73,7 +73,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 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  | \"mascots\"\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"
+      "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  | \"chip-link\"\n  | \"cn\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"glow-card\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\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  | \"stepper\"\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": "slot/index.ts",

package/registry/spinner.json

@@ -2,8 +2,8 @@
   "name": "spinner",
   "type": "primitive",
   "title": "Spinner",
-  "summary": "An indeterminate wait: a turning ring named by `label`.",
-  "description": "An indeterminate wait: a turning ring named by `label`.",
+  "summary": "The Krizaka spinner: light traced around a hexagon, its node breathing — indeterminate, or growing to a `value`; still and legible under reduced motion.",
+  "description": "The Krizaka spinner: light traced around a hexagon, its node breathing — indeterminate, or growing to a `value`; still and legible under reduced motion.",
   "status": "stable",
   "category": "feedback",
   "platforms": "both",
@@ -16,9 +16,13 @@
       "use": "skeleton"
     },
     {
-      "when": "When the progress is known.",
+      "when": "When the progress is known and the wait is long: a bar says how far.",
       "use": "progress"
     },
+    {
+      "when": "When the wait may be instant (it would flash), or ends with a result to announce.",
+      "use": "loader"
+    },
     {
       "when": "Inside a button that runs an action: set `loading` on the button.",
       "use": "button"
@@ -26,27 +30,49 @@
   ],
   "bestPractices": [
     "One spinner per region: never a page full of them.",
-    "Pass `label` translated (“Loading”, “Searching”)."
+    "Pass `label` translated (“Loading”, “Searching”) and, when you know it, `value`: a growing trace reassures more than a loop.",
+    "A wait that may be instant, that ends in success or failure, or that can last: use `Loader`, which waits before showing itself and hands over to a skeleton."
   ],
   "accessibility": {
     "keyboard": [],
     "notes": [
       "`role=\"status\"` named by `label`: announced politely.",
-      "It stops turning under `prefers-reduced-motion`."
+      "Under `prefers-reduced-motion` it rests on a designed still frame: a third of the hexagon traced and the node lit — never a frozen blur."
     ]
   },
   "related": [
+    "loader",
     "skeleton",
     "progress",
     "button"
   ],
   "web": {
     "entry": "@krizaka/ui/spinner",
-    "import": "import { Spinner } from \"@krizaka/ui/spinner\";",
+    "import": "import { Spinner, LoaderGlyph } from \"@krizaka/ui/spinner\";",
     "props": [
+      {
+        "component": "LoaderGlyph",
+        "description": "The glyph alone (decorative): the Spinner, the Loader and the Button's `loading` draw it.",
+        "props": [
+          {
+            "name": "state",
+            "type": "LoaderGlyphState",
+            "default": "loading",
+            "description": "loading · success · error.",
+            "required": false
+          },
+          {
+            "name": "value",
+            "type": "number | null",
+            "default": null,
+            "description": "Between 0 and 1: a determinate wait, the trace grows to it. Absent: indeterminate.",
+            "required": false
+          }
+        ]
+      },
       {
         "component": "Spinner",
-        "description": "A turning ring with `role=\"status\"` (it stops turning under prefers-reduced-motion).",
+        "description": "The Krizaka spinner: a hexagon traced by a segment of light around a breathing node, in `currentColor` (the accent by\ndefault). `role=\"status\"`, named by `label`. Under prefers-reduced-motion it rests — a segment and the node lit.",
         "props": [
           {
             "name": "label",
@@ -61,6 +87,13 @@
             "default": "md",
             "description": "sm · md · lg.",
             "required": false
+          },
+          {
+            "name": "value",
+            "type": "number | null",
+            "default": null,
+            "description": "Between 0 and 1: the trace grows to the value (a determinate wait). Absent: it travels around.",
+            "required": false
           }
         ]
       }
@@ -68,27 +101,27 @@
     "examples": [
       {
         "name": "default",
-        "title": "Default",
-        "description": "Named by `label`.",
+        "title": "Searching in place",
+        "description": "A short wait beside its words: the light travels, the node breathes.",
         "path": "examples/spinner/default.tsx",
         "module": "@krizaka/ui/registry/examples/spinner/default",
-        "code": "import { Spinner } from \"@krizaka/ui/spinner\";\n\nexport default function SpinnerDefault() {\n  return <Spinner label=\"Loading\" />;\n}\n"
+        "code": "import { Spinner } from \"@krizaka/ui/spinner\";\n\n// A short wait in place: light travels around the hexagon, the node breathes. Still and legible under reduced motion.\nexport default function SpinnerDefault() {\n  return (\n    <p className=\"flex items-center gap-2 text-sm text-fg-secondary\">\n      <Spinner label=\"Searching\" size=\"sm\" />\n      <span aria-hidden>Searching your library…</span>\n    </p>\n  );\n}\n"
+      },
+      {
+        "name": "value",
+        "title": "A determinate wait",
+        "description": "`value` from 0 to 1: the trace grows to what is done, in the same footprint.",
+        "path": "examples/spinner/value.tsx",
+        "module": "@krizaka/ui/registry/examples/spinner/value",
+        "code": "import { Spinner } from \"@krizaka/ui/spinner\";\n\n// `value` (0–1): the trace grows to what is done — a determinate wait in the same small footprint.\nexport default function SpinnerValue() {\n  return (\n    <div className=\"flex items-center gap-4\">\n      {[0.25, 0.6, 0.9].map((value) => (\n        <Spinner key={value} label={`Uploading, ${Math.round(value * 100)} %`} value={value} size=\"lg\" />\n      ))}\n    </div>\n  );\n}\n"
       },
       {
         "name": "sizes",
-        "title": "Sizes",
-        "description": "`sm`, `md`, `lg`.",
+        "title": "Sizes and colour",
+        "description": "The minimal API: `size` sm · md · lg; the colour is `currentColor`.",
         "path": "examples/spinner/sizes.tsx",
         "module": "@krizaka/ui/registry/examples/spinner/sizes",
-        "code": "import { Spinner } from \"@krizaka/ui/spinner\";\n\nexport default function SpinnerSizes() {\n  return (\n    <div className=\"flex items-center gap-4\">\n      <Spinner label=\"Loading\" size=\"sm\" />\n      <Spinner label=\"Loading\" size=\"md\" />\n      <Spinner label=\"Loading\" size=\"lg\" />\n    </div>\n  );\n}\n"
-      },
-      {
-        "name": "muted",
-        "title": "Muted",
-        "description": "The colour follows `className`.",
-        "path": "examples/spinner/muted.tsx",
-        "module": "@krizaka/ui/registry/examples/spinner/muted",
-        "code": "import { Spinner } from \"@krizaka/ui/spinner\";\n\n// The colour follows `className` (here a text role).\nexport default function SpinnerMuted() {\n  return <Spinner label=\"Loading\" className=\"text-fg-secondary\" />;\n}\n"
+        "code": "import { Spinner } from \"@krizaka/ui/spinner\";\n\n// The minimal API, last: `size` sm · md · lg; the colour is `currentColor` (the accent by default, or `className`).\nexport default function SpinnerSizes() {\n  return (\n    <div className=\"flex items-center gap-4\">\n      <Spinner label=\"Loading\" size=\"sm\" />\n      <Spinner label=\"Loading\" size=\"md\" />\n      <Spinner label=\"Loading\" size=\"lg\" />\n      <Spinner label=\"Loading\" size=\"lg\" className=\"text-fg-secondary\" />\n    </div>\n  );\n}\n"
       }
     ]
   },
@@ -138,19 +171,23 @@
   "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  | \"mascots\"\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"
+      "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  | \"chip-link\"\n  | \"cn\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"glow-card\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\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  | \"stepper\"\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": "spinner/glyph.tsx",
+      "content": "// The Krizaka loader glyph, server-safe: a hexagon (the marks' shape) traced by a segment of light around a node that\n// breathes; determinate, it fills to its value; done, the trace closes and a check (or a cross) draws itself. Animated by\n// motion.css (`kz-loader-*`); still under prefers-reduced-motion — a segment at rest and the node lit, never blank.\nimport type * as React from \"react\";\n\n/** The hexagon, pointy top, radius 9 around (12, 12). */\nconst HEX = \"M12 3 19.79 7.5 19.79 16.5 12 21 4.21 16.5 4.21 7.5Z\";\n\n/** What the glyph shows: a wait (with an optional value), or how it ended. */\nexport type LoaderGlyphState = \"loading\" | \"success\" | \"error\";\n\nexport interface LoaderGlyphProps extends Omit<React.ComponentProps<\"svg\">, \"children\"> {\n  /** loading · success · error. */\n  state?: LoaderGlyphState;\n  /** Between 0 and 1: a determinate wait, the trace grows to it. Absent: indeterminate. */\n  value?: number | null;\n}\n\n/** The glyph alone (decorative): the Spinner, the Loader and the Button's `loading` draw it. */\nexport function LoaderGlyph({ state = \"loading\", value, ...props }: LoaderGlyphProps) {\n  const known = typeof value === \"number\" && Number.isFinite(value);\n  const fill = state !== \"loading\" ? 100 : known ? Math.round(Math.min(1, Math.max(0, value)) * 100) : null;\n  return (\n    <svg viewBox=\"0 0 24 24\" fill=\"none\" aria-hidden data-state={state} data-progress={fill === null ? undefined : fill} {...props}>\n      <path d={HEX} stroke=\"currentColor\" strokeOpacity=\"0.22\" strokeWidth=\"2.2\" strokeLinejoin=\"round\" />\n      <path\n        d={HEX}\n        pathLength={100}\n        stroke=\"currentColor\"\n        strokeWidth=\"2.2\"\n        strokeLinejoin=\"round\"\n        strokeLinecap=\"round\"\n        className=\"kz-loader-trace\"\n        strokeDasharray={fill === null ? undefined : `${fill} ${100 - fill}`}\n      />\n      {state === \"loading\" && <circle cx=\"12\" cy=\"12\" r=\"2.6\" fill=\"currentColor\" className=\"kz-loader-node\" />}\n      {state === \"success\" && <path d=\"M8.3 12.3l2.6 2.6 4.9-5.3\" pathLength={20} stroke=\"currentColor\" strokeWidth=\"2.2\" strokeLinecap=\"round\" strokeLinejoin=\"round\" className=\"kz-loader-mark\" />}\n      {state === \"error\" && <path d=\"M9.4 9.4l5.2 5.2M14.6 9.4l-5.2 5.2\" pathLength={20} stroke=\"currentColor\" strokeWidth=\"2.2\" strokeLinecap=\"round\" className=\"kz-loader-mark\" />}\n    </svg>\n  );\n}\n"
     },
     {
       "path": "spinner/index.ts",
-      "content": "/** @krizaka/ui/spinner — `Spinner`, `spinnerVariants`. Server-safe. */\nexport { Spinner, type SpinnerProps, spinnerVariants } from \"./spinner\";\n"
+      "content": "/** @krizaka/ui/spinner — `Spinner`, `spinnerVariants`, and the glyph alone (`LoaderGlyph`). Server-safe. */\nexport { LoaderGlyph, type LoaderGlyphProps, type LoaderGlyphState } from \"./glyph\";\nexport { Spinner, type SpinnerProps, spinnerVariants } from \"./spinner\";\n"
     },
     {
       "path": "spinner/meta.ts",
-      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Spinner\",\n  summary: \"An indeterminate wait: a turning ring named by `label`.\",\n  status: \"stable\",\n  category: \"feedback\",\n  platforms: \"both\",\n  whenToUse: [\"For a short wait of unknown length: a search, a refresh, an infinite list loading more.\"],\n  whenNotToUse: [\n    { when: \"When the layout of what is loading is known.\", use: \"skeleton\" },\n    { when: \"When the progress is known.\", use: \"progress\" },\n    { when: \"Inside a button that runs an action: set `loading` on the button.\", use: \"button\" },\n  ],\n  bestPractices: [\"One spinner per region: never a page full of them.\", \"Pass `label` translated (“Loading”, “Searching”).\"],\n  accessibility: {\n    keyboard: [],\n    notes: [\"`role=\\\"status\\\"` named by `label`: announced politely.\", \"It stops turning under `prefers-reduced-motion`.\"],\n  },\n  related: [\"skeleton\", \"progress\", \"button\"],\n  web: {\n    imports: [\"Spinner\"],\n    examples: [\n      { name: \"default\", title: \"Default\", description: \"Named by `label`.\" },\n      { name: \"sizes\", title: \"Sizes\", description: \"`sm`, `md`, `lg`.\" },\n      { name: \"muted\", title: \"Muted\", description: \"The colour follows `className`.\" },\n    ],\n  },\n  native: {\n    imports: [\"Spinner\"],\n    differences: [\"The platform's `ActivityIndicator`, in the accent.\"],\n    examples: [{ name: \"sizes\", title: \"Sizes\", description: \"`sm`, `md`, `lg`, named by `label`.\" }],\n  },\n} satisfies ComponentMeta;\n"
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Spinner\",\n  summary: \"The Krizaka spinner: light traced around a hexagon, its node breathing — indeterminate, or growing to a `value`; still and legible under reduced motion.\",\n  status: \"stable\",\n  category: \"feedback\",\n  platforms: \"both\",\n  whenToUse: [\"For a short wait of unknown length: a search, a refresh, an infinite list loading more.\"],\n  whenNotToUse: [\n    { when: \"When the layout of what is loading is known.\", use: \"skeleton\" },\n    { when: \"When the progress is known and the wait is long: a bar says how far.\", use: \"progress\" },\n    { when: \"When the wait may be instant (it would flash), or ends with a result to announce.\", use: \"loader\" },\n    { when: \"Inside a button that runs an action: set `loading` on the button.\", use: \"button\" },\n  ],\n  bestPractices: [\n    \"One spinner per region: never a page full of them.\",\n    \"Pass `label` translated (“Loading”, “Searching”) and, when you know it, `value`: a growing trace reassures more than a loop.\",\n    \"A wait that may be instant, that ends in success or failure, or that can last: use `Loader`, which waits before showing itself and hands over to a skeleton.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"`role=\\\"status\\\"` named by `label`: announced politely.\",\n      \"Under `prefers-reduced-motion` it rests on a designed still frame: a third of the hexagon traced and the node lit — never a frozen blur.\",\n    ],\n  },\n  related: [\"loader\", \"skeleton\", \"progress\", \"button\"],\n  web: {\n    imports: [\"Spinner\", \"LoaderGlyph\"],\n    examples: [\n      { name: \"default\", title: \"Searching in place\", description: \"A short wait beside its words: the light travels, the node breathes.\" },\n      { name: \"value\", title: \"A determinate wait\", description: \"`value` from 0 to 1: the trace grows to what is done, in the same footprint.\" },\n      { name: \"sizes\", title: \"Sizes and colour\", description: \"The minimal API: `size` sm · md · lg; the colour is `currentColor`.\" },\n    ],\n  },\n  native: {\n    imports: [\"Spinner\"],\n    differences: [\"The platform's `ActivityIndicator`, in the accent.\"],\n    examples: [{ name: \"sizes\", title: \"Sizes\", description: \"`sm`, `md`, `lg`, named by `label`.\" }],\n  },\n} satisfies ComponentMeta;\n"
     },
     {
       "path": "spinner/spinner.tsx",
-      "content": "// Server-safe. An indeterminate wait: an SVG ring, announced as a status with its `label`.\nimport type * as React from \"react\";\nimport { tv, type VariantProps } from \"tailwind-variants\";\n\nexport const spinnerVariants = tv({\n  base: \"shrink-0 text-accent motion-safe:animate-spin\",\n  variants: { size: { sm: \"h-4 w-4\", md: \"h-6 w-6\", lg: \"h-10 w-10\" } },\n  defaultVariants: { size: \"md\" },\n});\n\nexport type SpinnerProps = Omit<React.ComponentProps<\"svg\">, \"children\"> &\n  VariantProps<typeof spinnerVariants> & {\n    /**\n     * sm · md · lg.\n     * @default \"md\"\n     */\n    size?: VariantProps<typeof spinnerVariants>[\"size\"];\n    /** The accessible name of the wait, e.g. \"Loading\" — passed translated. */\n    label: string;\n  };\n\n/** A turning ring with `role=\"status\"` (it stops turning under prefers-reduced-motion). */\nexport function Spinner({ label, size, className, ...props }: SpinnerProps) {\n  return (\n    <svg\n      role=\"status\"\n      aria-label={label}\n      viewBox=\"0 0 24 24\"\n      fill=\"none\"\n      data-size={size ?? \"md\"}\n      className={spinnerVariants({ size, className })}\n      {...props}\n    >\n      <circle cx=\"12\" cy=\"12\" r=\"9\" stroke=\"currentColor\" strokeOpacity=\"0.2\" strokeWidth=\"3\" />\n      <path d=\"M21 12a9 9 0 0 0-9-9\" stroke=\"currentColor\" strokeWidth=\"3\" strokeLinecap=\"round\" />\n    </svg>\n  );\n}\n"
+      "content": "// Server-safe. An indeterminate wait: the Krizaka loader glyph (a hexagon traced by light around a node), announced as\n// a status with its `label`. For a wait with a delay, a value, an ETA or an ending, see `@krizaka/ui/loader`.\nimport type * as React from \"react\";\nimport { tv, type VariantProps } from \"tailwind-variants\";\n\nimport { LoaderGlyph } from \"./glyph\";\n\nexport const spinnerVariants = tv({\n  base: \"shrink-0 text-accent\",\n  variants: { size: { sm: \"h-4 w-4\", md: \"h-6 w-6\", lg: \"h-10 w-10\" } },\n  defaultVariants: { size: \"md\" },\n});\n\nexport type SpinnerProps = Omit<React.ComponentProps<\"svg\">, \"children\"> &\n  VariantProps<typeof spinnerVariants> & {\n    /**\n     * sm · md · lg.\n     * @default \"md\"\n     */\n    size?: VariantProps<typeof spinnerVariants>[\"size\"];\n    /** The accessible name of the wait, e.g. \"Loading\" — passed translated. */\n    label: string;\n    /** Between 0 and 1: the trace grows to the value (a determinate wait). Absent: it travels around. */\n    value?: number | null;\n  };\n\n/**\n * The Krizaka spinner: a hexagon traced by a segment of light around a breathing node, in `currentColor` (the accent by\n * default). `role=\"status\"`, named by `label`. Under prefers-reduced-motion it rests — a segment and the node lit.\n */\nexport function Spinner({ label, size, value, className, ...props }: SpinnerProps) {\n  return (\n    <LoaderGlyph\n      role=\"status\"\n      aria-label={label}\n      aria-hidden={undefined}\n      value={value}\n      data-size={size ?? \"md\"}\n      className={spinnerVariants({ size, className })}\n      {...props}\n    />\n  );\n}\n"
     }
   ],
   "dependencies": [
@@ -159,12 +196,32 @@
   "registryDependencies": [],
   "demo": {
     "path": "examples/spinner/default.tsx",
-    "content": "import { Spinner } from \"@krizaka/ui/spinner\";\n\nexport default function SpinnerDefault() {\n  return <Spinner label=\"Loading\" />;\n}\n"
+    "content": "import { Spinner } from \"@krizaka/ui/spinner\";\n\n// A short wait in place: light travels around the hexagon, the node breathes. Still and legible under reduced motion.\nexport default function SpinnerDefault() {\n  return (\n    <p className=\"flex items-center gap-2 text-sm text-fg-secondary\">\n      <Spinner label=\"Searching\" size=\"sm\" />\n      <span aria-hidden>Searching your library…</span>\n    </p>\n  );\n}\n"
   },
   "props": [
+    {
+      "component": "LoaderGlyph",
+      "description": "The glyph alone (decorative): the Spinner, the Loader and the Button's `loading` draw it.",
+      "props": [
+        {
+          "name": "state",
+          "type": "LoaderGlyphState",
+          "default": "loading",
+          "description": "loading · success · error.",
+          "required": false
+        },
+        {
+          "name": "value",
+          "type": "number | null",
+          "default": null,
+          "description": "Between 0 and 1: a determinate wait, the trace grows to it. Absent: indeterminate.",
+          "required": false
+        }
+      ]
+    },
     {
       "component": "Spinner",
-      "description": "A turning ring with `role=\"status\"` (it stops turning under prefers-reduced-motion).",
+      "description": "The Krizaka spinner: a hexagon traced by a segment of light around a breathing node, in `currentColor` (the accent by\ndefault). `role=\"status\"`, named by `label`. Under prefers-reduced-motion it rests — a segment and the node lit.",
       "props": [
         {
           "name": "label",
@@ -179,6 +236,13 @@
           "default": "md",
           "description": "sm · md · lg.",
           "required": false
+        },
+        {
+          "name": "value",
+          "type": "number | null",
+          "default": null,
+          "description": "Between 0 and 1: the trace grows to the value (a determinate wait). Absent: it travels around.",
+          "required": false
         }
       ]
     }

package/registry/stat.json

@@ -134,7 +134,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 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  | \"mascots\"\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"
+      "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  | \"chip-link\"\n  | \"cn\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"glow-card\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\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  | \"stepper\"\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": "stat/index.ts",