@tangible/ui 0.0.2 → 0.0.4

package/tui-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.0.2",
-  "generated": "2026-02-17T04:01:35.339Z",
+  "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,13 +124,32 @@
           "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,
           "description": "Additional CSS class"
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-avatar-size",
+        "--tui-avatar-radius",
+        "--tui-avatar-bg",
+        "--tui-avatar-fg",
+        "--tui-avatar-border",
+        "--tui-avatar-indicator-bg",
+        "--tui-avatar-indicator-fg",
+        "--tui-avatar-overflow-bg",
+        "--tui-avatar-overflow-fg",
+        "--tui-avatar-group-overlap",
+        "--tui-avatar-group-gap",
+        "--tui-avatar-group-border-width",
+        "--tui-avatar-group-border-color"
+      ],
       "story": {
         "title": "Primitives/Avatar",
         "tags": [
@@ -140,7 +161,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Button": {
       "props": {
@@ -190,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,
@@ -228,7 +257,7 @@
         "iconSize": {
           "type": "\"xs\" | \"sm\" | \"md\" | \"lg\"",
           "required": false,
-          "defaultValue": "sm",
+          "defaultValue": "'sm'",
           "description": "Size of icons."
         },
         "className": {
@@ -270,7 +299,11 @@
         "--tui-button-radius",
         "--tui-button-bg-interact",
         "--tui-button-fg-interact",
-        "--tui-button-border-interact"
+        "--tui-button-border-interact",
+        "--tui-button-fg-active",
+        "--tui-control-height-sm",
+        "--tui-control-height-md",
+        "--tui-control-height-lg"
       ],
       "story": {
         "title": "Primitives/Button",
@@ -319,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": {
@@ -433,7 +469,9 @@
       ],
       "related": [
         "Notice"
-      ]
+      ],
+      "use": null,
+      "notFor": null
     },
     "Checkbox": {
       "props": {
@@ -474,7 +512,9 @@
           "required": false
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-input-accent"
+      ],
       "story": {
         "title": "Forms/Checkbox",
         "tags": [
@@ -486,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",
@@ -576,7 +619,14 @@
           "required": false
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-chip-bg",
+        "--tui-chip-fg",
+        "--tui-chip-border",
+        "--tui-chip-icon",
+        "--tui-chip-radius",
+        "--tui-chip-selected-ring"
+      ],
       "story": {
         "title": "Primitives/Chip",
         "tags": [
@@ -584,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": {
@@ -611,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
@@ -620,7 +714,9 @@
           "required": false
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-chip-group-gap"
+      ],
       "story": {
         "title": "Primitives/ChipGroup",
         "tags": [
@@ -632,7 +728,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Chips": {
       "props": {
@@ -664,7 +762,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Combobox": {
       "props": {
@@ -724,7 +824,19 @@
           "description": "Class name applied directly to the `<input>` element.\nUse for utilities like `tui-input-reset` that must target the input itself."
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-combobox-input-bg",
+        "--tui-combobox-input-fg",
+        "--tui-combobox-input-border",
+        "--tui-combobox-input-border-focus",
+        "--tui-combobox-input-radius",
+        "--tui-combobox-content-bg",
+        "--tui-combobox-content-border",
+        "--tui-combobox-content-shadow",
+        "--tui-combobox-content-radius",
+        "--tui-combobox-option-bg-hover",
+        "--tui-combobox-option-bg-selected"
+      ],
       "story": {
         "title": "Forms/Combobox",
         "tags": [
@@ -735,7 +847,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "ContentIndicator": {
       "props": {
@@ -773,7 +887,11 @@
           "description": "Additional CSS class names."
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-content-indicator-bg",
+        "--tui-content-indicator-border",
+        "--tui-content-indicator-fg"
+      ],
       "story": {
         "title": "Primitives/ContentIndicator",
         "tags": [
@@ -786,7 +904,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Dropdown": {
       "props": {
@@ -802,7 +922,17 @@
           "description": "Default open state for uncontrolled usage."
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-dropdown-bg",
+        "--tui-dropdown-fg",
+        "--tui-dropdown-radius",
+        "--tui-dropdown-shadow",
+        "--tui-dropdown-border",
+        "--tui-dropdown-z",
+        "--tui-dropdown-min-width",
+        "--tui-dropdown-item-bg-hover",
+        "--tui-dropdown-item-bg-active"
+      ],
       "story": {
         "title": "Primitives/Dropdown",
         "tags": [
@@ -814,7 +944,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Field": {
       "props": {
@@ -861,7 +993,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Icon": {
       "props": {
@@ -890,7 +1024,14 @@
           "required": false
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-icon-size-xs",
+        "--tui-icon-size-sm",
+        "--tui-icon-size-md",
+        "--tui-icon-size-lg",
+        "--tui-icon-size-xl",
+        "--tui-icon-size-xxl"
+      ],
       "story": {
         "title": "Primitives/Icon",
         "tags": [
@@ -902,7 +1043,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "IconButton": {
       "props": {
@@ -920,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\"",
@@ -932,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",
@@ -944,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,
@@ -953,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\"",
@@ -961,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,
@@ -1003,7 +1158,14 @@
           "required": false
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-icon-button-bg",
+        "--tui-icon-button-fg",
+        "--tui-icon-button-border",
+        "--tui-icon-button-radius",
+        "--tui-icon-button-bg-interact",
+        "--tui-icon-button-fg-interact"
+      ],
       "story": {
         "title": "Primitives/IconButton",
         "tags": [
@@ -1015,7 +1177,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Modal": {
       "props": {
@@ -1081,7 +1245,80 @@
       ],
       "related": [
         "Notice"
-      ]
+      ],
+      "use": null,
+      "notFor": null
+    },
+    "MoveHandle": {
+      "props": {
+        "mode": {
+          "type": "\"full\" | \"handle\"",
+          "required": false,
+          "defaultValue": "full",
+          "description": "Structural mode. 'full' (default) shows background panel with arrows/index. 'handle' shows only the bare drag icon button."
+        },
+        "size": {
+          "type": "\"sm\" | \"md\"",
+          "required": false,
+          "defaultValue": "md",
+          "description": "Component scale. sm = 32px, md = 40px. Ignored when mode is 'handle'."
+        },
+        "index": {
+          "type": "number",
+          "required": false,
+          "description": "Position index. When provided, shows number at rest, drag handle on hover."
+        },
+        "locked": {
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "When true, shows lock icon and disables all interaction."
+        },
+        "canMoveUp": {
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "When false, disables the move-up button without hiding it. Default: true."
+        },
+        "canMoveDown": {
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "When false, disables the move-down button without hiding it. Default: true."
+        },
+        "labels": {
+          "type": "MoveHandleLabels",
+          "required": false,
+          "description": "Override internal button labels for i18n."
+        },
+        "dragHandleProps": {
+          "type": "HTMLAttributes<HTMLButtonElement>",
+          "required": false,
+          "description": "Props to spread on the drag handle button (e.g., from dnd-kit useSortable)."
+        },
+        "className": {
+          "type": "string",
+          "required": false
+        }
+      },
+      "cssTokens": [
+        "--tui-move-handle-size",
+        "--tui-move-handle-icon-size"
+      ],
+      "story": {
+        "title": "Components/MoveHandle",
+        "tags": [
+          "autodocs",
+          "lms"
+        ]
+      },
+      "subcomponents": null,
+      "description": null,
+      "gotchas": null,
+      "examples": null,
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "MultiSelect": {
       "props": {
@@ -1141,7 +1378,21 @@
           "description": "Optional trigger ID override.\nUseful for Field integration via htmlFor."
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-multiselect-trigger-bg",
+        "--tui-multiselect-trigger-fg",
+        "--tui-multiselect-trigger-border",
+        "--tui-multiselect-trigger-border-focus",
+        "--tui-multiselect-trigger-radius",
+        "--tui-multiselect-content-bg",
+        "--tui-multiselect-content-border",
+        "--tui-multiselect-content-shadow",
+        "--tui-multiselect-content-radius",
+        "--tui-multiselect-option-bg-hover",
+        "--tui-multiselect-option-bg-selected",
+        "--tui-multiselect-chip-bg",
+        "--tui-multiselect-chip-fg"
+      ],
       "story": {
         "title": "Forms/MultiSelect",
         "tags": [
@@ -1153,7 +1404,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Notice": {
       "props": {
@@ -1252,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",
@@ -1304,7 +1558,9 @@
       "related": [
         "Card",
         "Modal"
-      ]
+      ],
+      "use": null,
+      "notFor": null
     },
     "OverlapStack": {
       "props": {
@@ -1350,7 +1606,14 @@
           "description": "Inline styles"
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-overlap-stack-overlap",
+        "--tui-overlap-stack-overflow-bg",
+        "--tui-overlap-stack-overflow-fg",
+        "--tui-overlap-stack-item-radius",
+        "--tui-overlap-stack-border-width",
+        "--tui-overlap-stack-border-color"
+      ],
       "story": {
         "title": "Components/OverlapStack",
         "tags": [
@@ -1362,7 +1625,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Pager": {
       "props": {
@@ -1410,7 +1675,9 @@
           "description": "Additional class name"
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-pager-gap"
+      ],
       "story": {
         "title": "Primitives/Pager",
         "tags": [
@@ -1422,7 +1689,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Progress": {
       "props": {
@@ -1505,7 +1774,17 @@
           "description": "Visual variant for circle mode.\n- `'ring'`: Hollow centre (default) — shows progress as a ring/donut\n- `'solid'`: Filled centre — shows as a solid filled circle\n\nOnly applies when `mode=\"circle\"`. Ignored in line mode."
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-progress-track",
+        "--tui-progress-fill",
+        "--tui-progress-label",
+        "--tui-progress-radius",
+        "--tui-progress-z1-fill",
+        "--tui-progress-z2-fill",
+        "--tui-progress-z3-fill",
+        "--tui-progress-z4-fill",
+        "--tui-progress-z5-fill"
+      ],
       "story": {
         "title": "Primitives/Progress",
         "tags": [
@@ -1517,7 +1796,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Radio": {
       "props": {
@@ -1535,7 +1816,9 @@
           "required": false
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-radio-accent"
+      ],
       "story": {
         "title": "Forms/RadioGroup",
         "tags": [
@@ -1547,7 +1830,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Rating": {
       "props": {
@@ -1609,7 +1894,11 @@
           "description": "Gap override (e.g. '0.25rem') – otherwise uses density utilities"
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-rating-active",
+        "--tui-rating-inactive",
+        "--tui-rating-scale"
+      ],
       "story": {
         "title": "Primitives/Rating",
         "tags": [
@@ -1621,7 +1910,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "SegmentedControl": {
       "props": {
@@ -1666,7 +1957,18 @@
           "description": "Additional classes"
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-segmented-gap",
+        "--tui-segmented-padding",
+        "--tui-segmented-radius",
+        "--tui-segmented-bg",
+        "--tui-segmented-border",
+        "--tui-segmented-item-padding",
+        "--tui-segmented-item-radius",
+        "--tui-segmented-item-fg",
+        "--tui-segmented-item-bg-active",
+        "--tui-segmented-item-fg-active"
+      ],
       "story": {
         "title": "Components/SegmentedControl",
         "tags": [
@@ -1674,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": {
@@ -1745,7 +2078,19 @@
           "description": "Optional trigger ID override.\nUseful for Field integration via htmlFor."
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-select-trigger-bg",
+        "--tui-select-trigger-fg",
+        "--tui-select-trigger-border",
+        "--tui-select-trigger-border-focus",
+        "--tui-select-trigger-radius",
+        "--tui-select-content-bg",
+        "--tui-select-content-border",
+        "--tui-select-content-shadow",
+        "--tui-select-content-radius",
+        "--tui-select-option-bg-hover",
+        "--tui-select-option-bg-selected"
+      ],
       "story": {
         "title": "Forms/Select",
         "tags": [
@@ -1757,7 +2102,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Sidebar": {
       "props": {
@@ -1767,34 +2114,40 @@
           "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": [],
+      "cssTokens": [
+        "--tui-sidebar-width",
+        "--tui-sidebar-bg",
+        "--tui-sidebar-border",
+        "--tui-sidebar-padding",
+        "--tui-sidebar-z"
+      ],
       "story": {
         "title": "Components/Sidebar",
         "tags": [
@@ -1807,7 +2160,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "StepIndicator": {
       "props": {
@@ -1863,7 +2218,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "StepList": {
       "props": {
@@ -1889,7 +2246,14 @@
           "description": "Additional CSS class names."
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-steplist-gap",
+        "--tui-steplist-padding",
+        "--tui-steplist-radius",
+        "--tui-steplist-current-bg",
+        "--tui-steplist-current-border",
+        "--tui-steplist-hover-bg"
+      ],
       "story": {
         "title": "Components/StepList",
         "tags": [
@@ -1902,7 +2266,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Switch": {
       "props": {
@@ -1944,7 +2310,10 @@
           "required": false
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-switch-accent",
+        "--tui-switch-track-off"
+      ],
       "story": {
         "title": "Forms/Switch",
         "tags": [
@@ -1956,7 +2325,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Tabs": {
       "props": {
@@ -2053,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": {
@@ -2126,7 +2499,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "TextInput": {
       "props": {
@@ -2190,7 +2565,9 @@
           "description": "Class name applied directly to the `<input>` element.\nUse for utilities like `tui-input-reset` that must target the input itself."
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-input-group-gap"
+      ],
       "story": {
         "title": "Forms/TextInput",
         "tags": [
@@ -2203,7 +2580,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Toolbar": {
       "props": {
@@ -2227,7 +2606,10 @@
           "description": "Inline styles for layout integration"
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-toolbar-gap",
+        "--tui-toolbar-padding"
+      ],
       "story": {
         "title": "Components/Toolbar",
         "tags": [
@@ -2239,7 +2621,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     },
     "Tooltip": {
       "props": {
@@ -2260,7 +2644,12 @@
           "description": "Override provider's delay for this tooltip."
         }
       },
-      "cssTokens": [],
+      "cssTokens": [
+        "--tui-tooltip-bg",
+        "--tui-tooltip-fg",
+        "--tui-tooltip-radius",
+        "--tui-tooltip-z"
+      ],
       "story": {
         "title": "Primitives/Tooltip",
         "tags": [
@@ -2272,7 +2661,9 @@
       "description": null,
       "gotchas": null,
       "examples": null,
-      "related": null
+      "related": null,
+      "use": null,
+      "notFor": null
     }
   },
   "utilities": {
@@ -2415,15 +2806,62 @@
       "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,
       "lms": 7,
       "player": 24,
       "reaction": 36,
-      "system": 75
+      "system": 76
     },
-    "total": 154,
+    "total": 155,
     "manifest": "./icons/manifest.json"
   }
 }