@usefragments/ui 1.6.0 → 1.7.0

package/src/components/Stack/index.tsx

@@ -107,7 +107,7 @@ const StackRoot = React.forwardRef<HTMLElement, StackProps>(function Stack(
 
   // Handle responsive direction
   if (isResponsiveDirection(direction)) {
-    directionClass = styles.directionResponsive;
+    directionClass = styles.directionResponsive ?? "";
     const vars: Record<string, string> = {};
     const baseDirection = direction.base ?? "column";
     const smDirection = direction.sm ?? baseDirection;
@@ -121,12 +121,12 @@ const StackRoot = React.forwardRef<HTMLElement, StackProps>(function Stack(
     vars["--fui-stack-direction-xl"] = xlDirection;
     inlineStyle = vars as unknown as React.CSSProperties;
   } else {
-    directionClass = styles[direction];
+    directionClass = styles[direction] ?? "";
   }
 
   // Handle responsive gap
   if (isResponsiveGap(gap)) {
-    gapClass = styles.gapResponsive;
+    gapClass = styles.gapResponsive ?? false;
     const gapVars: Record<string, string> = {};
     if (gap.base) gapVars["--fui-stack-gap"] = resolveLayoutGap(gap.base);
     if (gap.sm) gapVars["--fui-stack-gap-sm"] = resolveLayoutGap(gap.sm);

package/src/components/Switch/Switch.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Switch",
-  "description": "Binary on/off switch for settings and preferences. Provides immediate visual feedback and is ideal for options that take effect instantly.",
-  "category": "forms",
-  "tags": [
-    "switch",
-    "toggle",
-    "boolean",
-    "settings",
-    "preference"
-  ],
+  "description": "Toggles a setting that takes effect immediately.",
+  "category": "inputs",
+  "tags": ["switch", "toggle", "boolean", "settings", "preference"],
   "status": "stable",
   "sourcePath": "src/components/Switch/index.tsx",
   "exportName": "Switch",
@@ -78,11 +72,7 @@
       "description": "Switch track size",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["sm", "md", "lg"]
     },
     "className": {
       "type": "string",
@@ -117,35 +107,34 @@
   },
   "usage": {
     "when": [
-      "Binary settings that take effect immediately (e.g., dark mode, notifications)",
-      "Enabling/disabling features in a settings panel",
-      "Options where the result is immediately visible",
-      "Mobile-friendly boolean inputs"
+      "Settings that apply the moment they change",
+      "Turning a feature on or off in a settings panel",
+      "The result is visible straight away"
     ],
     "whenNot": [
-      "Multiple options in a group (use checkbox group)",
-      "Selection requires form submission to take effect (use checkbox)",
-      "Yes/No questions in forms (use radio buttons)",
-      "Complex multi-state options (use select or radio)"
+      "Choices that only apply on submit (use Checkbox)",
+      "Several options at once (use a Checkbox group)",
+      "Yes/no questions in a form (use RadioGroup)",
+      "More than two states (use Select or RadioGroup)"
     ],
     "guidelines": [
-      "Switch should always have a visible label explaining what it controls",
-      "The \"on\" state should be the positive/enabling action",
-      "Changes should take effect immediately - no save button needed",
-      "Include helperText for switches whose effect isn't obvious from the label",
-      "Group related switches visually in settings panels"
+      "The label names what is being turned on",
+      "On always means enabled, never the reverse",
+      "Apply the change immediately — no save button",
+      "Add helperText when the label alone is ambiguous",
+      "Stack related switches together"
     ],
     "accessibility": [
-      "Uses role=\"switch\" with aria-checked for proper semantics",
-      "Must have an accessible label (visible or aria-label)",
-      "Focus indicator must be clearly visible",
-      "State change must be announced by screen readers"
+      "role=\"switch\" with aria-checked",
+      "Every switch has a label, visible or aria-label",
+      "Focus ring stays visible",
+      "Flipping it is announced"
     ]
   },
   "examples": [
     {
       "name": "Default Off",
-      "description": "Switch in the off state",
+      "description": "Nothing happens until the user flips it.",
       "code": "<StatefulSwitch label=\"Email notifications\" />",
       "args": {
         "label": "Email notifications"
@@ -153,37 +142,37 @@
     },
     {
       "name": "Checked",
-      "description": "Switch in the on state",
-      "code": "<StatefulSwitch checked label=\"Dark mode\" />",
+      "description": "Starts on; the track fills with the accent colour.",
+      "code": "<StatefulSwitch defaultChecked label=\"Dark mode\" />",
       "args": {
-        "checked": true,
+        "defaultChecked": true,
         "label": "Dark mode"
       }
     },
     {
       "name": "With Helper Text",
-      "description": "Switch with explanatory helper text",
-      "code": "<StatefulSwitch\n  checked\n  label=\"Auto-save\"\n  helperText=\"Automatically save changes as you type\"\n/>",
+      "description": "Second line says what the setting actually does.",
+      "code": "<StatefulSwitch\n  defaultChecked\n  label=\"Auto-save\"\n  helperText=\"Automatically save changes as you type\"\n/>",
       "args": {
-        "checked": true,
+        "defaultChecked": true,
         "label": "Auto-save",
         "helperText": "Automatically save changes as you type"
       }
     },
     {
       "name": "Sizes",
-      "description": "Available size variants",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <StatefulSwitch size=\"sm\" checked label=\"Small switch\" />\n  <StatefulSwitch size=\"md\" checked label=\"Medium switch (default)\" />\n  <StatefulSwitch size=\"lg\" checked label=\"Large switch\" />\n</div>"
+      "description": "Three track sizes: sm, md, lg.",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <StatefulSwitch size=\"sm\" defaultChecked label=\"Small switch\" />\n  <StatefulSwitch size=\"md\" defaultChecked label=\"Medium switch (default)\" />\n  <StatefulSwitch size=\"lg\" defaultChecked label=\"Large switch\" />\n</div>"
     },
     {
       "name": "Disabled States",
-      "description": "Non-interactive switches showing both states",
+      "description": "Locked off and locked on, both dimmed.",
       "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <Switch disabled label=\"Premium feature (upgrade required)\" />\n  <Switch disabled checked label=\"System managed (read-only)\" />\n</div>"
     },
     {
       "name": "Settings Panel",
-      "description": "Multiple switches in a realistic settings layout",
-      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '320px' }}>\n  <StatefulSwitch\n    checked\n    label=\"Push notifications\"\n    helperText=\"Receive push notifications on your device\"\n  />\n  <StatefulSwitch\n    checked\n    label=\"Email digest\"\n    helperText=\"Weekly summary of your activity\"\n  />\n  <StatefulSwitch\n    label=\"Marketing emails\"\n    helperText=\"Product updates and promotional offers\"\n  />\n</div>"
+      "description": "Stacked switches sharing one rhythm and helper column.",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '320px' }}>\n  <StatefulSwitch\n    defaultChecked\n    label=\"Push notifications\"\n    helperText=\"Receive push notifications on your device\"\n  />\n  <StatefulSwitch\n    defaultChecked\n    label=\"Email digest\"\n    helperText=\"Weekly summary of your activity\"\n  />\n  <StatefulSwitch\n    label=\"Marketing emails\"\n    helperText=\"Product updates and promotional offers\"\n  />\n</div>"
     }
   ],
   "relations": [
@@ -218,9 +207,7 @@
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Switch/Switch.module.scss

@@ -7,28 +7,72 @@
 
 .root {
   --_switch-off-bg: light-dark(
-    color-mix(in srgb, var(--fui-bg-elevated) 92%, var(--fui-text-primary) 8%),
-    color-mix(in srgb, var(--fui-bg-elevated) 82%, var(--fui-text-primary) 18%)
+    color-mix(
+      in srgb,
+      var(--fui-bg-elevated, #{$fui-bg-elevated}) 92%,
+      var(--fui-text-primary, #{$fui-text-primary}) 8%
+    ),
+    color-mix(
+      in srgb,
+      var(--fui-bg-elevated, #{$fui-bg-elevated}) 82%,
+      var(--fui-text-primary, #{$fui-text-primary}) 18%
+    )
   );
   --_switch-off-bg-hover: light-dark(
-    color-mix(in srgb, var(--fui-bg-elevated) 88%, var(--fui-text-primary) 12%),
-    color-mix(in srgb, var(--fui-bg-elevated) 76%, var(--fui-text-primary) 24%)
+    color-mix(
+      in srgb,
+      var(--fui-bg-elevated, #{$fui-bg-elevated}) 88%,
+      var(--fui-text-primary, #{$fui-text-primary}) 12%
+    ),
+    color-mix(
+      in srgb,
+      var(--fui-bg-elevated, #{$fui-bg-elevated}) 76%,
+      var(--fui-text-primary, #{$fui-text-primary}) 24%
+    )
   );
   --_switch-off-border: light-dark(
-    color-mix(in srgb, var(--fui-border-strong) 72%, var(--fui-text-primary) 28%),
-    color-mix(in srgb, var(--fui-border-strong) 58%, var(--fui-text-primary) 42%)
+    color-mix(
+      in srgb,
+      var(--fui-border-strong, #{$fui-border-strong}) 72%,
+      var(--fui-text-primary, #{$fui-text-primary}) 28%
+    ),
+    color-mix(
+      in srgb,
+      var(--fui-border-strong, #{$fui-border-strong}) 58%,
+      var(--fui-text-primary, #{$fui-text-primary}) 42%
+    )
   );
   --_switch-off-border-hover: light-dark(
-    color-mix(in srgb, var(--fui-border-strong) 58%, var(--fui-text-primary) 42%),
-    color-mix(in srgb, var(--fui-border-strong) 44%, var(--fui-text-primary) 56%)
+    color-mix(
+      in srgb,
+      var(--fui-border-strong, #{$fui-border-strong}) 58%,
+      var(--fui-text-primary, #{$fui-text-primary}) 42%
+    ),
+    color-mix(
+      in srgb,
+      var(--fui-border-strong, #{$fui-border-strong}) 44%,
+      var(--fui-text-primary, #{$fui-text-primary}) 56%
+    )
   );
   --_switch-thumb-bg: light-dark(
-    color-mix(in srgb, var(--fui-bg-primary) 98%, white 2%),
-    color-mix(in srgb, var(--fui-bg-primary) 56%, var(--fui-text-primary) 44%)
+    color-mix(in srgb, var(--fui-bg-primary, #{$fui-bg-primary}) 98%, white 2%),
+    color-mix(
+      in srgb,
+      var(--fui-bg-primary, #{$fui-bg-primary}) 56%,
+      var(--fui-text-primary, #{$fui-text-primary}) 44%
+    )
   );
   --_switch-thumb-border: light-dark(
-    color-mix(in srgb, var(--fui-border-strong) 68%, var(--fui-text-primary) 32%),
-    color-mix(in srgb, var(--fui-border-strong) 45%, var(--fui-text-primary) 55%)
+    color-mix(
+      in srgb,
+      var(--fui-border-strong, #{$fui-border-strong}) 68%,
+      var(--fui-text-primary, #{$fui-text-primary}) 32%
+    ),
+    color-mix(
+      in srgb,
+      var(--fui-border-strong, #{$fui-border-strong}) 45%,
+      var(--fui-text-primary, #{$fui-text-primary}) 55%
+    )
   );
 
   @include target.hit-area("compact");
@@ -85,11 +129,8 @@
     box-shadow var(--fui-transition-normal, $fui-transition-normal);
 
   .root[data-checked] & {
-    background-color: var(--fui-button-primary-base, $fui-color-accent);
-    border-color: var(
-      --fui-button-primary-border,
-      var(--fui-button-primary-base, #{$fui-color-accent})
-    );
+    background-color: var(--fui-control-checked-bg, $fui-color-accent);
+    border-color: var(--fui-control-checked-border, $fui-color-accent);
     box-shadow: inset 0 1px 0 color-mix(in srgb, white 24%, transparent);
   }
 
@@ -99,11 +140,8 @@
   }
 
   .root:not([data-disabled])[data-checked] &:hover {
-    background-color: var(--fui-button-primary-hover, $fui-color-accent);
-    border-color: var(
-      --fui-button-primary-border-hover,
-      var(--fui-button-primary-hover, #{$fui-color-accent})
-    );
+    background-color: var(--fui-control-checked-bg-hover, $fui-color-accent-hover);
+    border-color: var(--fui-control-checked-border-hover, $fui-color-accent-hover);
   }
 
   .root:focus-visible & {
@@ -139,7 +177,7 @@
   box-sizing: border-box;
   width: var(--_fui-switch-thumb-size);
   height: var(--_fui-switch-thumb-size);
-  border-radius: 50%;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
   pointer-events: none;
   background-color: var(--_switch-thumb-bg);
   border: var(--fui-stroke-hairline, 1px) solid var(--_switch-thumb-border);
@@ -155,10 +193,10 @@
 
   .root[data-checked] & {
     transform: translate(var(--_fui-switch-travel), -50%);
-    background-color: var(--fui-button-primary-color, #fff);
+    background-color: var(--fui-control-checked-color, $fui-color-on-accent);
     border-color: color-mix(
       in srgb,
-      var(--fui-button-primary-active, #{$fui-color-accent}) 28%,
+      var(--fui-control-checked-border, #{$fui-color-accent}) 28%,
       transparent
     );
   }
@@ -198,7 +236,7 @@
   }
 
   .root[data-checked] .track {
-    border-color: var(--fui-button-primary-base, $fui-color-accent);
+    border-color: var(--fui-control-checked-border, $fui-color-accent);
   }
 }
 

package/src/components/Table/Table.contract.json

@@ -1,14 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Table",
-  "description": "Semantic HTML table with compound API. For data-rich tables with sorting and selection, use DataTable.",
+  "description": "Renders tabular data as a real HTML table — headers, rows, footer.",
   "category": "display",
-  "tags": [
-    "table",
-    "semantic",
-    "html",
-    "layout"
-  ],
+  "tags": ["table", "semantic", "html", "layout"],
   "status": "stable",
   "sourcePath": "src/components/Table/index.tsx",
   "exportName": "Table",
@@ -26,10 +21,7 @@
       "description": "Table density",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md"
-      ]
+      "values": ["sm", "md"]
     },
     "striped": {
       "type": "boolean",
@@ -61,22 +53,19 @@
   },
   "usage": {
     "when": [
-      "Displaying simple tabular data with semantic HTML",
-      "Static data that does not need sorting or selection",
-      "Showing structured information with headers and rows",
-      "Tables with footers or captions"
+      "The data is static — read it, do not interact with it",
+      "You need real thead/tbody/tfoot semantics",
+      "The table needs a caption or a totals footer"
     ],
     "whenNot": [
-      "Data that needs sorting (use DataTable)",
-      "Data that needs row selection (use DataTable)",
-      "Data that needs clickable rows (use DataTable)",
-      "Simple lists (use List component)"
+      "Rows need sorting, selection, or clicking (use DataTable)",
+      "Content is a single column of items (use List)"
     ],
     "guidelines": [
-      "Use Table.HeaderCell for column headers (adds scope=\"col\" by default)",
-      "Use Table.Caption for table descriptions (can be visually hidden)",
-      "Keep tables simple — use DataTable for interactive features",
-      "Consider mobile responsiveness; table scrolls horizontally on small screens"
+      "Header cells go in Table.HeaderCell — it sets scope=\"col\" for you",
+      "Give every table a caption or aria-label; visuallyHidden keeps it off screen",
+      "Reach for density, not the deprecated size prop",
+      "Narrow viewports scroll the table sideways — keep column count low"
     ],
     "accessibility": [
       "Semantic HTML table elements (thead, tbody, tfoot, th, td)",
@@ -88,37 +77,42 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic semantic table",
+      "description": "Header row plus body rows, no extra styling.",
       "code": "<Table aria-label=\"Team members\">\n  <Table.Head>\n    <Table.Row>\n      <Table.HeaderCell>Name</Table.HeaderCell>\n      <Table.HeaderCell>Role</Table.HeaderCell>\n      <Table.HeaderCell>Status</Table.HeaderCell>\n    </Table.Row>\n  </Table.Head>\n  <Table.Body>\n    <Table.Row>\n      <Table.Cell>Alice Johnson</Table.Cell>\n      <Table.Cell>Engineer</Table.Cell>\n      <Table.Cell>Active</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Bob Smith</Table.Cell>\n      <Table.Cell>Designer</Table.Cell>\n      <Table.Cell>Active</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Carol Williams</Table.Cell>\n      <Table.Cell>PM</Table.Cell>\n      <Table.Cell>Away</Table.Cell>\n    </Table.Row>\n  </Table.Body>\n</Table>"
     },
+    {
+      "name": "Empty",
+      "description": "Keep the headers and fill one full-width cell so the layout holds.",
+      "code": "<Table aria-label=\"Team members\">\n  <Table.Head>\n    <Table.Row>\n      <Table.HeaderCell>Name</Table.HeaderCell>\n      <Table.HeaderCell>Role</Table.HeaderCell>\n      <Table.HeaderCell>Status</Table.HeaderCell>\n    </Table.Row>\n  </Table.Head>\n  <Table.Body>\n    <Table.Row>\n      <Table.Cell colSpan={3}>No team members yet.</Table.Cell>\n    </Table.Row>\n  </Table.Body>\n</Table>"
+    },
     {
       "name": "Striped",
-      "description": "Alternating row backgrounds for readability",
+      "description": "Row tint alternates so the eye tracks across wide rows.",
       "code": "<Table striped aria-label=\"Inventory\">\n  <Table.Head>\n    <Table.Row>\n      <Table.HeaderCell>Item</Table.HeaderCell>\n      <Table.HeaderCell>Category</Table.HeaderCell>\n      <Table.HeaderCell>Qty</Table.HeaderCell>\n    </Table.Row>\n  </Table.Head>\n  <Table.Body>\n    <Table.Row>\n      <Table.Cell>Widget A</Table.Cell>\n      <Table.Cell>Hardware</Table.Cell>\n      <Table.Cell>120</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Widget B</Table.Cell>\n      <Table.Cell>Software</Table.Cell>\n      <Table.Cell>85</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Widget C</Table.Cell>\n      <Table.Cell>Hardware</Table.Cell>\n      <Table.Cell>200</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Widget D</Table.Cell>\n      <Table.Cell>Software</Table.Cell>\n      <Table.Cell>50</Table.Cell>\n    </Table.Row>\n  </Table.Body>\n</Table>"
     },
     {
       "name": "Bordered",
-      "description": "Table with bordered container",
+      "description": "A border wraps the data so it reads as one block on a busy page.",
       "code": "<Table bordered aria-label=\"Pricing\">\n  <Table.Head>\n    <Table.Row>\n      <Table.HeaderCell>Plan</Table.HeaderCell>\n      <Table.HeaderCell>Price</Table.HeaderCell>\n      <Table.HeaderCell>Features</Table.HeaderCell>\n    </Table.Row>\n  </Table.Head>\n  <Table.Body>\n    <Table.Row>\n      <Table.Cell>Basic</Table.Cell>\n      <Table.Cell>$9/mo</Table.Cell>\n      <Table.Cell>5 projects</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Pro</Table.Cell>\n      <Table.Cell>$29/mo</Table.Cell>\n      <Table.Cell>Unlimited</Table.Cell>\n    </Table.Row>\n  </Table.Body>\n</Table>"
     },
     {
       "name": "Compact",
-      "description": "Small, dense table",
-      "code": "<Table size=\"sm\" aria-label=\"Shortcuts\">\n  <Table.Head>\n    <Table.Row>\n      <Table.HeaderCell>Key</Table.HeaderCell>\n      <Table.HeaderCell>Action</Table.HeaderCell>\n    </Table.Row>\n  </Table.Head>\n  <Table.Body>\n    <Table.Row>\n      <Table.Cell>Ctrl+S</Table.Cell>\n      <Table.Cell>Save</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Ctrl+Z</Table.Cell>\n      <Table.Cell>Undo</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Ctrl+C</Table.Cell>\n      <Table.Cell>Copy</Table.Cell>\n    </Table.Row>\n  </Table.Body>\n</Table>"
+      "description": "Tighter rows fit more data in the same height.",
+      "code": "<Table density=\"compact\" aria-label=\"Shortcuts\">\n  <Table.Head>\n    <Table.Row>\n      <Table.HeaderCell>Key</Table.HeaderCell>\n      <Table.HeaderCell>Action</Table.HeaderCell>\n    </Table.Row>\n  </Table.Head>\n  <Table.Body>\n    <Table.Row>\n      <Table.Cell>Ctrl+S</Table.Cell>\n      <Table.Cell>Save</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Ctrl+Z</Table.Cell>\n      <Table.Cell>Undo</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Ctrl+C</Table.Cell>\n      <Table.Cell>Copy</Table.Cell>\n    </Table.Row>\n  </Table.Body>\n</Table>"
     },
     {
       "name": "With Caption",
-      "description": "Table with visible caption",
+      "description": "A visible caption titles the data for every reader.",
       "code": "<Table aria-label=\"Q1 results\">\n  <Table.Caption>Quarterly Results (Q1 2026)</Table.Caption>\n  <Table.Head>\n    <Table.Row>\n      <Table.HeaderCell>Metric</Table.HeaderCell>\n      <Table.HeaderCell>Value</Table.HeaderCell>\n      <Table.HeaderCell>Change</Table.HeaderCell>\n    </Table.Row>\n  </Table.Head>\n  <Table.Body>\n    <Table.Row>\n      <Table.Cell>Revenue</Table.Cell>\n      <Table.Cell>$1.2M</Table.Cell>\n      <Table.Cell>+15%</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Users</Table.Cell>\n      <Table.Cell>24,500</Table.Cell>\n      <Table.Cell>+8%</Table.Cell>\n    </Table.Row>\n  </Table.Body>\n</Table>"
     },
     {
       "name": "Screen Reader Caption",
-      "description": "Visually hidden caption for screen-reader context while keeping visual UI compact",
-      "code": "<Table\n  aria-label=\"API keys\"\n  wrapperProps={{ 'data-demo': 'table-wrapper' }}\n  wrapperClassName=\"demo-table-wrapper\"\n>\n  <Table.Caption visuallyHidden>API keys and last-used timestamps</Table.Caption>\n  <Table.Head>\n    <Table.Row>\n      <Table.HeaderCell>Name</Table.HeaderCell>\n      <Table.HeaderCell>Prefix</Table.HeaderCell>\n      <Table.HeaderCell>Last Used</Table.HeaderCell>\n    </Table.Row>\n  </Table.Head>\n  <Table.Body>\n    <Table.Row>\n      <Table.Cell>Deploy</Table.Cell>\n      <Table.Cell>frg_live_...</Table.Cell>\n      <Table.Cell>2 hours ago</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>CI</Table.Cell>\n      <Table.Cell>frg_test_...</Table.Cell>\n      <Table.Cell>Yesterday</Table.Cell>\n    </Table.Row>\n  </Table.Body>\n</Table>"
+      "description": "The caption reaches screen readers only; the layout stays tight.",
+      "code": "<Table aria-label=\"API keys\">\n  <Table.Caption visuallyHidden>API keys and last-used timestamps</Table.Caption>\n  <Table.Head>\n    <Table.Row>\n      <Table.HeaderCell>Name</Table.HeaderCell>\n      <Table.HeaderCell>Prefix</Table.HeaderCell>\n      <Table.HeaderCell>Last Used</Table.HeaderCell>\n    </Table.Row>\n  </Table.Head>\n  <Table.Body>\n    <Table.Row>\n      <Table.Cell>Deploy</Table.Cell>\n      <Table.Cell>frg_live_...</Table.Cell>\n      <Table.Cell>2 hours ago</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>CI</Table.Cell>\n      <Table.Cell>frg_test_...</Table.Cell>\n      <Table.Cell>Yesterday</Table.Cell>\n    </Table.Row>\n  </Table.Body>\n</Table>"
     },
     {
       "name": "With Footer",
-      "description": "Table with footer row for totals",
+      "description": "Totals sit in a footer that stays separate from the data.",
       "code": "<Table bordered aria-label=\"Expenses\">\n  <Table.Head>\n    <Table.Row>\n      <Table.HeaderCell>Category</Table.HeaderCell>\n      <Table.HeaderCell>Amount</Table.HeaderCell>\n    </Table.Row>\n  </Table.Head>\n  <Table.Body>\n    <Table.Row>\n      <Table.Cell>Marketing</Table.Cell>\n      <Table.Cell>$12,000</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Engineering</Table.Cell>\n      <Table.Cell>$45,000</Table.Cell>\n    </Table.Row>\n    <Table.Row>\n      <Table.Cell>Operations</Table.Cell>\n      <Table.Cell>$8,000</Table.Cell>\n    </Table.Row>\n  </Table.Body>\n  <Table.Footer>\n    <Table.Row>\n      <Table.Cell>Total</Table.Cell>\n      <Table.Cell>$65,000</Table.Cell>\n    </Table.Row>\n  </Table.Footer>\n</Table>"
     }
   ],
@@ -141,23 +135,11 @@
       "wrapperClassName/wrapperProps - customize outer scroll wrapper",
       "Table.Caption - caption with visuallyHidden prop (hidden is deprecated alias)"
     ],
-    "a11yRules": [
-      "A11Y_TABLE_HEADERS",
-      "A11Y_TABLE_CAPTION"
-    ]
+    "a11yRules": ["A11Y_TABLE_HEADERS", "A11Y_TABLE_CAPTION"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root",
-      "Head",
-      "Body",
-      "Footer",
-      "Row",
-      "Cell",
-      "HeaderCell",
-      "Caption"
-    ],
+    "subComponents": ["Root", "Head", "Body", "Footer", "Row", "Cell", "HeaderCell", "Caption"],
     "commonPatterns": [
       "<Table><Table.Head><Table.Row><Table.HeaderCell>Name</Table.HeaderCell></Table.Row></Table.Head><Table.Body><Table.Row><Table.Cell>Alice</Table.Cell></Table.Row></Table.Body></Table>"
     ]

package/src/components/Table/Table.module.scss

@@ -50,7 +50,7 @@
 .headerContent {
   display: flex;
   align-items: center;
-  gap: var(--fui-raw-space-4);
+  gap: var(--fui-raw-space-4, 4px);
 }
 
 .row {
@@ -78,6 +78,17 @@
   @include table-chrome.body-cell;
 }
 
+// Unbordered ledger edge: the first column starts at the surrounding surface's
+// own inset so a table inside a card reads as part of the card, not a box within
+// a box. A bordered table owns its frame and keeps the recipe's inline inset.
+.wrapper:not(.bordered) > .table {
+  > .thead > .row > .th:first-child,
+  > .tbody > .row > .td:first-child,
+  > .tfoot > .row > .td:first-child {
+    padding-inline-start: 0;
+  }
+}
+
 .selected {
   --fui-table-row-bg: var(
     --fui-table-row-selected-bg,
@@ -112,8 +123,9 @@
 }
 
 .bordered {
-  overflow: hidden;
-  border: var(--fui-table-divider-size, var(--fui-stroke-hairline)) solid
+  overflow-x: auto;
+  overflow-y: hidden;
+  border: var(--fui-table-divider-size, var(--fui-stroke-hairline, $fui-stroke-hairline)) solid
     var(--fui-table-border, var(--fui-border, #{$fui-border}));
   border-radius: var(--fui-radius-md, $fui-radius-md);
 }

package/src/components/TableOfContents/TableOfContents.contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "TableOfContents",
-  "description": "Sticky sidebar navigation for long-form content or filterable lists. Renders a quiet, flush index with nested indentation and an ink-weight active state.",
+  "description": "Indexes a long page and marks the section currently in view.",
   "category": "navigation",
   "tags": [
     "toc",
@@ -20,7 +20,8 @@
     "children: node (required)",
     "label: string (default: Table of contents)",
     "title: string (default: On This Page)",
-    "hideTitle: boolean (default: false)"
+    "hideTitle: boolean (default: false)",
+    "hideSubItems: boolean (default: false)"
   ],
   "props": {
     "children": {
@@ -45,28 +46,34 @@
       "description": "Hide the visible title",
       "default": "false",
       "required": false
+    },
+    "hideSubItems": {
+      "type": "boolean",
+      "description": "Hide indented items and nested groups",
+      "default": "false",
+      "required": false
     }
   },
   "usage": {
     "when": [
-      "Long-form content pages (docs, blog posts, articles)",
-      "Component documentation with multiple sections",
-      "Filterable list sidebars where items are grouped by category",
-      "Any page with 3+ headings or nested sections that benefit from quick navigation"
+      "Docs, articles, and other long reads",
+      "Reference pages with many sections",
+      "Filterable sidebars grouped by category",
+      "Anything past three headings"
     ],
     "whenNot": [
-      "Short pages with only 1-2 sections",
-      "Primary site navigation (use Sidebar or Header)",
-      "Step-by-step flows (use Stepper)"
+      "Pages with one or two sections",
+      "Site navigation (use Sidebar or Header)",
+      "Steps in an order (use Stepper)"
     ],
     "guidelines": [
-      "Pair with a scroll spy hook (e.g., IntersectionObserver) to track active heading",
-      "Use TableOfContents.Group to nest items under a labeled, optionally-collapsible parent",
-      "The legacy `indent` boolean on Item is preserved for back-compat; prefer Group for new code",
-      "Place in a sticky aside for best UX",
-      "Heading IDs must match between TOC items and the actual DOM headings",
-      "TableOfContents.Item performs smooth scrolling by default; call event.preventDefault() in onClick to override",
-      "Group is uncontrolled (defaultOpen=true) by default; pass open + onOpenChange for controlled state"
+      "Drive the active item from an IntersectionObserver scroll spy",
+      "Sub-items show by default — pass hideSubItems for a compact index",
+      "Group nests items under a labelled, optionally collapsible parent",
+      "Item ids must match the real heading ids",
+      "Items smooth-scroll — call preventDefault() in onClick to take over",
+      "Group is uncontrolled and open by default; pass open and onOpenChange to drive it",
+      "The legacy indent boolean still works; prefer Group in new code"
     ],
     "accessibility": [
       "Uses <nav aria-label=\"Table of contents\"> for landmark navigation",
@@ -79,27 +86,32 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic table of contents with section links",
+      "description": "Sections and their subsections, indented.",
       "code": "<TableOfContents>\n  <TableOfContents.Item id=\"introduction\">Introduction</TableOfContents.Item>\n  <TableOfContents.Item id=\"getting-started\">Getting Started</TableOfContents.Item>\n  <TableOfContents.Item id=\"installation\" indent>Installation</TableOfContents.Item>\n  <TableOfContents.Item id=\"configuration\" indent>Configuration</TableOfContents.Item>\n  <TableOfContents.Item id=\"api-reference\">API Reference</TableOfContents.Item>\n  <TableOfContents.Item id=\"examples\">Examples</TableOfContents.Item>\n</TableOfContents>"
     },
+    {
+      "name": "Top-level Only",
+      "description": "Drops subsections when the index would crowd.",
+      "code": "<TableOfContents hideSubItems>\n  <TableOfContents.Item id=\"overview\">Overview</TableOfContents.Item>\n  <TableOfContents.Item id=\"basic-usage\" indent>Basic usage</TableOfContents.Item>\n  <TableOfContents.Item id=\"advanced-usage\" indent>Advanced usage</TableOfContents.Item>\n  <TableOfContents.Item id=\"accessibility\">Accessibility</TableOfContents.Item>\n</TableOfContents>"
+    },
     {
       "name": "Nested Groups",
-      "description": "Filterable list grouped by category with clear nested indentation",
+      "description": "Collapsible categories with counts.",
       "code": "<TableOfContents title=\"Components\">\n  <TableOfContents.Item id=\"all\" active>All</TableOfContents.Item>\n  <TableOfContents.Group label=\"Primitives\" trailing={<span>3</span>}>\n    <TableOfContents.Item id=\"button\">Button</TableOfContents.Item>\n    <TableOfContents.Item id=\"card\">Card</TableOfContents.Item>\n    <TableOfContents.Item id=\"input\">Input</TableOfContents.Item>\n  </TableOfContents.Group>\n  <TableOfContents.Group label=\"Custom\" defaultOpen={false}>\n    <TableOfContents.Item id=\"features\">Features</TableOfContents.Item>\n    <TableOfContents.Item id=\"plans\">Plans</TableOfContents.Item>\n  </TableOfContents.Group>\n</TableOfContents>"
     },
     {
       "name": "With Active Item",
-      "description": "Active state highlighting the current section",
+      "description": "The current section stays marked while you read.",
       "code": "<TableOfContents>\n  <TableOfContents.Item id=\"overview\">Overview</TableOfContents.Item>\n  <TableOfContents.Item id=\"setup\" active>Setup</TableOfContents.Item>\n  <TableOfContents.Item id=\"usage\" indent>Basic Usage</TableOfContents.Item>\n  <TableOfContents.Item id=\"advanced\" indent>Advanced</TableOfContents.Item>\n  <TableOfContents.Item id=\"props\">Props</TableOfContents.Item>\n  <TableOfContents.Item id=\"accessibility\">Accessibility</TableOfContents.Item>\n</TableOfContents>"
     },
     {
       "name": "Custom Title",
-      "description": "Table of contents with a custom title",
+      "description": "Any heading in place of the default.",
       "code": "<TableOfContents title=\"Contents\">\n  <TableOfContents.Item id=\"chapter-1\">Chapter 1: The Beginning</TableOfContents.Item>\n  <TableOfContents.Item id=\"chapter-2\">Chapter 2: The Middle</TableOfContents.Item>\n  <TableOfContents.Item id=\"chapter-3\">Chapter 3: The End</TableOfContents.Item>\n</TableOfContents>"
     },
     {
       "name": "No Title",
-      "description": "Table of contents without a visible title",
+      "description": "Bare list where the surrounding layout already says enough.",
       "code": "<TableOfContents hideTitle>\n  <TableOfContents.Item id=\"section-a\">Section A</TableOfContents.Item>\n  <TableOfContents.Item id=\"section-b\" active>Section B</TableOfContents.Item>\n  <TableOfContents.Item id=\"section-c\">Section C</TableOfContents.Item>\n</TableOfContents>"
     }
   ],
@@ -124,6 +136,7 @@
     "propsSummary": [
       "title: string - visible heading (default \"On This Page\")",
       "hideTitle: boolean - hide the title",
+      "hideSubItems: boolean - hide indented items and nested groups (default false)",
       "label: string - aria-label for nav landmark",
       "TableOfContents.Item id: string - heading ID to link to",
       "TableOfContents.Item active: boolean - highlight the current item with ink and weight",