@usefragments/ui 1.6.0 → 2.0.0

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

@@ -5,30 +5,82 @@
 @use "../../recipes/target" as target;
 @use "../../recipes/typography" as typography;
 
+// Fallback travel for the thumb when no size class has set the track: the md
+// track's inline size minus its block size, exactly what `switch-track` computes.
+$_switch-travel-md: calc(#{boolean.switch-inline-size("md")} - #{boolean.switch-block-size("md")});
+
 .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%,
+      var(--fui-bg-elevated, #{$fui-bg-elevated}) 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");
@@ -57,8 +109,15 @@
   }
 
   &[data-disabled] {
-    cursor: not-allowed;
-    opacity: 0.5;
+    @include disabled-state;
+  }
+
+  // The focused element is the label root, but the field ring is drawn on
+  // .track — the box a user reads as the control. Left alone the root also
+  // takes the global :focus-visible ring, so a focused Switch paints two
+  // concentric rings where every other field paints one.
+  &:focus-visible {
+    outline: none;
   }
 
   @media (pointer: coarse) {
@@ -74,36 +133,36 @@
   flex-shrink: 0;
   box-sizing: border-box;
   border-radius: var(--fui-radius-full, $fui-radius-full);
-  border: var(--fui-stroke-hairline, 1px) solid var(--_switch-off-border);
-  background-color: var(--_switch-off-bg);
+  border: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+    var(--_switch-off-border, var(--fui-border-strong, #{$fui-border-strong}));
+  background-color: var(--_switch-off-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
+  // Specular sheen: the lightest neutral surface over the track, the ink under it.
   box-shadow:
-    inset 0 1px 0 color-mix(in srgb, white 26%, transparent),
-    inset 0 -1px 0 color-mix(in srgb, var(--fui-text-primary, $fui-text-primary) 5%, transparent);
+    inset 0 var(--fui-stroke-hairline, #{$fui-stroke-hairline}) 0
+      color-mix(in srgb, var(--fui-bg-elevated, #{$fui-bg-elevated}) 26%, transparent),
+    inset 0 calc(-1 * var(--fui-stroke-hairline, #{$fui-stroke-hairline})) 0
+      color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent);
+  @include high-contrast-outline;
   transition:
     background-color var(--fui-transition-normal, $fui-transition-normal),
     border-color var(--fui-transition-normal, $fui-transition-normal),
     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})
-    );
-    box-shadow: inset 0 1px 0 color-mix(in srgb, white 24%, transparent);
+    background-color: var(--fui-control-checked-bg, $fui-color-accent);
+    border-color: var(--fui-control-checked-border, $fui-color-accent);
+    box-shadow: inset 0 var(--fui-stroke-hairline, #{$fui-stroke-hairline}) 0
+      color-mix(in srgb, var(--fui-control-checked-color, #{$fui-color-on-accent}) 24%, transparent);
   }
 
   .root:not([data-disabled]):not([data-checked]) &:hover {
-    background-color: var(--_switch-off-bg-hover);
-    border-color: var(--_switch-off-border-hover);
+    background-color: var(--_switch-off-bg-hover, var(--fui-bg-hover, #{$fui-bg-hover}));
+    border-color: var(--_switch-off-border-hover, var(--fui-border-strong, #{$fui-border-strong}));
   }
 
   .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 & {
@@ -135,17 +194,21 @@
 .thumb {
   position: absolute;
   inset-block-start: 50%;
-  inset-inline-start: var(--_fui-switch-inset);
+  inset-inline-start: var(--_fui-switch-inset, var(--fui-stroke-default, #{$fui-stroke-default}));
   box-sizing: border-box;
-  width: var(--_fui-switch-thumb-size);
-  height: var(--_fui-switch-thumb-size);
-  border-radius: 50%;
+  width: var(--_fui-switch-thumb-size, #{boolean.switch-thumb-size("md")});
+  height: var(--_fui-switch-thumb-size, #{boolean.switch-thumb-size("md")});
+  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);
+  background-color: var(--_switch-thumb-bg, var(--fui-bg-primary, #{$fui-bg-primary}));
+  border: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+    var(--_switch-thumb-border, var(--fui-border-strong, #{$fui-border-strong}));
   box-shadow:
-    0 1px 1px color-mix(in srgb, black 18%, transparent),
-    inset 0 1px 0 color-mix(in srgb, white 42%, transparent);
+    0 var(--fui-stroke-hairline, #{$fui-stroke-hairline})
+      var(--fui-stroke-hairline, #{$fui-stroke-hairline})
+      color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 18%, transparent),
+    inset 0 var(--fui-stroke-hairline, #{$fui-stroke-hairline}) 0
+      color-mix(in srgb, var(--fui-bg-elevated, #{$fui-bg-elevated}) 42%, transparent);
   transform: translateY(-50%);
   transition:
     transform var(--fui-transition-normal, $fui-transition-normal),
@@ -154,17 +217,17 @@
     box-shadow var(--fui-transition-fast, $fui-transition-fast);
 
   .root[data-checked] & {
-    transform: translate(var(--_fui-switch-travel), -50%);
-    background-color: var(--fui-button-primary-color, #fff);
+    transform: translate(var(--_fui-switch-travel, #{$_switch-travel-md}), -50%);
+    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
     );
   }
 
   .root:dir(rtl)[data-checked] & {
-    transform: translate(calc(-1 * var(--_fui-switch-travel)), -50%);
+    transform: translate(calc(-1 * var(--_fui-switch-travel, #{$_switch-travel-md})), -50%);
   }
 
   .root:active:not([data-disabled]) & {
@@ -186,22 +249,6 @@
   @include field.helper;
 }
 
-// ============================================
-// Accessibility: High Contrast Mode
-// ============================================
-
-@media (prefers-contrast: more) {
-  .track {
-    border-color: var(--fui-text-primary, $fui-text-primary);
-    outline: var(--fui-stroke-hairline, 1px) solid var(--fui-text-primary, $fui-text-primary);
-    outline-offset: calc(-1 * var(--fui-stroke-default, 2px));
-  }
-
-  .root[data-checked] .track {
-    border-color: var(--fui-button-primary-base, $fui-color-accent);
-  }
-}
-
 // ============================================
 // Accessibility: Reduced Motion
 // ============================================

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

@@ -38,6 +38,7 @@
 
   > tr {
     @include table-chrome.row;
+    @include high-contrast-outline;
   }
 }
 
@@ -50,7 +51,7 @@
 .headerContent {
   display: flex;
   align-items: center;
-  gap: var(--fui-raw-space-4);
+  gap: var(--fui-raw-space-4, 4px);
 }
 
 .row {
@@ -62,8 +63,9 @@
   );
   --fui-table-row-bg: var(--fui-table-row-base-bg);
 
-  background-color: var(--fui-table-row-bg);
+  background-color: var(--fui-table-row-bg, var(--fui-bg-primary, #{$fui-bg-primary}));
   transition: background-color var(--fui-transition-fast, $fui-transition-fast);
+  @include high-contrast-outline;
 
   &:last-child {
     border-block-end: 0;
@@ -78,6 +80,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,
@@ -85,19 +98,20 @@
   );
 
   .td:first-child {
-    box-shadow: inset var(--fui-table-divider-size) 0 0
-      var(--fui-table-row-selected-border, var(--fui-border-strong, #{$fui-border-strong}));
+    box-shadow: inset var(--fui-table-divider-size, var(--fui-stroke-hairline, #{$fui-stroke-hairline}))
+      0 0 var(--fui-table-row-selected-border, var(--fui-border-strong, #{$fui-border-strong}));
   }
 
   &:dir(rtl) .td:first-child {
-    box-shadow: inset calc(-1 * var(--fui-table-divider-size)) 0 0
+    box-shadow: inset
+      calc(-1 * var(--fui-table-divider-size, var(--fui-stroke-hairline, #{$fui-stroke-hairline}))) 0 0
       var(--fui-table-row-selected-border, var(--fui-border-strong, #{$fui-border-strong}));
   }
 }
 
 .tfoot {
-  border-block-start: var(--fui-table-divider-size) solid
-    var(--fui-table-header-border, var(--fui-border, #{$fui-border}));
+  border-block-start: var(--fui-table-divider-size, var(--fui-stroke-hairline, #{$fui-stroke-hairline}))
+    solid var(--fui-table-header-border, var(--fui-border, #{$fui-border}));
 }
 
 .striped {
@@ -112,19 +126,13 @@
 }
 
 .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);
 }
 
-@media (prefers-contrast: more) {
-  .row,
-  .thead > tr {
-    border-block-end-color: CanvasText;
-  }
-}
-
 @media (prefers-reduced-motion: reduce) {
   .row {
     transition: none;

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",