@krizaka/ui 2.5.0 → 2.8.0

package/registry/mascot-state.json

@@ -0,0 +1,1249 @@
+{
+  "name": "mascot-state",
+  "type": "primitive",
+  "title": "Mascot state",
+  "summary": "A moment told by a bird of the flock: nothing yet, a long wait, done, it failed, welcome — the bird of the job beside the words and the next action.",
+  "description": "A moment told by a bird of the flock: nothing yet, a long wait, done, it failed, welcome — the bird of the job beside the words and the next action.",
+  "status": "beta",
+  "category": "feedback",
+  "platforms": "both",
+  "whenToUse": [
+    "An empty list or search the person reaches for the first time (`mood=\"empty\"`, `framed`).",
+    "A page or a panel that failed: a 404, a lost connection, a refused payment (`ErrorState`).",
+    "The end of something that matters: a payment received, an identity verified, a message sent (`SuccessState`).",
+    "A task of several seconds or more, with what runs in words (`LoadingState`).",
+    "The first screen of an onboarding (`WelcomeState`)."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "A short wait of a second or two, or a list that is loading.",
+      "use": "skeleton"
+    },
+    {
+      "when": "An error inside a form or a card, next to what it concerns.",
+      "use": "alert"
+    },
+    {
+      "when": "A result that needs no moment: a saved setting, a copied link.",
+      "use": "toast"
+    },
+    {
+      "when": "A plain empty list in a dense screen (a table, a sidebar).",
+      "use": "empty-state"
+    }
+  ],
+  "bestPractices": [
+    "Choose the bird by the job, not by the mood: the owl reads (documents, search), the falcon watches (security, verification), the duck builds (code, uploads), the flamingo answers and gets paid (support, payments), the pigeon delivers (messages, notifications), the lovebird introduces (matches, introductions).",
+    "One bird per screen: a moment, never decoration in working content.",
+    "The title says what happened in a few words, the description what comes next; one action — the way out.",
+    "`titleAs=\"h1\"` when the state is the whole page (a 404), so the page keeps a heading."
+  ],
+  "accessibility": {
+    "keyboard": [],
+    "notes": [
+      "`role=\"alert\"` for an error, `role=\"status\"` otherwise: announced when it appears; `aria-busy` while thinking.",
+      "The bird is decorative: the title and the description carry the meaning.",
+      "The staged arrival (bird, words, action) and the bird's gesture stop under `prefers-reduced-motion` and with `animated={false}`."
+    ]
+  },
+  "related": [
+    "mascots",
+    "empty-state",
+    "alert",
+    "progress"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/mascot-state",
+    "import": "import { MascotState, ErrorState, SuccessState, LoadingState, WelcomeState } from \"@krizaka/ui/mascot-state\";",
+    "props": [
+      {
+        "component": "ErrorState",
+        "description": "It failed: what went wrong and what to do (`role=\"alert\"`). `MascotState` with `mood=\"error\"`.",
+        "props": [
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What happened, in a few words (\"No videos yet\", \"Payment received\").",
+            "required": true
+          },
+          {
+            "name": "action",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What to do next: a Button, a link. One, at most two.",
+            "required": false
+          },
+          {
+            "name": "animated",
+            "type": "boolean",
+            "default": null,
+            "description": "The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`.",
+            "required": false
+          },
+          {
+            "name": "bird",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "default": null,
+            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Why, or what comes next.",
+            "required": false
+          },
+          {
+            "name": "framed",
+            "type": "boolean",
+            "default": null,
+            "description": "A dashed frame on the raised surface, for an empty list or panel.",
+            "required": false
+          },
+          {
+            "name": "layout",
+            "type": "\"inline\" | \"stacked\"",
+            "default": null,
+            "description": "`stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"md\" | \"lg\"",
+            "default": null,
+            "description": "The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px.",
+            "required": false
+          },
+          {
+            "name": "titleAs",
+            "type": "\"h1\" | \"h2\" | \"h3\" | \"p\"",
+            "default": null,
+            "description": "The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page.",
+            "required": false
+          },
+          {
+            "name": "tone",
+            "type": "MascotTone",
+            "default": null,
+            "description": "`brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "LoadingState",
+        "description": "A long task runs (`aria-busy`): what runs, beside the bird. `MascotState` with `mood=\"thinking\"`.",
+        "props": [
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What happened, in a few words (\"No videos yet\", \"Payment received\").",
+            "required": true
+          },
+          {
+            "name": "action",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What to do next: a Button, a link. One, at most two.",
+            "required": false
+          },
+          {
+            "name": "animated",
+            "type": "boolean",
+            "default": null,
+            "description": "The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`.",
+            "required": false
+          },
+          {
+            "name": "bird",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "default": null,
+            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Why, or what comes next.",
+            "required": false
+          },
+          {
+            "name": "framed",
+            "type": "boolean",
+            "default": null,
+            "description": "A dashed frame on the raised surface, for an empty list or panel.",
+            "required": false
+          },
+          {
+            "name": "layout",
+            "type": "\"inline\" | \"stacked\"",
+            "default": null,
+            "description": "`stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"md\" | \"lg\"",
+            "default": null,
+            "description": "The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px.",
+            "required": false
+          },
+          {
+            "name": "titleAs",
+            "type": "\"h1\" | \"h2\" | \"h3\" | \"p\"",
+            "default": null,
+            "description": "The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page.",
+            "required": false
+          },
+          {
+            "name": "tone",
+            "type": "MascotTone",
+            "default": null,
+            "description": "`brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "MascotState",
+        "description": "A moment told by a bird of the flock: an empty list, a long wait, a success, an error, a welcome. Announced to\nassistive technology — `role=\"alert\"` for an error, `role=\"status\"` otherwise (`aria-busy` while thinking).",
+        "props": [
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What happened, in a few words (\"No videos yet\", \"Payment received\").",
+            "required": true
+          },
+          {
+            "name": "action",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What to do next: a Button, a link. One, at most two.",
+            "required": false
+          },
+          {
+            "name": "animated",
+            "type": "boolean",
+            "default": "true",
+            "description": "The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`.",
+            "required": false
+          },
+          {
+            "name": "bird",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "default": "owl",
+            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Why, or what comes next.",
+            "required": false
+          },
+          {
+            "name": "framed",
+            "type": "boolean",
+            "default": null,
+            "description": "A dashed frame on the raised surface, for an empty list or panel.",
+            "required": false
+          },
+          {
+            "name": "layout",
+            "type": "\"inline\" | \"stacked\"",
+            "default": null,
+            "description": "`stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form.",
+            "required": false
+          },
+          {
+            "name": "mood",
+            "type": "\"success\" | \"error\" | \"empty\" | \"welcome\" | \"thinking\"",
+            "default": "empty",
+            "description": "The moment: `empty` (nothing yet), `thinking` (a long task runs), `success` (done), `error` (it failed), `welcome`.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"md\" | \"lg\"",
+            "default": "md",
+            "description": "The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px.",
+            "required": false
+          },
+          {
+            "name": "titleAs",
+            "type": "\"h1\" | \"h2\" | \"h3\" | \"p\"",
+            "default": "p",
+            "description": "The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page.",
+            "required": false
+          },
+          {
+            "name": "tone",
+            "type": "MascotTone",
+            "default": null,
+            "description": "`brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "SuccessState",
+        "description": "It is done: a payment, a verification, a delivery, a sent message. `MascotState` with `mood=\"success\"`.",
+        "props": [
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What happened, in a few words (\"No videos yet\", \"Payment received\").",
+            "required": true
+          },
+          {
+            "name": "action",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What to do next: a Button, a link. One, at most two.",
+            "required": false
+          },
+          {
+            "name": "animated",
+            "type": "boolean",
+            "default": null,
+            "description": "The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`.",
+            "required": false
+          },
+          {
+            "name": "bird",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "default": null,
+            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Why, or what comes next.",
+            "required": false
+          },
+          {
+            "name": "framed",
+            "type": "boolean",
+            "default": null,
+            "description": "A dashed frame on the raised surface, for an empty list or panel.",
+            "required": false
+          },
+          {
+            "name": "layout",
+            "type": "\"inline\" | \"stacked\"",
+            "default": null,
+            "description": "`stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"md\" | \"lg\"",
+            "default": null,
+            "description": "The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px.",
+            "required": false
+          },
+          {
+            "name": "titleAs",
+            "type": "\"h1\" | \"h2\" | \"h3\" | \"p\"",
+            "default": null,
+            "description": "The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page.",
+            "required": false
+          },
+          {
+            "name": "tone",
+            "type": "MascotTone",
+            "default": null,
+            "description": "`brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "WelcomeState",
+        "description": "A first screen, an onboarding step. `MascotState` with `mood=\"welcome\"`.",
+        "props": [
+          {
+            "name": "title",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What happened, in a few words (\"No videos yet\", \"Payment received\").",
+            "required": true
+          },
+          {
+            "name": "action",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What to do next: a Button, a link. One, at most two.",
+            "required": false
+          },
+          {
+            "name": "animated",
+            "type": "boolean",
+            "default": null,
+            "description": "The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`.",
+            "required": false
+          },
+          {
+            "name": "bird",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "default": null,
+            "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "ReactNode",
+            "default": null,
+            "description": "Why, or what comes next.",
+            "required": false
+          },
+          {
+            "name": "framed",
+            "type": "boolean",
+            "default": null,
+            "description": "A dashed frame on the raised surface, for an empty list or panel.",
+            "required": false
+          },
+          {
+            "name": "layout",
+            "type": "\"inline\" | \"stacked\"",
+            "default": null,
+            "description": "`stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"md\" | \"lg\"",
+            "default": null,
+            "description": "The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px.",
+            "required": false
+          },
+          {
+            "name": "titleAs",
+            "type": "\"h1\" | \"h2\" | \"h3\" | \"p\"",
+            "default": null,
+            "description": "The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page.",
+            "required": false
+          },
+          {
+            "name": "tone",
+            "type": "MascotTone",
+            "default": null,
+            "description": "`brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "empty",
+        "title": "Nothing yet",
+        "description": "A framed empty list: the pigeon has no message to deliver yet.",
+        "path": "examples/mascot-state/empty.tsx",
+        "module": "@krizaka/ui/registry/examples/mascot-state/empty",
+        "code": "import { Button } from \"@krizaka/ui/button\";\nimport { MascotState } from \"@krizaka/ui/mascot-state\";\n\n// An empty inbox: the pigeon has nothing to deliver yet; the action fills it.\nexport default function MascotStateEmpty() {\n  return (\n    <MascotState\n      bird=\"pigeon\"\n      framed\n      className=\"w-96\"\n      title=\"No messages yet\"\n      description=\"Answer a challenge or tip a creator to start a conversation.\"\n      action={\n        <Button variant=\"primary\" size=\"sm\">\n          Find creators\n        </Button>\n      }\n    />\n  );\n}\n"
+      },
+      {
+        "name": "error",
+        "title": "It failed",
+        "description": "A page that does not exist: the owl did not find it, with the way back.",
+        "path": "examples/mascot-state/error.tsx",
+        "module": "@krizaka/ui/registry/examples/mascot-state/error",
+        "code": "import { Button } from \"@krizaka/ui/button\";\nimport { ErrorState } from \"@krizaka/ui/mascot-state\";\n\n// A page that does not exist: the owl read everywhere and did not find it; the way back is the action.\nexport default function MascotStateError() {\n  return (\n    <ErrorState\n      bird=\"owl\"\n      size=\"lg\"\n      titleAs=\"h1\"\n      className=\"w-96\"\n      title=\"This page does not exist\"\n      description=\"The link may be old, or the page has moved.\"\n      action={\n        <Button variant=\"secondary\" size=\"sm\">\n          Back to the home page\n        </Button>\n      }\n    />\n  );\n}\n"
+      },
+      {
+        "name": "success",
+        "title": "Done",
+        "description": "A payment received: the flamingo answers, the next step beside it.",
+        "path": "examples/mascot-state/success.tsx",
+        "module": "@krizaka/ui/registry/examples/mascot-state/success",
+        "code": "import { Button } from \"@krizaka/ui/button\";\nimport { SuccessState } from \"@krizaka/ui/mascot-state\";\n\n// A payment received: the flamingo gets paid and answers; the receipt is the next step.\nexport default function MascotStateSuccess() {\n  return (\n    <SuccessState\n      bird=\"flamingo\"\n      className=\"w-96\"\n      title=\"Payment received\"\n      description=\"120 credits are on your balance. The receipt is in your email.\"\n      action={\n        <Button variant=\"secondary\" size=\"sm\">\n          See the receipt\n        </Button>\n      }\n    />\n  );\n}\n"
+      },
+      {
+        "name": "loading",
+        "title": "A long task",
+        "description": "The duck builds while the job runs, in a card (`layout=\"inline\"`).",
+        "path": "examples/mascot-state/loading.tsx",
+        "module": "@krizaka/ui/registry/examples/mascot-state/loading",
+        "code": "import { LoadingState } from \"@krizaka/ui/mascot-state\";\n\n// A job of a few minutes, in a card: the duck builds; the words say what runs.\nexport default function MascotStateLoading() {\n  return (\n    <LoadingState\n      bird=\"duck\"\n      size=\"sm\"\n      layout=\"inline\"\n      framed\n      className=\"w-96\"\n      title=\"Building the preview\"\n      description=\"About two minutes. You can leave this page.\"\n    />\n  );\n}\n"
+      },
+      {
+        "name": "welcome",
+        "title": "Welcome",
+        "description": "An onboarding's first screen: the falcon keeps the account safe.",
+        "path": "examples/mascot-state/welcome.tsx",
+        "module": "@krizaka/ui/registry/examples/mascot-state/welcome",
+        "code": "import { Button } from \"@krizaka/ui/button\";\nimport { WelcomeState } from \"@krizaka/ui/mascot-state\";\n\n// The first step of an onboarding: the falcon keeps the account safe — the step is a second factor.\nexport default function MascotStateWelcome() {\n  return (\n    <WelcomeState\n      bird=\"falcon\"\n      className=\"w-96\"\n      title=\"Welcome, Eric\"\n      description=\"First, protect your account with a second factor. It takes a minute.\"\n      action={\n        <Button variant=\"primary\" size=\"sm\">\n          Protect my account\n        </Button>\n      }\n    />\n  );\n}\n"
+      }
+    ]
+  },
+  "native": {
+    "entry": "@krizaka/ui/native",
+    "import": "import { MascotState, ErrorState, SuccessState, LoadingState, WelcomeState } from \"@krizaka/ui/native\";",
+    "differences": [
+      "`title` and `description` are strings; the action is a native `Button`.",
+      "No `framed` and no `titleAs`: style with `style`.",
+      "Only the idle bob and a fade-in: the web gestures (wave, dots, hop) stay on the web."
+    ],
+    "props": [
+      {
+        "component": "MascotState",
+        "description": "A moment told by a bird of the flock — an empty list, a long wait, a success, an error, a welcome — for React Native.\nAnnounced: `alert` for an error, a polite live region otherwise (`busy` while thinking).",
+        "props": [
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What happened, in a few words.",
+            "required": true
+          },
+          {
+            "name": "action",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What to do next: a Button.",
+            "required": false
+          },
+          {
+            "name": "animated",
+            "type": "boolean",
+            "default": "true",
+            "description": "The bird's bob and a short fade-in; still when the system reduces motion.",
+            "required": false
+          },
+          {
+            "name": "bird",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "default": "owl",
+            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions).",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "string",
+            "default": null,
+            "description": "Why, or what comes next.",
+            "required": false
+          },
+          {
+            "name": "layout",
+            "type": "\"stacked\" | \"inline\"",
+            "default": "stacked",
+            "description": "`stacked` (default): the bird above centred words. `inline`: the bird beside the words.",
+            "required": false
+          },
+          {
+            "name": "mood",
+            "type": "\"success\" | \"welcome\" | \"thinking\" | \"empty\" | \"error\"",
+            "default": "empty",
+            "description": "The moment: `empty` (default), `thinking`, `success`, `error`, `welcome`.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"md\" | \"lg\"",
+            "default": "md",
+            "description": "The bird's size: `sm` 64, `md` 96 (default), `lg` 128 points.",
+            "required": false
+          },
+          {
+            "name": "tone",
+            "type": "MascotTone",
+            "default": null,
+            "description": "`brand` (default): the theme's accent. `own`: the bird's colours of the Krizaka story.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "ErrorState",
+        "description": "It failed: what went wrong and what to do.",
+        "props": [
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What happened, in a few words.",
+            "required": true
+          },
+          {
+            "name": "action",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What to do next: a Button.",
+            "required": false
+          },
+          {
+            "name": "animated",
+            "type": "boolean",
+            "default": null,
+            "description": "The bird's bob and a short fade-in; still when the system reduces motion.",
+            "required": false
+          },
+          {
+            "name": "bird",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "default": null,
+            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions).",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "string",
+            "default": null,
+            "description": "Why, or what comes next.",
+            "required": false
+          },
+          {
+            "name": "layout",
+            "type": "\"stacked\" | \"inline\"",
+            "default": null,
+            "description": "`stacked` (default): the bird above centred words. `inline`: the bird beside the words.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"md\" | \"lg\"",
+            "default": null,
+            "description": "The bird's size: `sm` 64, `md` 96 (default), `lg` 128 points.",
+            "required": false
+          },
+          {
+            "name": "tone",
+            "type": "MascotTone",
+            "default": null,
+            "description": "`brand` (default): the theme's accent. `own`: the bird's colours of the Krizaka story.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "SuccessState",
+        "description": "It is done: a payment, a verification, a delivery.",
+        "props": [
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What happened, in a few words.",
+            "required": true
+          },
+          {
+            "name": "action",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What to do next: a Button.",
+            "required": false
+          },
+          {
+            "name": "animated",
+            "type": "boolean",
+            "default": null,
+            "description": "The bird's bob and a short fade-in; still when the system reduces motion.",
+            "required": false
+          },
+          {
+            "name": "bird",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "default": null,
+            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions).",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "string",
+            "default": null,
+            "description": "Why, or what comes next.",
+            "required": false
+          },
+          {
+            "name": "layout",
+            "type": "\"stacked\" | \"inline\"",
+            "default": null,
+            "description": "`stacked` (default): the bird above centred words. `inline`: the bird beside the words.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"md\" | \"lg\"",
+            "default": null,
+            "description": "The bird's size: `sm` 64, `md` 96 (default), `lg` 128 points.",
+            "required": false
+          },
+          {
+            "name": "tone",
+            "type": "MascotTone",
+            "default": null,
+            "description": "`brand` (default): the theme's accent. `own`: the bird's colours of the Krizaka story.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "LoadingState",
+        "description": "A long task runs: what runs, beside the bird.",
+        "props": [
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What happened, in a few words.",
+            "required": true
+          },
+          {
+            "name": "action",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What to do next: a Button.",
+            "required": false
+          },
+          {
+            "name": "animated",
+            "type": "boolean",
+            "default": null,
+            "description": "The bird's bob and a short fade-in; still when the system reduces motion.",
+            "required": false
+          },
+          {
+            "name": "bird",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "default": null,
+            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions).",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "string",
+            "default": null,
+            "description": "Why, or what comes next.",
+            "required": false
+          },
+          {
+            "name": "layout",
+            "type": "\"stacked\" | \"inline\"",
+            "default": null,
+            "description": "`stacked` (default): the bird above centred words. `inline`: the bird beside the words.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"md\" | \"lg\"",
+            "default": null,
+            "description": "The bird's size: `sm` 64, `md` 96 (default), `lg` 128 points.",
+            "required": false
+          },
+          {
+            "name": "tone",
+            "type": "MascotTone",
+            "default": null,
+            "description": "`brand` (default): the theme's accent. `own`: the bird's colours of the Krizaka story.",
+            "required": false
+          }
+        ]
+      },
+      {
+        "component": "WelcomeState",
+        "description": "A first screen, an onboarding step.",
+        "props": [
+          {
+            "name": "title",
+            "type": "string",
+            "default": null,
+            "description": "What happened, in a few words.",
+            "required": true
+          },
+          {
+            "name": "action",
+            "type": "ReactNode",
+            "default": null,
+            "description": "What to do next: a Button.",
+            "required": false
+          },
+          {
+            "name": "animated",
+            "type": "boolean",
+            "default": null,
+            "description": "The bird's bob and a short fade-in; still when the system reduces motion.",
+            "required": false
+          },
+          {
+            "name": "bird",
+            "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+            "default": null,
+            "description": "The bird whose job the moment is about: `owl` (documents), `falcon` (security), `duck` (code), `flamingo` (answers, payments), `pigeon` (delivery), `lovebird` (introductions).",
+            "required": false
+          },
+          {
+            "name": "description",
+            "type": "string",
+            "default": null,
+            "description": "Why, or what comes next.",
+            "required": false
+          },
+          {
+            "name": "layout",
+            "type": "\"stacked\" | \"inline\"",
+            "default": null,
+            "description": "`stacked` (default): the bird above centred words. `inline`: the bird beside the words.",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "\"sm\" | \"md\" | \"lg\"",
+            "default": null,
+            "description": "The bird's size: `sm` 64, `md` 96 (default), `lg` 128 points.",
+            "required": false
+          },
+          {
+            "name": "tone",
+            "type": "MascotTone",
+            "default": null,
+            "description": "`brand` (default): the theme's accent. `own`: the bird's colours of the Krizaka story.",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "default",
+        "title": "Default",
+        "description": "A payment received (flamingo) and a verification that failed (falcon).",
+        "path": "examples/mascot-state/native/default.tsx",
+        "module": "@krizaka/ui/registry/examples/mascot-state/native/default",
+        "code": "import { Button, ErrorState, SuccessState } from \"@krizaka/ui/native\";\nimport { View } from \"react-native\";\n\n// A payment received (the flamingo gets paid) and a verification that failed (the falcon watches).\nexport default function NativeMascotStateDefault() {\n  return (\n    <View style={{ width: 320, gap: 8 }}>\n      <SuccessState bird=\"flamingo\" size=\"sm\" animated={false} title=\"Payment received\" description=\"120 credits are on your balance.\" />\n      <ErrorState\n        bird=\"falcon\"\n        size=\"sm\"\n        animated={false}\n        title=\"We could not verify this code\"\n        description=\"It may have expired. Ask for a new one.\"\n        action={<Button variant=\"secondary\" label=\"Send a new code\" />}\n      />\n    </View>\n  );\n}\n",
+        "screenshots": {
+          "dark": "examples/mascot-state/native/default.dark.png",
+          "light": "examples/mascot-state/native/default.light.png"
+        }
+      }
+    ]
+  },
+  "files": [
+    {
+      "path": "mascot-state/index.ts",
+      "content": "/** @krizaka/ui/mascot-state — `MascotState` and its moments (`ErrorState`, `SuccessState`, `LoadingState`, `WelcomeState`). Client: the bird has an id per instance. */\nexport { ErrorState, LoadingState, MascotState, mascotState, type MascotStateProps, SuccessState, WelcomeState } from \"./mascot-state\";\n"
+    },
+    {
+      "path": "mascot-state/mascot-state.tsx",
+      "content": "// The moments a product speaks to a person — nothing yet, a long wait, done, it failed, welcome — told by a bird of\n// the flock beside the words. Every word is a prop; the bird never carries the message alone.\nimport type * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport type { MascotBird, MascotMood, MascotTone } from \"../mascots/geometry\";\nimport { Mascot } from \"../mascots/mascot\";\n\n// Staged: the bird arrives, then the words, then the action — once, and not at all under reduced motion.\nconst CSS = `\n@keyframes kzms-in { from { opacity: 0; transform: translateY(6px); } }\n@media (prefers-reduced-motion: no-preference) {\n  [data-kzms-staged] > [data-kzms-part] { animation: kzms-in .42s cubic-bezier(.2,.8,.2,1) both; }\n  [data-kzms-staged] > [data-kzms-part=\"words\"] { animation-delay: .12s; }\n  [data-kzms-staged] > [data-kzms-part=\"action\"] { animation-delay: .24s; }\n}\n`;\n\nexport const mascotState = tv({\n  slots: {\n    root: \"flex items-center gap-4 text-fg\",\n    bird: \"shrink-0\",\n    words: \"flex flex-col gap-1.5\",\n    title: \"text-base font-semibold text-fg\",\n    description: \"max-w-sm text-sm text-fg-secondary\",\n    action: \"flex flex-wrap items-center gap-2\",\n  },\n  variants: {\n    layout: {\n      stacked: { root: \"flex-col justify-center px-6 py-10 text-center\", words: \"items-center\", action: \"justify-center\" },\n      inline: { root: \"flex-row text-left\", action: \"mt-1\" },\n    },\n    framed: { true: { root: \"rounded-xl border border-dashed border-border-default bg-surface-1\" }, false: {} },\n  },\n  compoundVariants: [{ layout: \"inline\", framed: true, class: { root: \"p-4\" } }],\n  defaultVariants: { layout: \"stacked\", framed: false },\n});\n\nconst SIZE = { sm: 64, md: 96, lg: 128 } as const;\n\nexport type MascotStateProps = Omit<React.ComponentProps<\"div\">, \"title\"> & {\n  /**\n   * The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n   * (code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.\n   */\n  bird?: MascotBird;\n  /** The moment: `empty` (nothing yet), `thinking` (a long task runs), `success` (done), `error` (it failed), `welcome`. */\n  mood?: MascotMood;\n  /** What happened, in a few words (\"No videos yet\", \"Payment received\"). */\n  title: React.ReactNode;\n  /** Why, or what comes next. */\n  description?: React.ReactNode;\n  /** What to do next: a Button, a link. One, at most two. */\n  action?: React.ReactNode;\n  /** The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px. */\n  size?: keyof typeof SIZE;\n  /** `stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form. */\n  layout?: \"stacked\" | \"inline\";\n  /** A dashed frame on the raised surface, for an empty list or panel. */\n  framed?: boolean;\n  /** `brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story. */\n  tone?: MascotTone;\n  /** The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`. */\n  animated?: boolean;\n  /** The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page. */\n  titleAs?: \"p\" | \"h1\" | \"h2\" | \"h3\";\n};\n\n/**\n * A moment told by a bird of the flock: an empty list, a long wait, a success, an error, a welcome. Announced to\n * assistive technology — `role=\"alert\"` for an error, `role=\"status\"` otherwise (`aria-busy` while thinking).\n */\nexport function MascotState({\n  bird = \"owl\",\n  mood = \"empty\",\n  title,\n  description,\n  action,\n  size = \"md\",\n  layout,\n  framed,\n  tone,\n  animated = true,\n  titleAs: Title = \"p\",\n  className,\n  ...props\n}: MascotStateProps) {\n  const s = mascotState({ layout, framed });\n  return (\n    <div\n      role={mood === \"error\" ? \"alert\" : \"status\"}\n      aria-busy={mood === \"thinking\" ? true : undefined}\n      data-mood={mood}\n      data-kzms-staged={animated ? \"\" : undefined}\n      className={s.root({ className })}\n      {...props}\n    >\n      {animated && <style>{CSS}</style>}\n      <span data-kzms-part=\"bird\" className={s.bird()}>\n        <Mascot bird={bird} mood={mood} tone={tone} size={SIZE[size]} animated={animated} />\n      </span>\n      <div data-kzms-part=\"words\" className={s.words()}>\n        <Title className={s.title()}>{title}</Title>\n        {description && <p className={s.description()}>{description}</p>}\n        {layout === \"inline\" && action && <div className={s.action()}>{action}</div>}\n      </div>\n      {layout !== \"inline\" && action && (\n        <div data-kzms-part=\"action\" className={s.action()}>\n          {action}\n        </div>\n      )}\n    </div>\n  );\n}\n\ntype PresetProps = Omit<MascotStateProps, \"mood\">;\n\n/** It failed: what went wrong and what to do (`role=\"alert\"`). `MascotState` with `mood=\"error\"`. */\nexport function ErrorState(props: PresetProps) {\n  return <MascotState mood=\"error\" {...props} />;\n}\n\n/** It is done: a payment, a verification, a delivery, a sent message. `MascotState` with `mood=\"success\"`. */\nexport function SuccessState(props: PresetProps) {\n  return <MascotState mood=\"success\" {...props} />;\n}\n\n/** A long task runs (`aria-busy`): what runs, beside the bird. `MascotState` with `mood=\"thinking\"`. */\nexport function LoadingState(props: PresetProps) {\n  return <MascotState mood=\"thinking\" {...props} />;\n}\n\n/** A first screen, an onboarding step. `MascotState` with `mood=\"welcome\"`. */\nexport function WelcomeState(props: PresetProps) {\n  return <MascotState mood=\"welcome\" {...props} />;\n}\n"
+    },
+    {
+      "path": "mascot-state/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Mascot state\",\n  summary:\n    \"A moment told by a bird of the flock: nothing yet, a long wait, done, it failed, welcome — the bird of the job beside the words and the next action.\",\n  status: \"beta\",\n  category: \"feedback\",\n  platforms: \"both\",\n  whenToUse: [\n    \"An empty list or search the person reaches for the first time (`mood=\\\"empty\\\"`, `framed`).\",\n    \"A page or a panel that failed: a 404, a lost connection, a refused payment (`ErrorState`).\",\n    \"The end of something that matters: a payment received, an identity verified, a message sent (`SuccessState`).\",\n    \"A task of several seconds or more, with what runs in words (`LoadingState`).\",\n    \"The first screen of an onboarding (`WelcomeState`).\",\n  ],\n  whenNotToUse: [\n    { when: \"A short wait of a second or two, or a list that is loading.\", use: \"skeleton\" },\n    { when: \"An error inside a form or a card, next to what it concerns.\", use: \"alert\" },\n    { when: \"A result that needs no moment: a saved setting, a copied link.\", use: \"toast\" },\n    { when: \"A plain empty list in a dense screen (a table, a sidebar).\", use: \"empty-state\" },\n  ],\n  bestPractices: [\n    \"Choose the bird by the job, not by the mood: the owl reads (documents, search), the falcon watches (security, verification), the duck builds (code, uploads), the flamingo answers and gets paid (support, payments), the pigeon delivers (messages, notifications), the lovebird introduces (matches, introductions).\",\n    \"One bird per screen: a moment, never decoration in working content.\",\n    \"The title says what happened in a few words, the description what comes next; one action — the way out.\",\n    \"`titleAs=\\\"h1\\\"` when the state is the whole page (a 404), so the page keeps a heading.\",\n  ],\n  accessibility: {\n    keyboard: [],\n    notes: [\n      \"`role=\\\"alert\\\"` for an error, `role=\\\"status\\\"` otherwise: announced when it appears; `aria-busy` while thinking.\",\n      \"The bird is decorative: the title and the description carry the meaning.\",\n      \"The staged arrival (bird, words, action) and the bird's gesture stop under `prefers-reduced-motion` and with `animated={false}`.\",\n    ],\n  },\n  related: [\"mascots\", \"empty-state\", \"alert\", \"progress\"],\n  web: {\n    imports: [\"MascotState\", \"ErrorState\", \"SuccessState\", \"LoadingState\", \"WelcomeState\"],\n    examples: [\n      { name: \"empty\", title: \"Nothing yet\", description: \"A framed empty list: the pigeon has no message to deliver yet.\" },\n      { name: \"error\", title: \"It failed\", description: \"A page that does not exist: the owl did not find it, with the way back.\" },\n      { name: \"success\", title: \"Done\", description: \"A payment received: the flamingo answers, the next step beside it.\" },\n      { name: \"loading\", title: \"A long task\", description: \"The duck builds while the job runs, in a card (`layout=\\\"inline\\\"`).\" },\n      { name: \"welcome\", title: \"Welcome\", description: \"An onboarding's first screen: the falcon keeps the account safe.\" },\n    ],\n  },\n  native: {\n    imports: [\"MascotState\", \"ErrorState\", \"SuccessState\", \"LoadingState\", \"WelcomeState\"],\n    differences: [\"`title` and `description` are strings; the action is a native `Button`.\", \"No `framed` and no `titleAs`: style with `style`.\", \"Only the idle bob and a fade-in: the web gestures (wave, dots, hop) stay on the web.\"],\n    examples: [{ name: \"default\", title: \"Default\", description: \"A payment received (flamingo) and a verification that failed (falcon).\" }],\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  | \"action-bar\"\n  | \"alert\"\n  | \"argument-card\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"card-grid\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"code-block\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"cta-panel\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"decision-list\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"link-card\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascot-quote\"\n  | \"mascot-state\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page\"\n  | \"page-header\"\n  | \"page-hero\"\n  | \"pagination\"\n  | \"pointer-light\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"terminal-replay\"\n  | \"theme\"\n  | \"toast\"\n  | \"toc\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\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/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"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  /**\n   * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n   * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n   */\n  readonly entry?: string;\n  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\n}\n\nexport interface KeyboardInteraction {\n  /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n  readonly keys: string;\n  /** What they do. */\n  readonly action: string;\n}\n\nexport interface ComponentMeta {\n  /** The display name: `Button`, `Dropdown menu`. */\n  readonly title: string;\n  /** One sentence: what it is. */\n  readonly summary: string;\n  readonly status: Status;\n  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": [
+    "tailwind-variants@^3.3.1"
+  ],
+  "registryDependencies": [
+    "mascots"
+  ],
+  "demo": {
+    "path": "examples/mascot-state/empty.tsx",
+    "content": "import { Button } from \"@krizaka/ui/button\";\nimport { MascotState } from \"@krizaka/ui/mascot-state\";\n\n// An empty inbox: the pigeon has nothing to deliver yet; the action fills it.\nexport default function MascotStateEmpty() {\n  return (\n    <MascotState\n      bird=\"pigeon\"\n      framed\n      className=\"w-96\"\n      title=\"No messages yet\"\n      description=\"Answer a challenge or tip a creator to start a conversation.\"\n      action={\n        <Button variant=\"primary\" size=\"sm\">\n          Find creators\n        </Button>\n      }\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "ErrorState",
+      "description": "It failed: what went wrong and what to do (`role=\"alert\"`). `MascotState` with `mood=\"error\"`.",
+      "props": [
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What happened, in a few words (\"No videos yet\", \"Payment received\").",
+          "required": true
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What to do next: a Button, a link. One, at most two.",
+          "required": false
+        },
+        {
+          "name": "animated",
+          "type": "boolean",
+          "default": null,
+          "description": "The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`.",
+          "required": false
+        },
+        {
+          "name": "bird",
+          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+          "default": null,
+          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+          "required": false
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "default": null,
+          "description": "Why, or what comes next.",
+          "required": false
+        },
+        {
+          "name": "framed",
+          "type": "boolean",
+          "default": null,
+          "description": "A dashed frame on the raised surface, for an empty list or panel.",
+          "required": false
+        },
+        {
+          "name": "layout",
+          "type": "\"inline\" | \"stacked\"",
+          "default": null,
+          "description": "`stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form.",
+          "required": false
+        },
+        {
+          "name": "size",
+          "type": "\"sm\" | \"md\" | \"lg\"",
+          "default": null,
+          "description": "The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px.",
+          "required": false
+        },
+        {
+          "name": "titleAs",
+          "type": "\"h1\" | \"h2\" | \"h3\" | \"p\"",
+          "default": null,
+          "description": "The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page.",
+          "required": false
+        },
+        {
+          "name": "tone",
+          "type": "MascotTone",
+          "default": null,
+          "description": "`brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story.",
+          "required": false
+        }
+      ]
+    },
+    {
+      "component": "LoadingState",
+      "description": "A long task runs (`aria-busy`): what runs, beside the bird. `MascotState` with `mood=\"thinking\"`.",
+      "props": [
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What happened, in a few words (\"No videos yet\", \"Payment received\").",
+          "required": true
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What to do next: a Button, a link. One, at most two.",
+          "required": false
+        },
+        {
+          "name": "animated",
+          "type": "boolean",
+          "default": null,
+          "description": "The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`.",
+          "required": false
+        },
+        {
+          "name": "bird",
+          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+          "default": null,
+          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+          "required": false
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "default": null,
+          "description": "Why, or what comes next.",
+          "required": false
+        },
+        {
+          "name": "framed",
+          "type": "boolean",
+          "default": null,
+          "description": "A dashed frame on the raised surface, for an empty list or panel.",
+          "required": false
+        },
+        {
+          "name": "layout",
+          "type": "\"inline\" | \"stacked\"",
+          "default": null,
+          "description": "`stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form.",
+          "required": false
+        },
+        {
+          "name": "size",
+          "type": "\"sm\" | \"md\" | \"lg\"",
+          "default": null,
+          "description": "The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px.",
+          "required": false
+        },
+        {
+          "name": "titleAs",
+          "type": "\"h1\" | \"h2\" | \"h3\" | \"p\"",
+          "default": null,
+          "description": "The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page.",
+          "required": false
+        },
+        {
+          "name": "tone",
+          "type": "MascotTone",
+          "default": null,
+          "description": "`brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story.",
+          "required": false
+        }
+      ]
+    },
+    {
+      "component": "MascotState",
+      "description": "A moment told by a bird of the flock: an empty list, a long wait, a success, an error, a welcome. Announced to\nassistive technology — `role=\"alert\"` for an error, `role=\"status\"` otherwise (`aria-busy` while thinking).",
+      "props": [
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What happened, in a few words (\"No videos yet\", \"Payment received\").",
+          "required": true
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What to do next: a Button, a link. One, at most two.",
+          "required": false
+        },
+        {
+          "name": "animated",
+          "type": "boolean",
+          "default": "true",
+          "description": "The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`.",
+          "required": false
+        },
+        {
+          "name": "bird",
+          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+          "default": "owl",
+          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+          "required": false
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "default": null,
+          "description": "Why, or what comes next.",
+          "required": false
+        },
+        {
+          "name": "framed",
+          "type": "boolean",
+          "default": null,
+          "description": "A dashed frame on the raised surface, for an empty list or panel.",
+          "required": false
+        },
+        {
+          "name": "layout",
+          "type": "\"inline\" | \"stacked\"",
+          "default": null,
+          "description": "`stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form.",
+          "required": false
+        },
+        {
+          "name": "mood",
+          "type": "\"success\" | \"error\" | \"empty\" | \"welcome\" | \"thinking\"",
+          "default": "empty",
+          "description": "The moment: `empty` (nothing yet), `thinking` (a long task runs), `success` (done), `error` (it failed), `welcome`.",
+          "required": false
+        },
+        {
+          "name": "size",
+          "type": "\"sm\" | \"md\" | \"lg\"",
+          "default": "md",
+          "description": "The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px.",
+          "required": false
+        },
+        {
+          "name": "titleAs",
+          "type": "\"h1\" | \"h2\" | \"h3\" | \"p\"",
+          "default": "p",
+          "description": "The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page.",
+          "required": false
+        },
+        {
+          "name": "tone",
+          "type": "MascotTone",
+          "default": null,
+          "description": "`brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story.",
+          "required": false
+        }
+      ]
+    },
+    {
+      "component": "SuccessState",
+      "description": "It is done: a payment, a verification, a delivery, a sent message. `MascotState` with `mood=\"success\"`.",
+      "props": [
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What happened, in a few words (\"No videos yet\", \"Payment received\").",
+          "required": true
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What to do next: a Button, a link. One, at most two.",
+          "required": false
+        },
+        {
+          "name": "animated",
+          "type": "boolean",
+          "default": null,
+          "description": "The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`.",
+          "required": false
+        },
+        {
+          "name": "bird",
+          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+          "default": null,
+          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+          "required": false
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "default": null,
+          "description": "Why, or what comes next.",
+          "required": false
+        },
+        {
+          "name": "framed",
+          "type": "boolean",
+          "default": null,
+          "description": "A dashed frame on the raised surface, for an empty list or panel.",
+          "required": false
+        },
+        {
+          "name": "layout",
+          "type": "\"inline\" | \"stacked\"",
+          "default": null,
+          "description": "`stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form.",
+          "required": false
+        },
+        {
+          "name": "size",
+          "type": "\"sm\" | \"md\" | \"lg\"",
+          "default": null,
+          "description": "The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px.",
+          "required": false
+        },
+        {
+          "name": "titleAs",
+          "type": "\"h1\" | \"h2\" | \"h3\" | \"p\"",
+          "default": null,
+          "description": "The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page.",
+          "required": false
+        },
+        {
+          "name": "tone",
+          "type": "MascotTone",
+          "default": null,
+          "description": "`brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story.",
+          "required": false
+        }
+      ]
+    },
+    {
+      "component": "WelcomeState",
+      "description": "A first screen, an onboarding step. `MascotState` with `mood=\"welcome\"`.",
+      "props": [
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What happened, in a few words (\"No videos yet\", \"Payment received\").",
+          "required": true
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "default": null,
+          "description": "What to do next: a Button, a link. One, at most two.",
+          "required": false
+        },
+        {
+          "name": "animated",
+          "type": "boolean",
+          "default": null,
+          "description": "The bird's gesture and the staged arrival. Off with `false`; always off under `prefers-reduced-motion`.",
+          "required": false
+        },
+        {
+          "name": "bird",
+          "type": "\"falcon\" | \"owl\" | \"duck\" | \"flamingo\" | \"pigeon\" | \"lovebird\"",
+          "default": null,
+          "description": "The bird whose job the moment is about: `owl` (documents, reading), `falcon` (security, verification), `duck`\n(code, building), `flamingo` (answers, payments), `pigeon` (delivery, notifications), `lovebird` (introductions). One bird per idea.",
+          "required": false
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "default": null,
+          "description": "Why, or what comes next.",
+          "required": false
+        },
+        {
+          "name": "framed",
+          "type": "boolean",
+          "default": null,
+          "description": "A dashed frame on the raised surface, for an empty list or panel.",
+          "required": false
+        },
+        {
+          "name": "layout",
+          "type": "\"inline\" | \"stacked\"",
+          "default": null,
+          "description": "`stacked` (default): the bird above centred words — a page, a panel. `inline`: the bird beside the words — a card, a row of a form.",
+          "required": false
+        },
+        {
+          "name": "size",
+          "type": "\"sm\" | \"md\" | \"lg\"",
+          "default": null,
+          "description": "The bird's size: `sm` 64 px, `md` 96 px (default), `lg` 128 px.",
+          "required": false
+        },
+        {
+          "name": "titleAs",
+          "type": "\"h1\" | \"h2\" | \"h3\" | \"p\"",
+          "default": null,
+          "description": "The level of the title (default `p`): `h1` on a full page (a 404), `h2`/`h3` inside a page.",
+          "required": false
+        },
+        {
+          "name": "tone",
+          "type": "MascotTone",
+          "default": null,
+          "description": "`brand` (default): the product's accent. `own`: the bird's colours of the Krizaka story.",
+          "required": false
+        }
+      ]
+    }
+  ]
+}