@usefragments/ui 1.7.0 → 2.0.0

package/src/components/Separator/index.tsx

@@ -8,11 +8,14 @@ import styles from "./Separator.module.scss";
 // Types
 // ============================================
 
+export type SeparatorGap = "none" | "xs" | "sm" | "md" | "lg" | "xl";
+
 export interface SeparatorProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
   /** Orientation of the separator */
   orientation?: "horizontal" | "vertical";
-  /** Spacing around the separator */
-  spacing?: "none" | "sm" | "md" | "lg";
+  /** Breathing room around the rule
+   * @default "none" */
+  gap?: SeparatorGap;
   /** Softer visual appearance */
   soft?: boolean;
   /** Optional label text (creates a labeled divider) */
@@ -20,14 +23,16 @@ export interface SeparatorProps extends Omit<React.HTMLAttributes<HTMLDivElement
 }
 
 // ============================================
-// Spacing class map
+// Gap class map
 // ============================================
 
-const spacingClasses = {
-  none: styles.spacingNone,
-  sm: styles.spacingSm,
-  md: styles.spacingMd,
-  lg: styles.spacingLg,
+const GAP_CLASS: Record<SeparatorGap, string> = {
+  none: styles.gapNone,
+  xs: styles.gapXs,
+  sm: styles.gapSm,
+  md: styles.gapMd,
+  lg: styles.gapLg,
+  xl: styles.gapXl,
 };
 
 // ============================================
@@ -37,7 +42,7 @@ const spacingClasses = {
 const SeparatorRoot = React.forwardRef<HTMLDivElement, SeparatorProps>(function Separator(
   {
     orientation = "horizontal",
-    spacing = "none",
+    gap = "none",
     soft = false,
     label,
     className,
@@ -51,7 +56,7 @@ const SeparatorRoot = React.forwardRef<HTMLDivElement, SeparatorProps>(function
     const classes = [
       styles.separator,
       styles.withLabel,
-      spacingClasses[spacing],
+      GAP_CLASS[gap],
       soft && styles.soft,
       className,
     ]
@@ -76,7 +81,7 @@ const SeparatorRoot = React.forwardRef<HTMLDivElement, SeparatorProps>(function
   const classes = [
     styles.separator,
     orientation === "horizontal" ? styles.horizontal : styles.vertical,
-    spacingClasses[spacing],
+    GAP_CLASS[gap],
     soft && styles.soft,
     className,
   ]

package/src/components/Sidebar/Sidebar.contract.json

@@ -157,7 +157,7 @@
     {
       "name": "With Provider & External Trigger",
       "description": "useSidebar drives the sidebar from anywhere, plus Cmd/Ctrl+B.",
-      "code": "function App() {\n  return (\n    <SidebarProvider>\n      <Stack direction=\"row\" gap=\"lg\" align=\"start\">\n        <Sidebar>\n          <Sidebar.Header>\n            <Logo />\n            <span>Acme App</span>\n          </Sidebar.Header>\n          <Sidebar.Nav>\n            <Sidebar.Section>\n              <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n              <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n            </Sidebar.Section>\n          </Sidebar.Nav>\n        </Sidebar>\n        <MainContent />\n      </Stack>\n    </SidebarProvider>\n  );\n}\n\nfunction MainContent() {\n  const { toggleSidebar, state } = useSidebar();\n\n  return (\n    <Stack gap=\"sm\" align=\"start\">\n      <Text size=\"sm\" color=\"secondary\">State: {state}</Text>\n      <Button size=\"sm\" variant=\"secondary\" onClick={toggleSidebar}>\n        Toggle sidebar\n      </Button>\n    </Stack>\n  );\n}"
+      "code": "function App() {\n  return (\n    <SidebarProvider>\n      <Stack direction=\"row\" gap=\"lg\" align=\"start\">\n        <Sidebar>\n          <Sidebar.Header>\n            <Logo />\n            <span>Acme App</span>\n          </Sidebar.Header>\n          <Sidebar.Nav>\n            <Sidebar.Section>\n              <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n              <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n            </Sidebar.Section>\n          </Sidebar.Nav>\n        </Sidebar>\n        <MainContent />\n      </Stack>\n    </SidebarProvider>\n  );\n}\n\nfunction MainContent() {\n  const { toggleSidebar, state } = useSidebar();\n\n  return (\n    <Stack gap=\"sm\" align=\"start\">\n      <Text scale=\"sm\" color=\"secondary\">State: {state}</Text>\n      <Button size=\"sm\" variant=\"soft\" onClick={toggleSidebar}>\n        Toggle sidebar\n      </Button>\n    </Stack>\n  );\n}"
     },
     {
       "name": "With asChild (Polymorphic)",

package/src/components/Sidebar/Sidebar.module.scss

@@ -1,20 +1,20 @@
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
 @use "../../recipes/action" as action;
 @use "../../recipes/navigation" as navigation;
+@use "../../recipes/overlay" as overlay;
 @use "../../recipes/target" as target;
 
+$_gutter: navigation.gutter();
+$_leading-box: navigation.leading-box();
+$_active-rail: navigation.active-rail();
+
 .root {
   @include navigation.properties;
 
-  --fui-sidebar-row-height: var(--fui-navigation-row-track);
-  --fui-sidebar-row-radius: var(--fui-radius-full, #{$fui-radius-full});
-  --fui-sidebar-gutter: var(--fui-navigation-gutter);
-  --fui-sidebar-row-gap: var(--fui-navigation-content-gap);
-  --fui-sidebar-row-padding-x: var(--fui-navigation-inline-inset);
-  --fui-sidebar-icon-size: var(--fui-icon-md, #{$fui-icon-md});
-  --fui-sidebar-leading-size: var(--fui-navigation-leading-box);
-  --fui-sidebar-active-dot-size: var(--fui-navigation-active-dot);
+  // Folded reads of the public `--fui-sidebar-item-*` hooks (declared in
+  // tokens/_variables.scss); every read below carries the Sass twin.
   --fui-sidebar-muted: var(
     --fui-sidebar-item-color,
     var(--fui-text-secondary, #{$fui-text-secondary})
@@ -36,7 +36,7 @@
   width: var(--sidebar-width);
   height: 100%;
   background: var(--fui-sidebar-bg, var(--fui-bg-primary, #{$fui-bg-primary}));
-  border-inline-end: var(--fui-stroke-hairline, 1px) solid
+  border-inline-end: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
     var(--fui-sidebar-border, var(--fui-border-default, #{$fui-border-default}));
   transition: width var(--fui-transition-normal, $fui-transition-normal);
   overflow: hidden;
@@ -52,7 +52,7 @@
 }
 
 .positionRight {
-  border-inline-start: var(--fui-stroke-hairline, 1px) solid
+  border-inline-start: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
     var(--fui-sidebar-border, var(--fui-border-default, #{$fui-border-default}));
   border-inline-end: 0;
 }
@@ -63,7 +63,7 @@
   .header,
   .nav,
   .footer {
-    padding: var(--fui-navigation-gutter);
+    padding: var(--fui-navigation-gutter, #{$_gutter});
   }
 
   .header,
@@ -83,12 +83,12 @@
 
   .item {
     justify-content: center;
-    padding: 0;
-    min-height: var(--fui-sidebar-row-height);
+    padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
+    min-height: var(--fui-navigation-row-track, #{navigation.row-track()});
   }
 
   .itemIcon {
-    margin: 0;
+    margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   }
   .collapseToggle {
     margin: 0 auto;
@@ -128,7 +128,7 @@
   position: fixed;
   top: 0;
   left: 0;
-  z-index: 51;
+  z-index: var(--fui-overlay-layer-modal, #{$fui-overlay-layer-modal});
   transform: translateX(-100%);
   transition: transform var(--fui-transition-normal, $fui-transition-normal);
   box-shadow: var(--fui-shadow-md, $fui-shadow-md);
@@ -147,8 +147,7 @@
 .header {
   display: flex;
   align-items: center;
-  gap: 0;
-  padding: var(--fui-sidebar-gutter) var(--fui-sidebar-gutter) 0;
+  padding: var(--fui-navigation-gutter, #{$_gutter}) var(--fui-navigation-gutter, #{$_gutter}) 0;
   flex-shrink: 0;
   min-height: 0;
 }
@@ -159,7 +158,8 @@
   display: flex;
   flex-direction: column;
   overflow: hidden;
-  padding: var(--fui-sidebar-gutter) var(--fui-sidebar-gutter) var(--fui-space-3, $fui-space-3);
+  padding: var(--fui-navigation-gutter, #{$_gutter}) var(--fui-navigation-gutter, #{$_gutter})
+    var(--fui-space-3, $fui-space-3);
 }
 
 .navScrollArea {
@@ -168,9 +168,7 @@
 }
 
 .section:not(:first-child) {
-  // Consumers with sparse, reading-oriented navigation (docs sites) can open
-  // this up via --fui-sidebar-section-gap without touching the raw scale.
-  margin-top: var(--fui-sidebar-section-gap, var(--fui-raw-space-16, 16px));
+  margin-top: var(--fui-raw-space-16, #{measurements.raw-space(16)});
 }
 
 .sectionHeader {
@@ -178,28 +176,31 @@
 
   display: flex;
   align-items: center;
-  padding-block-end: var(--fui-raw-space-4, 4px);
+  // Items carry a hairline border inside the same inset; the header mirrors
+  // it so the group label and the item glyphs below share one left edge.
+  padding-inline: calc(
+    var(--fui-navigation-inline-inset, #{$_gutter}) +
+      var(--fui-stroke-hairline, #{$fui-stroke-hairline})
+  );
+  padding-block-end: var(--fui-raw-space-4, #{measurements.raw-space(4)});
 }
 
 .sectionTrigger {
   flex: 1;
 }
 
-// Override section-label-text inheritance — sidebar groups read as quiet
-// title-case headings, not shouty all-caps labels.
-// Section labels read as small tracked eyebrows — a clearly different voice
-// from the nav items beneath them, so groups can't be mistaken for links.
+// A group name is not a row: it is heavier and fainter than the items
+// beneath it, sits on a shorter track with no hover surface, carries no
+// glyph, and keeps its natural case.
 .sectionLabel {
   flex: 1;
   min-width: 0;
-  font-size: var(--fui-sidebar-section-label-size, var(--fui-font-size-2xs, #{$fui-font-size-2xs}));
-  letter-spacing: var(--fui-sidebar-section-label-tracking, 0.07em);
-  text-transform: var(--fui-sidebar-section-label-transform, uppercase);
-  color: var(--fui-sidebar-section-label-color, var(--fui-sidebar-faint));
-  font-weight: var(
-    --fui-sidebar-section-label-weight,
-    var(--fui-font-weight-medium, #{$fui-font-weight-medium})
-  );
+  font-size: var(--fui-sidebar-section-label-size, #{$fui-font-size-xs});
+  font-weight: var(--fui-font-weight-semibold, #{$fui-font-weight-semibold});
+  color: var(--fui-sidebar-faint, #{$fui-text-tertiary});
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
 
 .sectionActionWrapper {
@@ -213,11 +214,11 @@
   @include action.icon-only("micro");
   @include target.hit-area("compact");
 
-  border-radius: var(--fui-sidebar-row-radius);
-  color: var(--fui-sidebar-faint);
+  border-radius: var(--fui-radius-full, #{$fui-radius-full});
+  color: var(--fui-sidebar-faint, #{$fui-text-tertiary});
 
   &:hover {
-    background-color: var(--fui-sidebar-hover-bg);
+    background-color: var(--fui-sidebar-hover-bg, #{$fui-bg-hover});
     color: var(--fui-text-secondary, $fui-text-secondary);
   }
 
@@ -229,11 +230,11 @@
 .sectionList,
 .submenu {
   list-style: none;
-  margin: 0;
-  padding: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
+  padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   display: flex;
   flex-direction: column;
-  gap: var(--fui-sidebar-item-gap, var(--fui-raw-space-2, 2px));
+  gap: var(--fui-raw-space-2, #{measurements.raw-space(2)});
 }
 
 .sectionCollapsible .sectionTrigger {
@@ -243,8 +244,8 @@
   align-items: center;
   justify-content: flex-start;
   width: 100%;
-  padding: 0;
-  border-radius: var(--fui-sidebar-row-radius);
+  padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
+  border-radius: var(--fui-radius-full, #{$fui-radius-full});
   background: transparent;
 
   &:hover {
@@ -261,9 +262,9 @@
 
   // Trailing caret reads as a quiet disclosure twistie.
   svg {
-    width: var(--fui-raw-space-10, 10px);
-    height: var(--fui-raw-space-10, 10px);
-    color: var(--fui-sidebar-faint);
+    width: var(--fui-raw-space-10, #{measurements.raw-space(10)});
+    height: var(--fui-raw-space-10, #{measurements.raw-space(10)});
+    color: var(--fui-sidebar-faint, #{$fui-text-tertiary});
   }
 }
 
@@ -286,27 +287,25 @@
   display: flex;
   align-items: center;
   width: 100%;
-  font-size: var(--fui-sidebar-item-font-size, var(--fui-type-ui-compact-size, 12px));
-  line-height: var(--fui-sidebar-item-line-height, var(--fui-type-ui-compact-line, 16px));
-  border: var(--fui-stroke-hairline, 1px) solid transparent;
-  border-radius: var(--fui-sidebar-row-radius);
-  color: var(--fui-sidebar-muted);
+  border: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid transparent;
+  border-radius: var(--fui-sidebar-item-radius, #{$fui-radius-full});
+  color: var(--fui-sidebar-muted, #{$fui-text-secondary});
   text-decoration: none;
   font-weight: var(--fui-font-weight-normal, $fui-font-weight-normal);
-  outline-offset: calc(-1 * var(--fui-stroke-hairline, 1px));
+  outline-offset: calc(-1 * var(--fui-stroke-hairline, #{$fui-stroke-hairline}));
   transition:
     background-color var(--fui-transition-fast, $fui-transition-fast),
     border-color var(--fui-transition-fast, $fui-transition-fast),
     color var(--fui-transition-fast, $fui-transition-fast);
 
   &:hover:not(.itemDisabled) {
-    background-color: var(--fui-sidebar-hover-bg);
+    background-color: var(--fui-sidebar-hover-bg, #{$fui-bg-hover});
     color: var(--fui-sidebar-item-hover-color, var(--fui-text-primary, #{$fui-text-primary}));
     text-decoration: none;
   }
 
   &:active:not(.itemDisabled) {
-    background-color: var(--fui-sidebar-active-bg);
+    background-color: var(--fui-sidebar-active-bg, #{$fui-bg-active});
   }
 }
 
@@ -315,14 +314,14 @@
 .itemActive {
   @include navigation.active-indicator("start");
 
-  background-color: var(--fui-sidebar-active-bg);
-  border-color: var(--fui-sidebar-active-border);
+  background-color: var(--fui-sidebar-active-bg, #{$fui-bg-active});
+  border-color: var(--fui-sidebar-active-border, transparent);
   color: var(--fui-sidebar-item-active-color, var(--fui-text-primary, #{$fui-text-primary}));
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
 
   &::before {
-    border-start-end-radius: var(--fui-navigation-active-rail);
-    border-end-end-radius: var(--fui-navigation-active-rail);
+    border-start-end-radius: var(--fui-navigation-active-rail, #{$_active-rail});
+    border-end-end-radius: var(--fui-navigation-active-rail, #{$_active-rail});
     background: var(
       --fui-sidebar-item-active-indicator,
       var(--fui-color-accent, #{$fui-color-accent})
@@ -331,8 +330,8 @@
 
   &.item:hover,
   &.item:active {
-    background-color: var(--fui-sidebar-active-bg);
-    border-color: var(--fui-sidebar-active-border);
+    background-color: var(--fui-sidebar-active-bg, #{$fui-bg-active});
+    border-color: var(--fui-sidebar-active-border, transparent);
     color: var(--fui-sidebar-item-active-color, var(--fui-text-primary, #{$fui-text-primary}));
     text-decoration: none;
   }
@@ -348,7 +347,8 @@
   @include navigation.active-indicator("end");
 
   padding-inline-end: calc(
-    var(--fui-navigation-inline-inset) * 2 + var(--fui-navigation-active-dot)
+    var(--fui-navigation-inline-inset, #{$_gutter}) * 2 +
+      var(--fui-navigation-active-dot, #{navigation.active-dot()})
   );
 
   &::before {
@@ -365,8 +365,7 @@
 
 .itemDisabled,
 .subItemDisabled {
-  opacity: 0.46;
-  cursor: not-allowed;
+  @include disabled-state;
 }
 
 .itemIcon {
@@ -375,15 +374,15 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  color: var(--fui-sidebar-faint);
+  color: var(--fui-sidebar-faint, #{$fui-text-tertiary});
 
   svg {
-    width: var(--fui-sidebar-leading-size);
-    height: var(--fui-sidebar-leading-size);
+    width: var(--fui-navigation-leading-box, #{$_leading-box});
+    height: var(--fui-navigation-leading-box, #{$_leading-box});
   }
 
   .item:hover:not(.itemDisabled) & {
-    color: var(--fui-sidebar-muted);
+    color: var(--fui-sidebar-muted, #{$fui-text-secondary});
   }
 
   .itemActive & {
@@ -397,7 +396,7 @@
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
-  transform: translateY(var(--fui-navigation-label-optical-y));
+  transform: translateY(var(--fui-navigation-label-optical-y, #{navigation.label-optical-y()}));
 }
 
 // A row whose label is a block rather than a link: a title over a status line,
@@ -422,14 +421,14 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  width: var(--fui-sidebar-icon-size);
-  height: var(--fui-sidebar-icon-size);
+  width: var(--fui-icon-md, #{$fui-icon-md});
+  height: var(--fui-icon-md, #{$fui-icon-md});
   flex-shrink: 0;
   transition: transform var(--fui-transition-fast, $fui-transition-fast);
 
   svg {
-    width: var(--fui-sidebar-icon-size);
-    height: var(--fui-sidebar-icon-size);
+    width: var(--fui-icon-md, #{$fui-icon-md});
+    height: var(--fui-icon-md, #{$fui-icon-md});
   }
 }
 
@@ -438,7 +437,7 @@
 }
 
 .submenu {
-  padding-inline-start: var(--fui-raw-space-24, 24px);
+  padding-inline-start: var(--fui-raw-space-24, #{measurements.raw-space(24)});
   min-height: 0;
   overflow: hidden;
 }
@@ -460,8 +459,8 @@
 
   display: inline-flex;
   align-items: center;
-  border-radius: var(--fui-sidebar-row-radius);
-  color: var(--fui-sidebar-muted);
+  border-radius: var(--fui-sidebar-item-radius, #{$fui-radius-full});
+  color: var(--fui-sidebar-muted, #{$fui-text-secondary});
   text-decoration: none;
   position: relative;
 
@@ -471,21 +470,21 @@
     inset-inline-start: 0;
     top: 50%;
     transform: translateY(-50%);
-    width: var(--fui-navigation-active-rail);
-    height: var(--fui-navigation-leading-box);
+    width: var(--fui-navigation-active-rail, #{$_active-rail});
+    height: var(--fui-navigation-leading-box, #{$_leading-box});
     background-color: transparent;
     border-radius: var(--fui-radius-full, $fui-radius-full);
     transition: background-color var(--fui-transition-fast, $fui-transition-fast);
   }
 
   &:hover:not(.subItemDisabled) {
-    background-color: var(--fui-sidebar-hover-bg);
+    background-color: var(--fui-sidebar-hover-bg, #{$fui-bg-hover});
     color: var(--fui-sidebar-item-hover-color, var(--fui-text-primary, #{$fui-text-primary}));
     text-decoration: none;
   }
 
   &:active:not(.subItemDisabled) {
-    background-color: var(--fui-sidebar-active-bg);
+    background-color: var(--fui-sidebar-active-bg, #{$fui-bg-active});
   }
 }
 
@@ -504,11 +503,11 @@
 .footer {
   display: flex;
   flex-direction: column;
-  gap: var(--fui-sidebar-row-gap);
-  padding: var(--fui-sidebar-gutter);
+  gap: var(--fui-navigation-content-gap, #{$_gutter});
+  padding: var(--fui-navigation-gutter, #{$_gutter});
   margin-top: auto;
   flex-shrink: 0;
-  border-top: var(--fui-stroke-hairline, 1px) solid
+  border-top: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
     var(
       --fui-sidebar-footer-border,
       color-mix(in srgb, var(--fui-border-default, #{$fui-border-default}) 58%, transparent)
@@ -537,10 +536,8 @@
 }
 
 .overlay {
-  position: fixed;
-  inset: 0;
-  z-index: 50;
-  background-color: var(--fui-backdrop, $fui-backdrop);
+  @include overlay.backdrop;
+
   opacity: 0;
   transition: opacity var(--fui-transition-normal, $fui-transition-normal);
 
@@ -576,10 +573,10 @@
   position: absolute;
   top: var(--fui-space-3, $fui-space-3);
   left: calc(100% + var(--fui-space-2, $fui-space-2));
-  z-index: 20;
-  margin: 0;
+  z-index: 2;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   background-color: var(--fui-bg-primary, $fui-bg-primary);
-  border: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
+  border: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid var(--fui-border, $fui-border);
   box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
 
   .positionRight & {
@@ -594,9 +591,9 @@
   position: absolute;
   top: 0;
   right: 0;
-  width: var(--fui-navigation-leading-box);
+  width: var(--fui-navigation-leading-box, #{$_leading-box});
   height: 100%;
-  z-index: 10;
+  z-index: 1;
 
   .positionRight & {
     right: auto;
@@ -608,8 +605,8 @@
     position: absolute;
     top: 50%;
     transform: translateY(-50%);
-    right: var(--fui-raw-space-4, 4px);
-    width: var(--fui-raw-space-4, 4px);
+    right: var(--fui-raw-space-4, #{measurements.raw-space(4)});
+    width: var(--fui-raw-space-4, #{measurements.raw-space(4)});
     height: #{action.track("lg")};
     border-radius: var(--fui-radius-full, $fui-radius-full);
     background-color: var(--fui-border, $fui-border);
@@ -621,7 +618,7 @@
 
     .positionRight & {
       right: auto;
-      left: var(--fui-raw-space-4, 4px);
+      left: var(--fui-raw-space-4, #{measurements.raw-space(4)});
     }
   }
 
@@ -632,12 +629,12 @@
   }
 
   &:hover::before {
-    height: var(--fui-navigation-sidebar-collapsed-width, 56px);
+    height: #{navigation.collapsed-width()};
   }
 }
 
 .railCollapsed::before {
-  opacity: 0.7;
+  opacity: var(--fui-opacity-muted, #{$fui-opacity-muted});
 }
 
 .menuSkeleton {

package/src/components/Sidebar/index.tsx

@@ -35,7 +35,7 @@ function renderSidebarBadge(badge: React.ReactNode) {
   }
 
   return (
-    <Badge variant="default" size="sm">
+    <Badge tone="neutral" size="sm">
       {badge}
     </Badge>
   );
@@ -1122,10 +1122,10 @@ function SidebarMenuSkeleton({
     <div {...htmlProps} className={classes} aria-hidden="true">
       {Array.from({ length: count }).map((_, i) => (
         <div key={i} className={styles.skeletonItem}>
-          {showIcon && <Skeleton variant="avatar" size="sm" />}
+          {showIcon && <Skeleton shape="avatar" size="sm" />}
           {!isCollapsed && (
             <Skeleton
-              variant="text"
+              shape="text"
               className={styles.skeletonLabel}
               width={labelWidths[i % labelWidths.length]}
             />

package/src/components/Skeleton/Skeleton.contract.json

@@ -8,7 +8,7 @@
   "sourcePath": "src/components/Skeleton/index.tsx",
   "exportName": "Skeleton",
   "propsSummary": [
-    "variant: text|heading|avatar|button|input|rect (default: rect)",
+    "shape: text|heading|avatar|button|input|rect (default: rect)",
     "size: sm|md|lg (default: md)",
     "width: union",
     "height: union",
@@ -17,16 +17,16 @@
     "static: boolean (default: false)"
   ],
   "props": {
-    "variant": {
+    "shape": {
       "type": "enum",
-      "description": "Semantic variant that auto-sizes",
+      "description": "Semantic shape that auto-sizes",
       "default": "rect",
       "required": false,
       "values": ["text", "heading", "avatar", "button", "input", "rect"]
     },
     "size": {
       "type": "enum",
-      "description": "Size for avatar/button variants",
+      "description": "Size for avatar/button shapes",
       "default": "md",
       "required": false,
       "values": ["sm", "md", "lg"]
@@ -73,7 +73,7 @@
     ],
     "guidelines": [
       "Match the shape and size of the real content",
-      "Prefer the text, heading, and avatar variants over hand-rolled boxes",
+      "Prefer the text, heading, and avatar shapes over hand-rolled boxes",
       "Give Skeleton.Text an ancestor with a real width — percentage lines collapse without one",
       "A few big shapes beat many small ones",
       "Skeleton and Skeleton.Text forward id, aria-*, data-* and handlers"
@@ -96,9 +96,9 @@
       "code": "<div style={{ width: 260 }}>\n  <Skeleton.Text lines={3} />\n</div>"
     },
     {
-      "name": "Semantic Variants",
+      "name": "Semantic Shapes",
       "description": "Heading sits taller than the body lines under it.",
-      "code": "<div\n  style={{\n    width: 260,\n    display: 'flex',\n    flexDirection: 'column',\n    gap: 'var(--fui-space-2)',\n  }}\n>\n  <Skeleton variant=\"heading\" width={200} />\n  <Skeleton variant=\"text\" width=\"100%\" />\n  <Skeleton variant=\"text\" width=\"80%\" />\n</div>"
+      "code": "<div\n  style={{\n    width: 260,\n    display: 'flex',\n    flexDirection: 'column',\n    gap: 'var(--fui-space-2)',\n  }}\n>\n  <Skeleton shape=\"heading\" width={200} />\n  <Skeleton shape=\"text\" width=\"100%\" />\n  <Skeleton shape=\"text\" width=\"80%\" />\n</div>"
     },
     {
       "name": "Avatar Skeleton",
@@ -108,7 +108,7 @@
     {
       "name": "Card Skeleton",
       "description": "Media, title, then body — the card before it loads.",
-      "code": "<div\n  style={{\n    width: 300,\n    padding: 'var(--fui-space-2)',\n    border: '1px solid var(--fui-border)',\n    borderRadius: 'var(--fui-radius-lg)',\n  }}\n>\n  <Skeleton variant=\"rect\" height={120} radius=\"md\" />\n  <div style={{ marginTop: 'var(--fui-space-2)' }}>\n    <Skeleton variant=\"heading\" width=\"60%\" />\n  </div>\n  <div style={{ marginTop: 'var(--fui-space-1)' }}>\n    <Skeleton.Text lines={2} />\n  </div>\n</div>"
+      "code": "<div\n  style={{\n    width: 300,\n    padding: 'var(--fui-space-2)',\n    border: '1px solid var(--fui-border)',\n    borderRadius: 'var(--fui-radius-lg)',\n  }}\n>\n  <Skeleton shape=\"rect\" height={120} radius=\"md\" />\n  <div style={{ marginTop: 'var(--fui-space-2)' }}>\n    <Skeleton shape=\"heading\" width=\"60%\" />\n  </div>\n  <div style={{ marginTop: 'var(--fui-space-1)' }}>\n    <Skeleton.Text lines={2} />\n  </div>\n</div>"
     }
   ],
   "relations": [
@@ -120,7 +120,7 @@
   ],
   "contract": {
     "propsSummary": [
-      "variant: text|heading|avatar|button|input|rect",
+      "shape: text|heading|avatar|button|input|rect",
       "size: sm|md|lg (for avatar/button)",
       "width/height: custom dimensions",
       "fill: boolean - fill parent",