@tangible/ui 0.0.3 → 0.0.4

package/tui-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.0.3",
-  "generated": "2026-02-24T00:56:13.287Z",
+  "version": "0.0.4",
+  "generated": "2026-03-05T21:09:18.762Z",
   "components": {
     "Accordion": {
       "props": {
@@ -80,7 +80,9 @@
       ],
       "related": [
         "Tabs"
-      ]
+      ],
+      "use": null,
+      "notFor": null
     },
     "Avatar": {
       "props": {
@@ -122,6 +124,11 @@
           "defaultValue": "bottom-right",
           "description": "Position of the indicator"
         },
+        "tooltip": {
+          "type": "boolean",
+          "required": false,
+          "description": "When true, wraps the avatar with a Tooltip showing the `name`.\nHelps sighted users discover the user's name on hover/focus.\nHas no effect when `name` is not provided."
+        },
         "className": {
           "type": "string",
           "required": false,
@@ -154,7 +161,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Button": {
       "props": {
@@ -204,6 +213,12 @@
           "defaultValue": "false",
           "description": "Loading state. Shows spinner and prevents interaction."
         },
+        "loadingLabel": {
+          "type": "string",
+          "required": false,
+          "defaultValue": "`${label}, loading` (English)",
+          "description": "Accessible label override during loading state. For i18n support.\nWhen loading, this replaces the auto-composed label."
+        },
         "target": {
           "type": "HTMLAttributeAnchorTarget",
           "required": false,
@@ -242,7 +257,7 @@
         "iconSize": {
           "type": "\"xs\" | \"sm\" | \"md\" | \"lg\"",
           "required": false,
-          "defaultValue": "sm",
+          "defaultValue": "'sm'",
           "description": "Size of icons."
         },
         "className": {
@@ -285,6 +300,7 @@
         "--tui-button-bg-interact",
         "--tui-button-fg-interact",
         "--tui-button-border-interact",
+        "--tui-button-fg-active",
         "--tui-control-height-sm",
         "--tui-control-height-md",
         "--tui-control-height-lg"
@@ -336,8 +352,11 @@
         }
       ],
       "related": [
-        "IconButton"
-      ]
+        "IconButton",
+        "Chip"
+      ],
+      "use": "for actions the user performs — save, delete, submit, navigate, open a dialog",
+      "notFor": "labels, tags, or filter toggles that represent a value or category — use Chip or ChipGroup instead"
     },
     "Card": {
       "props": {
@@ -450,7 +469,9 @@
       ],
       "related": [
         "Notice"
-      ]
+      ],
+      "use": null,
+      "notFor": null
     },
     "Checkbox": {
       "props": {
@@ -505,14 +526,17 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Chip": {
       "props": {
         "as": {
           "type": "\"span\" | \"div\" | \"a\"",
           "required": false,
-          "defaultValue": "span"
+          "defaultValue": "span",
+          "description": "HTML element to render.\n- `'span'` (default): Inline element. Use for chips within text flow,\n  inline lists, or inside `<p>`/`<li>` elements.\n- `'div'`: Block element. Use when the chip contains block-level content\n  or needs to be a flex/grid child without inline constraints.\n- `'a'`: Anchor element. Use for navigational chips with an `href`."
         },
         "href": {
           "type": "string",
@@ -600,7 +624,8 @@
         "--tui-chip-fg",
         "--tui-chip-border",
         "--tui-chip-icon",
-        "--tui-chip-radius"
+        "--tui-chip-radius",
+        "--tui-chip-selected-ring"
       ],
       "story": {
         "title": "Primitives/Chip",
@@ -609,11 +634,49 @@
           "stable"
         ]
       },
-      "subcomponents": null,
-      "description": null,
-      "gotchas": null,
-      "examples": null,
-      "related": null
+      "subcomponents": [],
+      "description": "Compact label, tag, or interactive toggle. Use standalone for badges/status indicators, or inside ChipGroup for filter token sets.",
+      "gotchas": [
+        {
+          "note": "Add value prop when inside ChipGroup — without it the chip won't be managed by the group"
+        },
+        {
+          "note": "Interactive chips (onClick or inside ChipGroup) get role=button and aria-pressed automatically"
+        },
+        {
+          "note": "Anchor chips (as='a') inside a ChipGroup get role=button — toggle semantics override link semantics"
+        },
+        {
+          "note": "Non-interactive chips are pure display — no role, no tabIndex, no keyboard handling"
+        },
+        {
+          "note": "Size scale is xs/sm/md (compact), not sm/md/lg — Chip does not participate in control sizing"
+        }
+      ],
+      "examples": [
+        {
+          "name": "Label / badge",
+          "code": "<Chip theme=\"success\">Published</Chip>"
+        },
+        {
+          "name": "Filter toggle",
+          "code": "<Chip interactive onClick={toggle} selected={active}>Design</Chip>"
+        },
+        {
+          "name": "Filter group",
+          "code": "<ChipGroup value={filter} onValueChange={setFilter}>\n  <Chip value=\"all\">All</Chip>\n  <Chip value=\"active\">Active</Chip>\n  <Chip value=\"done\">Done</Chip>\n</ChipGroup>"
+        },
+        {
+          "name": "With icon",
+          "code": "<Chip leftIcon={<Icon name=\"system/check\" />} theme=\"success\">Verified</Chip>"
+        }
+      ],
+      "related": [
+        "ChipGroup",
+        "Button"
+      ],
+      "use": "for labels, tags, status badges, or filter toggles that represent a value or category",
+      "notFor": "actions like save, delete, submit, or navigation — use Button instead (action intent vs value state)"
     },
     "ChipGroup": {
       "props": {
@@ -636,6 +699,12 @@
           "required": false,
           "description": "Alignment along main axis."
         },
+        "multipleLabel": {
+          "type": "string",
+          "required": false,
+          "defaultValue": "'Multiple selections allowed'",
+          "description": "Visually hidden label describing multi-select behaviour. For i18n support."
+        },
         "className": {
           "type": "string",
           "required": false
@@ -659,7 +728,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Chips": {
       "props": {
@@ -691,7 +762,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Combobox": {
       "props": {
@@ -774,7 +847,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "ContentIndicator": {
       "props": {
@@ -829,7 +904,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Dropdown": {
       "props": {
@@ -867,7 +944,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Field": {
       "props": {
@@ -914,7 +993,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Icon": {
       "props": {
@@ -962,7 +1043,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "IconButton": {
       "props": {
@@ -980,7 +1063,7 @@
           "type": "\"xs\" | \"sm\" | \"md\" | \"lg\"",
           "required": false,
           "defaultValue": "'sm'",
-          "description": "Size of the button.\n- `'xs'`: 24px\n- `'sm'`: 32px (default)\n- `'md'`: 40px\n- `'lg'`: 48px"
+          "description": "Size of the button.\n- `'xs'`: 24px — below WCAG 2.5.8 minimum target size (24×24 CSS px).\n  Use only in dense, mouse-first UIs (toolbars, table rows) where touch\n  is not expected. Consider pairing with adequate spacing or a larger\n  touch target via padding/margin.\n- `'sm'`: 32px (default)\n- `'md'`: 40px\n- `'lg'`: 48px"
         },
         "theme": {
           "type": "\"primary\" | \"secondary\" | \"danger\"",
@@ -992,7 +1075,7 @@
           "type": "\"solid\" | \"outline\" | \"ghost\"",
           "required": false,
           "defaultValue": "'ghost'",
-          "description": "Visual style variant.\n- `'solid'`: Filled background\n- `'outline'`: Border only, transparent background\n- `'ghost'`: No border or background, icon only"
+          "description": "Visual style variant.\n- `'solid'`: Filled background\n- `'outline'`: Border only, transparent background\n- `'ghost'`: No border or background, icon only — has no at-rest visual\n  affordance. Best suited for toolbar groups, icon bars, or other contexts\n  where surrounding UI makes the interactive nature obvious."
         },
         "disabled": {
           "type": "boolean",
@@ -1004,6 +1087,12 @@
           "required": false,
           "description": "Loading state — shows spinner, disables interaction."
         },
+        "loadingLabel": {
+          "type": "string",
+          "required": false,
+          "defaultValue": "`${label}, loading` (English)",
+          "description": "Accessible label override during loading state. For i18n support."
+        },
         "pressed": {
           "type": "boolean",
           "required": false,
@@ -1013,7 +1102,7 @@
           "type": "boolean",
           "required": false,
           "defaultValue": "false",
-          "description": "Show the label as a tooltip on hover.\nSince icon-only buttons have no visible text, this helps sighted\nusers discover what the button does."
+          "description": "Show the label as a tooltip on hover.\nSince icon-only buttons have no visible text, enabling this helps\nsighted users discover what the button does. Recommended for most\nstandalone icon buttons. Can be omitted in toolbars where a shared\nTooltip provider handles it, or where adjacent visible text already\ncommunicates the action."
         },
         "tooltipSide": {
           "type": "\"top\" | \"right\" | \"bottom\" | \"left\"",
@@ -1021,6 +1110,12 @@
           "defaultValue": "'top'",
           "description": "Tooltip placement side."
         },
+        "shape": {
+          "type": "\"square\" | \"circle\"",
+          "required": false,
+          "defaultValue": "'square'",
+          "description": "Button shape. Use `'circle'` for avatar-adjacent actions, FABs,\nor anywhere a round affordance is expected."
+        },
         "className": {
           "type": "string",
           "required": false,
@@ -1082,7 +1177,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Modal": {
       "props": {
@@ -1148,7 +1245,9 @@
       ],
       "related": [
         "Notice"
-      ]
+      ],
+      "use": null,
+      "notFor": null
     },
     "MoveHandle": {
       "props": {
@@ -1217,7 +1316,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "MultiSelect": {
       "props": {
@@ -1303,7 +1404,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Notice": {
       "props": {
@@ -1402,6 +1505,7 @@
         "--tui-notice-bg",
         "--tui-notice-border",
         "--tui-notice-stripe",
+        "--tui-notice-stripe-width",
         "--tui-notice-fg",
         "--tui-notice-radius",
         "--tui-notice-padding",
@@ -1454,7 +1558,9 @@
       "related": [
         "Card",
         "Modal"
-      ]
+      ],
+      "use": null,
+      "notFor": null
     },
     "OverlapStack": {
       "props": {
@@ -1519,7 +1625,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Pager": {
       "props": {
@@ -1581,7 +1689,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Progress": {
       "props": {
@@ -1686,7 +1796,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Radio": {
       "props": {
@@ -1718,7 +1830,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Rating": {
       "props": {
@@ -1796,7 +1910,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "SegmentedControl": {
       "props": {
@@ -1860,11 +1976,42 @@
           "stable"
         ]
       },
-      "subcomponents": null,
-      "description": null,
-      "gotchas": null,
-      "examples": null,
-      "related": null
+      "subcomponents": [
+        "Item"
+      ],
+      "description": "Accessible radiogroup for standalone choices — filters, view modes, sort orders. No owned content panels.",
+      "gotchas": [
+        {
+          "note": "Always provide aria-label or aria-labelledby on the root — it is a radiogroup landmark"
+        },
+        {
+          "note": "Arrow keys move focus AND select simultaneously — there is no manual activation mode"
+        },
+        {
+          "note": "Uses aria-disabled (not native disabled) to keep items visible and focusable"
+        },
+        {
+          "note": "Supports controlled (value) and uncontrolled (defaultValue) modes"
+        },
+        {
+          "note": "Keyboard: Arrow keys navigate and select, Tab moves out of the group"
+        }
+      ],
+      "examples": [
+        {
+          "name": "Basic",
+          "code": "<SegmentedControl defaultValue=\"week\" aria-label=\"Time period\">\n  <SegmentedControl.Item value=\"day\">Day</SegmentedControl.Item>\n  <SegmentedControl.Item value=\"week\">Week</SegmentedControl.Item>\n  <SegmentedControl.Item value=\"month\">Month</SegmentedControl.Item>\n</SegmentedControl>"
+        },
+        {
+          "name": "Controlled",
+          "code": "<SegmentedControl value={view} onValueChange={setView} aria-label=\"View mode\">\n  <SegmentedControl.Item value=\"list\">List</SegmentedControl.Item>\n  <SegmentedControl.Item value=\"grid\">Grid</SegmentedControl.Item>\n</SegmentedControl>"
+        }
+      ],
+      "related": [
+        "Tabs"
+      ],
+      "use": "when selection is a standalone choice that drives external state (filter, view mode, sort order, time period)",
+      "notFor": "switching between content sections on the same page — use Tabs instead (owns the content panels)"
     },
     "Select": {
       "props": {
@@ -1955,7 +2102,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Sidebar": {
       "props": {
@@ -1965,31 +2114,31 @@
           "defaultValue": "'left'",
           "description": "Sidebar position. Affects border placement and drawer slide direction."
         },
+        "children": {
+          "type": "ReactNode",
+          "required": true,
+          "description": "Sidebar content (Header, Nav, etc.)."
+        },
+        "className": {
+          "type": "string",
+          "required": false,
+          "description": "Additional CSS class names."
+        },
         "drawer": {
           "type": "boolean",
           "required": false,
           "defaultValue": "false",
-          "description": "Enable drawer mode (mobile overlay).\nWhen true, sidebar renders via portal with backdrop and focus trap."
+          "description": "Enable drawer mode (mobile overlay).\nEnable drawer mode (mobile overlay).\nWhen true, sidebar renders with backdrop, focus trap, and dialog semantics."
         },
         "open": {
           "type": "boolean",
           "required": false,
-          "description": "Drawer open state. Required when `drawer={true}`."
+          "description": "Drawer open state."
         },
         "onClose": {
           "type": "() => void",
-          "required": false,
-          "description": "Callback to close the drawer.\nCalled when ESC is pressed or backdrop is clicked."
-        },
-        "children": {
-          "type": "ReactNode",
           "required": true,
-          "description": "Sidebar content (Header, Nav, etc.)."
-        },
-        "className": {
-          "type": "string",
-          "required": false,
-          "description": "Additional CSS class names."
+          "description": "Callback to close the drawer. Required when `drawer={true}`.\nCalled when ESC is pressed or backdrop is clicked.\nOmitting this in drawer mode means the user cannot dismiss the overlay,\nwhich is a WCAG 2.1.1 (Keyboard) failure."
         }
       },
       "cssTokens": [
@@ -2011,7 +2160,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "StepIndicator": {
       "props": {
@@ -2067,7 +2218,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "StepList": {
       "props": {
@@ -2113,7 +2266,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Switch": {
       "props": {
@@ -2170,7 +2325,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Tabs": {
       "props": {
@@ -2267,7 +2424,9 @@
       ],
       "related": [
         "SegmentedControl"
-      ]
+      ],
+      "use": "when selecting reveals a content panel owned by this component (Tabs.Panel below the tab list)",
+      "notFor": "filters, view-mode switches, or sort-order pickers — use SegmentedControl instead (no owned panels)"
     },
     "Textarea": {
       "props": {
@@ -2340,7 +2499,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "TextInput": {
       "props": {
@@ -2419,7 +2580,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Toolbar": {
       "props": {
@@ -2458,7 +2621,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Tooltip": {
       "props": {
@@ -2496,7 +2661,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     }
   },
   "utilities": {
@@ -2639,6 +2806,53 @@
       "is-layer-top"
     ]
   },
+  "guides": {
+    "tabsVsSegmentedControl": {
+      "title": "Tabs vs SegmentedControl",
+      "question": "Does selecting an option reveal a content panel owned by this component?",
+      "rules": [
+        {
+          "answer": "Yes — selecting shows a Tabs.Panel below the tab list",
+          "use": "Tabs"
+        },
+        {
+          "answer": "No — selection drives external state (filter, view mode, sort order)",
+          "use": "SegmentedControl"
+        }
+      ],
+      "components": [
+        "Tabs",
+        "SegmentedControl"
+      ],
+      "storybookPath": "Guides/Tabs vs SegmentedControl",
+      "detail": "Both components look identical across all visual variants (pill, underline, outline). The difference is semantic, not visual. Tabs uses role=tablist/tab/tabpanel with aria-selected and aria-controls. SegmentedControl uses role=radiogroup/radio with aria-checked. Using the wrong one produces incorrect screen reader announcements."
+    },
+    "chipVsButton": {
+      "title": "Chip vs Button",
+      "question": "Is this an action the user performs, or a label/tag/toggle representing a value?",
+      "rules": [
+        {
+          "answer": "Action — save, delete, submit, navigate, open a modal",
+          "use": "Button"
+        },
+        {
+          "answer": "Label or tag — a category, status badge, or read-only value indicator",
+          "use": "Chip (non-interactive, no onClick)"
+        },
+        {
+          "answer": "Filter toggle or multi-select token — represents 'is this category active?'",
+          "use": "Chip (interactive or inside ChipGroup)"
+        }
+      ],
+      "components": [
+        "Chip",
+        "ChipGroup",
+        "Button"
+      ],
+      "storybookPath": "Guides/Chip vs Button",
+      "detail": "The visual overlap comes from shared size tokens and variants. The semantic difference is the ARIA contract. Button always means 'do something' — it carries action intent. Chip means 'this value is present or selected' — it carries state. An interactive Chip uses aria-pressed (toggle), not action semantics. Use ChipGroup when you have multiple selectable filter tokens — it manages selection state, keyboard navigation, and aria-pressed across the group. A ghost or outline Button that looks like a Chip is still a Button if the intent is to trigger an action, not represent a value."
+    }
+  },
   "icons": {
     "sets": {
       "cred": 12,