@sakaniui/react 0.8.7 → 0.8.9

package/dist/manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://www.sakaniui.com/manifest.schema.json",
-  "schemaVersion": 1,
+  "schemaVersion": 3,
   "name": "@sakaniui/react",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "Machine-readable contract of the SakaniUI React library, generated from its TypeScript source.",
   "docs": "https://www.sakaniui.com",
   "guide": "https://www.sakaniui.com/llms-full.txt",
@@ -24,13 +24,16 @@
     "@sakaniui/react/icons": "Tabler icons: IconName and IconNameFilled, one module each (5184 outline, 1054 filled)."
   },
   "conventions": {
+    "version": "This manifest describes @sakaniui/react@0.8.9. Each component has `since`, the first release that contained it: if the project has an older version installed, a component or prop that is newer than that does not exist there.",
     "acceptsNativeProps": "Components forward native HTML attributes (className, style, aria-*, event handlers) to their root element unless a prop says otherwise; only the props that are specific to SakaniUI are listed here.",
     "accessibleName": "When `contract.requiresAccessibleName` is true, a required prop (aria-label, aria-labelledby or an alt text) is the only thing that names the control or image. Do not omit it.",
     "tokens": "Use only the token names listed under `tokens`. Colour tokens follow the theme (the `.dark` class flips them); do not hard-code colours.",
-    "icons": "Icon props take the component itself (IconSettings), not an element (<IconSettings />)."
+    "icons": "Icon props take the component itself (IconSettings), not an element (<IconSettings />). Only names in icon-index.json exist; search them (MCP: search_icons) instead of guessing.",
+    "examples": "Each component has `example`: its imports and the element with every required prop filled in, type-checked against this build. Start from it.",
+    "literals": "Prop `values` keep their real type: a number is a number (columns: 2), a string is a string (\"md\")."
   },
   "tokens": {
-    "count": 182,
+    "count": 231,
     "groups": {
       "bp": {
         "--bp-sm": "640px",
@@ -235,12 +238,68 @@
         "--transition-fast": "var(--motion-fast) var(--ease-in-out)",
         "--transition-slow": "var(--motion-slow) var(--ease-in-out)",
         "--transition-hover": "var(--motion-slow) var(--ease-out)"
+      },
+      "glass": {
+        "--glass-bg": "rgba(255, 255, 255, 0.64)",
+        "--glass-bg-overlay": "rgba(255, 255, 255, 0.76)",
+        "--glass-bg-chrome": "rgba(255, 255, 255, 0.52)",
+        "--glass-bg-subtle": "rgba(16, 15, 12, 0.05)",
+        "--glass-bg-subtle-hover": "rgba(16, 15, 12, 0.09)",
+        "--glass-border": "rgba(255, 255, 255, 0.55)",
+        "--glass-border-strong": "rgba(255, 255, 255, 0.75)",
+        "--glass-highlight": "inset 0 1px 0 0 rgba(255, 255, 255, 0.7)",
+        "--glass-fg-muted": "var(--color-neutral-600)",
+        "--glass-blur": "blur(16px) saturate(160%)",
+        "--glass-blur-overlay": "blur(24px) saturate(180%)"
+      },
+      "surface": {
+        "--surface-bg": "var(--color-bg-surface)",
+        "--surface-bg-overlay": "var(--color-bg-surface)",
+        "--surface-bg-chrome": "transparent",
+        "--surface-bg-subtle": "var(--color-bg-subtle)",
+        "--surface-bg-subtle-hover": "var(--color-bg-muted)",
+        "--surface-border": "var(--color-border-subtle)",
+        "--surface-border-strong": "var(--color-border-default)",
+        "--surface-highlight": "0 0 #0000",
+        "--surface-blur": "none",
+        "--surface-blur-overlay": "none",
+        "--surface-fg-muted": "var(--color-fg-muted)"
+      },
+      "liquid": {
+        "--liquid-tint-regular": "rgba(255, 255, 255, 0.66)",
+        "--liquid-tint-clear": "rgba(255, 255, 255, 0.28)",
+        "--liquid-tint-subtle": "rgba(16, 15, 12, 0.05)",
+        "--liquid-overlay-tint": "var(--liquid-tint-subtle)",
+        "--liquid-panel-tint": "rgba(255, 255, 255, 0.76)",
+        "--liquid-refraction-regular": "0.55",
+        "--liquid-refraction-clear": "0.8",
+        "--liquid-depth-regular": "16",
+        "--liquid-depth-clear": "20",
+        "--liquid-dispersion-regular": "0.3",
+        "--liquid-dispersion-clear": "0.4",
+        "--liquid-frost-regular": "4",
+        "--liquid-frost-clear": "1",
+        "--liquid-light-intensity-regular": "0.7",
+        "--liquid-light-intensity-clear": "0.8",
+        "--liquid-light-angle": "-45",
+        "--liquid-fallback-blur": "blur(14px) saturate(180%)",
+        "--liquid-lx": "sin(calc(var(--liquid-light-angle) * 1deg))",
+        "--liquid-ly": "calc(-1 * cos(calc(var(--liquid-light-angle) * 1deg)))",
+        "--liquid-rim": "rgba(255, 255, 255, 0.5)",
+        "--liquid-rim-soft": "rgba(255, 255, 255, 0.47)",
+        "--liquid-rim-far-soft": "rgba(255, 255, 255, 0.27)",
+        "--liquid-rim-far": "rgba(255, 255, 255, 0.25)",
+        "--liquid-edge-shade": "inset calc(var(--liquid-lx) * -4px) calc(var(--liquid-ly) * -4px) 8px 1px rgba(0, 0, 0, 0.1), inset calc(var(--liquid-lx) * 4px) calc(var(--liquid-ly) * 4px) 8px 1px rgba(255, 255, 255, 0.07)",
+        "--liquid-shadow-regular": "0 6px 12px -6px rgba(16, 15, 12, 0.16), 0 2px 4px rgba(16, 15, 12, 0.08)",
+        "--liquid-shadow-clear": "0 3px 8px -4px rgba(16, 15, 12, 0.16), 0 1px 3px rgba(16, 15, 12, 0.08)",
+        "--liquid-glare": "rgba(255, 255, 255, 0.35)"
       }
     }
   },
   "counts": {
-    "components": 123,
-    "blocks": 42
+    "components": 126,
+    "blocks": 42,
+    "utilities": 6
   },
   "components": [
     {
@@ -248,8 +307,7 @@
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Accordion/Accordion.tsx",
-      "summary": "Collapsible content sections. Matches Figma \"Accordion Item\" set (Closed|Open) plus the \"Accordion\" wrapper component.",
+      "summary": "Collapsible content sections.",
       "props": [
         {
           "name": "className",
@@ -260,15 +318,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Accordion } from '@sakaniui/react';\n\n<Accordion>Label</Accordion>"
     },
     {
       "name": "AccordionItem",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Accordion/Accordion.tsx",
-      "summary": "Collapsible content sections. Matches Figma \"Accordion Item\" set (Closed|Open) plus the \"Accordion\" wrapper component.",
+      "summary": "One collapsible item of an Accordion; `open` / `defaultOpen` control it.",
       "props": [
         {
           "name": "title",
@@ -285,7 +344,7 @@
           "name": "defaultOpen",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Uncontrolled initial open state."
         },
         {
@@ -299,15 +358,16 @@
           "title"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { AccordionItem } from '@sakaniui/react';\n\n<AccordionItem title=\"Title\">Label</AccordionItem>"
     },
     {
       "name": "ActivityFeed",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/ActivityFeed/ActivityFeed.tsx",
-      "summary": "Timeline of recent activity. Matches Figma \"Activity Feed\": Style: Default — icon-in-circle rail with a connector stub between dots, content wraps onto multiple lines if long.",
+      "summary": "Timeline of recent activity.",
       "props": [
         {
           "name": "items",
@@ -335,28 +395,30 @@
           "items"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { ActivityFeed } from '@sakaniui/react';\n\n<ActivityFeed items={[{ actor: \"Actor\", description: \"Description\", timestamp: \"2 min ago\" }]} />"
     },
     {
       "name": "ActivityFeedHighlight",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/ActivityFeed/ActivityFeed.tsx",
-      "summary": "Timeline of recent activity. Matches Figma \"Activity Feed\": Style: Default — icon-in-circle rail with a connector stub between dots, content wraps onto multiple lines if long.",
+      "summary": "Emphasised inline text (a name, a file, a page) inside an ActivityFeed item description.",
       "props": [],
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { ActivityFeedHighlight } from '@sakaniui/react';\n\n<ActivityFeedHighlight>Label</ActivityFeedHighlight>"
     },
     {
       "name": "Alert",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Alert/Alert.tsx",
-      "summary": "Inline status message. Matches Figma \"Alert\" set: Color (Info|Success|Warning|Danger|Neutral), Title/Description toggles.",
+      "summary": "Inline status message.",
       "props": [
         {
           "name": "color",
@@ -369,8 +431,7 @@
             "danger",
             "neutral"
           ],
-          "default": "info",
-          "description": "Figma Color axis. Defaults to \"info\"."
+          "default": "info"
         },
         {
           "name": "title",
@@ -397,14 +458,15 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Alert } from '@sakaniui/react';\n\n<Alert />"
     },
     {
       "name": "Announcement",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/Announcement/Announcement.tsx",
       "summary": "Full-width announcement bar.",
       "props": [
         {
@@ -455,15 +517,16 @@
           "message"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Announcement } from '@sakaniui/react';\n\n<Announcement message=\"Message\" />"
     },
     {
       "name": "AreaChart",
       "kind": "component",
       "category": "Charts",
       "import": "@sakaniui/react",
-      "source": "src/components/AreaChart/AreaChart.tsx",
-      "summary": "Recharts wrapper styled with Sakani chart tokens. Matches Figma \"Area Chart\" (type: Default | Stacked | Step | Linear, each with an optional second series).",
+      "summary": "An area chart (Recharts) styled with Sakani chart tokens; `variant` is \"default\", \"stacked\", \"step\" or \"linear\".",
       "props": [
         {
           "name": "data",
@@ -517,14 +580,15 @@
           "data"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { AreaChart } from '@sakaniui/react';\n\n<AreaChart data={[{ label: \"Label\", value: 50 }]} />"
     },
     {
       "name": "Avatar",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/Avatar/Avatar.tsx",
       "summary": "User/entity avatar.",
       "props": [
         {
@@ -537,8 +601,7 @@
             "lg",
             "xl"
           ],
-          "default": "md",
-          "description": "Figma AV axis. Defaults to \"md\"."
+          "default": "md"
         },
         {
           "name": "src",
@@ -574,15 +637,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Avatar } from '@sakaniui/react';\n\n<Avatar />"
     },
     {
       "name": "AvatarGroup",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/AvatarGroup/AvatarGroup.tsx",
-      "summary": "Overlapping stack of avatars with an optional \"+N\" overflow chip. Figma \"Avatar Group\" is a single composed component; this renders a flexible group from Avatar children with a ring gap so they read as a stack.",
+      "summary": "Overlapping stack of avatars with an optional \"+N\" overflow chip.",
       "props": [
         {
           "name": "size",
@@ -601,7 +665,7 @@
           "name": "max",
           "type": "number",
           "required": false,
-          "default": "4",
+          "default": 4,
           "description": "Max avatars to show before collapsing into a +N chip."
         },
         {
@@ -621,15 +685,16 @@
           "avatars"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { AvatarGroup } from '@sakaniui/react';\n\n<AvatarGroup avatars={[{}]} />"
     },
     {
       "name": "AvatarUpload",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/AvatarUpload/AvatarUpload.tsx",
-      "summary": "Profile photo picker. Matches Figma \"Avatar Upload\": Orientation: Vertical — big (64px) avatar with a camera badge overlapping its bottom-right corner, text or a \"Change photo\" link below.",
+      "summary": "Profile photo picker.",
       "props": [
         {
           "name": "src",
@@ -692,14 +757,15 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { AvatarUpload } from '@sakaniui/react';\n\n<AvatarUpload />"
     },
     {
       "name": "Badge",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/Badge/Badge.tsx",
       "summary": "Compact label for status, category, or count.",
       "props": [
         {
@@ -715,7 +781,7 @@
             "accent"
           ],
           "default": "neutral",
-          "description": "Color scheme. Maps to Figma BD axis. Defaults to \"neutral\"."
+          "description": "Color scheme. Defaults to \"neutral\"."
         },
         {
           "name": "emphasis",
@@ -726,7 +792,7 @@
             "solid"
           ],
           "default": "subtle",
-          "description": "Fill strength. Maps to Figma Emphasis axis. Defaults to \"subtle\"."
+          "description": "Fill strength. Defaults to \"subtle\"."
         },
         {
           "name": "leftIcon",
@@ -747,14 +813,15 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Badge } from '@sakaniui/react';\n\n<Badge>Label</Badge>"
     },
     {
       "name": "Balance",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/Balance/Balance.tsx",
       "summary": "Prominent balance display.",
       "props": [
         {
@@ -801,15 +868,16 @@
           "value"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Balance } from '@sakaniui/react';\n\n<Balance value=\"Value\" />"
     },
     {
       "name": "BarChart",
       "kind": "component",
       "category": "Charts",
       "import": "@sakaniui/react",
-      "source": "src/components/BarChart/BarChart.tsx",
-      "summary": "Recharts wrapper styled with Sakani chart tokens.",
+      "summary": "A bar chart (Recharts) styled with Sakani chart tokens; `variant` is \"default\", \"horizontal\", \"stacked\", \"active\", \"multiple\" or \"negative\".",
       "props": [
         {
           "name": "data",
@@ -860,15 +928,16 @@
           "data"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { BarChart } from '@sakaniui/react';\n\n<BarChart data={[{ label: \"Label\", value: 50 }]} />"
     },
     {
       "name": "BlogBlockquote",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/BlogBlockquote/BlogBlockquote.tsx",
-      "summary": "Matches Figma \"Blog Blockquote\" (Marketing primitives set, first of the category): a left vertical Divider rail + quote text.",
+      "summary": "A blog pull quote: a vertical rail beside the quote text. Passing `author` switches to the attributed card style.",
       "props": [
         {
           "name": "quote",
@@ -892,15 +961,16 @@
           "quote"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { BlogBlockquote } from '@sakaniui/react';\n\n<BlogBlockquote quote=\"Quote\" />"
     },
     {
       "name": "BlogFeatureText",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/BlogFeatureText/BlogFeatureText.tsx",
-      "summary": "Matches Figma \"Blog Feature Text\" (Marketing primitives set): a brand-colored accent rule + a pulled-out heading/md line of body copy.",
+      "summary": "A pulled-out line of blog body copy beside a brand-coloured accent rule; `align` is \"left\" (vertical rule) or \"top\".",
       "props": [
         {
           "name": "text",
@@ -915,8 +985,7 @@
             "left",
             "top"
           ],
-          "default": "left",
-          "description": "Figma Align axis. Defaults to \"left\"."
+          "default": "left"
         },
         {
           "name": "className",
@@ -929,15 +998,16 @@
           "text"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { BlogFeatureText } from '@sakaniui/react';\n\n<BlogFeatureText text=\"Text\" />"
     },
     {
       "name": "BlogImage",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/BlogImage/BlogImage.tsx",
-      "summary": "Matches Figma \"Blog Image\" (Marketing primitives set, 4 previews: Style (Default/With Caption) x Size (Large/Small)).",
+      "summary": "A blog article image with an optional caption (shown when `caption` is set); `size` is \"large\" or \"small\".",
       "props": [
         {
           "name": "src",
@@ -958,8 +1028,7 @@
             "large",
             "small"
           ],
-          "default": "large",
-          "description": "Figma Size axis. Defaults to \"large\"."
+          "default": "large"
         },
         {
           "name": "caption",
@@ -978,15 +1047,16 @@
           "src"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { BlogImage } from '@sakaniui/react';\n\n<BlogImage src=\"/images/example.jpg\" />"
     },
     {
       "name": "BlogListingCard",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/BlogListingCard/BlogListingCard.tsx",
-      "summary": "Matches Figma \"Blog Listing Card\" (Marketing primitives set, 2 style previews: Default, Horizontal).",
+      "summary": "A blog post card with image, category, read time, title, excerpt and author. `layout` is \"default\" (image on top) or \"horizontal\" (square image on the left).",
       "props": [
         {
           "name": "image",
@@ -1032,8 +1102,7 @@
             "default",
             "horizontal"
           ],
-          "default": "default",
-          "description": "Figma Style axis. Defaults to \"default\"."
+          "default": "default"
         },
         {
           "name": "className",
@@ -1051,15 +1120,16 @@
           "author"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { BlogListingCard } from '@sakaniui/react';\n\n<BlogListingCard image=\"/images/example.jpg\" category=\"Category\" readTime=\"5 min read\" title=\"Title\" excerpt=\"Excerpt\" author={{ name: \"Name\", date: \"Oct 21, 2026\" }} />"
     },
     {
       "name": "BlogListingFeaturedCard",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/BlogListingFeaturedCard/BlogListingFeaturedCard.tsx",
-      "summary": "Matches Figma \"Blog Listing Featured Card\" (Marketing primitives set, 2 orientations: Horizontal, Vertical).",
+      "summary": "A featured blog post card with image, optional badge, title, excerpt, author and a call to action; `orientation` is \"vertical\" or \"horizontal\".",
       "props": [
         {
           "name": "image",
@@ -1075,8 +1145,7 @@
           "name": "badgeLabel",
           "type": "string",
           "required": false,
-          "default": "Featured",
-          "description": "Defaults to \"Featured\", matching this card's own purpose."
+          "default": "Featured"
         },
         {
           "name": "title",
@@ -1112,8 +1181,7 @@
             "vertical",
             "horizontal"
           ],
-          "default": "horizontal",
-          "description": "Figma Orientation axis. Defaults to \"horizontal\"."
+          "default": "horizontal"
         },
         {
           "name": "className",
@@ -1129,14 +1197,15 @@
           "author"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { BlogListingFeaturedCard } from '@sakaniui/react';\n\n<BlogListingFeaturedCard image=\"/images/example.jpg\" title=\"Title\" excerpt=\"Excerpt\" author={{ name: \"Name\", date: \"Oct 21, 2026\" }} />"
     },
     {
       "name": "BoardCard",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/BoardCard/BoardCard.tsx",
       "summary": "Flexible board/list card.",
       "props": [
         {
@@ -1226,14 +1295,15 @@
           "title"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { BoardCard } from '@sakaniui/react';\n\n<BoardCard title=\"Title\" />"
     },
     {
       "name": "BoardColumn",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/BoardColumn/BoardColumn.tsx",
       "summary": "One Kanban column.",
       "props": [
         {
@@ -1292,15 +1362,16 @@
           "title"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { BoardColumn } from '@sakaniui/react';\n\n<BoardColumn title=\"Title\" />"
     },
     {
       "name": "Breadcrumb",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Breadcrumb/Breadcrumb.tsx",
-      "summary": "Navigation trail. Matches Figma \"Breadcrumb\" set (1–6 crumbs) x Type: Text — plain inline links, gap 6, chevron 16px. crumbs fg/muted, current crumb fg/default + medium, underline on link hover.",
+      "summary": "A navigation trail of one to six crumbs; `variant` is \"text\" (inline links) or \"button\".",
       "props": [
         {
           "name": "items",
@@ -1328,15 +1399,16 @@
           "items"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Breadcrumb } from '@sakaniui/react';\n\n<Breadcrumb items={[{ label: \"Label\" }]} />"
     },
     {
       "name": "Button",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/Button/Button.tsx",
-      "summary": "The primary action primitive for the SakaniUI. Maps 1:1 with the Figma \"Button\" component set (45 variants).",
+      "summary": "The primary action primitive for the SakaniUI.",
       "props": [
         {
           "name": "variant",
@@ -1380,7 +1452,7 @@
           "name": "loading",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Render the button in a loading state (disables interaction)."
         },
         {
@@ -1395,14 +1467,15 @@
           "children"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Button } from '@sakaniui/react';\n\n<Button>Label</Button>"
     },
     {
       "name": "Calendar",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Calendar/Calendar.tsx",
       "summary": "Month calendar / date picker.",
       "props": [
         {
@@ -1446,8 +1519,7 @@
             "arrows",
             "dropdowns"
           ],
-          "default": "arrows",
-          "description": "Header style (Figma: Calendar Header Type). Defaults to \"arrows\"."
+          "default": "arrows"
         },
         {
           "name": "defaultMonth",
@@ -1474,15 +1546,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Calendar } from '@sakaniui/react';\n\n<Calendar />"
     },
     {
       "name": "Card",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Card/Card.tsx",
-      "summary": "Container surface. Matches Figma \"Card\" set: Variant (Default|Hover|Two buttons|Three buttons), Title/Description/CTA toggles.",
+      "summary": "Container surface.",
       "props": [
         {
           "name": "title",
@@ -1498,19 +1571,17 @@
           "name": "actions",
           "type": "ReactNode",
           "required": false,
-          "description": "Footer action buttons (maps to Figma CTA / Two buttons variants). Hugs left."
+          "description": "Hugs left."
         },
         {
           "name": "leadingAction",
           "type": "ReactNode",
-          "required": false,
-          "description": "A standalone action opposite `actions` (maps to Figma's Three buttons Ghost button) -- providing it switches the footer to space-between."
+          "required": false
         },
         {
           "name": "interactive",
           "type": "boolean",
-          "required": false,
-          "description": "Enables the hover elevation (Figma: Hover)."
+          "required": false
         },
         {
           "name": "className",
@@ -1521,15 +1592,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Card } from '@sakaniui/react';\n\n<Card />"
     },
     {
       "name": "CardMetaItem",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/CardMetaItem/CardMetaItem.tsx",
-      "summary": "Icon + value pair used in the BoardCard footer (due date, comments, attachments, links, subtask progress). Matches the Figma \"Card Meta Item\" component, whose `icon` (instance-swap) and `label` (text) map to these props.",
+      "summary": "Icon + value pair used in the BoardCard footer (due date, comments, attachments, links, subtask progress).",
       "props": [
         {
           "name": "icon",
@@ -1548,15 +1620,16 @@
           "icon"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { CardMetaItem } from '@sakaniui/react';\n\n<CardMetaItem icon=\"Icon\">Label</CardMetaItem>"
     },
     {
       "name": "CartItem",
       "kind": "component",
       "category": "E-commerce",
       "import": "@sakaniui/react",
-      "source": "src/components/ECommerceComponents/CartItem/CartItem.tsx",
-      "summary": "Matches Figma \"Cart Item\" (E-commerce set): thumbnail + name/variant/ quantity stepper -> price + remove button, right-aligned.",
+      "summary": "A cart row: thumbnail, name and variant, quantity stepper, price and a remove button. Passing `compareAtPrice` shows the sale treatment.",
       "props": [
         {
           "name": "image",
@@ -1604,7 +1677,7 @@
           "name": "minQuantity",
           "type": "number",
           "required": false,
-          "default": "1"
+          "default": 1
         },
         {
           "name": "maxQuantity",
@@ -1625,8 +1698,7 @@
         {
           "name": "formatPrice",
           "type": "((amount: number) => string)",
-          "required": false,
-          "default": "(amount: number) =>\n  amount.toLocaleString('en-US', { style: 'currency', currency: 'USD' })"
+          "required": false
         },
         {
           "name": "className",
@@ -1642,15 +1714,16 @@
           "quantity"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { CartItem } from '@sakaniui/react';\n\n<CartItem image=\"/images/example.jpg\" name=\"Name\" price={49} quantity={1} />"
     },
     {
       "name": "ChatComposer",
       "kind": "component",
       "category": "Chat",
       "import": "@sakaniui/react",
-      "source": "src/components/ChatComposer/ChatComposer-simple.tsx",
-      "summary": "",
+      "summary": "Message input for a chat thread: attach, text input, emoji and send, with default, typing, uploading and disabled states.",
       "props": [
         {
           "name": "state",
@@ -1694,7 +1767,7 @@
           "name": "uploadProgress",
           "type": "number",
           "required": false,
-          "default": "0"
+          "default": 0
         },
         {
           "name": "onCancelUpload",
@@ -1710,15 +1783,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { ChatComposer } from '@sakaniui/react';\n\n<ChatComposer />"
     },
     {
       "name": "Checkbox",
       "kind": "component",
       "category": "Forms",
       "import": "@sakaniui/react",
-      "source": "src/components/Checkbox/Checkbox.tsx",
-      "summary": "Matches Figma \"Checkbox\" set: Unchecked | Checked | Indeterminate | Disabled, with Title/Description toggles (label + description props).",
+      "summary": "Checkbox with optional label and description; supports checked, indeterminate and disabled states.",
       "props": [
         {
           "name": "label",
@@ -1740,15 +1814,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Checkbox } from '@sakaniui/react';\n\n<Checkbox />"
     },
     {
       "name": "CheckoutSteps",
       "kind": "component",
       "category": "E-commerce",
       "import": "@sakaniui/react",
-      "source": "src/components/ECommerceComponents/CheckoutSteps/CheckoutSteps.tsx",
-      "summary": "Matches Figma \"Checkout Steps\" (E-commerce set): a fixed-width horizontal breadcrumb of 24px circles joined by fixed 32px connector lines -- Cart / Shipping / Payment / Confirmation by default.",
+      "summary": "A horizontal checkout breadcrumb of numbered steps (Cart, Shipping, Payment, Confirmation by default). `currentStep` marks earlier steps completed and later ones upcoming.",
       "props": [
         {
           "name": "steps",
@@ -1773,14 +1848,15 @@
           "currentStep"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { CheckoutSteps } from '@sakaniui/react';\n\n<CheckoutSteps currentStep={1} />"
     },
     {
       "name": "CodeSnippet",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/CodeSnippet/CodeSnippet.tsx",
       "summary": "Code block.",
       "props": [
         {
@@ -1803,7 +1879,7 @@
           "name": "editable",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Lets people type directly into the block. Defaults to false (read-only)."
         },
         {
@@ -1829,15 +1905,16 @@
           "code"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { CodeSnippet } from '@sakaniui/react';\n\n<CodeSnippet code=\"Code\" />"
     },
     {
       "name": "ColorSwatch",
       "kind": "component",
       "category": "E-commerce",
       "import": "@sakaniui/react",
-      "source": "src/components/ECommerceComponents/ColorSwatch/ColorSwatch.tsx",
-      "summary": "Matches Figma \"Color Swatch\" (E-commerce set): a 24px filled circle in a 32px hit target.",
+      "summary": "A round colour choice for product variants. `selected` marks the chosen one; `available={false}` marks it out of stock.",
       "props": [
         {
           "name": "color",
@@ -1855,13 +1932,13 @@
           "name": "selected",
           "type": "boolean",
           "required": false,
-          "default": "false"
+          "default": false
         },
         {
           "name": "available",
           "type": "boolean",
           "required": false,
-          "default": "true",
+          "default": true,
           "description": "Defaults to true. False renders a disabled, unclickable swatch."
         },
         {
@@ -1881,14 +1958,15 @@
           "label"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { ColorSwatch } from '@sakaniui/react';\n\n<ColorSwatch color=\"var(--color-accent-default)\" label=\"Label\" />"
     },
     {
       "name": "Combobox",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Combobox/Combobox.tsx",
       "summary": "Searchable select with single or multi-select.",
       "props": [
         {
@@ -1946,8 +2024,7 @@
         {
           "name": "loading",
           "type": "boolean",
-          "required": false,
-          "description": "Shows the panel's loading state (Figma: Panel State=Loading)."
+          "required": false
         },
         {
           "name": "value",
@@ -1971,14 +2048,15 @@
           "options"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Combobox } from '@sakaniui/react';\n\n<Combobox options={[{ value: \"Value\", label: \"Label\" }]} />"
     },
     {
       "name": "ConversationItem",
       "kind": "component",
       "category": "Chat",
       "import": "@sakaniui/react",
-      "source": "src/components/ConversationItem/ConversationItem.tsx",
       "summary": "One row in a chat conversation list.",
       "props": [
         {
@@ -2040,14 +2118,15 @@
           "name"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { ConversationItem } from '@sakaniui/react';\n\n<ConversationItem avatar=\"/images/example.jpg\" name=\"Name\" />"
     },
     {
       "name": "Divider",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/Divider/Divider.tsx",
       "summary": "Visual separator. Horizontal (default) or vertical. Optional label sits centred in the line — common for \"or\" dividers in auth forms.",
       "props": [
         {
@@ -2076,15 +2155,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Divider } from '@sakaniui/react';\n\n<Divider />"
     },
     {
       "name": "DonutChart",
       "kind": "component",
       "category": "Charts",
       "import": "@sakaniui/react",
-      "source": "src/components/DonutChart/DonutChart.tsx",
-      "summary": "Recharts wrapper styled with Sakani chart tokens. Matches Figma \"Donut Chart\" (Size sm|md|lg|xl, with center value + caption). Segments cycle through the 5 chart tokens so they re-theme in dark mode.",
+      "summary": "A donut chart (Recharts) styled with Sakani chart tokens, with an optional centre value and caption.",
       "props": [
         {
           "name": "data",
@@ -2106,14 +2186,12 @@
         {
           "name": "centerValue",
           "type": "string",
-          "required": false,
-          "description": "Big number shown in the center (Figma: value)."
+          "required": false
         },
         {
           "name": "centerCaption",
           "type": "string",
-          "required": false,
-          "description": "Small caption under the center value (Figma: caption)."
+          "required": false
         },
         {
           "name": "height",
@@ -2132,14 +2210,15 @@
           "data"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { DonutChart } from '@sakaniui/react';\n\n<DonutChart data={[{ label: \"Label\", value: 50 }]} />"
     },
     {
       "name": "EmptyState",
       "kind": "component",
       "category": "Data",
       "import": "@sakaniui/react",
-      "source": "src/components/EmptyState/EmptyState.tsx",
       "summary": "Reusable empty/error content for tables, lists, and cards.",
       "props": [
         {
@@ -2189,14 +2268,15 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { EmptyState } from '@sakaniui/react';\n\n<EmptyState />"
     },
     {
       "name": "Expenses",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/Expenses/Expenses.tsx",
       "summary": "Spending-by-category list.",
       "props": [
         {
@@ -2218,7 +2298,6 @@
           "name": "formatAmount",
           "type": "((amount: number) => string)",
           "required": false,
-          "default": "(amount: number) =>\n  amount.toLocaleString('en-US', { style: 'currency', currency: 'USD' })",
           "description": "Defaults to USD currency, 2 decimals (e.g. \"$840.20\")."
         },
         {
@@ -2232,35 +2311,37 @@
           "categories"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Expenses } from '@sakaniui/react';\n\n<Expenses categories={[{ icon: \"Icon\", label: \"Label\", amount: 49 }]} />"
     },
     {
       "name": "FacebookIcon",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/TeamCard/TeamSocialIcons.tsx",
-      "summary": "tsx).",
+      "summary": "Facebook glyph drawn in currentColor, for the `socialLinks` of TeamCard.",
       "props": [
         {
           "name": "size",
           "type": "number",
           "required": false,
-          "default": "16"
+          "default": 16
         }
       ],
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { FacebookIcon } from '@sakaniui/react';\n\n<FacebookIcon />"
     },
     {
       "name": "FeaturedIcon",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/FeaturedIcon/FeaturedIcon.tsx",
-      "summary": "Matches Figma \"Featured Icon\" (Marketing primitives set): a rounded icon chip used to headline a feature/benefit callout.",
+      "summary": "A rounded icon chip to headline a feature or benefit, in sm, md or lg and subtle, solid, outline or light styles.",
       "props": [
         {
           "name": "icon",
@@ -2276,8 +2357,7 @@
             "md",
             "lg"
           ],
-          "default": "md",
-          "description": "Figma Size axis. Defaults to \"md\"."
+          "default": "md"
         },
         {
           "name": "variant",
@@ -2289,8 +2369,7 @@
             "outline",
             "light"
           ],
-          "default": "light",
-          "description": "Figma Style axis (renamed to avoid colliding with the DOM `style` prop). Defaults to \"light\"."
+          "default": "light"
         },
         {
           "name": "className",
@@ -2303,15 +2382,16 @@
           "icon"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { FeaturedIcon } from '@sakaniui/react';\n\n<FeaturedIcon icon=\"Icon\" />"
     },
     {
       "name": "FileUpload",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/FileUpload/FileUpload.tsx",
-      "summary": "Dropzone for file uploads. Matches Figma \"File Upload\": dashed dropzone (radius-md), upload icon, \"Click to upload or drag and drop\" (label/md fg/default) + hint (body/xs fg/muted), plus an uploaded-file row.",
+      "summary": "Dropzone for file uploads.",
       "props": [
         {
           "name": "accept",
@@ -2347,14 +2427,15 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { FileUpload } from '@sakaniui/react';\n\n<FileUpload />"
     },
     {
       "name": "FilterChip",
       "kind": "component",
       "category": "Data",
       "import": "@sakaniui/react",
-      "source": "src/components/FilterChip/FilterChip.tsx",
       "summary": "Toolbar filter pill.",
       "props": [
         {
@@ -2389,15 +2470,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { FilterChip } from '@sakaniui/react';\n\n<FilterChip>Label</FilterChip>"
     },
     {
       "name": "FirstPageHeading",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/FirstPageHeading/FirstPageHeading.tsx",
-      "summary": "Matches Figma \"First Page Heading\" (Marketing primitives set, 16 previews: Align (Center/Left) x CTAs/Badge/Avatars (each True/False)). Align stays a real, explicit prop (Figma's own axis) -- a genuine layout choice.",
+      "summary": "The heading that opens a page: title and description with optional badge, call-to-action buttons and avatars; `align` is \"left\" or \"center\".",
       "props": [
         {
           "name": "title",
@@ -2445,8 +2527,7 @@
             "left",
             "center"
           ],
-          "default": "center",
-          "description": "Figma Align axis. Defaults to \"center\"."
+          "default": "center"
         },
         {
           "name": "className",
@@ -2459,15 +2540,16 @@
           "title"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { FirstPageHeading } from '@sakaniui/react';\n\n<FirstPageHeading title=\"Title\" />"
     },
     {
       "name": "FunnelChart",
       "kind": "component",
       "category": "Charts",
       "import": "@sakaniui/react",
-      "source": "src/components/FunnelChart/FunnelChart.tsx",
-      "summary": "Matches Figma's new \"Other charts\" set (\"Funnel chart\" / \"Funnel chart hover\") exactly: stages run left to right (not top to bottom), narrowing via smooth curved transitions rather than straight diagonal edges.",
+      "summary": "A funnel chart whose stages run left to right and narrow through curved transitions, in sizes sm to xl.",
       "props": [
         {
           "name": "data",
@@ -2497,35 +2579,37 @@
           "data"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { FunnelChart } from '@sakaniui/react';\n\n<FunnelChart data={[{ label: \"Label\", value: 50 }]} />"
     },
     {
       "name": "GithubIcon",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/ProfileCard/SocialIcons.tsx",
-      "summary": "svg) -- lucide-react ships no brand/logo icons in the version this library uses.",
+      "summary": "GitHub brand mark drawn in currentColor, for social links.",
       "props": [
         {
           "name": "size",
           "type": "number",
           "required": false,
-          "default": "16"
+          "default": 16
         }
       ],
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { GithubIcon } from '@sakaniui/react';\n\n<GithubIcon />"
     },
     {
       "name": "HeatmapChart",
       "kind": "component",
       "category": "Charts",
       "import": "@sakaniui/react",
-      "source": "src/components/HeatmapChart/HeatmapChart.tsx",
-      "summary": "Matches Figma's new \"Other charts\" set (\"Heatmap chart\" / \"Heatmap chart hover\").",
+      "summary": "A heatmap: a grid of coloured cells with optional row and column labels, in sizes sm to xl.",
       "props": [
         {
           "name": "data",
@@ -2547,8 +2631,7 @@
           "name": "valueLabel",
           "type": "string",
           "required": false,
-          "default": "Value",
-          "description": "Legend label for the tooltip's value row (Figma: \"Revenue\")."
+          "default": "Value"
         },
         {
           "name": "size",
@@ -2573,15 +2656,30 @@
           "data"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { HeatmapChart } from '@sakaniui/react';\n\n<HeatmapChart data={[[1]]} />"
+    },
+    {
+      "name": "HoverGroup",
+      "kind": "component",
+      "category": "Utilities",
+      "import": "@sakaniui/react",
+      "summary": "Flowing hover highlight: one element that glides between the items of a group instead of each item fading its own background in and out.",
+      "props": [],
+      "contract": {
+        "requiredProps": [],
+        "requiresAccessibleName": false
+      },
+      "since": "0.3.21",
+      "example": "import { HoverGroup } from '@sakaniui/react';\n\n<HoverGroup />"
     },
     {
       "name": "IconButton",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/IconButton/IconButton.tsx",
-      "summary": "Icon-only button. Matches Figma \"Icon Button\": variant (IB axis): primary | secondary | outline | ghost | destructive size: sm (32) | md (40) | lg (48) — square, radius-sm State handled via CSS (:hover, :disabled).",
+      "summary": "Icon-only button.",
       "props": [
         {
           "name": "icon",
@@ -2626,14 +2724,15 @@
           "aria-label"
         ],
         "requiresAccessibleName": true
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { IconButton } from '@sakaniui/react';\nimport { IconStar } from '@sakaniui/react/icons';\n\n<IconButton icon={IconStar} aria-label=\"Describe the action\" />"
     },
     {
       "name": "InlineHint",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/InlineHint/InlineHint.tsx",
       "summary": "Small inline helper text with a colored accent bar.",
       "props": [
         {
@@ -2662,27 +2761,26 @@
           "message"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { InlineHint } from '@sakaniui/react';\n\n<InlineHint message=\"Message\" />"
     },
     {
       "name": "Input",
       "kind": "component",
       "category": "Forms",
       "import": "@sakaniui/react",
-      "source": "src/components/Input/Input.tsx",
       "summary": "Text input with optional label (Title), help text (Description), and leading/trailing icons.",
       "props": [
         {
           "name": "label",
           "type": "string",
-          "required": false,
-          "description": "Field label (Figma: Title)."
+          "required": false
         },
         {
           "name": "description",
           "type": "string",
-          "required": false,
-          "description": "Help text under the field (Figma: Description)."
+          "required": false
         },
         {
           "name": "error",
@@ -2699,8 +2797,7 @@
             "md",
             "lg"
           ],
-          "default": "md",
-          "description": "Figma Size axis. Defaults to \"md\"."
+          "default": "md"
         },
         {
           "name": "unstyled",
@@ -2722,35 +2819,37 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Input } from '@sakaniui/react';\n\n<Input />"
     },
     {
       "name": "InstagramIcon",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/TeamCard/TeamSocialIcons.tsx",
-      "summary": "tsx).",
+      "summary": "Instagram glyph drawn in currentColor, for the `socialLinks` of TeamCard.",
       "props": [
         {
           "name": "size",
           "type": "number",
           "required": false,
-          "default": "16"
+          "default": 16
         }
       ],
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { InstagramIcon } from '@sakaniui/react';\n\n<InstagramIcon />"
     },
     {
       "name": "JobListing",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/JobListing/JobListing.tsx",
-      "summary": "Matches Figma \"Job Listing\" (Marketing primitives set, 2 styles: Card, Row).",
+      "summary": "A job opening with title, description, department, employment type and location, plus an apply button. `layout` is \"row\" or \"card\".",
       "props": [
         {
           "name": "title",
@@ -2786,7 +2885,7 @@
             "remote"
           ],
           "default": "remote",
-          "description": "Drives LocationDot's color. Defaults to \"remote\", matching Figma's own Job Listing instances."
+          "description": "Drives LocationDot's color."
         },
         {
           "name": "onApply",
@@ -2807,8 +2906,7 @@
             "row",
             "card"
           ],
-          "default": "card",
-          "description": "Figma Style axis. Defaults to \"card\"."
+          "default": "card"
         },
         {
           "name": "className",
@@ -2825,14 +2923,15 @@
           "location"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { JobListing } from '@sakaniui/react';\n\n<JobListing title=\"Title\" description=\"Description\" department=\"Department\" employmentType=\"Employment type\" location=\"Location\" />"
     },
     {
       "name": "Kbd",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/Kbd/Kbd.tsx",
       "summary": "Keyboard shortcut display. Renders a <kbd> element styled as a key cap. Use inline inside prose or next to menu items to hint shortcuts.",
       "props": [
         {
@@ -2844,14 +2943,15 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Kbd } from '@sakaniui/react';\n\n<Kbd>Label</Kbd>"
     },
     {
       "name": "Label",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/Label/Label.tsx",
       "summary": "Form field label with optional required asterisk. Wraps a native <label> so htmlFor wiring works correctly.",
       "props": [
         {
@@ -2864,14 +2964,15 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Label } from '@sakaniui/react';\n\n<Label>Label</Label>"
     },
     {
       "name": "LineChart",
       "kind": "component",
       "category": "Charts",
       "import": "@sakaniui/react",
-      "source": "src/components/LineChart/LineChart.tsx",
       "summary": "Recharts wrapper styled with Sakani chart tokens.",
       "props": [
         {
@@ -2951,14 +3052,15 @@
           "series"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { LineChart } from '@sakaniui/react';\n\n<LineChart data={[{ name: \"Name\" }]} series={[\"Sery\"]} />"
     },
     {
       "name": "Link",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/Link/Link.tsx",
       "summary": "Inline anchor with hover/visited states and optional external icon. Use for navigation and inline references — not for page-level CTAs (use Button).",
       "props": [
         {
@@ -2971,35 +3073,157 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Link } from '@sakaniui/react';\n\n<Link>Label</Link>"
     },
     {
       "name": "LinkedinIcon",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/TeamCard/TeamSocialIcons.tsx",
-      "summary": "tsx).",
+      "summary": "LinkedIn glyph drawn in currentColor, for the `socialLinks` of TeamCard.",
       "props": [
         {
           "name": "size",
           "type": "number",
           "required": false,
-          "default": "16"
+          "default": 16
         }
       ],
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { LinkedinIcon } from '@sakaniui/react';\n\n<LinkedinIcon />"
+    },
+    {
+      "name": "LiquidBackdrop",
+      "kind": "component",
+      "category": "Utilities",
+      "import": "@sakaniui/react",
+      "summary": "The image behind the glass, shared by every LiquidGlass inside it. Pass `src`.",
+      "props": [
+        {
+          "name": "src",
+          "type": "string",
+          "required": true,
+          "description": "The image behind the glass, cover-fitted."
+        },
+        {
+          "name": "position",
+          "type": "string",
+          "required": false,
+          "default": "center",
+          "description": "background-position of the image. Default 'center'."
+        },
+        {
+          "name": "veil",
+          "type": "string",
+          "required": false,
+          "description": "Any CSS color, var() included."
+        }
+      ],
+      "contract": {
+        "requiredProps": [
+          "src"
+        ],
+        "requiresAccessibleName": false
+      },
+      "since": "0.4.0",
+      "example": "import { LiquidBackdrop } from '@sakaniui/react';\n\n<LiquidBackdrop />"
+    },
+    {
+      "name": "LiquidGlass",
+      "kind": "component",
+      "category": "Utilities",
+      "import": "@sakaniui/react",
+      "summary": "Apple-style liquid glass material (the Liquid surface mode): bends the backdrop at the edge with refraction, dispersion, rim light and depth. Use it inside a LiquidBackdrop when the image behind the UI is known.",
+      "props": [
+        {
+          "name": "variant",
+          "type": "\"regular\" | \"clear\"",
+          "required": false,
+          "values": [
+            "regular",
+            "clear"
+          ],
+          "default": "regular",
+          "description": "regular: text-safe tint (panels, sidebars, modals). clear: icons and large labels only."
+        },
+        {
+          "name": "tint",
+          "type": "\"subtle\" | \"none\" | \"auto\" | \"regular\" | \"clear\"",
+          "required": false,
+          "values": [
+            "subtle",
+            "none",
+            "auto",
+            "regular",
+            "clear"
+          ],
+          "default": "auto",
+          "description": "How much of the backdrop shows through. Default 'auto' (follows `variant`)."
+        },
+        {
+          "name": "radius",
+          "type": "number",
+          "required": false,
+          "default": 20,
+          "description": "Corner radius in px. Default 20."
+        },
+        {
+          "name": "refraction",
+          "type": "\"off\" | \"auto\"",
+          "required": false,
+          "values": [
+            "off",
+            "auto"
+          ],
+          "default": "auto",
+          "description": "'off' forces the frosted fallback."
+        },
+        {
+          "name": "effect",
+          "type": "Partial<LiquidGlassEffect>",
+          "required": false,
+          "description": "Defaults come from the variant's --liquid-* tokens."
+        },
+        {
+          "name": "source",
+          "type": "boolean",
+          "required": false,
+          "default": true,
+          "description": "Inside a <LiquidBackdrop>: true (default) refracts the backdrop image; false bends whatever is painted below instead (UI under a slider knob)."
+        },
+        {
+          "name": "bake",
+          "type": "boolean | \"auto\"",
+          "required": false,
+          "default": "auto",
+          "description": "'auto' (default): inside a LiquidBackdrop, lenses over 300×300 bake their glass once (fast; for surfaces that stay put). false: always live (a big lens that moves)."
+        },
+        {
+          "name": "interactive",
+          "type": "boolean",
+          "required": false,
+          "description": "Squish slightly when pressed (buttons, toolbar pills)."
+        }
+      ],
+      "contract": {
+        "requiredProps": [],
+        "requiresAccessibleName": false
+      },
+      "since": "0.4.0",
+      "example": "import { LiquidGlass } from '@sakaniui/react';\n\n<LiquidGlass />"
     },
     {
       "name": "List",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/List/List.tsx",
-      "summary": "Matches Figma \"List\" (Marketing primitives set, 3 styles: Check, Bullet, Arrow).",
+      "summary": "A list of text items with a leading marker; `style` is \"check\", \"bullet\" or \"arrow\".",
       "props": [
         {
           "name": "items",
@@ -3015,8 +3239,7 @@
             "bullet",
             "arrow"
           ],
-          "default": "check",
-          "description": "Figma Style axis. Defaults to \"check\"."
+          "default": "check"
         },
         {
           "name": "className",
@@ -3029,15 +3252,16 @@
           "items"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { List } from '@sakaniui/react';\n\n<List items={[\"Item\"]} />"
     },
     {
       "name": "ListItem",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/ListItem/ListItem.tsx",
-      "summary": "Row for lists/menus. Matches Figma \"List Item\": State (Default|Hover|Selected), Title/Description toggles.",
+      "summary": "Row for lists/menus. Supports leading (icon/avatar) and trailing (badge/action) slots.",
       "props": [
         {
           "name": "title",
@@ -3085,15 +3309,16 @@
           "title"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { ListItem } from '@sakaniui/react';\n\n<ListItem title=\"Title\" />"
     },
     {
       "name": "LocationDot",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/LocationDot/LocationDot.tsx",
-      "summary": "Matches Figma \"Location Dot\" (Marketing primitives set, shared across any marketing component that shows a location -- JobListing is the first consumer).g. a real office location (\"Lagos, Nigeria\").g.",
+      "summary": "A status dot and location label; `status` \"active\" is green (a real office), \"remote\" is gray.",
       "props": [
         {
           "name": "location",
@@ -3108,8 +3333,7 @@
             "active",
             "remote"
           ],
-          "default": "active",
-          "description": "Figma Status axis. Defaults to \"active\"."
+          "default": "active"
         },
         {
           "name": "className",
@@ -3122,15 +3346,16 @@
           "location"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { LocationDot } from '@sakaniui/react';\n\n<LocationDot location=\"Location\" />"
     },
     {
       "name": "Marquee",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/Marquee/Marquee.tsx",
-      "summary": "Matches Figma \"Marquee\" (Marketing primitives set, 2 content previews: Logos, Text).",
+      "summary": "An infinitely scrolling horizontal row of items (logos or text) with adjustable `speed` and `gap`.",
       "props": [
         {
           "name": "items",
@@ -3141,14 +3366,14 @@
           "name": "speed",
           "type": "number",
           "required": false,
-          "default": "40",
+          "default": 40,
           "description": "Scroll speed in pixels/second at rest (pre-hover). Defaults to 40."
         },
         {
           "name": "gap",
           "type": "number",
           "required": true,
-          "description": "Gap between items, in px. Figma uses 32 for Logos, 12 for Text -- no shared default assumption, so this must be passed explicitly."
+          "description": "Gap between items, in px."
         },
         {
           "name": "className",
@@ -3162,15 +3387,16 @@
           "gap"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { Marquee } from '@sakaniui/react';\n\n<Marquee items={[\"Item\"]} gap={1} />"
     },
     {
       "name": "Menu",
       "kind": "component",
       "category": "Overlays",
       "import": "@sakaniui/react",
-      "source": "src/components/Menu/Menu.tsx",
-      "summary": "Dropdown menu container. Matches the Figma \"Menu\" component: mirrors Combobox Panel exactly — radius 6, padding 4, gap 2, bg/surface, border/default, shadow/lg.",
+      "summary": "Dropdown menu container.",
       "props": [
         {
           "name": "aria-label",
@@ -3182,8 +3408,8 @@
           "name": "minWidth",
           "type": "number",
           "required": false,
-          "default": "208",
-          "description": "Minimum width in px. Defaults to 208 (matches Figma)."
+          "default": 208,
+          "description": "Minimum width in px."
         },
         {
           "name": "className",
@@ -3194,27 +3420,29 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Menu } from '@sakaniui/react';\n\n<Menu>Label</Menu>"
     },
     {
       "name": "MenuDivider",
       "kind": "component",
       "category": "Overlays",
       "import": "@sakaniui/react",
-      "source": "src/components/Menu/Menu.tsx",
-      "summary": "Dropdown menu container. Matches the Figma \"Menu\" component: mirrors Combobox Panel exactly — radius 6, padding 4, gap 2, bg/surface, border/default, shadow/lg.",
+      "summary": "A divider that separates groups of items inside a Menu.",
       "props": [],
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { MenuDivider } from '@sakaniui/react';\n\n<MenuDivider />"
     },
     {
       "name": "MenuItem",
       "kind": "component",
       "category": "Overlays",
       "import": "@sakaniui/react",
-      "source": "src/components/MenuItem/MenuItem.tsx",
       "summary": "One row of a dropdown Menu.",
       "props": [
         {
@@ -3228,7 +3456,7 @@
             "checked"
           ],
           "default": "default",
-          "description": "Visual state. Maps to Figma State axis."
+          "description": "Visual state."
         },
         {
           "name": "icon",
@@ -3256,14 +3484,15 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { MenuItem } from '@sakaniui/react';\n\n<MenuItem>Label</MenuItem>"
     },
     {
       "name": "MessageBubble",
       "kind": "component",
       "category": "Chat",
       "import": "@sakaniui/react",
-      "source": "src/components/MessageBubble/MessageBubble.tsx",
       "summary": "A chat message.",
       "props": [
         {
@@ -3348,15 +3577,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { MessageBubble } from '@sakaniui/react';\n\n<MessageBubble />"
     },
     {
       "name": "Metric",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/Metric/Metric.tsx",
-      "summary": "Matches Figma \"Metric\" (Marketing primitives set, 2 styles: Simple, With Trend).",
+      "summary": "A value with a label; passing `trend` adds a trend chip.",
       "props": [
         {
           "name": "value",
@@ -3386,15 +3616,16 @@
           "label"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { Metric } from '@sakaniui/react';\n\n<Metric value=\"Value\" label=\"Label\" />"
     },
     {
       "name": "MobileNavigationMenu",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/MobileNavigationMenu/MobileNavigationMenu.tsx",
-      "summary": "Matches Figma \"Mobile Navigation Menu\" (Marketing primitives set, 2 states: Closed, Open).",
+      "summary": "A mobile navigation menu: a toggle that opens a list of links and an optional call-to-action. Controlled with `open` or uncontrolled with `defaultOpen`.",
       "props": [
         {
           "name": "label",
@@ -3427,7 +3658,7 @@
           "name": "defaultOpen",
           "type": "boolean",
           "required": false,
-          "default": "false"
+          "default": false
         },
         {
           "name": "onOpenChange",
@@ -3446,14 +3677,15 @@
           "links"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { MobileNavigationMenu } from '@sakaniui/react';\n\n<MobileNavigationMenu label=\"Label\" links={[{ label: \"Label\" }]} />"
     },
     {
       "name": "Modal",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/Modal/Modal.tsx",
       "summary": "Confirmation dialog.",
       "props": [
         {
@@ -3506,8 +3738,7 @@
         {
           "name": "onCancel",
           "type": "(() => void)",
-          "required": false,
-          "description": "Defaults to `onClose`."
+          "required": false
         },
         {
           "name": "onConfirm",
@@ -3523,13 +3754,13 @@
           "name": "closeOnEscape",
           "type": "boolean",
           "required": false,
-          "default": "true"
+          "default": true
         },
         {
           "name": "closeOnBackdropClick",
           "type": "boolean",
           "required": false,
-          "default": "true"
+          "default": true
         },
         {
           "name": "children",
@@ -3541,15 +3772,14 @@
           "name": "hideHeader",
           "type": "boolean",
           "required": false,
-          "default": "false",
-          "description": "Hides the title+close-X header row entirely, so `children` owns the whole top of the card (e.g. MultistepModalBlock's own steps-row + title + description, which Figma draws with no header bar or close control at all). `title` is still required and used as the dialog's aria-label in this mode, since there's no #modal-title element to point aria-labelledby at."
+          "default": false,
+          "description": "`title` is still required and used as the dialog's aria-label in this mode, since there's no #modal-title element to point aria-labelledby at."
         },
         {
           "name": "hideFooterDivider",
           "type": "boolean",
           "required": false,
-          "default": "false",
-          "description": "Hides the Divider between the body and the footer buttons (Figma's Multistep Modal has no such rule)."
+          "default": false
         },
         {
           "name": "footerJustify",
@@ -3560,7 +3790,7 @@
             "between"
           ],
           "default": "end",
-          "description": "Footer button alignment. 'end' (default) clusters Cancel/Confirm at the right, matching the base Modal's Figma spec. 'between' spreads them across the full width (Figma: Multistep Modal's Back / Continue footer), so the footer <div> fills the card instead of just wrapping its two buttons."
+          "description": "Footer button alignment."
         },
         {
           "name": "className",
@@ -3575,15 +3805,16 @@
           "title"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Modal } from '@sakaniui/react';\n\n<Modal open={true} onClose={() => {}} title=\"Title\" />"
     },
     {
       "name": "NotificationItem",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/NotificationItem/NotificationItem.tsx",
-      "summary": "Matches Figma \"Notification Item\" (3 style previews -- Unread, Read, Dismissable -- collapsed into composable props, same judgment already applied throughout this Application set):",
+      "summary": "A notification row with icon, title and timestamp; `read` toggles the unread style, with optional description, dismiss and action buttons.",
       "props": [
         {
           "name": "icon",
@@ -3605,7 +3836,7 @@
           "name": "read",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Simple row only -- false (default) shows the unread background + dot."
         },
         {
@@ -3647,15 +3878,16 @@
           "title"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { NotificationItem } from '@sakaniui/react';\n\n<NotificationItem title=\"Title\" />"
     },
     {
       "name": "Pagination",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Pagination/Pagination.tsx",
-      "summary": "Page navigation. Matches Figma \"Pagination\": prev/next arrows + numbered page buttons (32px, radius-sm, bg/surface, border/subtle), active page filled accent.",
+      "summary": "Page navigation. Collapses long ranges with ellipses; the numbers between them come in fixed blocks the highlight moves across (see buildRange).",
       "props": [
         {
           "name": "total",
@@ -3678,7 +3910,7 @@
           "name": "siblings",
           "type": "number",
           "required": false,
-          "default": "1",
+          "default": 1,
           "description": "Sets how many page numbers show between the ellipses: blocks of siblings * 2 + 1 (3 by default). Total slots are siblings * 2 + 5."
         },
         {
@@ -3694,14 +3926,15 @@
           "onPageChange"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Pagination } from '@sakaniui/react';\n\n<Pagination total={49} page={1} onPageChange={() => {}} />"
     },
     {
       "name": "PieChart",
       "kind": "component",
       "category": "Charts",
       "import": "@sakaniui/react",
-      "source": "src/components/PieChart/PieChart.tsx",
       "summary": "Recharts wrapper styled with Sakani chart tokens.",
       "props": [
         {
@@ -3761,15 +3994,16 @@
           "data"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { PieChart } from '@sakaniui/react';\n\n<PieChart data={[{ label: \"Label\", value: 50 }]} />"
     },
     {
       "name": "PlaceholderLogo",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/PlaceholderLogo/PlaceholderLogo.tsx",
-      "summary": "Matches Figma \"Placeholder Logo\" (Marketing primitives set, 3 sizes: sm 22 / md 40 / lg 46) -- a bg/surface + border/subtle + radius/lg square slot for a company/brand mark, same \"empty-state avatar\" role Avatar's own Icon type fills for a person.",
+      "summary": "A square slot for a company or brand mark in sm, md or lg; pass `logo` to replace the default mark.",
       "props": [
         {
           "name": "size",
@@ -3780,14 +4014,13 @@
             "md",
             "lg"
           ],
-          "default": "md",
-          "description": "Figma Size axis. Defaults to \"md\"."
+          "default": "md"
         },
         {
           "name": "logo",
           "type": "ReactNode",
           "required": false,
-          "description": "Custom logo/icon slot. Defaults to the Sakani mark, matching Figma."
+          "description": "Custom logo/icon slot."
         },
         {
           "name": "label",
@@ -3804,15 +4037,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { PlaceholderLogo } from '@sakaniui/react';\n\n<PlaceholderLogo />"
     },
     {
       "name": "Popover",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Popover/Popover.tsx",
-      "summary": "Floating panel anchored to a trigger. Matches Figma \"Popover\" (Buttons 1-3), with title/description toggles.",
+      "summary": "Floating panel anchored to a trigger.",
       "props": [
         {
           "name": "trigger",
@@ -3859,15 +4093,16 @@
           "trigger"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Popover } from '@sakaniui/react';\n\n<Popover trigger=\"Trigger\" />"
     },
     {
       "name": "PriceDisplay",
       "kind": "component",
       "category": "E-commerce",
       "import": "@sakaniui/react",
-      "source": "src/components/ECommerceComponents/PriceDisplay/PriceDisplay.tsx",
-      "summary": "Matches Figma \"Price Display\" (E-commerce set).",
+      "summary": "A product price. Pass `compareAtPrice` for a struck-through original price with the current price in the danger colour; `showBadge` adds the sale badge.",
       "props": [
         {
           "name": "price",
@@ -3884,14 +4119,13 @@
           "name": "showBadge",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Shows a \"Save X%\" badge, computed from price vs. compareAtPrice. No-op without compareAtPrice."
         },
         {
           "name": "formatPrice",
           "type": "((amount: number) => string)",
-          "required": false,
-          "default": "(amount: number) =>\n  amount.toLocaleString('en-US', { style: 'currency', currency: 'USD' })"
+          "required": false
         },
         {
           "name": "className",
@@ -3904,15 +4138,16 @@
           "price"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { PriceDisplay } from '@sakaniui/react';\n\n<PriceDisplay price={49} />"
     },
     {
       "name": "ProductCard",
       "kind": "component",
       "category": "E-commerce",
       "import": "@sakaniui/react",
-      "source": "src/components/ECommerceComponents/ProductCard/ProductCard.tsx",
-      "summary": "Matches Figma \"Product Card\" (E-commerce set): image (wishlist button + sale badge overlay) -> rating -> name/price -> description -> color swatches -> \"Add Item\" button.",
+      "summary": "An e-commerce product card: image with wishlist button and sale badge, rating, name, price, description, colour swatches and an add button. `compareAtPrice` shows the sale treatment.",
       "props": [
         {
           "name": "image",
@@ -3970,13 +4205,13 @@
           "name": "inStock",
           "type": "boolean",
           "required": false,
-          "default": "true"
+          "default": true
         },
         {
           "name": "wishlisted",
           "type": "boolean",
           "required": false,
-          "default": "false"
+          "default": false
         },
         {
           "name": "onWishlistToggle",
@@ -3997,8 +4232,7 @@
         {
           "name": "formatPrice",
           "type": "((amount: number) => string)",
-          "required": false,
-          "default": "(amount: number) =>\n  amount.toLocaleString('en-US', { style: 'currency', currency: 'USD' })"
+          "required": false
         },
         {
           "name": "className",
@@ -4013,15 +4247,16 @@
           "price"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { ProductCard } from '@sakaniui/react';\n\n<ProductCard image=\"/images/example.jpg\" name=\"Name\" price={49} />"
     },
     {
       "name": "ProductGallery",
       "kind": "component",
       "category": "E-commerce",
       "import": "@sakaniui/react",
-      "source": "src/components/ECommerceComponents/ProductGallery/ProductGallery.tsx",
-      "summary": "Matches Figma \"Product Gallery\" (E-commerce set): a main image plus selectable thumbnails, click a thumb to make it the main image.",
+      "summary": "A main product image with selectable thumbnails; `thumbsPosition` is \"bottom\" or \"left\". Controlled or uncontrolled via `activeIndex` / `defaultActiveIndex`.",
       "props": [
         {
           "name": "images",
@@ -4048,7 +4283,7 @@
           "name": "defaultActiveIndex",
           "type": "number",
           "required": false,
-          "default": "0"
+          "default": 0
         },
         {
           "name": "onActiveIndexChange",
@@ -4066,15 +4301,16 @@
           "images"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { ProductGallery } from '@sakaniui/react';\n\n<ProductGallery images={[{ src: \"/images/example.jpg\" }]} />"
     },
     {
       "name": "ProfileCard",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/ProfileCard/ProfileCard.tsx",
-      "summary": "Matches Figma \"Profile Card\" (Marketing primitives set, 2 styles: Compact, Detailed).",
+      "summary": "A person card with avatar, name and role, plus an optional bio and social links (the detailed layout follows the data you pass).",
       "props": [
         {
           "name": "name",
@@ -4120,15 +4356,16 @@
           "role"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { ProfileCard } from '@sakaniui/react';\n\n<ProfileCard name=\"Name\" role=\"Role\" />"
     },
     {
       "name": "Progress",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/Progress/Progress.tsx",
-      "summary": "Linear progress bar.g.",
+      "summary": "Linear progress bar.",
       "props": [
         {
           "name": "value",
@@ -4163,14 +4400,15 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Progress } from '@sakaniui/react';\n\n<Progress />"
     },
     {
       "name": "ProgressItem",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/ProgressItem/ProgressItem.tsx",
       "summary": "One row of a numbered step list.",
       "props": [
         {
@@ -4192,7 +4430,7 @@
           "name": "completed",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Shows a checkmark in the circle instead of `step`."
         },
         {
@@ -4209,7 +4447,7 @@
           "name": "isLast",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Hides the trailing connector -- the last row in a list."
         },
         {
@@ -4224,14 +4462,15 @@
           "title"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { ProgressItem } from '@sakaniui/react';\n\n<ProgressItem step={1} title=\"Title\" />"
     },
     {
       "name": "ProgressStat",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/ProgressStat/ProgressStat.tsx",
       "summary": "Label + value row above a progress bar.",
       "props": [
         {
@@ -4264,15 +4503,16 @@
           "progress"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { ProgressStat } from '@sakaniui/react';\n\n<ProgressStat label=\"Label\" value=\"Value\" progress={50} />"
     },
     {
       "name": "QuantitySelector",
       "kind": "component",
       "category": "E-commerce",
       "import": "@sakaniui/react",
-      "source": "src/components/ECommerceComponents/QuantitySelector/QuantitySelector.tsx",
-      "summary": "Matches Figma \"Quantity Selector\" (E-commerce set): a 3-cell stepper -- decrement / value / increment, separated by 1px dividers, only the outer frame rounded/bordered.",
+      "summary": "A decrement / value / increment stepper for quantity, bounded by `min` and `max`.",
       "props": [
         {
           "name": "quantity",
@@ -4288,7 +4528,7 @@
           "name": "min",
           "type": "number",
           "required": false,
-          "default": "1"
+          "default": 1
         },
         {
           "name": "max",
@@ -4313,14 +4553,15 @@
           "quantity"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { QuantitySelector } from '@sakaniui/react';\n\n<QuantitySelector quantity={1} />"
     },
     {
       "name": "RadarChart",
       "kind": "component",
       "category": "Charts",
       "import": "@sakaniui/react",
-      "source": "src/components/RadarChart/RadarChart.tsx",
       "summary": "Recharts wrapper styled with Sakani chart tokens.",
       "props": [
         {
@@ -4377,14 +4618,15 @@
           "data"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { RadarChart } from '@sakaniui/react';\n\n<RadarChart data={[{ label: \"Label\", value: 50 }]} />"
     },
     {
       "name": "RadialChart",
       "kind": "component",
       "category": "Charts",
       "import": "@sakaniui/react",
-      "source": "src/components/RadialChart/RadialChart.tsx",
       "summary": "Recharts wrapper styled with Sakani chart tokens.",
       "props": [
         {
@@ -4441,15 +4683,16 @@
           "data"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { RadialChart } from '@sakaniui/react';\n\n<RadialChart data={[{ label: \"Label\", value: 50 }]} />"
     },
     {
       "name": "Radio",
       "kind": "component",
       "category": "Forms",
       "import": "@sakaniui/react",
-      "source": "src/components/Radio/Radio.tsx",
-      "summary": "Single radio button. Matches Figma \"Radio\" set: Unchecked | Hover | Checked | Disabled, with Title/Description toggles.",
+      "summary": "Single radio button.",
       "props": [
         {
           "name": "label",
@@ -4465,15 +4708,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Radio } from '@sakaniui/react';\n\n<Radio />"
     },
     {
       "name": "RichSeparator",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/RichSeparator/RichSeparator.tsx",
-      "summary": "Two divider lines flanking arbitrary centered content.",
+      "summary": "Two divider lines flanking arbitrary centered content. `label` is a convenience shorthand for the common Text case, styled as that same overline automatically.",
       "props": [
         {
           "name": "children",
@@ -4496,15 +4740,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { RichSeparator } from '@sakaniui/react';\n\n<RichSeparator />"
     },
     {
       "name": "RichTextHeading",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/RichTextHeading/RichTextHeading.tsx",
-      "summary": "Matches Figma \"Rich Text Heading\" (Marketing primitives set, 2 levels: H2, H3).",
+      "summary": "A heading for rich-text content; `level` is \"h2\" or \"h3\" and sets the real HTML tag.",
       "props": [
         {
           "name": "level",
@@ -4514,8 +4759,7 @@
             "h2",
             "h3"
           ],
-          "default": "h2",
-          "description": "Figma Level axis. Defaults to \"h2\"."
+          "default": "h2"
         },
         {
           "name": "className",
@@ -4526,15 +4770,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { RichTextHeading } from '@sakaniui/react';\n\n<RichTextHeading>Label</RichTextHeading>"
     },
     {
       "name": "RichTextParagraph",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/RichTextParagraph/RichTextParagraph.tsx",
-      "summary": "Matches Figma \"Rich Text Paragraph\" (Marketing primitives set, 2 style previews: Default, With Link).",
+      "summary": "A muted body paragraph for rich-text content; it can contain inline links.",
       "props": [
         {
           "name": "className",
@@ -4545,15 +4790,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { RichTextParagraph } from '@sakaniui/react';\n\n<RichTextParagraph>Label</RichTextParagraph>"
     },
     {
       "name": "SectionHeading",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/SectionHeading/SectionHeading.tsx",
-      "summary": "Matches Figma \"Section Heading\" (Marketing primitives set, 2 alignments: Center, Left). `align` stays a real, explicit prop (Figma's own axis) -- a genuine layout choice, not derivable from the heading's own content.",
+      "summary": "A section heading with an optional eyebrow badge and subtitle; `align` is \"left\" or \"center\" and `titleAs` sets the heading tag.",
       "props": [
         {
           "name": "eyebrow",
@@ -4579,8 +4825,7 @@
             "left",
             "center"
           ],
-          "default": "center",
-          "description": "Figma Align axis. Defaults to \"center\"."
+          "default": "center"
         },
         {
           "name": "titleAs",
@@ -4606,15 +4851,16 @@
           "title"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { SectionHeading } from '@sakaniui/react';\n\n<SectionHeading title=\"Title\" />"
     },
     {
       "name": "SegmentedControl",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/SegmentedControl/SegmentedControl.tsx",
-      "summary": "iOS-style toggle group. Matches Figma \"Segmented Control\" (2-6 buttons). Figma spec: track bg/subtle, radius-lg, padding 4, gap 2; active segment bg/surface, radius-md, label/md fg/default; inactive fg/muted.",
+      "summary": "An iOS-style toggle group (segmented control).",
       "props": [
         {
           "name": "options",
@@ -4653,15 +4899,16 @@
           "options"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { SegmentedControl } from '@sakaniui/react';\n\n<SegmentedControl options={[{ value: \"Value\", label: \"Label\" }]} />"
     },
     {
       "name": "Select",
       "kind": "component",
       "category": "Forms",
       "import": "@sakaniui/react",
-      "source": "src/components/Select/Select.tsx",
-      "summary": "Single-select dropdown. Matches the Figma \"Select\" component: Size (sm|md|lg) x State (Default|Open|Disabled|Filled), Title/Description toggles.",
+      "summary": "Single-select dropdown.",
       "props": [
         {
           "name": "label",
@@ -4738,21 +4985,22 @@
           "options"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Select } from '@sakaniui/react';\n\n<Select options={[{ label: \"Label\", value: \"Value\" }]} />"
     },
     {
       "name": "Sidebar",
       "kind": "component",
       "category": "Composite/Sidebar",
       "import": "@sakaniui/react",
-      "source": "src/components/Sidebar/Sidebar.tsx",
       "summary": "Sidebar (container)",
       "props": [
         {
           "name": "collapsed",
           "type": "boolean",
           "required": false,
-          "default": "false"
+          "default": false
         },
         {
           "name": "className",
@@ -4763,28 +5011,30 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Sidebar } from '@sakaniui/react';\n\n<Sidebar>Label</Sidebar>"
     },
     {
       "name": "SidebarDivider",
       "kind": "component",
       "category": "Composite/Sidebar",
       "import": "@sakaniui/react",
-      "source": "src/components/SidebarDivider/SidebarDivider.tsx",
-      "summary": "Horizontal rule between sections. Matches Figma \"Sidebar Divider\": border/subtle, full width, small vertical margin.",
+      "summary": "Horizontal rule between sections.",
       "props": [],
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { SidebarDivider } from '@sakaniui/react';\n\n<SidebarDivider />"
     },
     {
       "name": "SidebarFooter",
       "kind": "component",
       "category": "Composite/Sidebar",
       "import": "@sakaniui/react",
-      "source": "src/components/SidebarFooter/SidebarFooter.tsx",
-      "summary": "Bottom user/actions area. Matches Figma \"Sidebar Footer\": Type (User | User + Menu | Actions) x Collapsed.",
+      "summary": "Bottom user/actions area. The user avatar uses the system Avatar component.",
       "props": [
         {
           "name": "type",
@@ -4838,28 +5088,30 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { SidebarFooter } from '@sakaniui/react';\n\n<SidebarFooter />"
     },
     {
       "name": "SidebarGroupLabel",
       "kind": "component",
       "category": "Composite/Sidebar",
       "import": "@sakaniui/react",
-      "source": "src/components/SidebarGroupLabel/SidebarGroupLabel.tsx",
-      "summary": "Section heading. Matches Figma \"Sidebar Group Label\": padding 8/10/4, overline text style, fg/subtle, uppercase.",
+      "summary": "Section heading.",
       "props": [],
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { SidebarGroupLabel } from '@sakaniui/react';\n\n<SidebarGroupLabel>Label</SidebarGroupLabel>"
     },
     {
       "name": "SidebarHeader",
       "kind": "component",
       "category": "Composite/Sidebar",
       "import": "@sakaniui/react",
-      "source": "src/components/SidebarHeader/SidebarHeader.tsx",
-      "summary": "Matches Figma \"Sidebar Header\": Type (Brand | Workspace | Brand + Toggle) x Collapsed. Figma spec: padding 6/4, gap 10, title label/md-strong (fg/default), subtitle caption (fg/muted).",
+      "summary": "The top of a sidebar: brand, workspace switcher or brand with a collapse toggle; supports a collapsed state.",
       "props": [
         {
           "name": "type",
@@ -4902,7 +5154,6 @@
           "name": "toggleIcon",
           "type": "IconComponent",
           "required": false,
-          "default": "createIcon(\"layout-sidebar-left-collapse\", [\"M4 6a2 2 0 0 1 2 -2h12a2 2 0 0 1 2 2v12a2 2 0 0 1 -2 2h-12a2 2 0 0 1 -2 -2l0 -12\",\"M9 4v16\",\"M15 10l-2 2l2 2\"])",
           "description": "Icon for the toggle button. Defaults to PanelLeftClose."
         }
       ],
@@ -4911,14 +5162,15 @@
           "title"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { SidebarHeader } from '@sakaniui/react';\n\n<SidebarHeader title=\"Title\" />"
     },
     {
       "name": "SidebarItem",
       "kind": "component",
       "category": "Composite/Sidebar",
       "import": "@sakaniui/react",
-      "source": "src/components/SidebarItem/SidebarItem.tsx",
       "summary": "Primary nav item.",
       "props": [
         {
@@ -4940,8 +5192,8 @@
           "name": "activeIndicator",
           "type": "boolean",
           "required": false,
-          "default": "true",
-          "description": "Only matters when `active`. true (default) = bg/surface card + shadow + left accent bar (\"Active - Indicator\"). false = flat bg/subtle tint, no bar, no shadow (\"Active - Default\"). Works the same collapsed or not — Figma now defines both flavors in both layouts."
+          "default": true,
+          "description": "Only matters when `active`. true (default) = bg/surface card + shadow + left accent bar (\"Active - Indicator\"). false = flat bg/subtle tint, no bar, no shadow (\"Active - Default\")."
         },
         {
           "name": "disabled",
@@ -4967,7 +5219,7 @@
           "name": "expanded",
           "type": "boolean",
           "required": false,
-          "description": "Only matters when `hasSubmenu`. Rotates the chevron 90° (pointing down) to show the section is open; the resting state points right, toward a closed section — matches Figma's collapsible \"Navigation group\" / \"Project group\" headers (node 2307:42338, e.g. 2308:18305 \"Projects\" expanded vs 2308:18387 \"Website refresh\" collapsed). Not a navigation disclosure like `active` — the caller owns the open/closed state and toggles this alongside conditionally rendering the children."
+          "description": "Only matters when `hasSubmenu`. Not a navigation disclosure like `active` — the caller owns the open/closed state and toggles this alongside conditionally rendering the children."
         },
         {
           "name": "onClick",
@@ -4983,7 +5235,7 @@
           "name": "nativeTooltip",
           "type": "boolean",
           "required": false,
-          "default": "true",
+          "default": true,
           "description": "Native title-attribute tooltip on collapse. Defaults to true; set false when the caller already wraps this in its own Tooltip component to avoid the two competing on hover."
         }
       ],
@@ -4992,15 +5244,16 @@
           "label"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { SidebarItem } from '@sakaniui/react';\n\n<SidebarItem label=\"Label\" />"
     },
     {
       "name": "SidebarPromo",
       "kind": "component",
       "category": "Composite/Sidebar",
       "import": "@sakaniui/react",
-      "source": "src/components/SidebarPromo/SidebarPromo.tsx",
-      "summary": "Upsell / announcement card. Matches Figma \"Sidebar Promo\": Type (Upgrade | Announcement).",
+      "summary": "Upsell / announcement card.",
       "props": [
         {
           "name": "type",
@@ -5041,8 +5294,7 @@
         {
           "name": "icon",
           "type": "IconComponent",
-          "required": false,
-          "default": "createIcon(\"sparkles\", [\"M16 18a2 2 0 0 1 2 2a2 2 0 0 1 2 -2a2 2 0 0 1 -2 -2a2 2 0 0 1 -2 2m0 -12a2 2 0 0 1 2 2a2 2 0 0 1 2 -2a2 2 0 0 1 -2 -2a2 2 0 0 1 -2 2m-7 12a6 6 0 0 1 6 -6a6 6 0 0 1 -6 -6a6 6 0 0 1 -6 6a6 6 0 0 1 6 6\"])"
+          "required": false
         }
       ],
       "contract": {
@@ -5050,15 +5302,16 @@
           "title"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { SidebarPromo } from '@sakaniui/react';\n\n<SidebarPromo title=\"Title\" />"
     },
     {
       "name": "SidebarSearch",
       "kind": "component",
       "category": "Composite/Sidebar",
       "import": "@sakaniui/react",
-      "source": "src/components/SidebarSearch/SidebarSearch.tsx",
-      "summary": "Matches Figma \"Sidebar Search\": Type (Field | Command) x Collapsed. Figma spec: 36px height, bg/subtle, border/subtle, radius-sm, padding 8/8/8/10, search icon (Lucide), placeholder body/sm fg/subtle.",
+      "summary": "A sidebar search; `type` is \"field\" or \"command\" (shows a keyboard-shortcut hint), and it supports a collapsed state.",
       "props": [
         {
           "name": "type",
@@ -5100,15 +5353,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { SidebarSearch } from '@sakaniui/react';\n\n<SidebarSearch />"
     },
     {
       "name": "SidebarSubItem",
       "kind": "component",
       "category": "Composite/Sidebar",
       "import": "@sakaniui/react",
-      "source": "src/components/SidebarSubItem/SidebarSubItem.tsx",
-      "summary": "Nested nav item. Matches Figma \"Sidebar Sub Item\": State (Default|Hover|Active|Disabled). Figma spec: radius-sm, padding 0/10, label/sm. Default/Hover fg/muted, Active fg/default.",
+      "summary": "A nested navigation item under a SidebarItem, with active and disabled states.",
       "props": [
         {
           "name": "label",
@@ -5141,15 +5395,16 @@
           "label"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { SidebarSubItem } from '@sakaniui/react';\n\n<SidebarSubItem label=\"Label\" />"
     },
     {
       "name": "SizeSelector",
       "kind": "component",
       "category": "E-commerce",
       "import": "@sakaniui/react",
-      "source": "src/components/ECommerceComponents/SizeSelector/SizeSelector.tsx",
-      "summary": "Matches Figma \"Size Selector\" (E-commerce set): a 40px label circle.",
+      "summary": "A round size option with `selected` and `available` states.",
       "props": [
         {
           "name": "size",
@@ -5161,13 +5416,13 @@
           "name": "selected",
           "type": "boolean",
           "required": false,
-          "default": "false"
+          "default": false
         },
         {
           "name": "available",
           "type": "boolean",
           "required": false,
-          "default": "true",
+          "default": true,
           "description": "Defaults to true. False renders a disabled, unclickable button."
         },
         {
@@ -5186,14 +5441,15 @@
           "size"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { SizeSelector } from '@sakaniui/react';\n\n<SizeSelector size=\"Size\" />"
     },
     {
       "name": "Skeleton",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/Skeleton/Skeleton.tsx",
       "summary": "Placeholder loading shape — shimmer animation on a muted background. Use to represent content that is loading before data arrives.",
       "props": [
         {
@@ -5228,15 +5484,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Skeleton } from '@sakaniui/react';\n\n<Skeleton />"
     },
     {
       "name": "Slider",
       "kind": "component",
       "category": "Forms",
       "import": "@sakaniui/react",
-      "source": "src/components/Slider/Slider.tsx",
-      "summary": "Range slider. Figma \"Slider\" is a single component; this implements a functional controlled/uncontrolled range input styled to the token system.",
+      "summary": "Range slider.",
       "props": [
         {
           "name": "label",
@@ -5253,26 +5510,27 @@
           "name": "min",
           "type": "number",
           "required": false,
-          "default": "0"
+          "default": 0
         },
         {
           "name": "max",
           "type": "number",
           "required": false,
-          "default": "100"
+          "default": 100
         }
       ],
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Slider } from '@sakaniui/react';\n\n<Slider />"
     },
     {
       "name": "SpendingBalance",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/SpendingBalance/SpendingBalance.tsx",
       "summary": "Amount spent against a limit, with a bar and a remaining/over-limit footer.",
       "props": [
         {
@@ -5295,7 +5553,6 @@
           "name": "formatAmount",
           "type": "((amount: number) => string)",
           "required": false,
-          "default": "(amount: number) =>\n  amount.toLocaleString('en-US', { style: 'currency', currency: 'USD' })",
           "description": "Defaults to USD currency, 2 decimals (e.g. \"$1,240.00\")."
         },
         {
@@ -5310,14 +5567,15 @@
           "limit"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { SpendingBalance } from '@sakaniui/react';\n\n<SpendingBalance spent={1} limit={1} />"
     },
     {
       "name": "Spinner",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/Spinner/Spinner.tsx",
       "summary": "Animated loading indicator. Inherits currentColor so it works on any background. Use inside buttons (loading state) or as a standalone page/section loader.",
       "props": [
         {
@@ -5347,15 +5605,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Spinner } from '@sakaniui/react';\n\n<Spinner />"
     },
     {
       "name": "StarRating",
       "kind": "component",
       "category": "E-commerce",
       "import": "@sakaniui/react",
-      "source": "src/components/ECommerceComponents/StarRating/StarRating.tsx",
-      "summary": "g.9 (2,300 reviews)\".",
+      "summary": "Five stars with an optional numeric rating and review count (e.g. \"4.9 (2,300 reviews)\"); `showLabel` hides the text and `orientation` sets the layout.",
       "props": [
         {
           "name": "rating",
@@ -5372,7 +5631,7 @@
           "name": "showLabel",
           "type": "boolean",
           "required": false,
-          "default": "true",
+          "default": true,
           "description": "Shows the numeric rating + review count text next to the stars. Defaults to true."
         },
         {
@@ -5385,13 +5644,12 @@
             "horizontal-reverse"
           ],
           "default": "horizontal",
-          "description": "Figma Orientation axis. Only meaningful while showLabel is true. Defaults to \"horizontal\"."
+          "description": "Only meaningful while showLabel is true. Defaults to \"horizontal\"."
         },
         {
           "name": "formatReviewCount",
           "type": "((count: number) => string)",
-          "required": false,
-          "default": "(count: number) => count.toLocaleString('en-US')"
+          "required": false
         },
         {
           "name": "className",
@@ -5404,15 +5662,16 @@
           "rating"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { StarRating } from '@sakaniui/react';\n\n<StarRating rating={4} />"
     },
     {
       "name": "StatCard",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/StatCard/StatCard.tsx",
-      "summary": "Dashboard metric card. Matches Figma \"Stat Card\": Style (Minimal | Icon | Featured) x Trend (Up | Down | Flat), with Icon / Menu / Trend / Sparkline toggles.",
+      "summary": "Dashboard metric card.",
       "props": [
         {
           "name": "title",
@@ -5427,14 +5686,12 @@
         {
           "name": "description",
           "type": "string",
-          "required": false,
-          "description": "Supporting line under the delta (Figma: description)."
+          "required": false
         },
         {
           "name": "sparkline",
           "type": "number[]",
-          "required": false,
-          "description": "Data points for the inline sparkline (Figma: Sparkline toggle)."
+          "required": false
         },
         {
           "name": "delta",
@@ -5464,8 +5721,7 @@
             "danger",
             "neutral",
             "accent"
-          ],
-          "description": "Overrides the trend-derived badge color (e.g. a \"down\" delta that Figma still wants shown as warning, not danger, for a given card)."
+          ]
         },
         {
           "name": "variant",
@@ -5507,15 +5763,16 @@
           "value"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { StatCard } from '@sakaniui/react';\n\n<StatCard title=\"Title\" value=\"Value\" />"
     },
     {
       "name": "Stepper",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Stepper/Stepper.tsx",
-      "summary": "Progress stepper. Matches Figma \"Stepper\" (Steps 2-6) + \"Stepper Step\" (Completed | Current | Upcoming).",
+      "summary": "Progress stepper.",
       "props": [
         {
           "name": "steps",
@@ -5551,15 +5808,16 @@
           "current"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Stepper } from '@sakaniui/react';\n\n<Stepper steps={[{ label: \"Label\" }]} current={1} />"
     },
     {
       "name": "StepperStep",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Stepper/Stepper.tsx",
-      "summary": "Progress stepper. Matches Figma \"Stepper\" (Steps 2-6) + \"Stepper Step\" (Completed | Current | Upcoming).",
+      "summary": "One step of a Stepper; `state` is \"completed\", \"current\" or \"upcoming\".",
       "props": [
         {
           "name": "index",
@@ -5600,7 +5858,7 @@
           "name": "delay",
           "type": "number",
           "required": false,
-          "default": "0",
+          "default": 0,
           "description": "ms to wait before this step's state change plays (the stepper uses it to sequence a multi-step move)."
         },
         {
@@ -5617,15 +5875,16 @@
           "label"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { StepperStep } from '@sakaniui/react';\n\n<StepperStep index={0} state=\"completed\" label=\"Label\" />"
     },
     {
       "name": "StockMarket",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/StockMarket/StockMarket.tsx",
-      "summary": "Matches Figma \"Stock Market\" -- its 3 style previews collapse to 2 real axes, both derived rather than manual props (same judgment applied throughout this Application set): Positive vs.",
+      "summary": "A stock row or card: logo, symbol, name, price and change, with an optional chart and period label.",
       "props": [
         {
           "name": "logo",
@@ -5655,9 +5914,7 @@
         {
           "name": "formatAmount",
           "type": "((amount: number) => string)",
-          "required": false,
-          "default": "(amount: number) =>\n  Math.abs(amount).toLocaleString('en-US', { style: 'currency', currency: 'USD' })",
-          "description": "Defaults to USD currency, 2 decimals."
+          "required": false
         },
         {
           "name": "chart",
@@ -5691,15 +5948,16 @@
           "change"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { StockMarket } from '@sakaniui/react';\n\n<StockMarket logo=\"/images/example.jpg\" symbol=\"Symbol\" name=\"Name\" price={49} change={{ amount: 49, percent: 50 }} />"
     },
     {
       "name": "StockStatus",
       "kind": "component",
       "category": "E-commerce",
       "import": "@sakaniui/react",
-      "source": "src/components/ECommerceComponents/StockStatus/StockStatus.tsx",
-      "summary": "Matches Figma \"Stock Status\" (E-commerce set): a subtle-emphasis Badge in success/warning/danger.",
+      "summary": "A stock availability badge (success, warning or danger) derived from `quantity` and `lowStockThreshold`.",
       "props": [
         {
           "name": "quantity",
@@ -5710,7 +5968,7 @@
           "name": "lowStockThreshold",
           "type": "number",
           "required": false,
-          "default": "5",
+          "default": 5,
           "description": "At or below this (and above 0), shows \"Only N left\" in warning. Defaults to 5."
         },
         {
@@ -5730,15 +5988,16 @@
           "quantity"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { StockStatus } from '@sakaniui/react';\n\n<StockStatus quantity={1} />"
     },
     {
       "name": "SubFeature",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/SubFeature/SubFeature.tsx",
-      "summary": "Matches Figma \"Sub Feature\" (Marketing primitives set, 2 independent axes: Layout (Horizontal/Vertical) x Left border (True/False)).",
+      "summary": "A feature item with icon, title and description; `layout` is \"vertical\" or \"horizontal\" and `leftBorder` adds a rail.",
       "props": [
         {
           "name": "icon",
@@ -5763,15 +6022,13 @@
             "vertical",
             "horizontal"
           ],
-          "default": "horizontal",
-          "description": "Figma Layout axis. Defaults to \"horizontal\"."
+          "default": "horizontal"
         },
         {
           "name": "leftBorder",
           "type": "boolean",
           "required": false,
-          "default": "false",
-          "description": "Figma \"Left border\" axis. Defaults to false."
+          "default": false
         },
         {
           "name": "className",
@@ -5786,15 +6043,16 @@
           "description"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { SubFeature } from '@sakaniui/react';\n\n<SubFeature icon=\"Icon\" title=\"Title\" description=\"Description\" />"
     },
     {
       "name": "Switch",
       "kind": "component",
       "category": "Forms",
       "import": "@sakaniui/react",
-      "source": "src/components/Switch/Switch.tsx",
-      "summary": "Toggle switch. Matches Figma \"Switch\" set (SW axis): Off | On | Disabled. Track spec from Figma: 36x20, radius-full, bg/muted (off) / accent/default (on).",
+      "summary": "Toggle switch.",
       "props": [
         {
           "name": "label",
@@ -5817,20 +6075,21 @@
             "stretch"
           ],
           "default": "default",
-          "description": "`stretch` adds a liquid motion: the thumb stretches as it travels, then settles to a circle. `default` is the plain switch. Figma: Switch, Type axis."
+          "description": "`stretch` adds a liquid motion: the thumb stretches as it travels, then settles to a circle. `default` is the plain switch."
         }
       ],
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Switch } from '@sakaniui/react';\n\n<Switch />"
     },
     {
       "name": "Table",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Table/Table.tsx",
       "summary": "Data table.",
       "props": [
         {
@@ -5878,8 +6137,8 @@
           "name": "bordered",
           "type": "boolean",
           "required": false,
-          "default": "true",
-          "description": "Draws the table's own container border/radius. Defaults to true; set false when nesting inside a card that already has its own border (Figma: some Table instances sit borderless inside a Panel)."
+          "default": true,
+          "description": "Draws the table's own container border/radius."
         },
         {
           "name": "responsive",
@@ -5890,8 +6149,7 @@
             "stacked",
             "auto"
           ],
-          "default": "auto",
-          "description": "Matches Figma's \"Responsive\" variant (Default / Stacked). - 'auto' (default): renders as a normal table, and switches to the stacked card layout automatically below --bp-sm (640px). - 'default' / 'stacked': force one layout regardless of viewport — useful for Storybook, tests, or a deliberately narrow container."
+          "default": "auto"
         },
         {
           "name": "className",
@@ -5905,15 +6163,16 @@
           "rows"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Table } from '@sakaniui/react';\n\n<Table columns={[]} rows={[{}]} />"
     },
     {
       "name": "Tabs",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Tabs/Tabs.tsx",
-      "summary": "Horizontal tab navigation. Matches Figma \"Tabs\" set (2–6 tabs).",
+      "summary": "Horizontal tab navigation.",
       "props": [
         {
           "name": "items",
@@ -5941,14 +6200,14 @@
           "name": "bordered",
           "type": "boolean",
           "required": false,
-          "default": "true",
+          "default": true,
           "description": "Bottom border under the whole track. Defaults to true."
         },
         {
           "name": "fill",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Stretch every tab to share the row's width equally, like a segmented control, instead of each tab hugging its own label. Defaults to false."
         },
         {
@@ -5962,15 +6221,16 @@
           "items"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Tabs } from '@sakaniui/react';\n\n<Tabs items={[{ value: \"Value\", label: \"Label\" }]} />"
     },
     {
       "name": "Tags",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/Tags/Tags.tsx",
-      "summary": "Matches Figma \"Tags\" -- a wrapped row of pill tags.",
+      "summary": "A wrapped row of pill tags. Passing `onRemove` makes every tag removable.",
       "props": [
         {
           "name": "tags",
@@ -5994,15 +6254,16 @@
           "tags"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Tags } from '@sakaniui/react';\n\n<Tags tags={[\"Tag\"]} />"
     },
     {
       "name": "TeamCard",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/TeamCard/TeamCard.tsx",
-      "summary": "Matches Figma \"Team Card\" (Marketing primitives set, 2 styles: Card, Card details).",
+      "summary": "A team member card with photo, name, role, location and social links; passing `bio` switches to the detailed style.",
       "props": [
         {
           "name": "image",
@@ -6065,15 +6326,16 @@
           "location"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { TeamCard } from '@sakaniui/react';\n\n<TeamCard image=\"/images/example.jpg\" name=\"Name\" role=\"Role\" location=\"Location\" />"
     },
     {
       "name": "Textarea",
       "kind": "component",
       "category": "Forms",
       "import": "@sakaniui/react",
-      "source": "src/components/Textarea/Textarea.tsx",
-      "summary": "Multi-line text input. Matches Figma \"Textarea\" parent component: State (Default|Focus|Error|Disabled|Filled), Title/Description toggles.",
+      "summary": "Multi-line text input.",
       "props": [
         {
           "name": "label",
@@ -6094,15 +6356,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Textarea } from '@sakaniui/react';\n\n<Textarea />"
     },
     {
       "name": "Ticker",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/Ticker/Ticker.tsx",
-      "summary": "Matches Figma \"Ticker\" -- a row of symbol/change pairs with fade-out edges.",
+      "summary": "A scrolling row of symbol and change pairs with faded edges; pauses on hover and stops under prefers-reduced-motion.",
       "props": [
         {
           "name": "items",
@@ -6113,14 +6376,13 @@
           "name": "speed",
           "type": "number",
           "required": false,
-          "default": "40",
+          "default": 40,
           "description": "Scroll speed in pixels/second. Defaults to 40."
         },
         {
           "name": "formatChange",
           "type": "((changePercent: number) => string)",
-          "required": false,
-          "default": "(changePercent: number) =>\n  `${changePercent >= 0 ? '+' : ''}${changePercent}%`"
+          "required": false
         },
         {
           "name": "className",
@@ -6133,15 +6395,16 @@
           "items"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Ticker } from '@sakaniui/react';\n\n<Ticker items={[{ symbol: \"Symbol\", changePercent: 50 }]} />"
     },
     {
       "name": "Toast",
       "kind": "component",
       "category": "Composite",
       "import": "@sakaniui/react",
-      "source": "src/components/Toast/Toast.tsx",
-      "summary": "Transient notification. Matches Figma \"Toast\" set: Status (Success|Error|Info), Title/Description toggles.",
+      "summary": "Transient notification.",
       "props": [
         {
           "name": "status",
@@ -6152,8 +6415,7 @@
             "success",
             "error"
           ],
-          "default": "info",
-          "description": "Figma Status axis. Defaults to \"info\"."
+          "default": "info"
         },
         {
           "name": "title",
@@ -6180,27 +6442,26 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Toast } from '@sakaniui/react';\n\n<Toast />"
     },
     {
       "name": "Tooltip",
       "kind": "component",
       "category": "Core",
       "import": "@sakaniui/react",
-      "source": "src/components/Tooltip/Tooltip.tsx",
       "summary": "Hover/focus tooltip with a title, optional subtitle, a caret (tail), and 8 pointer positions.",
       "props": [
         {
           "name": "title",
           "type": "string",
-          "required": true,
-          "description": "Tooltip title (Figma: Title)."
+          "required": true
         },
         {
           "name": "subtitle",
           "type": "string",
-          "required": false,
-          "description": "Optional supporting line (Figma: Subtitle)."
+          "required": false
         },
         {
           "name": "pointer",
@@ -6217,7 +6478,7 @@
             "center-right"
           ],
           "default": "top-center",
-          "description": "Pointer position. Maps to Figma Pointer axis. Defaults to \"top-center\"."
+          "description": "Pointer position. Defaults to \"top-center\"."
         },
         {
           "name": "children",
@@ -6237,15 +6498,16 @@
           "children"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Tooltip } from '@sakaniui/react';\n\n<Tooltip title=\"Title\">Label</Tooltip>"
     },
     {
       "name": "TopBar",
       "kind": "component",
       "category": "Navigation",
       "import": "@sakaniui/react",
-      "source": "src/components/TopBar/TopBar.tsx",
-      "summary": "Application top bar — sits beside the Sidebar (1440 − 248 = 1192 default, but stretches to fill).",
+      "summary": "The application top bar, placed beside the Sidebar; `type` is \"search\", \"minimal\", \"breadcrumb\", \"tabs\" or \"chat\", and `density` is \"sm\" or \"md\".",
       "props": [
         {
           "name": "type",
@@ -6280,7 +6542,7 @@
           "name": "showToggle",
           "type": "boolean",
           "required": false,
-          "default": "true",
+          "default": true,
           "description": "Show the sidebar toggle. Defaults to true."
         },
         {
@@ -6292,28 +6554,27 @@
           "name": "toggleIcon",
           "type": "IconComponent",
           "required": false,
-          "default": "createIcon(\"layout-sidebar\", [\"M4 6a2 2 0 0 1 2 -2h12a2 2 0 0 1 2 2v12a2 2 0 0 1 -2 2h-12a2 2 0 0 1 -2 -2l0 -12\",\"M9 4l0 16\"])",
           "description": "Icon for the sidebar toggle button. Defaults to PanelLeft."
         },
         {
           "name": "showActions",
           "type": "boolean",
           "required": false,
-          "default": "true",
+          "default": true,
           "description": "Show help + notification icons. Defaults to true."
         },
         {
           "name": "showHelp",
           "type": "boolean",
           "required": false,
-          "default": "true",
+          "default": true,
           "description": "Show the help icon within the actions group. Defaults to true."
         },
         {
           "name": "hasUnread",
           "type": "boolean",
           "required": false,
-          "default": "false"
+          "default": false
         },
         {
           "name": "rightSlot",
@@ -6331,7 +6592,7 @@
           "name": "accountOpen",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Flips the account chevron when the menu it opens is open. Defaults to false."
         },
         {
@@ -6367,14 +6628,15 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { TopBar } from '@sakaniui/react';\n\n<TopBar />"
     },
     {
       "name": "TopBarMobile",
       "kind": "component",
       "category": "Navigation",
       "import": "@sakaniui/react",
-      "source": "src/components/TopBarMobile/TopBarMobile.tsx",
       "summary": "Mobile app bar (390×56).",
       "props": [
         {
@@ -6430,15 +6692,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { TopBarMobile } from '@sakaniui/react';\n\n<TopBarMobile />"
     },
     {
       "name": "Transactions",
       "kind": "component",
       "category": "Application",
       "import": "@sakaniui/react",
-      "source": "src/components/ApplicationComponents/Transactions/Transactions.tsx",
-      "summary": "Matches Figma \"Transactions\" -- both style previews collapse to one derived axis, same judgment applied throughout this Application set: the Empty state renders whenever `transactions` is empty, rather than a separate manual prop that could disagree with th...",
+      "summary": "A list of transactions; shows an empty state when `transactions` is empty.",
       "props": [
         {
           "name": "transactions",
@@ -6448,8 +6711,7 @@
         {
           "name": "formatAmount",
           "type": "((amount: number) => string)",
-          "required": false,
-          "default": "(amount: number) =>\n  `${amount >= 0 ? '+' : '-'}${Math.abs(amount).toLocaleString('en-US', { style: 'currency', currency: 'USD' })}`"
+          "required": false
         },
         {
           "name": "emptyTitle",
@@ -6474,21 +6736,22 @@
           "transactions"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { Transactions } from '@sakaniui/react';\n\n<Transactions transactions={[{ name: \"Name\", category: \"Category\", amount: 49, icon: \"Icon\" }]} />"
     },
     {
       "name": "WishlistButton",
       "kind": "component",
       "category": "E-commerce",
       "import": "@sakaniui/react",
-      "source": "src/components/ECommerceComponents/WishlistButton/WishlistButton.tsx",
-      "summary": "Matches Figma \"Wishlist Button\" (E-commerce set): a 36px bg/surface square, radius-md, shadow-xs, no border.",
+      "summary": "A square heart toggle for saving a product; `saved` fills the heart.",
       "props": [
         {
           "name": "saved",
           "type": "boolean",
           "required": false,
-          "default": "false"
+          "default": false
         },
         {
           "name": "onToggle",
@@ -6511,35 +6774,37 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { WishlistButton } from '@sakaniui/react';\n\n<WishlistButton />"
     },
     {
       "name": "XIcon",
       "kind": "component",
       "category": "Marketing",
       "import": "@sakaniui/react",
-      "source": "src/components/MarketingComponents/ProfileCard/SocialIcons.tsx",
-      "summary": "svg) -- lucide-react ships no brand/logo icons in the version this library uses.",
+      "summary": "X (Twitter) brand mark drawn in currentColor, for social links.",
       "props": [
         {
           "name": "size",
           "type": "number",
           "required": false,
-          "default": "16"
+          "default": 16
         }
       ],
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { XIcon } from '@sakaniui/react';\n\n<XIcon />"
     },
     {
       "name": "AccountOverviewBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/AccountOverviewBlock/AccountOverviewBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "Account Overview block (Application): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "state",
@@ -6560,15 +6825,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { AccountOverviewBlock } from '@sakaniui/react/blocks';\n\n<AccountOverviewBlock />"
     },
     {
       "name": "ActivityLogBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/ActivityLogBlock/ActivityLogBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "Activity Log block (Application): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "state",
@@ -6589,15 +6855,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { ActivityLogBlock } from '@sakaniui/react/blocks';\n\n<ActivityLogBlock />"
     },
     {
       "name": "AddCardFormBlock",
       "kind": "block",
       "category": "Blocks/Billing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/Billing/AddCardFormBlock/AddCardFormBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component.) in place of the simulated one here -- a real integration should never send a raw PAN/CVC to your own backend at all.",
+      "summary": "Add Card Form block (Billing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "initialValue",
@@ -6631,15 +6898,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { AddCardFormBlock } from '@sakaniui/react/blocks';\n\n<AddCardFormBlock />"
     },
     {
       "name": "AppHeaderBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/AppHeaderBlock/AppHeaderBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "App Header block (Application): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "breadcrumbs",
@@ -6674,27 +6942,26 @@
           "title"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { AppHeaderBlock } from '@sakaniui/react/blocks';\n\n<AppHeaderBlock breadcrumbs={[{ label: \"Label\" }]} title=\"Title\" />"
     },
     {
       "name": "BillingAddressBlock",
       "kind": "block",
       "category": "Blocks/Billing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/Billing/BillingAddressBlock/BillingAddressBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire `onSave` to your real API call in place of the simulated one here.",
+      "summary": "Billing Address block (Billing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "initialValue",
           "type": "Partial<BillingAddressValue>",
-          "required": false,
-          "description": "Seeds the fields -- presence/absence is what distinguishes Figma's own Default vs. Filled previews."
+          "required": false
         },
         {
           "name": "countries",
           "type": "SelectOption[]",
-          "required": false,
-          "default": "[\n  { label: '🇳🇬 Nigeria', value: 'NG' },\n  { label: '🇺🇸 United States', value: 'US' },\n  { label: '🇬🇧 United Kingdom', value: 'GB' },\n  { label: '🇰🇪 Kenya', value: 'KE' },\n  { label: '🇿🇦 South Africa', value: 'ZA' },\n]"
+          "required": false
         },
         {
           "name": "initialStatus",
@@ -6723,15 +6990,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { BillingAddressBlock } from '@sakaniui/react/blocks';\n\n<BillingAddressBlock />"
     },
     {
       "name": "BillingHistoryBlock",
       "kind": "block",
       "category": "Blocks/Billing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/Billing/BillingHistoryBlock/BillingHistoryBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire `onDownload` to your real invoice PDF endpoint in place of the callback here.",
+      "summary": "Billing History block (Billing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "invoices",
@@ -6743,7 +7011,7 @@
           "name": "loading",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Shows the Skeleton loading state in place of `invoices` -- unlike Empty (derived from `invoices.length === 0`), there's no data yet at this point to derive it from."
         },
         {
@@ -6755,15 +7023,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { BillingHistoryBlock } from '@sakaniui/react/blocks';\n\n<BillingHistoryBlock />"
     },
     {
       "name": "BlogListingBlock",
       "kind": "block",
       "category": "Blocks/Marketing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/BlogListingBlock/BlogListingBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire \"Read article\"/card clicks to your real routing in place of the callbacks here.",
+      "summary": "Blog Listing block (Marketing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "eyebrow",
@@ -6805,15 +7074,16 @@
           "posts"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { BlogListingBlock } from '@sakaniui/react/blocks';\n\n<BlogListingBlock title=\"Title\" featuredPost={{ image: \"/images/example.jpg\", title: \"Title\", excerpt: \"Excerpt\", author: { name: \"Name\", date: \"Oct 21, 2026\" } }} posts={[{ image: \"/images/example.jpg\", category: \"Category\", readTime: \"5 min read\", title: \"Title\", excerpt: \"Excerpt\", author: { name: \"Name\", date: \"Oct 21, 2026\" } }]} />"
     },
     {
       "name": "CareersBlock",
       "kind": "block",
       "category": "Blocks/Marketing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/CareersBlock/CareersBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire \"Apply now\" to your real ATS/ application flow in place of the callback here.",
+      "summary": "Careers block (Marketing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "eyebrow",
@@ -6849,15 +7119,16 @@
           "jobs"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { CareersBlock } from '@sakaniui/react/blocks';\n\n<CareersBlock title=\"Title\" jobs={[{ description: \"Description\", title: \"Title\", department: \"Department\", employmentType: \"Employment type\", location: \"Location\" }]} />"
     },
     {
       "name": "ChatInterfaceBlock",
       "kind": "block",
       "category": "Blocks/Chat",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/ChatInterfaceBlock/ChatInterfaceBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file and edit it: change the nav groups, swap the conversations, edit the thread.",
+      "summary": "Chat Interface block (Chat): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "state",
@@ -6879,15 +7150,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { ChatInterfaceBlock } from '@sakaniui/react/blocks';\n\n<ChatInterfaceBlock />"
     },
     {
       "name": "CheckoutFlowBlock",
       "kind": "block",
       "category": "Blocks/E-commerce",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/CheckoutFlowBlock/CheckoutFlowBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire the form submissions to your real shipping/payment APIs in place of the simulated flow here.",
+      "summary": "Checkout Flow block (E-commerce): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "items",
@@ -6898,8 +7170,7 @@
           "name": "shippingCost",
           "type": "number",
           "required": false,
-          "default": "0",
-          "description": "0 (default) renders \"Free\" in the summary, matching Figma."
+          "default": 0
         },
         {
           "name": "initialStep",
@@ -6919,8 +7190,7 @@
         {
           "name": "formatPrice",
           "type": "((amount: number) => string)",
-          "required": false,
-          "default": "(amount: number) =>\n  amount.toLocaleString('en-US', { style: 'currency', currency: 'USD' })"
+          "required": false
         },
         {
           "name": "className",
@@ -6933,15 +7203,16 @@
           "items"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { CheckoutFlowBlock } from '@sakaniui/react/blocks';\n\n<CheckoutFlowBlock items={[{ image: \"/images/example.jpg\", name: \"Name\", price: 49, quantity: 1 }]} />"
     },
     {
       "name": "CRMDashboardBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/CRMDashboardBlock/CRMDashboardBlock.tsx",
-      "summary": "A full-page CRM leads view assembled entirely from Sakani components: Sidebar (icon rail) · TopBar · Breadcrumb · Tabs · Checkbox · Select · Slider · Input · FilterChip · Button · Table · Pagination · Badge · Avatar.",
+      "summary": "CRM Dashboard block (Application): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "className",
@@ -6958,15 +7229,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { CRMDashboardBlock } from '@sakaniui/react/blocks';\n\n<CRMDashboardBlock />"
     },
     {
       "name": "CtaBannerBlock",
       "kind": "block",
       "category": "Blocks/Marketing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/CtaBannerBlock/CtaBannerBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire the two actions to your real signup/repo links in place of the callbacks here.",
+      "summary": "Cta Banner block (Marketing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "title",
@@ -6992,7 +7264,7 @@
           "name": "secondaryActionIcon",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Shows the GitHub icon before the secondary action's label."
         },
         {
@@ -7003,8 +7275,7 @@
             "neutral",
             "accent"
           ],
-          "default": "neutral",
-          "description": "Figma Style axis (renamed to avoid colliding with the DOM `style` prop). Defaults to \"neutral\"."
+          "default": "neutral"
         },
         {
           "name": "className",
@@ -7019,15 +7290,16 @@
           "primaryAction"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { CtaBannerBlock } from '@sakaniui/react/blocks';\n\n<CtaBannerBlock title=\"Title\" description=\"Description\" primaryAction={{ label: \"Label\" }} />"
     },
     {
       "name": "CurrentPlanBlock",
       "kind": "block",
       "category": "Blocks/Billing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/Billing/CurrentPlanBlock/CurrentPlanBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire the action callbacks to your real subscription-management API in place of the ones here.",
+      "summary": "Current Plan block (Billing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "planName",
@@ -7064,8 +7336,7 @@
           "name": "usageLabel",
           "type": "string",
           "required": false,
-          "default": "Projects used",
-          "description": "Usage row -- shown only in the \"active\" status, matching Figma."
+          "default": "Projects used"
         },
         {
           "name": "usageValue",
@@ -7076,7 +7347,7 @@
           "name": "usagePercent",
           "type": "number",
           "required": false,
-          "default": "0",
+          "default": 0,
           "description": "0–100, drives the Progress bar."
         },
         {
@@ -7114,7 +7385,7 @@
           "name": "loading",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Shows the Skeleton loading state in place of everything else -- there's no plan data yet at this point to derive a status from."
         },
         {
@@ -7129,15 +7400,16 @@
           "price"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { CurrentPlanBlock } from '@sakaniui/react/blocks';\n\n<CurrentPlanBlock planName=\"Plan name\" price=\"Price\" />"
     },
     {
       "name": "DataTableBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/DataTableBlock/DataTableBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: swap the sample data for your own, change the columns, add or remove toolbar controls.",
+      "summary": "Data Table block (Application): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "state",
@@ -7168,21 +7440,22 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { DataTableBlock } from '@sakaniui/react/blocks';\n\n<DataTableBlock />"
     },
     {
       "name": "EmailVerificationBlock",
       "kind": "block",
       "category": "Blocks/Authentication",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/EmailVerificationBlock/EmailVerificationBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire `onVerify`/`onResend` to your real API calls in place of the simulated ones here.",
+      "summary": "Email Verification block (Authentication): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "email",
           "type": "string",
           "required": false,
-          "default": "sam@sakani.com"
+          "default": "<email>"
         },
         {
           "name": "initialStatus",
@@ -7218,15 +7491,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { EmailVerificationBlock } from '@sakaniui/react/blocks';\n\n<EmailVerificationBlock />"
     },
     {
       "name": "FaqBlock",
       "kind": "block",
       "category": "Blocks/Marketing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/FaqBlock/FaqBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "Faq block (Marketing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "eyebrow",
@@ -7246,14 +7520,13 @@
         },
         {
           "name": "columns",
-          "type": "\"1\" | \"2\"",
+          "type": "1 | 2",
           "required": false,
           "values": [
-            "1",
-            "2"
+            1,
+            2
           ],
-          "default": "1",
-          "description": "Figma Layout axis: 1 = Single, 2 = Two-Column. Defaults to 1."
+          "default": 1
         },
         {
           "name": "className",
@@ -7267,15 +7540,16 @@
           "items"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { FaqBlock } from '@sakaniui/react/blocks';\n\n<FaqBlock title=\"Title\" items={[{ question: \"Question\", answer: \"Answer\" }]} />"
     },
     {
       "name": "FeatureGridBlock",
       "kind": "block",
       "category": "Blocks/Marketing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/FeatureGridBlock/FeatureGridBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "Feature Grid block (Marketing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "features",
@@ -7286,7 +7560,7 @@
           "name": "columns",
           "type": "number",
           "required": false,
-          "description": "Number of columns. Defaults to `features.length` (Figma's own examples never wrap)."
+          "description": "Number of columns."
         },
         {
           "name": "className",
@@ -7299,15 +7573,16 @@
           "features"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { FeatureGridBlock } from '@sakaniui/react/blocks';\n\n<FeatureGridBlock features={[{ icon: \"Icon\", title: \"Title\", description: \"Description\" }]} />"
     },
     {
       "name": "FileUploadPanelBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/FileUploadPanelBlock/FileUploadPanelBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "File Upload Panel block (Application): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "state",
@@ -7329,15 +7604,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { FileUploadPanelBlock } from '@sakaniui/react/blocks';\n\n<FileUploadPanelBlock />"
     },
     {
       "name": "ForgotPasswordBlock",
       "kind": "block",
       "category": "Blocks/Authentication",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/ForgotPasswordBlock/ForgotPasswordBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire `onSubmit`/`onResend` to your real API calls in place of the simulated ones here.",
+      "summary": "Forgot Password block (Authentication): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "initialStatus",
@@ -7383,15 +7659,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { ForgotPasswordBlock } from '@sakaniui/react/blocks';\n\n<ForgotPasswordBlock />"
     },
     {
       "name": "FormModalBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/FormModalBlock/FormModalBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: swap the fields for your own form.",
+      "summary": "Form Modal block (Application): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "open",
@@ -7415,15 +7692,16 @@
           "onClose"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { FormModalBlock } from '@sakaniui/react/blocks';\n\n<FormModalBlock open={true} onClose={() => {}} />"
     },
     {
       "name": "HeroBlock",
       "kind": "block",
       "category": "Blocks/Marketing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/HeroBlock/HeroBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire the two actions to your real signup/repo links in place of the callbacks here.",
+      "summary": "Hero block (Marketing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "eyebrow",
@@ -7455,7 +7733,7 @@
           "name": "secondaryActionIcon",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Shows the GitHub icon before the secondary action's label."
         },
         {
@@ -7488,8 +7766,7 @@
             "centered",
             "split"
           ],
-          "default": "centered",
-          "description": "Figma Layout axis. Defaults to \"centered\"."
+          "default": "centered"
         },
         {
           "name": "className",
@@ -7505,15 +7782,16 @@
           "image"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { HeroBlock } from '@sakaniui/react/blocks';\n\n<HeroBlock title=\"Title\" description=\"Description\" primaryAction={{ label: \"Label\" }} image=\"/images/example.jpg\" />"
     },
     {
       "name": "InlineCtaBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/InlineCtaBlock/InlineCtaBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "Inline Cta block (Application): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "variant",
@@ -7563,15 +7841,16 @@
           "actionLabel"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { InlineCtaBlock } from '@sakaniui/react/blocks';\n\n<InlineCtaBlock title=\"Title\" description=\"Description\" actionLabel=\"Action label\" />"
     },
     {
       "name": "KanbanBoardBlock",
       "kind": "block",
       "category": "Blocks/Data & Content",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/KanbanBoardBlock/KanbanBoardBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file and edit it: change the columns, swap the sample tasks, adjust the card content. Assembled entirely from Sakani components.",
+      "summary": "Kanban Board block (Data & Content): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "state",
@@ -7600,15 +7879,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { KanbanBoardBlock } from '@sakaniui/react/blocks';\n\n<KanbanBoardBlock />"
     },
     {
       "name": "LiquidDashboardBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/LiquidDashboardBlock/LiquidDashboardBlock.tsx",
-      "summary": "A full dashboard on a photograph, built the way the Sakani glass docs describe it: 1.",
+      "summary": "A composition example: a full dashboard over a photograph, with the photo as a LiquidBackdrop so every liquid-glass lens refracts it.",
       "props": [
         {
           "name": "backgroundImage",
@@ -7639,15 +7919,16 @@
           "backgroundImage"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.4.0",
+      "example": "import { LiquidDashboardBlock } from '@sakaniui/react/blocks';\n\n<LiquidDashboardBlock backgroundImage=\"/images/example.jpg\" />"
     },
     {
       "name": "LoginBlock",
       "kind": "block",
       "category": "Blocks/Authentication",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/LoginBlock/LoginBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire `onSubmit` to your real auth call in place of the simulated one here.",
+      "summary": "Login block (Authentication): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "initialStatus",
@@ -7698,15 +7979,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { LoginBlock } from '@sakaniui/react/blocks';\n\n<LoginBlock />"
     },
     {
       "name": "LogoCloudBlock",
       "kind": "block",
       "category": "Blocks/Marketing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/LogoCloudBlock/LogoCloudBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component.tsx for your own actual customers' logos.",
+      "summary": "Logo Cloud block (Marketing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "label",
@@ -7717,8 +7999,7 @@
         {
           "name": "brands",
           "type": "LogoCloudBrand[]",
-          "required": false,
-          "default": "['vercel', 'netlify', 'github', 'figma', 'notion', 'linear', 'stripe']"
+          "required": false
         },
         {
           "name": "variant",
@@ -7728,8 +8009,7 @@
             "color",
             "monochrome"
           ],
-          "default": "monochrome",
-          "description": "Figma Style axis (renamed to avoid colliding with the DOM `style` prop). Defaults to \"monochrome\"."
+          "default": "monochrome"
         },
         {
           "name": "className",
@@ -7740,15 +8020,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { LogoCloudBlock } from '@sakaniui/react/blocks';\n\n<LogoCloudBlock />"
     },
     {
       "name": "MultistepModalBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/MultistepModalBlock/MultistepModalBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: swap the steps/content for your own flow.",
+      "summary": "Multistep Modal block (Application): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "open",
@@ -7764,7 +8045,7 @@
           "name": "initialStep",
           "type": "number",
           "required": false,
-          "default": "0",
+          "default": 0,
           "description": "Which step to open on — for demoing a mid-flow state. Defaults to the first step."
         },
         {
@@ -7779,15 +8060,16 @@
           "onClose"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { MultistepModalBlock } from '@sakaniui/react/blocks';\n\n<MultistepModalBlock open={true} onClose={() => {}} />"
     },
     {
       "name": "NotificationPanelBlock",
       "kind": "block",
-      "category": "New comment on your design",
+      "category": "Blocks",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/NotificationPanelBlock/NotificationPanelBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "Notification Panel block: a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "items",
@@ -7810,15 +8092,16 @@
           "items"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { NotificationPanelBlock } from '@sakaniui/react/blocks';\n\n<NotificationPanelBlock items={[{ id: \"item-1\", title: \"Title\", timestamp: \"2 min ago\" }]} />"
     },
     {
       "name": "OnboardingProgressBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/OnboardingProgressBlock/OnboardingProgressBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "Onboarding Progress block (Application): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "title",
@@ -7852,15 +8135,16 @@
           "items"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { OnboardingProgressBlock } from '@sakaniui/react/blocks';\n\n<OnboardingProgressBlock items={[{ label: \"Label\", progress: 50 }]} />"
     },
     {
       "name": "OrderConfirmationBlock",
       "kind": "block",
       "category": "Blocks/E-commerce",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/OrderConfirmationBlock/OrderConfirmationBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire the \"Continue shopping\"/\"Track order\" actions to your real navigation in place of the no-op callbacks here.",
+      "summary": "Order Confirmation block (E-commerce): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "orderNumber",
@@ -7896,8 +8180,7 @@
         {
           "name": "formatPrice",
           "type": "((amount: number) => string)",
-          "required": false,
-          "default": "(amount: number) =>\n  amount.toLocaleString('en-US', { style: 'currency', currency: 'USD' })"
+          "required": false
         },
         {
           "name": "className",
@@ -7912,15 +8195,16 @@
           "total"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { OrderConfirmationBlock } from '@sakaniui/react/blocks';\n\n<OrderConfirmationBlock orderNumber=\"Order number\" items={[{ image: \"/images/example.jpg\", name: \"Name\", price: 49 }]} total={49} />"
     },
     {
       "name": "PaymentMethodBlock",
       "kind": "block",
       "category": "Blocks/Billing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/Billing/PaymentMethodBlock/PaymentMethodBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component.) update/add flows.",
+      "summary": "Payment Method block (Billing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "card",
@@ -7942,7 +8226,7 @@
           "name": "loading",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Shows the Skeleton loading state in place of everything else -- there's no card data yet at this point to derive a status from."
         },
         {
@@ -7954,15 +8238,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { PaymentMethodBlock } from '@sakaniui/react/blocks';\n\n<PaymentMethodBlock />"
     },
     {
       "name": "PricingTableBlock",
       "kind": "block",
       "category": "Blocks/Marketing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/PricingTableBlock/PricingTableBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire each plan's CTA to your real checkout/contact flow in place of the callbacks here.",
+      "summary": "Pricing Table block (Marketing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "eyebrow",
@@ -7998,15 +8283,16 @@
           "plans"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { PricingTableBlock } from '@sakaniui/react/blocks';\n\n<PricingTableBlock title=\"Title\" plans={[{ name: \"Name\", price: \"Price\", description: \"Description\", ctaLabel: \"Cta label\", features: [\"Feature\"] }]} />"
     },
     {
       "name": "ProductDetailBlock",
       "kind": "block",
       "category": "Blocks/E-commerce",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/ProductDetailBlock/ProductDetailBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire \"Add to cart\" to your real cart state/API in place of the callback here.",
+      "summary": "Product Detail block (E-commerce): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "name",
@@ -8064,8 +8350,7 @@
         {
           "name": "defaultColor",
           "type": "string",
-          "required": false,
-          "description": "Defaults to the first available option in each list."
+          "required": false
         },
         {
           "name": "defaultSize",
@@ -8076,7 +8361,7 @@
           "name": "minQuantity",
           "type": "number",
           "required": false,
-          "default": "1"
+          "default": 1
         },
         {
           "name": "maxQuantity",
@@ -8087,7 +8372,7 @@
           "name": "defaultSaved",
           "type": "boolean",
           "required": false,
-          "default": "false"
+          "default": false
         },
         {
           "name": "onAddToCart",
@@ -8097,8 +8382,7 @@
         {
           "name": "formatPrice",
           "type": "((amount: number) => string)",
-          "required": false,
-          "default": "(amount: number) =>\n  amount.toLocaleString('en-US', { style: 'currency', currency: 'USD' })"
+          "required": false
         },
         {
           "name": "className",
@@ -8116,15 +8400,16 @@
           "description"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { ProductDetailBlock } from '@sakaniui/react/blocks';\n\n<ProductDetailBlock name=\"Name\" images={[{ src: \"/images/example.jpg\" }]} rating={4} stockQuantity={1} price={49} description=\"Description\" />"
     },
     {
       "name": "ProductGridBlock",
       "kind": "block",
       "category": "Blocks/E-commerce",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/ProductGridBlock/ProductGridBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire \"Add Item\"/wishlist/sort to your real cart/catalog state in place of the callbacks here.",
+      "summary": "Product Grid block (E-commerce): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "eyebrow",
@@ -8152,7 +8437,7 @@
           "name": "showFilterBar",
           "type": "boolean",
           "required": false,
-          "default": "false",
+          "default": false,
           "description": "Adds the \"N products\" count + Sort button row above the grid -- see the file doc for why this stays a real prop rather than being derived."
         },
         {
@@ -8170,8 +8455,8 @@
           "name": "columns",
           "type": "number",
           "required": false,
-          "default": "4",
-          "description": "Number of columns at full width. Defaults to 4, matching Figma."
+          "default": 4,
+          "description": "Number of columns at full width."
         },
         {
           "name": "className",
@@ -8185,15 +8470,16 @@
           "products"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { ProductGridBlock } from '@sakaniui/react/blocks';\n\n<ProductGridBlock title=\"Title\" products={[{ image: \"/images/example.jpg\", name: \"Name\", price: 49 }]} />"
     },
     {
       "name": "ProfileSettingsBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/ProfileSettingsBlock/ProfileSettingsBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "Profile Settings block (Application): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "name",
@@ -8226,15 +8512,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.1.0",
+      "example": "import { ProfileSettingsBlock } from '@sakaniui/react/blocks';\n\n<ProfileSettingsBlock />"
     },
     {
       "name": "ResetPasswordBlock",
       "kind": "block",
       "category": "Blocks/Authentication",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/ResetPasswordBlock/ResetPasswordBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component.",
+      "summary": "Reset Password block (Authentication): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "initialStatus",
@@ -8274,15 +8561,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { ResetPasswordBlock } from '@sakaniui/react/blocks';\n\n<ResetPasswordBlock />"
     },
     {
       "name": "SectionFooterBlock",
       "kind": "block",
       "category": "Blocks/Application",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/SectionFooterBlock/SectionFooterBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "Section Footer block (Application): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "text",
@@ -8293,8 +8581,7 @@
         {
           "name": "links",
           "type": "SectionFooterLink[]",
-          "required": false,
-          "default": "[\n  { label: 'Docs', href: '#' },\n  { label: 'Status', href: '#' },\n  { label: 'Support', href: '#' },\n]"
+          "required": false
         },
         {
           "name": "variant",
@@ -8315,15 +8602,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { SectionFooterBlock } from '@sakaniui/react/blocks';\n\n<SectionFooterBlock />"
     },
     {
       "name": "ShoppingCartBlock",
       "kind": "block",
       "category": "Blocks/E-commerce",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/ShoppingCartBlock/ShoppingCartBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire \"Checkout\"/\"Continue shopping\" to your real cart/checkout flow in place of the callbacks here.",
+      "summary": "Shopping Cart block (E-commerce): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "items",
@@ -8334,8 +8622,7 @@
           "name": "shippingCost",
           "type": "number",
           "required": false,
-          "default": "0",
-          "description": "0 (default) renders \"Free\" in the summary, matching Figma."
+          "default": 0
         },
         {
           "name": "onCheckout",
@@ -8350,8 +8637,7 @@
         {
           "name": "formatPrice",
           "type": "((amount: number) => string)",
-          "required": false,
-          "default": "(amount: number) =>\n  amount.toLocaleString('en-US', { style: 'currency', currency: 'USD' })"
+          "required": false
         },
         {
           "name": "className",
@@ -8364,15 +8650,16 @@
           "items"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { ShoppingCartBlock } from '@sakaniui/react/blocks';\n\n<ShoppingCartBlock items={[{ image: \"/images/example.jpg\", name: \"Name\", price: 49, quantity: 1 }]} />"
     },
     {
       "name": "SignUpBlock",
       "kind": "block",
       "category": "Blocks/Authentication",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/SignUpBlock/SignUpBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire `onSubmit` to your real registration call in place of the simulated one here.",
+      "summary": "Sign Up block (Authentication): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "initialStatus",
@@ -8412,15 +8699,16 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { SignUpBlock } from '@sakaniui/react/blocks';\n\n<SignUpBlock />"
     },
     {
       "name": "TeamSectionBlock",
       "kind": "block",
       "category": "Blocks/Marketing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/TeamSectionBlock/TeamSectionBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "Team Section block (Marketing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "eyebrow",
@@ -8456,15 +8744,16 @@
           "members"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { TeamSectionBlock } from '@sakaniui/react/blocks';\n\n<TeamSectionBlock title=\"Title\" members={[{ name: \"Name\", role: \"Role\", location: \"Location\", image: \"/images/example.jpg\" }]} />"
     },
     {
       "name": "TestimonialBlock",
       "kind": "block",
       "category": "Blocks/Marketing",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/TestimonialBlock/TestimonialBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly.",
+      "summary": "Testimonial block (Marketing): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "testimonials",
@@ -8482,15 +8771,16 @@
           "testimonials"
         ],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { TestimonialBlock } from '@sakaniui/react/blocks';\n\n<TestimonialBlock testimonials={[{ quote: \"Quote\", authorName: \"Author name\", authorRole: \"Author role\" }]} />"
     },
     {
       "name": "TwoFactorAuthBlock",
       "kind": "block",
       "category": "Blocks/Authentication",
       "import": "@sakaniui/react/blocks",
-      "source": "src/blocks/TwoFactorAuthBlock/TwoFactorAuthBlock.tsx",
-      "summary": "A COMPOSITION EXAMPLE, not a configurable component. Copy this file into your project and edit it directly: wire `onVerify`/`onUseBackupCode` to your real API calls in place of the simulated ones here.",
+      "summary": "Two Factor Auth block (Authentication): a composition example. Copy it into your project and edit it.",
       "props": [
         {
           "name": "initialStatus",
@@ -8526,7 +8816,41 @@
       "contract": {
         "requiredProps": [],
         "requiresAccessibleName": false
-      }
+      },
+      "since": "0.3.0",
+      "example": "import { TwoFactorAuthBlock } from '@sakaniui/react/blocks';\n\n<TwoFactorAuthBlock />"
+    }
+  ],
+  "utilities": [
+    {
+      "name": "DEFAULT_CHECKOUT_STEPS",
+      "kind": "constant",
+      "import": "@sakaniui/react"
+    },
+    {
+      "name": "getContrastColor",
+      "kind": "helper",
+      "import": "@sakaniui/react"
+    },
+    {
+      "name": "iconStrokeWidth",
+      "kind": "helper",
+      "import": "@sakaniui/react"
+    },
+    {
+      "name": "syncLiquidBackdrop",
+      "kind": "helper",
+      "import": "@sakaniui/react"
+    },
+    {
+      "name": "useHoverHighlight",
+      "kind": "hook",
+      "import": "@sakaniui/react"
+    },
+    {
+      "name": "useLiquidGlass",
+      "kind": "hook",
+      "import": "@sakaniui/react"
     }
   ]
 }