ui-lab-registry 0.3.44 → 0.3.45

package/src/components/Button/examples.json

@@ -1,13 +1,13 @@
 {
   "01-variants": {
     "title": "Button Variants",
-    "description": "All available button variants including primary, default, secondary, outline, and ghost styles.",
-    "code": "import React from 'react'\nimport { Button } from 'ui-lab-components'\n\nexport default function Example() {\n  return (\n    <div className=\"p-4 space-y-8\">\n      <div>\n        <h3 className=\"text-sm font-semibold text-foreground-200 mb-3\">Primary Variant</h3>\n        <div className=\"flex gap-2 flex-wrap\">\n          <Button variant=\"primary\">Primary Button</Button>\n          <Button variant=\"primary\" disabled>Disabled</Button>\n        </div>\n      </div>\n\n      <div>\n        <h3 className=\"text-sm font-semibold text-foreground-200 mb-3\">Default Variant</h3>\n        <div className=\"flex gap-2 flex-wrap\">\n          <Button variant=\"default\">Default Button</Button>\n          <Button variant=\"default\" disabled>Disabled</Button>\n        </div>\n      </div>\n\n      <div>\n        <h3 className=\"text-sm font-semibold text-foreground-200 mb-3\">Secondary Variant</h3>\n        <div className=\"flex gap-2 flex-wrap\">\n          <Button variant=\"secondary\">Secondary Button</Button>\n          <Button variant=\"secondary\" disabled>Disabled</Button>\n        </div>\n      </div>\n\n      <div>\n        <h3 className=\"text-sm font-semibold text-foreground-200 mb-3\">Outline Variant</h3>\n        <div className=\"flex gap-2 flex-wrap\">\n          <Button variant=\"outline\">Outline Button</Button>\n          <Button variant=\"outline\" disabled>Disabled</Button>\n        </div>\n      </div>\n\n      <div>\n        <h3 className=\"text-sm font-semibold text-foreground-200 mb-3\">Ghost Variant</h3>\n        <div className=\"flex gap-2 flex-wrap\">\n          <Button variant=\"ghost\">Ghost Button</Button>\n          <Button variant=\"ghost\" disabled>Disabled</Button>\n        </div>\n      </div>\n\n      <div>\n        <h3 className=\"text-sm font-semibold text-foreground-200 mb-3\">Sizes</h3>\n        <div className=\"flex gap-2 flex-wrap items-center\">\n          <Button size=\"sm\">Small</Button>\n          <Button size=\"md\">Medium</Button>\n          <Button size=\"lg\">Large</Button>\n        </div>\n      </div>\n    </div>\n  )\n}"
+    "description": "All available button variants side by side in a single row.",
+    "code": "import React from 'react'\nimport { Button, Flex } from 'ui-lab-components'\n\nconst buttonVariants = [\n  { label: \"Primary\", variant: \"primary\" },\n  { label: \"Default\", variant: \"default\" },\n  { label: \"Secondary\", variant: \"secondary\" },\n  { label: \"Outline\", variant: \"outline\" },\n  { label: \"Ghost\", variant: \"ghost\" },\n  { label: \"Danger\", variant: \"danger\" },\n] as const;\n\nexport default function Example() {\n  return (\n    <Flex gap=\"xs\" align=\"center\" justify=\"center\" wrap=\"nowrap\">\n      {buttonVariants.map((button) => (\n        <Button key={button.variant} variant={button.variant}>\n          {button.label}\n        </Button>\n      ))}\n    </Flex>\n  )\n}"
   },
   "02-multi-actions": {
     "title": "Multiple Actions",
     "description": "A primary action button grouped with secondary actions and an options menu.",
-    "code": "\"use client\";\n\nimport React, { useState } from 'react'\nimport { Button, Flex } from 'ui-lab-components'\nimport { FaEllipsisVertical } from \"react-icons/fa6\";\n\nexport default function Example() {\n  return (\n    <Flex gap=\"xs\" className=\"w-110 *:not-last:flex-1\">\n      <Button size=\"sm\" variant=\"primary\" >Subscribe</Button>\n      <Button size=\"sm\" >Message</Button>\n      <Button size=\"icon\" variant=\"outline\" icon={<FaEllipsisVertical />} />\n    </Flex>\n  );\n}"
+    "code": "\"use client\";\n\nimport { Button, Flex } from 'ui-lab-components'\nimport { FaEllipsisVertical } from \"react-icons/fa6\";\n\nexport default function Example() {\n  return (\n    <Flex gap=\"xs\" className=\"w-110 *:not-last:flex-1\">\n      <Button size=\"sm\" variant=\"primary\" >Subscribe</Button>\n      <Button size=\"sm\" >Message</Button>\n      <Button size=\"icon\" variant=\"outline\" icon={<FaEllipsisVertical />} />\n    </Flex>\n  );\n}"
   },
   "03-joined-toggle": {
     "title": "Joined Toggle Buttons",
@@ -17,11 +17,26 @@
   "04-sub-stack-actions": {
     "title": "Sub Stack Actions",
     "description": "A collection of buttons and inputs arranged horizontally for grouped actions and filtering.",
-    "code": "\"use client\";\n\nimport React, { useState } from 'react'\nimport { Button, Group, Input, Badge, Flex } from 'ui-lab-components'\nimport { FaList, FaGrip, FaPlus } from \"react-icons/fa6\";\nimport { LuSearch } from \"react-icons/lu\";\n\nexport default function Example() {\n  const [viewMode, setViewMode] = useState(\"list\");\n  return (\n    <Flex align=\"center\" gap=\"xs\" className=\"w-110\">\n      <Group orientation=\"horizontal\" spacing=\"xs\" value={viewMode} onChange={setViewMode}>\n        <Group.Button size=\"icon\" value=\"list\"><FaList /></Group.Button>\n        <Group.Button size=\"icon\" value=\"grid\"><FaGrip /></Group.Button>\n      </Group>\n      <Input\n        placeholder=\"Search...\"\n        icon={<LuSearch />}\n        hint={<Badge size=\"sm\" variant=\"secondary\" >Ctrl+K</Badge>}\n      />\n      <Button size=\"sm\" icon={{ right: <FaPlus size={12} /> }} >Upload</Button>\n    </Flex>\n  );\n}"
+    "code": "\"use client\";\n\nimport React, { useState } from 'react'\nimport { Button, Group, Input, Badge, Flex } from 'ui-lab-components'\nimport { FaList, FaGrip, FaPlus } from \"react-icons/fa6\";\nimport { LuSearch } from \"react-icons/lu\";\n\nexport default function Example() {\n  const [viewMode, setViewMode] = useState(\"list\");\n  return (\n    <Flex align=\"center\" gap=\"xs\" className=\"w-110\">\n      <Group orientation=\"horizontal\" spacing=\"xs\" value={viewMode} onChange={setViewMode}>\n        <Group.Button size=\"icon\" value=\"list\"><FaList /></Group.Button>\n        <Group.Button size=\"icon\" value=\"grid\"><FaGrip /></Group.Button>\n      </Group>\n      <Input\n        placeholder=\"Search...\"\n        icon={<LuSearch />}\n        hint={<Badge variant=\"secondary\" >Ctrl+K</Badge>}\n      />\n      <Button size=\"sm\" icon={{ right: <FaPlus size={12} /> }} >Upload</Button>\n    </Flex>\n  );\n}"
   },
   "05-split-action-button": {
     "title": "Split Action Button",
     "description": "A split button for bulk actions with dynamic icons, variants, and async feedback while keeping the primary action easy to repeat.",
     "code": "\"use client\";\n\nimport React, { useState } from 'react'\nimport { Button, Divider, Select, Badge, Flex } from 'ui-lab-components'\nimport { FaBox, FaSpinner, FaCheck, FaEllipsisVertical, FaCopy, FaTags, FaTrash } from \"react-icons/fa6\";\n\ntype BulkAction = \"archive\" | \"duplicate\" | \"tag\" | \"delete\";\n\nconst selectedCount: number = 12;\n\nconst bulkActions: Record<BulkAction, {\n  label: string;\n  loadingLabel: string;\n  successLabel: string;\n  variant: \"primary\" | \"outline\" | \"danger\";\n  icon: React.ReactNode;\n}> = {\n  archive: {\n    label: \"Archive\",\n    loadingLabel: \"Archiving...\",\n    successLabel: \"Archived\",\n    variant: \"primary\",\n    icon: <FaBox />,\n  },\n  duplicate: {\n    label: \"Duplicate\",\n    loadingLabel: \"Duplicating...\",\n    successLabel: \"Duplicated\",\n    variant: \"outline\",\n    icon: <FaCopy />,\n  },\n  tag: {\n    label: \"Add Tags\",\n    loadingLabel: \"Applying tags...\",\n    successLabel: \"Tagged\",\n    variant: \"outline\",\n    icon: <FaTags />,\n  },\n  delete: {\n    label: \"Delete\",\n    loadingLabel: \"Deleting...\",\n    successLabel: \"Deleted\",\n    variant: \"danger\",\n    icon: <FaTrash />,\n  },\n};\n\nexport default function Example() {\n  const [action, setAction] = useState<BulkAction>(\"archive\");\n  const [status, setStatus] = useState<\"idle\" | \"loading\" | \"done\">(\"idle\");\n  const cfg = bulkActions[action];\n  const itemsLabel = `${selectedCount} ${selectedCount === 1 ? \"item\" : \"items\"}`;\n\n  const handleExecute = () => {\n    setStatus(\"loading\");\n    setTimeout(() => {\n      setStatus(\"done\");\n      setTimeout(() => setStatus(\"idle\"), 2000);\n    }, 1500);\n  };\n\n  const leftIcon = status === \"loading\" ? <FaSpinner className=\"animate-spin\" /> : status === \"done\" ? <FaCheck /> : cfg.icon;\n  const label = status === \"loading\" ? cfg.loadingLabel : status === \"done\" ? cfg.successLabel : `${cfg.label} ${itemsLabel}`;\n\n  return (\n    <Flex gap=\"xs\" className=\"w-110\" align=\"center\">\n      <Badge variant=\"secondary\">{selectedCount} selected</Badge>\n      <Select className=\"flex h-10\" selectedKey={action} onSelectionChange={(key) => setAction(key as BulkAction)} isDisabled={status !== \"idle\"}>\n        <Button\n          onPress={handleExecute}\n          variant={cfg.variant}\n          size=\"sm\"\n          className=\"w-full rounded-none justify-start\"\n          isDisabled={status !== \"idle\" || selectedCount === 0}\n          icon={leftIcon}\n        >\n          {label}\n        </Button>\n        <Divider orientation=\"vertical\" spacing=\"none\" />\n        <Select.Trigger aria-label=\"Choose a bulk action\" />\n        <Select.Content>\n          <Select.Item value=\"archive\" textValue=\"Archive\" icon={<FaBox className=\"h-3 w-3\" />}>Archive</Select.Item>\n          <Select.Item value=\"duplicate\" textValue=\"Duplicate\" icon={<FaCopy className=\"h-3 w-3\" />}>Duplicate</Select.Item>\n          <Select.Item value=\"tag\" textValue=\"Add Tags\" icon={<FaTags className=\"h-3 w-3\" />}>Add Tags</Select.Item>\n          <Select.Item value=\"delete\" textValue=\"Delete\" icon={<FaTrash className=\"h-3 w-3\" />}>Delete</Select.Item>\n        </Select.Content>\n      </Select>\n      <Button size=\"icon\" variant=\"outline\" icon={<FaEllipsisVertical />} aria-label=\"More bulk actions\" />\n    </Flex>\n  );\n}"
+  },
+  "06-icons": {
+    "title": "Icons",
+    "description": "Left, right, and icon-only button patterns.",
+    "code": "import React from 'react'\nimport { Button, Flex } from 'ui-lab-components'\nimport { FaArrowRight, FaDownload, FaEllipsisVertical, FaPlus } from 'react-icons/fa6'\n\nexport default function Example() {\n  return (\n    <Flex gap=\"xs\" align=\"center\" justify=\"center\" wrap=\"wrap\">\n      <Button variant=\"primary\" icon={{ left: <FaPlus /> }}>\n        New Project\n      </Button>\n      <Button variant=\"outline\" icon={{ right: <FaArrowRight /> }}>\n        Continue\n      </Button>\n      <Button variant=\"secondary\" icon={<FaDownload />}>\n        Download\n      </Button>\n      <Button size=\"icon\" variant=\"ghost\" aria-label=\"More actions\" icon={<FaEllipsisVertical />} />\n    </Flex>\n  )\n}"
+  },
+  "07-split-button": {
+    "title": "Split Button",
+    "description": "Group + Select primitives for a classic split button with a primary action and a separate menu trigger.",
+    "code": "\"use client\";\n\nimport React, { useState } from 'react'\nimport { Button, Divider, Flex, Group, Select } from 'ui-lab-components'\nimport { FaChevronDown } from 'react-icons/fa6'\n\nconst splitActions = [\n  { value: \"publish\", label: \"Publish now\" },\n  { value: \"schedule\", label: \"Schedule publish\" },\n  { value: \"save\", label: \"Save draft\" },\n] as const;\n\nexport default function Example() {\n  const [action, setAction] = useState<string | number | null>(splitActions[0].value);\n  const selectedAction = splitActions.find((item) => item.value === action) ?? splitActions[0];\n\n  return (\n    <Flex direction=\"column\" gap=\"sm\" align=\"center\">\n      <Group orientation=\"horizontal\">\n        <Group.Select className=\"w-full\" selectedKey={action} onSelectionChange={setAction}>\n          <Select.Value>\n            <Button variant=\"primary\">{selectedAction.label}</Button>\n          </Select.Value>\n          <Divider />\n          <Select.Trigger\n            chevron={<FaChevronDown className=\"h-3.5 w-3.5\" />}\n            aria-label=\"Choose split action\"\n          />\n          <Select.Content>\n            <Select.List>\n              {splitActions.map((item) => (\n                <Select.Item key={item.value} value={item.value} textValue={item.label}>\n                  {item.label}\n                </Select.Item>\n              ))}\n            </Select.List>\n          </Select.Content>\n        </Group.Select>\n      </Group>\n    </Flex>\n  )\n}"
+  },
+  "08-button-group": {
+    "title": "Button Group",
+    "description": "Joined view switcher using the Group compound component with active state.",
+    "code": "\"use client\";\n\nimport React, { useState } from 'react'\nimport { Button, Divider, Group } from 'ui-lab-components'\nimport { FaGrip, FaList, FaTable } from 'react-icons/fa6'\n\nexport default function Example() {\n  const [viewMode, setViewMode] = useState(\"list\");\n\n  return (\n    <Group orientation=\"horizontal\" spacing=\"xs\">\n      <Group.Button active={viewMode === \"list\"} onPress={() => setViewMode(\"list\")}>\n        <FaList className=\"mr-1.5 text-foreground-400\" /> List\n      </Group.Button>\n      <Divider orientation=\"vertical\" />\n      <Group.Button active={viewMode === \"grid\"} onPress={() => setViewMode(\"grid\")}>\n        <FaGrip className=\"mr-1.5 text-foreground-400\" /> Grid\n      </Group.Button>\n      <Divider orientation=\"vertical\" />\n      <Group.Button active={viewMode === \"table\"} onPress={() => setViewMode(\"table\")}>\n        <FaTable className=\"mr-1.5 text-foreground-400\" /> Table\n      </Group.Button>\n    </Group>\n  )\n}"
   }
 }

package/src/components/Button/index.tsx

@@ -6,6 +6,9 @@ import Example2, { metadata as metadata2 } from './examples/02-multi-actions.js'
 import Example3, { metadata as metadata3 } from './examples/03-joined-toggle.js';
 import Example4, { metadata as metadata4 } from './examples/04-sub-stack-actions.js';
 import Example5, { metadata as metadata5 } from './examples/05-split-action-button.js';
+import Example6, { metadata as metadata6 } from './examples/06-icons.js';
+import Example7, { metadata as metadata7 } from './examples/07-split-button.js';
+import Example8, { metadata as metadata8 } from './examples/08-button-group.js';
 import examplesJson from './examples.json' with { type: 'json' };
 import { loadComponentExamples } from '../../utils/load-component-examples.js';
 
@@ -16,6 +19,9 @@ const examplesData = [
   { id: '03-joined-toggle', Component: Example3, metadata: metadata3 },
   { id: '04-sub-stack-actions', Component: Example4, metadata: metadata4 },
   { id: '05-split-action-button', Component: Example5, metadata: metadata5 },
+  { id: '06-icons', Component: Example6, metadata: metadata6 },
+  { id: '07-split-button', Component: Example7, metadata: metadata7 },
+  { id: '08-button-group', Component: Example8, metadata: metadata8 },
 ];
 
 const buttonControls: ControlDef[] = [

package/src/components/Card/examples/01-notification.tsx

@@ -0,0 +1,37 @@
+"use client";
+
+import { useState } from 'react';
+import { Card, Button, Flex, Badge } from 'ui-lab-components';
+
+export const metadata = {
+  title: 'Notification Card',
+  description: 'A status-driven card with a badge, body copy, and a footer action. Caller controls read state.',
+};
+
+export default function Example() {
+  const [read, setRead] = useState(false);
+
+  return (
+    <Card style={{ width: 360, opacity: read ? 0.6 : 1, transition: 'opacity 0.2s' }}>
+      <Card.Header>
+        <Flex justify="between" align="center">
+          <span className="text-sm font-medium text-foreground-100">Deployment failed</span>
+          <Badge variant="destructive">Error</Badge>
+        </Flex>
+      </Card.Header>
+      <Card.Body>
+        <p className="text-sm text-foreground-400">
+          The production deploy of <span className="text-foreground-200">api-gateway</span> failed at step "Run tests". Check the logs for details.
+        </p>
+      </Card.Body>
+      <Card.Footer>
+        <Flex justify="between" align="center">
+          <span className="text-xs text-foreground-500">2 minutes ago</span>
+          <Button size="sm" variant="ghost" onPress={() => setRead(true)}>
+            Mark as read
+          </Button>
+        </Flex>
+      </Card.Footer>
+    </Card>
+  );
+}

package/src/components/Card/examples/02-settings-panel.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+import { useState } from 'react';
+import { Card, Button, Flex, Switch } from 'ui-lab-components';
+
+export const metadata = {
+  title: 'Settings Panel',
+  description: 'Card used as a settings section with a list of toggle rows and save/cancel actions in the footer.',
+};
+
+const items = [
+  { label: 'Email alerts', description: 'Receive alerts via email' },
+  { label: 'Push notifications', description: 'Browser push notifications' },
+  { label: 'Weekly digest', description: 'Summary sent every Monday' },
+];
+
+export default function Example() {
+  const [enabled, setEnabled] = useState(true);
+
+  return (
+    <Card style={{ width: 360 }}>
+      <Card.Header>
+        <span className="text-sm font-medium text-foreground-100">Notifications</span>
+      </Card.Header>
+      <Card.Body className="space-y-4 py-4">
+        {items.map((item) => (
+          <Flex key={item.label} justify="between" align="center">
+            <div>
+              <p className="text-sm text-foreground-100">{item.label}</p>
+              <p className="text-xs text-foreground-500">{item.description}</p>
+            </div>
+            <Switch
+              isSelected={enabled}
+              onChange={setEnabled}
+              aria-label={item.label}
+            />
+          </Flex>
+        ))}
+      </Card.Body>
+      <Card.Footer>
+        <Flex justify="end" gap="xs">
+          <Button size="sm" variant="ghost">Cancel</Button>
+          <Button size="sm" variant="primary">Save</Button>
+        </Flex>
+      </Card.Footer>
+    </Card>
+  );
+}

package/src/components/Card/examples/03-task-progress.tsx

@@ -0,0 +1,43 @@
+import { Card, Button, Flex, Progress } from 'ui-lab-components';
+
+export const metadata = {
+  title: 'Task Progress',
+  description: 'Card displaying a checklist with a progress bar in the header to summarize completion state.',
+};
+
+const tasks = [
+  { label: 'Design review', done: true },
+  { label: 'Write changelog', done: true },
+  { label: 'Update docs', done: false },
+  { label: 'Deploy to staging', done: false },
+];
+
+const completed = tasks.filter((t) => t.done).length;
+
+export default function Example() {
+  return (
+    <Card style={{ width: 360 }}>
+      <Card.Header>
+        <Flex justify="between" align="center">
+          <span className="text-sm font-medium text-foreground-100">Release v2.4.0</span>
+          <span className="text-xs text-foreground-500">{completed}/{tasks.length}</span>
+        </Flex>
+        <Progress value={(completed / tasks.length) * 100} className="mt-2" />
+      </Card.Header>
+      <Card.Body className="py-3">
+        <ul className="space-y-2">
+          {tasks.map((task) => (
+            <li key={task.label} className="flex items-center gap-2 text-sm">
+              <span className={task.done ? 'text-foreground-500 line-through' : 'text-foreground-200'}>
+                {task.label}
+              </span>
+            </li>
+          ))}
+        </ul>
+      </Card.Body>
+      <Card.Footer>
+        <Button size="sm" variant="outline" className="w-full">View milestone</Button>
+      </Card.Footer>
+    </Card>
+  );
+}

package/src/components/Card/examples/index.ts

@@ -1,2 +1,8 @@
-export { default as Example1 } from './01-basic-card.js';
-export { metadata as metadata1 } from './01-basic-card.js';
+export { default as Example1 } from './01-notification.js';
+export { metadata as metadata1 } from './01-notification.js';
+
+export { default as Example2 } from './02-settings-panel.js';
+export { metadata as metadata2 } from './02-settings-panel.js';
+
+export { default as Example3 } from './03-task-progress.js';
+export { metadata as metadata3 } from './03-task-progress.js';

package/src/components/Card/examples.json

@@ -1,7 +1,17 @@
 {
-  "01-basic-card": {
-    "title": "Basic Card",
-    "description": "A simple card container with header, body, and footer sections. Use this to group related content in your interface.",
-    "code": "import { Card } from 'ui-lab-components';\n\nexport default function Example() {\n  return (\n    <Card>\n      <Card.Header>\n        <h3>Card Title</h3>\n      </Card.Header>\n      <Card.Body>\n        <p>This is the card content area where you can place any information or components.</p>\n      </Card.Body>\n      <Card.Footer>\n        <p>Footer content</p>\n      </Card.Footer>\n    </Card>\n  );\n}"
+  "01-notification": {
+    "title": "Notification Card",
+    "description": "A status-driven card with a badge, body copy, and a footer action. Caller controls read state.",
+    "code": "\"use client\";\n\nimport { useState } from 'react';\nimport { Card, Button, Flex, Badge } from 'ui-lab-components';\n\nexport default function Example() {\n  const [read, setRead] = useState(false);\n\n  return (\n    <Card style={{ width: 360, opacity: read ? 0.6 : 1, transition: 'opacity 0.2s' }}>\n      <Card.Header>\n        <Flex justify=\"between\" align=\"center\">\n          <span className=\"text-sm font-medium text-foreground-100\">Deployment failed</span>\n          <Badge variant=\"destructive\">Error</Badge>\n        </Flex>\n      </Card.Header>\n      <Card.Body>\n        <p className=\"text-sm text-foreground-400\">\n          The production deploy of <span className=\"text-foreground-200\">api-gateway</span> failed at step \"Run tests\". Check the logs for details.\n        </p>\n      </Card.Body>\n      <Card.Footer>\n        <Flex justify=\"between\" align=\"center\">\n          <span className=\"text-xs text-foreground-500\">2 minutes ago</span>\n          <Button size=\"sm\" variant=\"ghost\" onPress={() => setRead(true)}>\n            Mark as read\n          </Button>\n        </Flex>\n      </Card.Footer>\n    </Card>\n  );\n}"
+  },
+  "02-settings-panel": {
+    "title": "Settings Panel",
+    "description": "Card used as a settings section with a list of toggle rows and save/cancel actions in the footer.",
+    "code": "\"use client\";\n\nimport { useState } from 'react';\nimport { Card, Button, Flex, Switch } from 'ui-lab-components';\n\nconst items = [\n  { label: 'Email alerts', description: 'Receive alerts via email' },\n  { label: 'Push notifications', description: 'Browser push notifications' },\n  { label: 'Weekly digest', description: 'Summary sent every Monday' },\n];\n\nexport default function Example() {\n  const [enabled, setEnabled] = useState(true);\n\n  return (\n    <Card style={{ width: 360 }}>\n      <Card.Header>\n        <span className=\"text-sm font-medium text-foreground-100\">Notifications</span>\n      </Card.Header>\n      <Card.Body className=\"space-y-4 py-4\">\n        {items.map((item) => (\n          <Flex key={item.label} justify=\"between\" align=\"center\">\n            <div>\n              <p className=\"text-sm text-foreground-100\">{item.label}</p>\n              <p className=\"text-xs text-foreground-500\">{item.description}</p>\n            </div>\n            <Switch\n              isSelected={enabled}\n              onChange={setEnabled}\n              aria-label={item.label}\n            />\n          </Flex>\n        ))}\n      </Card.Body>\n      <Card.Footer>\n        <Flex justify=\"end\" gap=\"xs\">\n          <Button size=\"sm\" variant=\"ghost\">Cancel</Button>\n          <Button size=\"sm\" variant=\"primary\">Save</Button>\n        </Flex>\n      </Card.Footer>\n    </Card>\n  );\n}"
+  },
+  "03-task-progress": {
+    "title": "Task Progress",
+    "description": "Card displaying a checklist with a progress bar in the header to summarize completion state.",
+    "code": "import { Card, Button, Flex, Progress } from 'ui-lab-components';\n\nconst tasks = [\n  { label: 'Design review', done: true },\n  { label: 'Write changelog', done: true },\n  { label: 'Update docs', done: false },\n  { label: 'Deploy to staging', done: false },\n];\n\nconst completed = tasks.filter((t) => t.done).length;\n\nexport default function Example() {\n  return (\n    <Card style={{ width: 360 }}>\n      <Card.Header>\n        <Flex justify=\"between\" align=\"center\">\n          <span className=\"text-sm font-medium text-foreground-100\">Release v2.4.0</span>\n          <span className=\"text-xs text-foreground-500\">{completed}/{tasks.length}</span>\n        </Flex>\n        <Progress value={(completed / tasks.length) * 100} className=\"mt-2\" />\n      </Card.Header>\n      <Card.Body className=\"py-3\">\n        <ul className=\"space-y-2\">\n          {tasks.map((task) => (\n            <li key={task.label} className=\"flex items-center gap-2 text-sm\">\n              <span className={task.done ? 'text-foreground-500 line-through' : 'text-foreground-200'}>\n                {task.label}\n              </span>\n            </li>\n          ))}\n        </ul>\n      </Card.Body>\n      <Card.Footer>\n        <Button size=\"sm\" variant=\"outline\" className=\"w-full\">View milestone</Button>\n      </Card.Footer>\n    </Card>\n  );\n}"
   }
 }

package/src/components/Card/index.tsx

@@ -1,12 +1,16 @@
 import React from 'react';
 import { Card } from 'ui-lab-components';
 import { ControlDef, ComponentDetail } from '@/types';
-import Example1, { metadata as metadata1 } from './examples/01-basic-card.js';
+import Example1, { metadata as metadata1 } from './examples/01-notification.js';
+import Example2, { metadata as metadata2 } from './examples/02-settings-panel.js';
+import Example3, { metadata as metadata3 } from './examples/03-task-progress.js';
 import examplesJson from './examples.json' with { type: 'json' };
 import { loadComponentExamples } from '../../utils/load-component-examples.js';
 
 const examplesData = [
-  { id: '01-basic-card', Component: Example1, metadata: metadata1 },
+  { id: '01-notification', Component: Example1, metadata: metadata1 },
+  { id: '02-settings-panel', Component: Example2, metadata: metadata2 },
+  { id: '03-task-progress', Component: Example3, metadata: metadata3 },
 ];
 
 const cardControls: ControlDef[] = [];

package/src/components/Card/metadata.json

@@ -23,5 +23,47 @@
       "Semantic HTML structure",
       "Proper heading hierarchy"
     ]
+  },
+  "usage": {
+    "summary": "Use Card as a top-level surface that groups related content into a single visual panel.",
+    "whenToUse": [
+      "Page sections that need their own surface boundary",
+      "Standalone panels such as summaries, settings sections, and detail blocks",
+      "Collections of related content that benefit from header/body/footer structure"
+    ],
+    "whenNotToUse": [
+      "Inside other surfaced overlays like Modal, Popover, Confirm, or Menu",
+      "For simple internal spacing inside an existing surfaced component",
+      "As a generic replacement for every padded container"
+    ],
+    "rules": [
+      {
+        "type": "do",
+        "title": "Reserve Card for top-level surfaces",
+        "description": "Treat Card as the main boundary for a section or standalone block, not as a default inner wrapper."
+      },
+      {
+        "type": "avoid",
+        "title": "Do not nest Card inside overlay surfaces",
+        "description": "Avoid putting Card inside Modal, Popover, Confirm, or Menu because it creates double-surface chrome and weakens hierarchy.",
+        "relatedComponents": [
+          "modal",
+          "popover",
+          "confirm",
+          "menu"
+        ]
+      },
+      {
+        "type": "prefer",
+        "title": "Prefer layout primitives for internal grouping",
+        "description": "When content already sits inside a surfaced component, use Flex, Grid, Group, or the host component's slots to structure it instead of adding another Card.",
+        "relatedComponents": [
+          "flex",
+          "grid",
+          "group",
+          "modal"
+        ]
+      }
+    ]
   }
 }

package/src/components/Checkbox/examples/01-basic-states.tsx

@@ -0,0 +1,17 @@
+import { Checkbox, Flex } from 'ui-lab-components';
+
+export const metadata = {
+  title: 'Basic States',
+  description: 'The default checkbox states: unchecked, checked, disabled, and disabled checked.',
+};
+
+export default function Example() {
+  return (
+    <Flex direction="column" gap="md" style={{ width: 280 }}>
+      <Checkbox id="basic-unchecked" label="Unchecked" />
+      <Checkbox id="basic-checked" label="Checked" defaultChecked />
+      <Checkbox id="basic-disabled" label="Disabled" disabled />
+      <Checkbox id="basic-disabled-checked" label="Disabled checked" disabled defaultChecked />
+    </Flex>
+  );
+}

package/src/components/Checkbox/examples/02-helper-text.tsx

@@ -0,0 +1,26 @@
+import { Checkbox, Flex } from 'ui-lab-components';
+
+export const metadata = {
+  title: 'Helper and Error Text',
+  description: 'A labeled checkbox can include supporting text and an invalid state for form feedback.',
+};
+
+export default function Example() {
+  return (
+    <Flex direction="column" gap="lg" style={{ width: 320 }}>
+      <Checkbox
+        id="helper-release-notes"
+        label="Release notes"
+        helper="Get a short product update when a new version ships."
+        defaultChecked
+      />
+      <Checkbox
+        id="helper-terms"
+        label="Accept terms"
+        helper="You must accept the terms before continuing."
+        helperTextError
+        aria-invalid="true"
+      />
+    </Flex>
+  );
+}

package/src/components/Checkbox/examples/03-controlled.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import { useState } from 'react';
+import { Button, Checkbox, Flex } from 'ui-lab-components';
+
+export const metadata = {
+  title: 'Controlled',
+  description: 'Use checked and onChange when checkbox state is owned by the surrounding interface.',
+};
+
+export default function Example() {
+  const [checked, setChecked] = useState(true);
+
+  return (
+    <Flex direction="column" gap="md" style={{ width: 300 }}>
+      <Checkbox
+        id="controlled-email"
+        label="Email notifications"
+        helper={checked ? 'Notifications are enabled.' : 'Notifications are paused.'}
+        checked={checked}
+        onChange={(event) => setChecked(event.currentTarget.checked)}
+      />
+      <Button variant="secondary" onClick={() => setChecked((value) => !value)}>
+        {checked ? 'Turn off' : 'Turn on'}
+      </Button>
+    </Flex>
+  );
+}

package/src/components/Checkbox/examples/04-group.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { useState } from 'react';
+import { Checkbox, Flex } from 'ui-lab-components';
+
+export const metadata = {
+  title: 'Checkbox Group',
+  description: 'Use a small group when a user can select any number of related options.',
+};
+
+const subscriptionOptions = [
+  'Product updates',
+  'Security alerts',
+  'Billing reminders',
+];
+
+export default function Example() {
+  const [selected, setSelected] = useState<Set<string>>(
+    new Set(['Product updates', 'Security alerts'])
+  );
+
+  const toggleOption = (option: string) => {
+    setSelected((current) => {
+      const next = new Set(current);
+      next.has(option) ? next.delete(option) : next.add(option);
+      return next;
+    });
+  };
+
+  return (
+    <Flex direction="column" gap="md" style={{ width: 300 }}>
+      <div>
+        <p className="text-sm font-medium text-foreground-100">Subscriptions</p>
+        <p className="text-xs text-foreground-400">Choose the emails this workspace receives.</p>
+      </div>
+      <Flex direction="column" gap="sm">
+        {subscriptionOptions.map((option) => (
+          <Checkbox
+            key={option}
+            id={`subscription-${option.toLowerCase().replace(/ /g, '-')}`}
+            label={option}
+            checked={selected.has(option)}
+            onChange={() => toggleOption(option)}
+          />
+        ))}
+      </Flex>
+    </Flex>
+  );
+}

package/src/components/Checkbox/examples/05-indeterminate.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { useState } from 'react';
+import { Checkbox, Divider, Flex } from 'ui-lab-components';
+
+export const metadata = {
+  title: 'Indeterminate',
+  description: 'A parent checkbox can show partial selection when only some child options are checked.',
+};
+
+const tableColumns = ['Name', 'Email', 'Role', 'Last active'];
+
+export default function Example() {
+  const [visibleColumns, setVisibleColumns] = useState<Set<string>>(
+    new Set(['Name', 'Email'])
+  );
+
+  const allSelected = visibleColumns.size === tableColumns.length;
+  const isIndeterminate = visibleColumns.size > 0 && !allSelected;
+
+  const toggleAll = () => {
+    setVisibleColumns(allSelected ? new Set() : new Set(tableColumns));
+  };
+
+  const toggleColumn = (column: string) => {
+    setVisibleColumns((current) => {
+      const next = new Set(current);
+      next.has(column) ? next.delete(column) : next.add(column);
+      return next;
+    });
+  };
+
+  return (
+    <Flex direction="column" gap="sm" style={{ width: 280 }}>
+      <Checkbox
+        id="columns-all"
+        label="Show all columns"
+        checked={allSelected}
+        isIndeterminate={isIndeterminate}
+        onChange={toggleAll}
+      />
+      <Divider />
+      <Flex direction="column" gap="sm" styles={{ root: 'pl-8' }}>
+        {tableColumns.map((column) => (
+          <Checkbox
+            key={column}
+            id={`column-${column.toLowerCase().replace(/ /g, '-')}`}
+            label={column}
+            checked={visibleColumns.has(column)}
+            onChange={() => toggleColumn(column)}
+          />
+        ))}
+      </Flex>
+    </Flex>
+  );
+}

package/src/components/Checkbox/examples/06-consent-form.tsx

@@ -0,0 +1,35 @@
+"use client";
+
+import { useState } from 'react';
+import { Button, Checkbox, Flex } from 'ui-lab-components';
+
+export const metadata = {
+  title: 'Consent Form',
+  description: 'A required checkbox can gate a form action while optional choices remain independent.',
+};
+
+export default function Example() {
+  const [accepted, setAccepted] = useState(false);
+  const [updates, setUpdates] = useState(false);
+
+  return (
+    <Flex direction="column" gap="md" style={{ width: 320 }}>
+      <Checkbox
+        id="consent-terms"
+        label="I agree to the terms"
+        helper="Required to create a workspace."
+        checked={accepted}
+        onChange={(event) => setAccepted(event.currentTarget.checked)}
+      />
+      <Checkbox
+        id="consent-updates"
+        label="Send product updates"
+        checked={updates}
+        onChange={(event) => setUpdates(event.currentTarget.checked)}
+      />
+      <Button variant="primary" isDisabled={!accepted} styles={{ root: 'w-full' }}>
+        Continue
+      </Button>
+    </Flex>
+  );
+}

package/src/components/Checkbox/examples/index.ts

@@ -1,5 +1,17 @@
-export { default as Example1 } from './01-basic-checkbox.js';
-export { metadata as metadata1 } from './01-basic-checkbox.js';
+export { default as Example1 } from './01-basic-states.js';
+export { metadata as metadata1 } from './01-basic-states.js';
 
-export { default as Example2 } from './02-checkbox-group-with-descriptions.js';
-export { metadata as metadata2 } from './02-checkbox-group-with-descriptions.js';
+export { default as Example2 } from './02-helper-text.js';
+export { metadata as metadata2 } from './02-helper-text.js';
+
+export { default as Example3 } from './03-controlled.js';
+export { metadata as metadata3 } from './03-controlled.js';
+
+export { default as Example4 } from './04-group.js';
+export { metadata as metadata4 } from './04-group.js';
+
+export { default as Example5 } from './05-indeterminate.js';
+export { metadata as metadata5 } from './05-indeterminate.js';
+
+export { default as Example6 } from './06-consent-form.js';
+export { metadata as metadata6 } from './06-consent-form.js';