@krizaka/ui 2.0.0-beta.5 → 2.0.0

package/registry/button.json

@@ -1,15 +1,529 @@
 {
   "name": "button",
   "type": "primitive",
-  "description": "`Button`, `IconButton`, `buttonVariants`. Server-safe.",
+  "title": "Button",
+  "summary": "The action: a button in six looks (primary, gradient, secondary, outline, ghost, danger), three sizes and two shapes.",
+  "description": "The action: a button in six looks (primary, gradient, secondary, outline, ghost, danger), three sizes and two shapes.",
+  "status": "stable",
+  "category": "actions",
+  "platforms": "both",
+  "whenToUse": [
+    "To run an action: submit a form, open a dialog, start an upload, save a draft.",
+    "One `primary` button for the main action of a view; `secondary`, `outline` or `ghost` for the others.",
+    "`IconButton` for a compact action shown by its icon alone (close, add, more), with a `label` for its name."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "To go to another page: use a link (`asChild` with your router's `<Link>` keeps the button look)."
+    },
+    {
+      "when": "To turn a setting on or off, with an immediate effect.",
+      "use": "switch"
+    },
+    {
+      "when": "For a destructive action that needs a second press to confirm, in place.",
+      "use": "confirm-button"
+    },
+    {
+      "when": "To choose one option among several, or filter a list.",
+      "use": "chip"
+    }
+  ],
+  "bestPractices": [
+    "Name the action with a verb: “Save”, “Send the invitation” — not “OK” or “Yes”.",
+    "One primary per view; the danger variant only for what destroys or cannot be undone.",
+    "`loading` while the action runs: the button is disabled and says it is busy; keep its width by keeping its words short.",
+    "Style a link without the component with `buttonVariants({ variant, size })`."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Enter / Space",
+        "action": "Runs the action."
+      },
+      {
+        "keys": "Tab",
+        "action": "Moves the focus to the next control; the focus ring uses `--kz-ring`."
+      }
+    ],
+    "notes": [
+      "A native `<button type=\"button\">`: the role, the focus and the keyboard come from the platform.",
+      "`IconButton` requires `label`: it becomes the `aria-label` of a button that shows no text.",
+      "`loading` sets `aria-busy` and disables the button; `disabled` keeps it out of the tab order."
+    ]
+  },
+  "related": [
+    "confirm-button",
+    "dialog",
+    "dropdown-menu",
+    "tooltip"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/button",
+    "import": "import { Button, IconButton } from \"@krizaka/ui/button\";",
+    "props": [
+      {
+        "component": "Button",
+        "description": "",
+        "props": [
+          {
+            "name": "asChild",
+            "type": "boolean",
+            "default": null,
+            "description": "Renders the child (e.g. a <Link>) instead of the <button>, with props, classes and ref merged.",
+            "required": false
+          },
+          {
+            "name": "loading",
+            "type": "boolean",
+            "default": null,
+            "description": "Disables and signals the wait (aria-busy, data-loading) — the product adds a spinner if it wants one.",
+            "required": false
+          },
+          {
+            "name": "shape",
+            "type": "\"rounded\" | \"pill\"",
+            "default": "rounded",
+            "description": "rounded · pill.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"icon\" | \"sm\" | \"md\" | \"lg\"",
+            "default": "md",
+            "description": "sm · md · lg, or `icon` (a square).",
+            "required": false
+          },
+          {
+            "name": "variant",
+            "type": "\"danger\" | \"primary\" | \"gradient\" | \"secondary\" | \"outline\" | \"ghost\"",
+            "default": "secondary",
+            "description": "The look: `primary` (the accent), `gradient` (accent → accent-2), `secondary` (a raised surface), `outline`,\n`ghost`, `danger`.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "IconButton",
+        "description": "An icon-only button: `label` is required, it is its accessible name.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "The accessible name (and tooltip) of the button — required, passed translated.",
+            "required": true
+          },
+          {
+            "name": "asChild",
+            "type": "boolean",
+            "default": null,
+            "description": "Renders the child (e.g. a <Link>) instead of the <button>, with props, classes and ref merged.",
+            "required": false
+          },
+          {
+            "name": "loading",
+            "type": "boolean",
+            "default": null,
+            "description": "Disables and signals the wait (aria-busy, data-loading) — the product adds a spinner if it wants one.",
+            "required": false
+          },
+          {
+            "name": "shape",
+            "type": "\"rounded\" | \"pill\"",
+            "default": "rounded",
+            "description": "rounded · pill.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"icon\" | \"sm\" | \"md\" | \"lg\"",
+            "default": "icon",
+            "description": "sm · md · lg, or `icon` (a square).",
+            "required": false
+          },
+          {
+            "name": "variant",
+            "type": "\"danger\" | \"primary\" | \"gradient\" | \"secondary\" | \"outline\" | \"ghost\"",
+            "default": "secondary",
+            "description": "The look: `primary` (the accent), `gradient` (accent → accent-2), `secondary` (a raised surface), `outline`,\n`ghost`, `danger`.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "primary",
+        "title": "Primary",
+        "description": "The main action of a view: the accent.",
+        "path": "examples/button/primary.tsx",
+        "module": "@krizaka/ui/registry/examples/button/primary",
+        "code": "import { Button } from \"@krizaka/ui/button\";\n\nexport default function ButtonPrimary() {\n  return <Button variant=\"primary\">Continue</Button>;\n}\n"
+      },
+      {
+        "name": "gradient",
+        "title": "Gradient",
+        "description": "The brand's signature, accent → accent-2: a hero or a closing call to action, once per page.",
+        "path": "examples/button/gradient.tsx",
+        "module": "@krizaka/ui/registry/examples/button/gradient",
+        "code": "import { Button } from \"@krizaka/ui/button\";\n\nexport default function ButtonGradient() {\n  return <Button variant=\"gradient\">Start free</Button>;\n}\n"
+      },
+      {
+        "name": "secondary",
+        "title": "Secondary",
+        "description": "The default: a raised surface, for the other actions.",
+        "path": "examples/button/secondary.tsx",
+        "module": "@krizaka/ui/registry/examples/button/secondary",
+        "code": "import { Button } from \"@krizaka/ui/button\";\n\n// `secondary` is the default variant: a raised surface.\nexport default function ButtonSecondary() {\n  return <Button>Continue</Button>;\n}\n"
+      },
+      {
+        "name": "outline",
+        "title": "Outline",
+        "description": "A lighter action next to a primary one.",
+        "path": "examples/button/outline.tsx",
+        "module": "@krizaka/ui/registry/examples/button/outline",
+        "code": "import { Button } from \"@krizaka/ui/button\";\n\nexport default function ButtonOutline() {\n  return <Button variant=\"outline\">Continue</Button>;\n}\n"
+      },
+      {
+        "name": "ghost",
+        "title": "Ghost",
+        "description": "In toolbars and dense lists: no frame until hovered.",
+        "path": "examples/button/ghost.tsx",
+        "module": "@krizaka/ui/registry/examples/button/ghost",
+        "code": "import { Button } from \"@krizaka/ui/button\";\n\nexport default function ButtonGhost() {\n  return <Button variant=\"ghost\">Continue</Button>;\n}\n"
+      },
+      {
+        "name": "danger",
+        "title": "Danger",
+        "description": "A destructive action: the border and the tint carry the danger, the label stays legible in both themes.",
+        "path": "examples/button/danger.tsx",
+        "module": "@krizaka/ui/registry/examples/button/danger",
+        "code": "import { Button } from \"@krizaka/ui/button\";\n\nexport default function ButtonDanger() {\n  return <Button variant=\"danger\">Delete</Button>;\n}\n"
+      },
+      {
+        "name": "sizes",
+        "title": "Sizes",
+        "description": "`sm`, `md` (default) and `lg`.",
+        "path": "examples/button/sizes.tsx",
+        "module": "@krizaka/ui/registry/examples/button/sizes",
+        "code": "import { Button } from \"@krizaka/ui/button\";\n\nexport default function ButtonSizes() {\n  return (\n    <div className=\"flex items-center gap-3\">\n      <Button variant=\"primary\" size=\"sm\">\n        Continue\n      </Button>\n      <Button variant=\"primary\" size=\"md\">\n        Continue\n      </Button>\n      <Button variant=\"primary\" size=\"lg\">\n        Continue\n      </Button>\n    </div>\n  );\n}\n"
+      },
+      {
+        "name": "pill",
+        "title": "Pill",
+        "description": "`shape=\"pill\"`: fully rounded.",
+        "path": "examples/button/pill.tsx",
+        "module": "@krizaka/ui/registry/examples/button/pill",
+        "code": "import { Button } from \"@krizaka/ui/button\";\n\nexport default function ButtonPill() {\n  return (\n    <Button variant=\"primary\" shape=\"pill\">\n      Continue\n    </Button>\n  );\n}\n"
+      },
+      {
+        "name": "disabled",
+        "title": "Disabled",
+        "description": "Not available yet: out of the tab order.",
+        "path": "examples/button/disabled.tsx",
+        "module": "@krizaka/ui/registry/examples/button/disabled",
+        "code": "import { Button } from \"@krizaka/ui/button\";\n\nexport default function ButtonDisabled() {\n  return (\n    <Button variant=\"primary\" disabled>\n      Continue\n    </Button>\n  );\n}\n"
+      },
+      {
+        "name": "loading",
+        "title": "Loading",
+        "description": "While the action runs: disabled, `aria-busy`, `data-loading`.",
+        "path": "examples/button/loading.tsx",
+        "module": "@krizaka/ui/registry/examples/button/loading",
+        "code": "import { Button } from \"@krizaka/ui/button\";\n\n// Disabled, `aria-busy` and `data-loading`: add your own spinner if you want one.\nexport default function ButtonLoading() {\n  return (\n    <Button variant=\"primary\" loading>\n      Saving…\n    </Button>\n  );\n}\n"
+      },
+      {
+        "name": "as-child-link",
+        "title": "As a link",
+        "description": "`asChild` renders your `<a>` (or router link) with the button's look.",
+        "path": "examples/button/as-child-link.tsx",
+        "module": "@krizaka/ui/registry/examples/button/as-child-link",
+        "code": "import { Button } from \"@krizaka/ui/button\";\n\n// `asChild`: the `<a>` is rendered, with the button's classes and props merged into it.\nexport default function ButtonAsChildLink() {\n  return (\n    <Button variant=\"outline\" asChild>\n      <a href=\"#docs\">Read the docs</a>\n    </Button>\n  );\n}\n"
+      },
+      {
+        "name": "icon",
+        "title": "Icon button",
+        "description": "`IconButton`: a square button holding an icon; `label` is its accessible name.",
+        "path": "examples/button/icon.tsx",
+        "module": "@krizaka/ui/registry/examples/button/icon",
+        "code": "import { IconButton } from \"@krizaka/ui/button\";\n\nexport default function ButtonIcon() {\n  return (\n    <div className=\"flex items-center gap-3\">\n      <IconButton label=\"Close\" variant=\"ghost\">\n        <svg viewBox=\"0 0 24 24\" className=\"h-4 w-4\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" strokeLinecap=\"round\" aria-hidden>\n          <path d=\"M18 6 6 18M6 6l12 12\" />\n        </svg>\n      </IconButton>\n      <IconButton label=\"Add\" variant=\"primary\" shape=\"pill\">\n        <svg viewBox=\"0 0 24 24\" className=\"h-4 w-4\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" strokeLinecap=\"round\" aria-hidden>\n          <path d=\"M12 5v14M5 12h14\" />\n        </svg>\n      </IconButton>\n    </div>\n  );\n}\n"
+      }
+    ]
+  },
+  "native": {
+    "entry": "@krizaka/ui/native",
+    "import": "import { Button, IconButton } from \"@krizaka/ui/native\";",
+    "differences": [
+      "The text is the `label` prop (a string), not children: it is also the accessible name.",
+      "`onPress` instead of `onClick` (a `Pressable`); haptics, if any, belong to your `onPress`.",
+      "`icon` places an icon before the label; there is no `asChild`.",
+      "`loading` shows the platform's `ActivityIndicator` in place of the icon.",
+      "`variant=\"gradient\"` draws its fill with react-native-svg (React Native has no CSS gradient)."
+    ],
+    "props": [
+      {
+        "component": "Button",
+        "description": "The action. `variant` × `size` × `shape`, `loading`, `icon`; the haptics, if any, belong to the app's `onPress`.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "The visible text — passed translated. It is also the accessible name.",
+            "required": true
+          },
+          {
+            "name": "icon",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Before the label (an icon component from the app's icon set).",
+            "required": false
+          },
+          {
+            "name": "loading",
+            "type": "boolean",
+            "default": "false",
+            "description": "Disables, shows a spinner in place of the icon and says busy.",
+            "required": false
+          },
+          {
+            "name": "shape",
+            "type": "\"rounded\" | \"pill\"",
+            "default": null,
+            "description": "`rounded` (default) or `pill`.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "ButtonSize",
+            "default": "md",
+            "description": "sm · md (default) · lg: 32, 40 or 48 points high.",
+            "required": false
+          },
+          {
+            "name": "style",
+            "type": "StyleProp<ViewStyle>",
+            "default": null,
+            "description": "Styles merged last, over the button's frame.",
+            "required": false
+          },
+          {
+            "name": "variant",
+            "type": "ButtonVariant",
+            "default": null,
+            "description": "The look: `primary`, `gradient` (accent → accent-2), `secondary` (default), `outline`, `ghost`, `danger` — as on the web.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "IconButton",
+        "description": "A square button holding only an icon: `label` is required, it is its accessible name.",
+        "props": [
+          {
+            "name": "icon",
+            "type": "ReactNode",
+            "default": null,
+            "description": "The icon (from the app's icon set); the button shows nothing else.",
+            "required": true
+          },
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "The accessible name — required, passed translated.",
+            "required": true
+          },
+          {
+            "name": "loading",
+            "type": "boolean",
+            "default": "false",
+            "description": "Disables, shows a spinner in place of the icon and says busy.",
+            "required": false
+          },
+          {
+            "name": "shape",
+            "type": "\"rounded\" | \"pill\"",
+            "default": null,
+            "description": "`rounded` (default) or `pill`.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "ButtonSize",
+            "default": "md",
+            "description": "sm · md (default) · lg: 32, 40 or 48 points high.",
+            "required": false
+          },
+          {
+            "name": "style",
+            "type": "StyleProp<ViewStyle>",
+            "default": null,
+            "description": "Styles merged last, over the button's frame.",
+            "required": false
+          },
+          {
+            "name": "variant",
+            "type": "ButtonVariant",
+            "default": null,
+            "description": "The look: `primary`, `gradient` (accent → accent-2), `secondary` (default), `outline`, `ghost`, `danger` — as on the web.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "primary",
+        "title": "Primary",
+        "description": "The main action of a screen.",
+        "path": "examples/button/native/primary.tsx",
+        "module": "@krizaka/ui/registry/examples/button/native/primary",
+        "code": "import { Button } from \"@krizaka/ui/native\";\n\nexport default function NativeButtonPrimary() {\n  return <Button variant=\"primary\" label=\"Continue\" onPress={() => {}} />;\n}\n",
+        "screenshots": {
+          "dark": "examples/button/native/primary.dark.png",
+          "light": "examples/button/native/primary.light.png"
+        }
+      },
+      {
+        "name": "gradient",
+        "title": "Gradient",
+        "description": "accent → accent-2, drawn with react-native-svg: the hero action of a screen.",
+        "path": "examples/button/native/gradient.tsx",
+        "module": "@krizaka/ui/registry/examples/button/native/gradient",
+        "code": "import { Button } from \"@krizaka/ui/native\";\n\nexport default function NativeButtonGradient() {\n  return <Button variant=\"gradient\" label=\"Start free\" onPress={() => {}} />;\n}\n",
+        "screenshots": {
+          "dark": "examples/button/native/gradient.dark.png",
+          "light": "examples/button/native/gradient.light.png"
+        }
+      },
+      {
+        "name": "secondary",
+        "title": "Secondary",
+        "description": "The default look.",
+        "path": "examples/button/native/secondary.tsx",
+        "module": "@krizaka/ui/registry/examples/button/native/secondary",
+        "code": "import { Button } from \"@krizaka/ui/native\";\n\n// `secondary` is the default variant: a raised surface.\nexport default function NativeButtonSecondary() {\n  return <Button label=\"Continue\" onPress={() => {}} />;\n}\n",
+        "screenshots": {
+          "dark": "examples/button/native/secondary.dark.png",
+          "light": "examples/button/native/secondary.light.png"
+        }
+      },
+      {
+        "name": "outline",
+        "title": "Outline",
+        "description": "A lighter action.",
+        "path": "examples/button/native/outline.tsx",
+        "module": "@krizaka/ui/registry/examples/button/native/outline",
+        "code": "import { Button } from \"@krizaka/ui/native\";\n\nexport default function NativeButtonOutline() {\n  return <Button variant=\"outline\" label=\"Continue\" onPress={() => {}} />;\n}\n",
+        "screenshots": {
+          "dark": "examples/button/native/outline.dark.png",
+          "light": "examples/button/native/outline.light.png"
+        }
+      },
+      {
+        "name": "ghost",
+        "title": "Ghost",
+        "description": "No frame: toolbars, headers.",
+        "path": "examples/button/native/ghost.tsx",
+        "module": "@krizaka/ui/registry/examples/button/native/ghost",
+        "code": "import { Button } from \"@krizaka/ui/native\";\n\nexport default function NativeButtonGhost() {\n  return <Button variant=\"ghost\" label=\"Continue\" onPress={() => {}} />;\n}\n",
+        "screenshots": {
+          "dark": "examples/button/native/ghost.dark.png",
+          "light": "examples/button/native/ghost.light.png"
+        }
+      },
+      {
+        "name": "danger",
+        "title": "Danger",
+        "description": "A destructive action.",
+        "path": "examples/button/native/danger.tsx",
+        "module": "@krizaka/ui/registry/examples/button/native/danger",
+        "code": "import { Button } from \"@krizaka/ui/native\";\n\nexport default function NativeButtonDanger() {\n  return <Button variant=\"danger\" label=\"Delete\" onPress={() => {}} />;\n}\n",
+        "screenshots": {
+          "dark": "examples/button/native/danger.dark.png",
+          "light": "examples/button/native/danger.light.png"
+        }
+      },
+      {
+        "name": "sizes",
+        "title": "Sizes",
+        "description": "`sm`, `md`, `lg`, and `shape=\"pill\"`.",
+        "path": "examples/button/native/sizes.tsx",
+        "module": "@krizaka/ui/registry/examples/button/native/sizes",
+        "code": "import { Button } from \"@krizaka/ui/native\";\n\nexport default function NativeButtonSizes() {\n  return (\n    <>\n      <Button variant=\"primary\" size=\"sm\" label=\"Continue\" />\n      <Button variant=\"primary\" size=\"md\" label=\"Continue\" />\n      <Button variant=\"primary\" size=\"lg\" shape=\"pill\" label=\"Continue\" />\n    </>\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/button/native/sizes.dark.png",
+          "light": "examples/button/native/sizes.light.png"
+        }
+      },
+      {
+        "name": "icon",
+        "title": "With an icon",
+        "description": "`icon` before the label.",
+        "path": "examples/button/native/icon.tsx",
+        "module": "@krizaka/ui/registry/examples/button/native/icon",
+        "code": "import { Button, useTheme } from \"@krizaka/ui/native\";\nimport Svg, { Path } from \"react-native-svg\";\n\nfunction PlusIcon({ color }: { color: string }) {\n  return (\n    <Svg width={16} height={16} viewBox=\"0 0 24 24\" fill=\"none\" stroke={color} strokeWidth={2} strokeLinecap=\"round\" strokeLinejoin=\"round\">\n      <Path d=\"M12 5v14M5 12h14\" />\n    </Svg>\n  );\n}\n\nexport default function NativeButtonIcon() {\n  const { theme } = useTheme();\n  return <Button variant=\"primary\" label=\"New set\" icon={<PlusIcon color={theme.onAccent} />} />;\n}\n",
+        "screenshots": {
+          "dark": "examples/button/native/icon.dark.png",
+          "light": "examples/button/native/icon.light.png"
+        }
+      },
+      {
+        "name": "disabled",
+        "title": "Disabled",
+        "description": "Not available yet.",
+        "path": "examples/button/native/disabled.tsx",
+        "module": "@krizaka/ui/registry/examples/button/native/disabled",
+        "code": "import { Button } from \"@krizaka/ui/native\";\n\nexport default function NativeButtonDisabled() {\n  return <Button variant=\"primary\" label=\"Continue\" disabled />;\n}\n",
+        "screenshots": {
+          "dark": "examples/button/native/disabled.dark.png",
+          "light": "examples/button/native/disabled.light.png"
+        }
+      },
+      {
+        "name": "loading",
+        "title": "Loading",
+        "description": "Disabled and busy, a spinner in place of the icon.",
+        "path": "examples/button/native/loading.tsx",
+        "module": "@krizaka/ui/registry/examples/button/native/loading",
+        "code": "import { Button } from \"@krizaka/ui/native\";\n\n// Disabled and busy: a spinner takes the place of the icon.\nexport default function NativeButtonLoading() {\n  return <Button variant=\"primary\" label=\"Saving…\" loading />;\n}\n",
+        "screenshots": {
+          "dark": "examples/button/native/loading.dark.png",
+          "light": "examples/button/native/loading.light.png"
+        }
+      },
+      {
+        "name": "icon-only",
+        "title": "Icon button",
+        "description": "`IconButton`: `label` is required, it is the accessible name.",
+        "path": "examples/button/native/icon-only.tsx",
+        "module": "@krizaka/ui/registry/examples/button/native/icon-only",
+        "code": "import { IconButton, useTheme } from \"@krizaka/ui/native\";\nimport Svg, { Path } from \"react-native-svg\";\n\nfunction Icon({ d, color }: { d: string; color: string }) {\n  return (\n    <Svg width={16} height={16} viewBox=\"0 0 24 24\" fill=\"none\" stroke={color} strokeWidth={2} strokeLinecap=\"round\" strokeLinejoin=\"round\">\n      <Path d={d} />\n    </Svg>\n  );\n}\n\n// `label` is required: it is the accessible name of a button that shows no text.\nexport default function NativeButtonIconOnly() {\n  const { theme } = useTheme();\n  return (\n    <>\n      <IconButton label=\"Close\" variant=\"ghost\" icon={<Icon d=\"M18 6 6 18M6 6l12 12\" color={theme.textPrimary} />} />\n      <IconButton label=\"Add\" variant=\"primary\" shape=\"pill\" icon={<Icon d=\"M12 5v14M5 12h14\" color={theme.onAccent} />} />\n    </>\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/button/native/icon-only.dark.png",
+          "light": "examples/button/native/icon-only.light.png"
+        }
+      }
+    ]
+  },
   "files": [
     {
       "path": "button/button.tsx",
-      "content": "// Server-safe: no hook, no context. `buttonVariants` styles a <Link> or a Server Component without the component.\nimport { Slot } from \"radix-ui\";\nimport type * as React from \"react\";\nimport { tv, type VariantProps } from \"tailwind-variants\";\n\nexport const buttonVariants = tv({\n  base:\n    \"inline-flex shrink-0 select-none items-center justify-center gap-2 whitespace-nowrap font-semibold transition-all \" +\n    \"focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-surface-0 \" +\n    \"disabled:pointer-events-none disabled:opacity-40 data-loading:cursor-progress active:scale-[0.98]\",\n  variants: {\n    variant: {\n      primary: \"bg-accent text-on-accent shadow-sm hover:bg-accent-hover\",\n      secondary: \"border border-border-default bg-surface-2 text-fg hover:border-border-strong hover:bg-surface-3\",\n      outline: \"border border-border-default bg-transparent text-fg hover:border-accent hover:text-fg-accent\",\n      ghost: \"text-fg-secondary hover:bg-surface-2 hover:text-fg\",\n      // The danger token is invariant and too light for small text on a light surface (3.6:1): the label stays a\n      // text role, the border and the tint carry the danger.\n      danger: \"border border-danger/50 bg-danger/10 text-fg hover:border-danger hover:bg-danger/20\",\n    },\n    size: { sm: \"h-8 px-3 text-xs\", md: \"h-10 px-4 text-sm\", lg: \"h-12 px-6 text-sm\", icon: \"h-10 w-10\" },\n    shape: { rounded: \"rounded-lg\", pill: \"rounded-full\" },\n  },\n  defaultVariants: { variant: \"secondary\", size: \"md\", shape: \"rounded\" },\n});\n\nexport type ButtonVariants = VariantProps<typeof buttonVariants>;\n\nexport type ButtonProps = React.ComponentProps<\"button\"> &\n  ButtonVariants & {\n    /**\n     * The look: `primary` (the accent), `secondary` (a raised surface), `outline`, `ghost`, `danger`.\n     * @default \"secondary\"\n     */\n    variant?: ButtonVariants[\"variant\"];\n    /**\n     * sm · md · lg, or `icon` (a square).\n     * @default \"md\"\n     */\n    size?: ButtonVariants[\"size\"];\n    /**\n     * rounded · pill.\n     * @default \"rounded\"\n     */\n    shape?: ButtonVariants[\"shape\"];\n    /** Renders the child (e.g. a <Link>) instead of the <button>, with props, classes and ref merged. */\n    asChild?: boolean;\n    /** Disables and signals the wait (aria-busy, data-loading) — the product adds a spinner if it wants one. */\n    loading?: boolean;\n  };\n\nexport function Button({ asChild, loading, variant, size, shape, className, disabled, ...props }: ButtonProps) {\n  const Comp = asChild ? Slot.Root : \"button\";\n  return (\n    <Comp\n      type={asChild ? undefined : \"button\"}\n      aria-busy={loading || undefined}\n      data-loading={loading ? \"\" : undefined}\n      data-variant={variant ?? \"secondary\"}\n      disabled={asChild ? undefined : disabled || loading}\n      aria-disabled={asChild && (disabled || loading) ? true : undefined}\n      className={buttonVariants({ variant, size, shape, className })}\n      {...props}\n    />\n  );\n}\n\nexport type IconButtonProps = Omit<ButtonProps, \"size\"> & {\n  /** The accessible name (and tooltip) of the button — required, passed translated. */\n  label: string;\n  /**\n   * sm · md · lg, or `icon` (a square).\n   * @default \"icon\"\n   */\n  size?: ButtonProps[\"size\"];\n};\n\n/** An icon-only button: `label` is required, it is its accessible name. */\nexport function IconButton({ label, size = \"icon\", ...props }: IconButtonProps) {\n  return <Button aria-label={label} title={label} size={size} {...props} />;\n}\n"
+      "content": "// Server-safe: no hook, no context. `buttonVariants` styles a <Link> or a Server Component without the component.\nimport { Slot } from \"radix-ui\";\nimport type * as React from \"react\";\nimport { tv, type VariantProps } from \"tailwind-variants\";\n\nexport const buttonVariants = tv({\n  base:\n    \"inline-flex shrink-0 select-none items-center justify-center gap-2 whitespace-nowrap font-semibold transition-all \" +\n    \"focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-surface-0 \" +\n    \"disabled:pointer-events-none disabled:opacity-40 data-loading:cursor-progress active:scale-[0.98]\",\n  variants: {\n    variant: {\n      primary: \"bg-accent text-on-accent shadow-sm hover:bg-accent-hover\",\n      // The brand's signature: accent → accent-2 (on-accent reads on both stops, tested in @krizaka/tokens).\n      gradient: \"bg-linear-to-r from-accent to-accent-2 text-on-accent shadow-sm hover:brightness-110\",\n      secondary: \"border border-border-default bg-surface-2 text-fg hover:border-border-strong hover:bg-surface-3\",\n      outline: \"border border-border-default bg-transparent text-fg hover:border-accent hover:text-fg-accent\",\n      ghost: \"text-fg-secondary hover:bg-surface-2 hover:text-fg\",\n      // The border and the tint carry the danger; the label stays the primary text role, legible on the tint at rest\n      // and hovered over every surface (`text-fg-danger` is for text set directly on a surface).\n      danger: \"border border-danger/50 bg-danger/10 text-fg hover:border-danger hover:bg-danger/20\",\n    },\n    size: { sm: \"h-8 px-3 text-xs\", md: \"h-10 px-4 text-sm\", lg: \"h-12 px-6 text-sm\", icon: \"h-10 w-10\" },\n    shape: { rounded: \"rounded-lg\", pill: \"rounded-full\" },\n  },\n  defaultVariants: { variant: \"secondary\", size: \"md\", shape: \"rounded\" },\n});\n\nexport type ButtonVariants = VariantProps<typeof buttonVariants>;\n\nexport type ButtonProps = React.ComponentProps<\"button\"> &\n  ButtonVariants & {\n    /**\n     * The look: `primary` (the accent), `gradient` (accent → accent-2), `secondary` (a raised surface), `outline`,\n     * `ghost`, `danger`.\n     * @default \"secondary\"\n     */\n    variant?: ButtonVariants[\"variant\"];\n    /**\n     * sm · md · lg, or `icon` (a square).\n     * @default \"md\"\n     */\n    size?: ButtonVariants[\"size\"];\n    /**\n     * rounded · pill.\n     * @default \"rounded\"\n     */\n    shape?: ButtonVariants[\"shape\"];\n    /** Renders the child (e.g. a <Link>) instead of the <button>, with props, classes and ref merged. */\n    asChild?: boolean;\n    /** Disables and signals the wait (aria-busy, data-loading) — the product adds a spinner if it wants one. */\n    loading?: boolean;\n  };\n\nexport function Button({ asChild, loading, variant, size, shape, className, disabled, ...props }: ButtonProps) {\n  const Comp = asChild ? Slot.Root : \"button\";\n  return (\n    <Comp\n      type={asChild ? undefined : \"button\"}\n      aria-busy={loading || undefined}\n      data-loading={loading ? \"\" : undefined}\n      data-variant={variant ?? \"secondary\"}\n      disabled={asChild ? undefined : disabled || loading}\n      aria-disabled={asChild && (disabled || loading) ? true : undefined}\n      className={buttonVariants({ variant, size, shape, className })}\n      {...props}\n    />\n  );\n}\n\nexport type IconButtonProps = Omit<ButtonProps, \"size\"> & {\n  /** The accessible name (and tooltip) of the button — required, passed translated. */\n  label: string;\n  /**\n   * sm · md · lg, or `icon` (a square).\n   * @default \"icon\"\n   */\n  size?: ButtonProps[\"size\"];\n};\n\n/** An icon-only button: `label` is required, it is its accessible name. */\nexport function IconButton({ label, size = \"icon\", ...props }: IconButtonProps) {\n  return <Button aria-label={label} title={label} size={size} {...props} />;\n}\n"
     },
     {
       "path": "button/index.ts",
       "content": "/** @krizaka/ui/button — `Button`, `IconButton`, `buttonVariants`. Server-safe. */\nexport { Button, type ButtonProps, type ButtonVariants, buttonVariants, IconButton, type IconButtonProps } from \"./button\";\n"
+    },
+    {
+      "path": "button/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Button\",\n  summary: \"The action: a button in six looks (primary, gradient, secondary, outline, ghost, danger), three sizes and two shapes.\",\n  status: \"stable\",\n  category: \"actions\",\n  platforms: \"both\",\n  whenToUse: [\n    \"To run an action: submit a form, open a dialog, start an upload, save a draft.\",\n    \"One `primary` button for the main action of a view; `secondary`, `outline` or `ghost` for the others.\",\n    \"`IconButton` for a compact action shown by its icon alone (close, add, more), with a `label` for its name.\",\n  ],\n  whenNotToUse: [\n    { when: \"To go to another page: use a link (`asChild` with your router's `<Link>` keeps the button look).\" },\n    { when: \"To turn a setting on or off, with an immediate effect.\", use: \"switch\" },\n    { when: \"For a destructive action that needs a second press to confirm, in place.\", use: \"confirm-button\" },\n    { when: \"To choose one option among several, or filter a list.\", use: \"chip\" },\n  ],\n  bestPractices: [\n    \"Name the action with a verb: “Save”, “Send the invitation” — not “OK” or “Yes”.\",\n    \"One primary per view; the danger variant only for what destroys or cannot be undone.\",\n    \"`loading` while the action runs: the button is disabled and says it is busy; keep its width by keeping its words short.\",\n    \"Style a link without the component with `buttonVariants({ variant, size })`.\",\n  ],\n  accessibility: {\n    keyboard: [\n      { keys: \"Enter / Space\", action: \"Runs the action.\" },\n      { keys: \"Tab\", action: \"Moves the focus to the next control; the focus ring uses `--kz-ring`.\" },\n    ],\n    notes: [\n      \"A native `<button type=\\\"button\\\">`: the role, the focus and the keyboard come from the platform.\",\n      \"`IconButton` requires `label`: it becomes the `aria-label` of a button that shows no text.\",\n      \"`loading` sets `aria-busy` and disables the button; `disabled` keeps it out of the tab order.\",\n    ],\n  },\n  related: [\"confirm-button\", \"dialog\", \"dropdown-menu\", \"tooltip\"],\n  web: {\n    imports: [\"Button\", \"IconButton\"],\n    examples: [\n      { name: \"primary\", title: \"Primary\", description: \"The main action of a view: the accent.\" },\n      { name: \"gradient\", title: \"Gradient\", description: \"The brand's signature, accent → accent-2: a hero or a closing call to action, once per page.\" },\n      { name: \"secondary\", title: \"Secondary\", description: \"The default: a raised surface, for the other actions.\" },\n      { name: \"outline\", title: \"Outline\", description: \"A lighter action next to a primary one.\" },\n      { name: \"ghost\", title: \"Ghost\", description: \"In toolbars and dense lists: no frame until hovered.\" },\n      { name: \"danger\", title: \"Danger\", description: \"A destructive action: the border and the tint carry the danger, the label stays legible in both themes.\" },\n      { name: \"sizes\", title: \"Sizes\", description: \"`sm`, `md` (default) and `lg`.\" },\n      { name: \"pill\", title: \"Pill\", description: \"`shape=\\\"pill\\\"`: fully rounded.\" },\n      { name: \"disabled\", title: \"Disabled\", description: \"Not available yet: out of the tab order.\" },\n      { name: \"loading\", title: \"Loading\", description: \"While the action runs: disabled, `aria-busy`, `data-loading`.\" },\n      { name: \"as-child-link\", title: \"As a link\", description: \"`asChild` renders your `<a>` (or router link) with the button's look.\" },\n      { name: \"icon\", title: \"Icon button\", description: \"`IconButton`: a square button holding an icon; `label` is its accessible name.\" },\n    ],\n  },\n  native: {\n    imports: [\"Button\", \"IconButton\"],\n    differences: [\n      \"The text is the `label` prop (a string), not children: it is also the accessible name.\",\n      \"`onPress` instead of `onClick` (a `Pressable`); haptics, if any, belong to your `onPress`.\",\n      \"`icon` places an icon before the label; there is no `asChild`.\",\n      \"`loading` shows the platform's `ActivityIndicator` in place of the icon.\",\n      \"`variant=\\\"gradient\\\"` draws its fill with react-native-svg (React Native has no CSS gradient).\",\n    ],\n    examples: [\n      { name: \"primary\", title: \"Primary\", description: \"The main action of a screen.\" },\n      { name: \"gradient\", title: \"Gradient\", description: \"accent → accent-2, drawn with react-native-svg: the hero action of a screen.\" },\n      { name: \"secondary\", title: \"Secondary\", description: \"The default look.\" },\n      { name: \"outline\", title: \"Outline\", description: \"A lighter action.\" },\n      { name: \"ghost\", title: \"Ghost\", description: \"No frame: toolbars, headers.\" },\n      { name: \"danger\", title: \"Danger\", description: \"A destructive action.\" },\n      { name: \"sizes\", title: \"Sizes\", description: \"`sm`, `md`, `lg`, and `shape=\\\"pill\\\"`.\" },\n      { name: \"icon\", title: \"With an icon\", description: \"`icon` before the label.\" },\n      { name: \"disabled\", title: \"Disabled\", description: \"Not available yet.\" },\n      { name: \"loading\", title: \"Loading\", description: \"Disabled and busy, a spinner in place of the icon.\" },\n      { name: \"icon-only\", title: \"Icon button\", description: \"`IconButton`: `label` is required, it is the accessible name.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "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"
     }
   ],
   "dependencies": [
@@ -18,8 +532,8 @@
   ],
   "registryDependencies": [],
   "demo": {
-    "path": "demos/button.tsx",
-    "content": "import { Button } from \"@krizaka/ui/button\";\n\nexport default function ButtonDemo() {\n  return <Button variant=\"primary\">Continue</Button>;\n}\n"
+    "path": "examples/button/primary.tsx",
+    "content": "import { Button } from \"@krizaka/ui/button\";\n\nexport default function ButtonPrimary() {\n  return <Button variant=\"primary\">Continue</Button>;\n}\n"
   },
   "props": [
     {
@@ -56,9 +570,9 @@
         },
         {
           "name": "variant",
-          "type": "\"danger\" | \"primary\" | \"secondary\" | \"outline\" | \"ghost\"",
+          "type": "\"danger\" | \"primary\" | \"gradient\" | \"secondary\" | \"outline\" | \"ghost\"",
           "default": "secondary",
-          "description": "The look: `primary` (the accent), `secondary` (a raised surface), `outline`, `ghost`, `danger`.",
+          "description": "The look: `primary` (the accent), `gradient` (accent → accent-2), `secondary` (a raised surface), `outline`,\n`ghost`, `danger`.",
           "required": false
         }
       ]
@@ -104,9 +618,9 @@
         },
         {
           "name": "variant",
-          "type": "\"danger\" | \"primary\" | \"secondary\" | \"outline\" | \"ghost\"",
+          "type": "\"danger\" | \"primary\" | \"gradient\" | \"secondary\" | \"outline\" | \"ghost\"",
           "default": "secondary",
-          "description": "The look: `primary` (the accent), `secondary` (a raised surface), `outline`, `ghost`, `danger`.",
+          "description": "The look: `primary` (the accent), `gradient` (accent → accent-2), `secondary` (a raised surface), `outline`,\n`ghost`, `danger`.",
           "required": false
         }
       ]