@usefragments/ui 1.7.0 → 2.0.0

package/src/components/Field/Field.module.scss

@@ -1,3 +1,4 @@
+@use "../../tokens/variables" as *;
 @use "../../recipes/field";
 
 .root {
@@ -8,7 +9,7 @@
   @include field.label;
 
   &[data-disabled] {
-    opacity: 0.5;
+    opacity: var(--fui-opacity-disabled, #{$fui-opacity-disabled});
   }
 }
 

package/src/components/Fieldset/Fieldset.module.scss

@@ -1,5 +1,6 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../recipes/typography";
 
 .root {
@@ -7,12 +8,12 @@
 
   display: flex;
   flex-direction: column;
-  gap: 0;
+  gap: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   padding: var(--fui-surface-inset-default, 16px);
-  margin: 0;
+  margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 
   &[data-disabled] {
-    opacity: 0.5;
+    opacity: var(--fui-opacity-disabled, #{$fui-opacity-disabled});
   }
 
   // Legend and description carry their own block margins, so spacing is added
@@ -27,7 +28,7 @@
   @include typography.role("ui-standard");
 
   color: var(--fui-text-secondary, $fui-text-secondary);
-  padding: 0;
+  padding: var(--fui-raw-space-0, #{measurements.raw-space(0)});
   margin-block-end: var(--fui-raw-space-16, 16px);
 
   &:has(+ .description) {

package/src/components/Form/Form.contract.json

@@ -75,22 +75,22 @@
     {
       "name": "Sign up",
       "description": "Paired name fields, then full-width rows and a right-aligned submit.",
-      "code": "<Form onSubmit={(e) => { e.preventDefault(); }}>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"firstName\">\n      <Field.Label>First Name</Field.Label>\n      <Field.Control>\n        <Input placeholder=\"Jane\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"lastName\">\n      <Field.Label>Last Name</Field.Label>\n      <Field.Control>\n        <Input placeholder=\"Doe\" />\n      </Field.Control>\n    </Field>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"email\">\n        <Field.Label>Email</Field.Label>\n        <Field.Control>\n          <Input type=\"email\" placeholder=\"jane@example.com\" />\n        </Field.Control>\n        <Field.Error match=\"typeMismatch\">Enter a valid email address</Field.Error>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"password\">\n        <Field.Label>Password</Field.Label>\n        <Field.Control>\n          <Input type=\"password\" placeholder=\"At least 8 characters\" />\n        </Field.Control>\n        <Field.Description>Must be at least 8 characters</Field.Description>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"terms\">\n        <Field.Control>\n          <Checkbox label=\"I agree to the terms and conditions\" />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n  </Grid>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Create Account</Button>\n  </Form.Actions>\n</Form>"
+      "code": "<Form onSubmit={(e) => { e.preventDefault(); }}>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"firstName\">\n      <Field.Label>First Name</Field.Label>\n      <Field.Control>\n        <Input placeholder=\"Jane\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"lastName\">\n      <Field.Label>Last Name</Field.Label>\n      <Field.Control>\n        <Input placeholder=\"Doe\" />\n      </Field.Control>\n    </Field>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"email\">\n        <Field.Label>Email</Field.Label>\n        <Field.Control>\n          <Input type=\"email\" placeholder=\"jane@example.com\" />\n        </Field.Control>\n        <Field.Error match=\"typeMismatch\">Enter a valid email address</Field.Error>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"password\">\n        <Field.Label>Password</Field.Label>\n        <Field.Control>\n          <Input type=\"password\" placeholder=\"At least 8 characters\" />\n        </Field.Control>\n        <Field.Description>Must be at least 8 characters</Field.Description>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"terms\">\n        <Field.Control>\n          <Checkbox label=\"I agree to the terms and conditions\" />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n  </Grid>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"solid\">Create Account</Button>\n  </Form.Actions>\n</Form>"
     },
     {
       "name": "Profile settings",
       "description": "Fieldsets split a long form into sections the user can scan.",
-      "code": "<Form onSubmit={(e) => { e.preventDefault(); }}>\n  <Fieldset>\n    <Fieldset.Legend>Profile</Fieldset.Legend>\n    <Grid columns={2} gap=\"md\">\n      <Field name=\"displayName\">\n        <Field.Label>Display Name</Field.Label>\n        <Field.Control>\n          <Input placeholder=\"How others see you\" />\n        </Field.Control>\n      </Field>\n      <Field name=\"timezone\">\n        <Field.Label>Timezone</Field.Label>\n        <Field.Control>\n          <Select placeholder=\"Select timezone\">\n            <Select.Trigger />\n            <Select.Content>\n              <Select.Item value=\"utc\">UTC</Select.Item>\n              <Select.Item value=\"est\">Eastern (EST)</Select.Item>\n              <Select.Item value=\"pst\">Pacific (PST)</Select.Item>\n              <Select.Item value=\"gmt\">GMT</Select.Item>\n            </Select.Content>\n          </Select>\n        </Field.Control>\n      </Field>\n      <Grid.Item colSpan=\"full\">\n        <Field name=\"bio\">\n          <Field.Label>Bio</Field.Label>\n          <Field.Control>\n            <Textarea placeholder=\"Tell us about yourself\" rows={3} maxLength={280} />\n          </Field.Control>\n          <Field.Description>Max 280 characters</Field.Description>\n        </Field>\n      </Grid.Item>\n    </Grid>\n  </Fieldset>\n  <Fieldset>\n    <Fieldset.Legend>Notifications</Fieldset.Legend>\n    <Field name=\"emailNotifs\">\n      <Field.Control>\n        <Switch label=\"Email notifications\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"marketingEmails\">\n      <Field.Control>\n        <Switch label=\"Marketing emails\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"frequency\">\n      <Field.Label>Digest frequency</Field.Label>\n      <Field.Control>\n        <RadioGroup name=\"frequency\" orientation=\"vertical\">\n          <RadioGroup.Item value=\"daily\" label=\"Daily\" />\n          <RadioGroup.Item value=\"weekly\" label=\"Weekly\" />\n          <RadioGroup.Item value=\"monthly\" label=\"Monthly\" />\n        </RadioGroup>\n      </Field.Control>\n    </Field>\n  </Fieldset>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Save Changes</Button>\n  </Form.Actions>\n</Form>"
+      "code": "<Form onSubmit={(e) => { e.preventDefault(); }}>\n  <Fieldset>\n    <Fieldset.Legend>Profile</Fieldset.Legend>\n    <Grid columns={2} gap=\"md\">\n      <Field name=\"displayName\">\n        <Field.Label>Display Name</Field.Label>\n        <Field.Control>\n          <Input placeholder=\"How others see you\" />\n        </Field.Control>\n      </Field>\n      <Field name=\"timezone\">\n        <Field.Label>Timezone</Field.Label>\n        <Field.Control>\n          <Select placeholder=\"Select timezone\">\n            <Select.Trigger />\n            <Select.Content>\n              <Select.Item value=\"utc\">UTC</Select.Item>\n              <Select.Item value=\"est\">Eastern (EST)</Select.Item>\n              <Select.Item value=\"pst\">Pacific (PST)</Select.Item>\n              <Select.Item value=\"gmt\">GMT</Select.Item>\n            </Select.Content>\n          </Select>\n        </Field.Control>\n      </Field>\n      <Grid.Item colSpan=\"full\">\n        <Field name=\"bio\">\n          <Field.Label>Bio</Field.Label>\n          <Field.Control>\n            <Textarea placeholder=\"Tell us about yourself\" rows={3} maxLength={280} />\n          </Field.Control>\n          <Field.Description>Max 280 characters</Field.Description>\n        </Field>\n      </Grid.Item>\n    </Grid>\n  </Fieldset>\n  <Fieldset>\n    <Fieldset.Legend>Notifications</Fieldset.Legend>\n    <Field name=\"emailNotifs\">\n      <Field.Control>\n        <Switch label=\"Email notifications\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"marketingEmails\">\n      <Field.Control>\n        <Switch label=\"Marketing emails\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"frequency\">\n      <Field.Label>Digest frequency</Field.Label>\n      <Field.Control>\n        <RadioGroup name=\"frequency\" orientation=\"vertical\">\n          <RadioGroup.Item value=\"daily\" label=\"Daily\" />\n          <RadioGroup.Item value=\"weekly\" label=\"Weekly\" />\n          <RadioGroup.Item value=\"monthly\" label=\"Monthly\" />\n        </RadioGroup>\n      </Field.Control>\n    </Field>\n  </Fieldset>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"solid\">Save Changes</Button>\n  </Form.Actions>\n</Form>"
     },
     {
       "name": "Contact form",
       "description": "Mixed control types in one submission flow.",
-      "code": "<Form onSubmit={(e) => { e.preventDefault(); }}>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"name\">\n      <Field.Label>Name</Field.Label>\n      <Field.Control>\n        <Input placeholder=\"Your name\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"email\">\n      <Field.Label>Email</Field.Label>\n      <Field.Control>\n        <Input type=\"email\" placeholder=\"you@example.com\" />\n      </Field.Control>\n    </Field>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"subject\">\n        <Field.Label>Subject</Field.Label>\n        <Field.Control>\n          <Select placeholder=\"What is this about?\">\n            <Select.Trigger />\n            <Select.Content>\n              <Select.Item value=\"general\">General Inquiry</Select.Item>\n              <Select.Item value=\"support\">Technical Support</Select.Item>\n              <Select.Item value=\"billing\">Billing</Select.Item>\n              <Select.Item value=\"feedback\">Feedback</Select.Item>\n            </Select.Content>\n          </Select>\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"message\">\n        <Field.Label>Message</Field.Label>\n        <Field.Control>\n          <Textarea placeholder=\"How can we help?\" rows={5} />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"copy\">\n        <Field.Control>\n          <Checkbox label=\"Send me a copy\" />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n  </Grid>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Send Message</Button>\n  </Form.Actions>\n</Form>"
+      "code": "<Form onSubmit={(e) => { e.preventDefault(); }}>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"name\">\n      <Field.Label>Name</Field.Label>\n      <Field.Control>\n        <Input placeholder=\"Your name\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"email\">\n      <Field.Label>Email</Field.Label>\n      <Field.Control>\n        <Input type=\"email\" placeholder=\"you@example.com\" />\n      </Field.Control>\n    </Field>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"subject\">\n        <Field.Label>Subject</Field.Label>\n        <Field.Control>\n          <Select placeholder=\"What is this about?\">\n            <Select.Trigger />\n            <Select.Content>\n              <Select.Item value=\"general\">General Inquiry</Select.Item>\n              <Select.Item value=\"support\">Technical Support</Select.Item>\n              <Select.Item value=\"billing\">Billing</Select.Item>\n              <Select.Item value=\"feedback\">Feedback</Select.Item>\n            </Select.Content>\n          </Select>\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"message\">\n        <Field.Label>Message</Field.Label>\n        <Field.Control>\n          <Textarea placeholder=\"How can we help?\" rows={5} />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"copy\">\n        <Field.Control>\n          <Checkbox label=\"Send me a copy\" />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n  </Grid>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"solid\">Send Message</Button>\n  </Form.Actions>\n</Form>"
     },
     {
       "name": "With server errors",
       "description": "Errors from the server land on the fields that caused them.",
-      "code": "<Form errors={{ username: 'Username is already taken', email: 'Email is already registered' }}>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"username\">\n      <Field.Label>Username</Field.Label>\n      <Field.Control>\n        <Input defaultValue=\"janedoe\" />\n      </Field.Control>\n      <Field.Error />\n    </Field>\n    <Field name=\"email\">\n      <Field.Label>Email</Field.Label>\n      <Field.Control>\n        <Input type=\"email\" defaultValue=\"jane@example.com\" />\n      </Field.Control>\n      <Field.Error />\n    </Field>\n  </Grid>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Submit</Button>\n  </Form.Actions>\n</Form>"
+      "code": "<Form errors={{ username: 'Username is already taken', email: 'Email is already registered' }}>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"username\">\n      <Field.Label>Username</Field.Label>\n      <Field.Control>\n        <Input defaultValue=\"janedoe\" />\n      </Field.Control>\n      <Field.Error />\n    </Field>\n    <Field name=\"email\">\n      <Field.Label>Email</Field.Label>\n      <Field.Control>\n        <Input type=\"email\" defaultValue=\"jane@example.com\" />\n      </Field.Control>\n      <Field.Error />\n    </Field>\n  </Grid>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"solid\">Submit</Button>\n  </Form.Actions>\n</Form>"
     }
   ],
   "relations": [

package/src/components/Grid/Grid.module.scss

@@ -8,7 +8,7 @@
 .grid {
   display: grid;
   width: 100%;
-  gap: var(--_fui-grid-gap, #{layout.gap("md")});
+  gap: layout.gap("md");
 }
 
 // ============================================
@@ -75,7 +75,7 @@
 .columnsResponsive {
   --_cols: var(--fui-grid-cols, 1);
 
-  grid-template-columns: repeat(var(--_cols), 1fr);
+  grid-template-columns: repeat(var(--_cols, var(--fui-grid-cols, 1)), 1fr);
 
   @include breakpoint-sm {
     --_cols: var(--fui-grid-cols-sm, var(--fui-grid-cols, 1));

package/src/components/Header/Header.contract.json

@@ -98,7 +98,7 @@
     {
       "name": "For Default Layout",
       "description": "Brand, nav, and actions for AppShell layout=\"default\".",
-      "code": "import { Box } from '@/components/Box';\nimport { Button } from '@/components/Button';\nimport { Header } from '@/components/Header';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header>\n    <Header.SkipLink />\n    <Header.Trigger />\n    <Header.Brand href=\"/\">MyApp</Header.Brand>\n    <Header.Nav>\n      <Header.NavItem href=\"/dashboard\" active>Dashboard</Header.NavItem>\n      <Header.NavItem href=\"/projects\">Projects</Header.NavItem>\n      <Header.NavItem href=\"/settings\">Settings</Header.NavItem>\n    </Header.Nav>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n      <Button variant=\"secondary\" size=\"sm\">Sign In</Button>\n    </Header.Actions>\n  </Header>\n</Box>"
+      "code": "import { Box } from '@/components/Box';\nimport { Button } from '@/components/Button';\nimport { Header } from '@/components/Header';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header>\n    <Header.SkipLink />\n    <Header.Trigger />\n    <Header.Brand href=\"/\">MyApp</Header.Brand>\n    <Header.Nav>\n      <Header.NavItem href=\"/dashboard\" active>Dashboard</Header.NavItem>\n      <Header.NavItem href=\"/projects\">Projects</Header.NavItem>\n      <Header.NavItem href=\"/settings\">Settings</Header.NavItem>\n    </Header.Nav>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n      <Button variant=\"soft\" size=\"sm\">Sign In</Button>\n    </Header.Actions>\n  </Header>\n</Box>"
     },
     {
       "name": "Marketing Header",
@@ -128,7 +128,7 @@
     {
       "name": "With NavigationMenu",
       "description": "Rich dropdown panels with titles and descriptions.",
-      "code": "import { Box } from '@/components/Box';\nimport { Button } from '@/components/Button';\nimport { Header } from '@/components/Header';\nimport { NavigationMenu } from '@/components/NavigationMenu';\nimport { Stack } from '@/components/Stack';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header>\n    <Header.Brand href=\"/\">MyApp</Header.Brand>\n    <Header.Nav>\n      <NavigationMenu aria-label=\"Site navigation\">\n        <NavigationMenu.List>\n          <NavigationMenu.Item value=\"products\">\n            <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>\n            <NavigationMenu.Content>\n              <Box padding=\"xs\" style={{ minWidth: '200px' }}>\n                <Stack gap=\"none\">\n                  <NavigationMenu.Link href=\"/analytics\" title=\"Analytics\" description=\"Track your metrics.\" />\n                  <NavigationMenu.Link href=\"/automation\" title=\"Automation\" description=\"Automate workflows.\" />\n                </Stack>\n              </Box>\n            </NavigationMenu.Content>\n          </NavigationMenu.Item>\n          <NavigationMenu.Item>\n            <NavigationMenu.Link href=\"/pricing\">Pricing</NavigationMenu.Link>\n          </NavigationMenu.Item>\n        </NavigationMenu.List>\n        <NavigationMenu.Viewport />\n      </NavigationMenu>\n    </Header.Nav>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n      <Button variant=\"primary\" size=\"sm\">Sign Up</Button>\n    </Header.Actions>\n  </Header>\n</Box>"
+      "code": "import { Box } from '@/components/Box';\nimport { Button } from '@/components/Button';\nimport { Header } from '@/components/Header';\nimport { NavigationMenu } from '@/components/NavigationMenu';\nimport { Stack } from '@/components/Stack';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header>\n    <Header.Brand href=\"/\">MyApp</Header.Brand>\n    <Header.Nav>\n      <NavigationMenu aria-label=\"Site navigation\">\n        <NavigationMenu.List>\n          <NavigationMenu.Item value=\"products\">\n            <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>\n            <NavigationMenu.Content>\n              <Box padding=\"xs\" style={{ minWidth: '200px' }}>\n                <Stack gap=\"none\">\n                  <NavigationMenu.Link href=\"/analytics\" title=\"Analytics\" description=\"Track your metrics.\" />\n                  <NavigationMenu.Link href=\"/automation\" title=\"Automation\" description=\"Automate workflows.\" />\n                </Stack>\n              </Box>\n            </NavigationMenu.Content>\n          </NavigationMenu.Item>\n          <NavigationMenu.Item>\n            <NavigationMenu.Link href=\"/pricing\">Pricing</NavigationMenu.Link>\n          </NavigationMenu.Item>\n        </NavigationMenu.List>\n        <NavigationMenu.Viewport />\n      </NavigationMenu>\n    </Header.Nav>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n      <Button variant=\"solid\" size=\"sm\">Sign Up</Button>\n    </Header.Actions>\n  </Header>\n</Box>"
     }
   ],
   "relations": [

package/src/components/Header/Header.module.scss

@@ -1,8 +1,10 @@
 @use "../../tokens/variables" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../tokens/mixins" as *;
 @use "../../recipes/action" as action;
 @use "../../recipes/layout" as layout;
 @use "../../recipes/navigation" as navigation;
+@use "../../recipes/overlay" as overlay;
 @use "../../recipes/popup" as popup;
 
 // ============================================
@@ -39,7 +41,7 @@
 }
 
 .elevatedOnScroll {
-  border-bottom: var(--fui-stroke-hairline, 1px) solid transparent;
+  border-bottom: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid transparent;
   transition: border-color var(--fui-transition-fast, $fui-transition-fast);
 }
 
@@ -127,8 +129,8 @@
   align-items: center;
   gap: var(--fui-space-1, $fui-space-1);
   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)});
 }
 
 .navItem {
@@ -192,7 +194,7 @@
 // ============================================
 
 .navMenuPositioner {
-  z-index: 52;
+  z-index: var(--fui-overlay-layer-anchored, #{$fui-overlay-layer-anchored});
   outline: none;
 }
 
@@ -200,7 +202,6 @@
   @include popup.container;
 
   min-width: layout.measure("field-minimum");
-  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
 
   opacity: 0;
   transform: scale(0.95);
@@ -338,24 +339,15 @@
 // ============================================
 
 .mobileNavBackdrop {
-  position: fixed;
-  inset: 0;
-  z-index: 98;
-  background: var(--fui-backdrop, $fui-backdrop);
+  @include overlay.backdrop;
+
   animation: mobileNavFadeIn var(--fui-transition-normal, $fui-transition-normal);
 }
 
+// The mobile nav is the Drawer surface: same frame, width, layer and chrome.
 .mobileNavDrawer {
-  position: fixed;
-  top: 0;
-  right: 0;
-  bottom: 0;
-  z-index: 99;
-  width: min(320px, 85vw);
-  background-color: var(--fui-bg-primary, $fui-bg-primary);
-  border-left: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
-  display: flex;
-  flex-direction: column;
+  @include overlay.side-panel("end");
+
   animation: mobileNavSlideIn var(--fui-transition-normal, $fui-transition-normal);
 }
 
@@ -364,7 +356,8 @@
   align-items: center;
   justify-content: flex-end;
   padding: var(--fui-space-3, $fui-space-3) var(--fui-space-4, $fui-space-4);
-  border-bottom: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
+  border-bottom: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+    var(--fui-border, $fui-border);
 }
 
 .mobileNavClose {
@@ -388,30 +381,23 @@
 .mobileNavBody {
   flex: 1;
   overflow-y: auto;
-  padding: var(--fui-space-3, $fui-space-3) var(--fui-space-4, $fui-space-4);
+  // Same gutter as NavigationMenu.drawerBody so both mobile navs inset their
+  // rows identically (UIR-D42).
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-navigation-gutter, #{navigation.gutter()});
 }
 
 .mobileNavLink {
   @include button-reset;
   @include navigation.row;
+  @include navigation.link-states;
 
   display: flex;
   align-items: center;
   width: 100%;
-  border-radius: var(--fui-radius-md, $fui-radius-md);
-  color: var(--fui-text-secondary, $fui-text-secondary);
-  text-decoration: none;
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
-
-  &:hover {
-    background-color: var(--fui-bg-hover, $fui-bg-hover);
-    color: var(--fui-text-primary, $fui-text-primary);
-  }
 }
 
 .mobileNavLinkActive {
-  color: var(--fui-text-primary, $fui-text-primary);
-  background-color: var(--fui-control-selected-bg, var(--fui-bg-active, $fui-bg-active));
+  @include navigation.link-active;
 }
 
 .mobileNavActions {
@@ -432,7 +418,7 @@
 
 @keyframes mobileNavSlideIn {
   from {
-    transform: translateX(100%);
+    transform: translateX(overlay.side-panel-offscreen("end"));
   }
   to {
     transform: translateX(0);
@@ -456,11 +442,13 @@
   position: absolute;
   top: var(--fui-space-2, $fui-space-2);
   left: var(--fui-space-2, $fui-space-2);
-  z-index: 100;
+  // Top of the layer scale: a skip link must win over every overlay.
+  z-index: var(--fui-overlay-layer-tooltip, #{$fui-overlay-layer-tooltip});
   padding: var(--fui-space-2, $fui-space-2) var(--fui-space-4, $fui-space-4);
   background-color: var(--fui-bg-primary, $fui-bg-primary);
   color: var(--fui-text-primary, $fui-text-primary);
-  border: var(--fui-stroke-default, 2px) solid var(--fui-color-accent, $fui-color-accent);
+  border: var(--fui-stroke-default, #{$fui-stroke-default}) solid
+    var(--fui-color-accent, $fui-color-accent);
   border-radius: var(--fui-radius-md, $fui-radius-md);
   text-decoration: none;
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
@@ -471,7 +459,7 @@
     height: auto;
     clip: auto;
     white-space: normal;
-    margin: 0;
+    margin: var(--fui-raw-space-0, #{measurements.raw-space(0)});
     padding: var(--fui-space-2, $fui-space-2) var(--fui-space-4, $fui-space-4);
     overflow: visible;
 

package/src/components/Icon/Icon.contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Icon",
-  "description": "Sizes and colors any icon so it lines up with the text beside it.",
+  "description": "Sizes and colours any icon so it lines up with the text beside it.",
   "category": "display",
   "tags": ["icon", "visual", "symbol", "graphic"],
   "status": "stable",
@@ -12,8 +12,8 @@
     "icon: union (required)",
     "size: xs|sm|md|lg|xl (default: md)",
     "weight: string (default: regular)",
-    "variant: default|primary|secondary|tertiary|accent|success|warning|error",
-    "color: primary|secondary|tertiary|accent|success|warning|error",
+    "tone: accent|info|success|warning|danger",
+    "color: primary|secondary|tertiary",
     "iconProps: object"
   ],
   "props": {
@@ -41,27 +41,17 @@
       "required": false,
       "values": ["thin", "light", "regular", "bold", "fill", "duotone"]
     },
-    "variant": {
+    "tone": {
       "type": "enum",
-      "description": "Semantic color variant",
-      "default": "default",
+      "description": "Semantic colour. Reserve success, warning and danger for real state; omit to inherit currentColor",
       "required": false,
-      "values": [
-        "default",
-        "primary",
-        "secondary",
-        "tertiary",
-        "accent",
-        "success",
-        "warning",
-        "error"
-      ]
+      "values": ["accent", "info", "success", "warning", "danger"]
     },
     "color": {
       "type": "enum",
-      "description": "Deprecated alias for variant",
+      "description": "Text-hierarchy colour, the same axis as Text color. tone wins when both are set",
       "required": false,
-      "values": ["primary", "secondary", "tertiary", "accent", "success", "warning", "error"]
+      "values": ["primary", "secondary", "tertiary"]
     },
     "iconProps": {
       "type": "object",
@@ -76,7 +66,7 @@
     ],
     "whenNot": ["Artwork or illustration (use Image)", "Multi-color or animated graphics"],
     "guidelines": [
-      "Reserve success, warning, and error colors for real state",
+      "Reserve the success, warning, and danger tones for real state",
       "Hold one size per context",
       "Match weight to the text weight beside it",
       "iconProps reaches options the wrapper does not expose"
@@ -99,9 +89,14 @@
       "code": "<div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>\n  <Icon icon={Star} size=\"xs\" />\n  <Icon icon={Star} size=\"sm\" />\n  <Icon icon={Star} size=\"md\" />\n  <Icon icon={Star} size=\"lg\" />\n  <Icon icon={Star} size=\"xl\" />\n</div>"
     },
     {
-      "name": "Semantic Colors",
-      "description": "Color states carry meaning — never use them for decoration.",
-      "code": "<div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>\n  <Icon icon={Check} variant=\"success\" />\n  <Icon icon={Warning} variant=\"warning\" />\n  <Icon icon={Warning} variant=\"error\" />\n  <Icon icon={Info} variant=\"accent\" />\n</div>"
+      "name": "Tones",
+      "description": "Tone states carry meaning — never use them for decoration.",
+      "code": "<div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>\n  <Icon icon={Check} tone=\"success\" />\n  <Icon icon={Warning} tone=\"warning\" />\n  <Icon icon={Warning} tone=\"danger\" />\n  <Icon icon={Info} tone=\"accent\" />\n</div>"
+    },
+    {
+      "name": "Hierarchy",
+      "description": "The text colour ladder, for glyphs that sit beside secondary or tertiary copy.",
+      "code": "<div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>\n  <Icon icon={Heart} color=\"primary\" />\n  <Icon icon={Heart} color=\"secondary\" />\n  <Icon icon={Heart} color=\"tertiary\" />\n</div>"
     },
     {
       "name": "Weights",
@@ -136,7 +131,8 @@
       "icon: React component - icon component (required)",
       "size: xs|sm|md|lg|xl - icon size",
       "weight: string - optional style/weight hint for icons that support it",
-      "variant: default|primary|secondary|tertiary|accent|success|warning|error - color",
+      "tone: accent|info|success|warning|danger - semantic colour",
+      "color: primary|secondary|tertiary - text-hierarchy colour",
       "iconProps: typed from the passed icon component - advanced icon-specific props"
     ],
     "a11yRules": ["A11Y_ICON_LABEL", "A11Y_COLOR_CONTRAST"]

package/src/components/Icon/Icon.module.scss

@@ -20,35 +20,36 @@
   }
 }
 
-.size2xl {
-  @include representation.glyph("2xl");
-}
-
-// Color variants (matching Badge/Alert pattern)
-.primary {
+// Text-hierarchy colour (Text's `color` axis). Absence inherits currentColor.
+.colorPrimary {
   color: var(--fui-text-primary, $fui-text-primary);
 }
 
-.secondary {
+.colorSecondary {
   color: var(--fui-text-secondary, $fui-text-secondary);
 }
 
-.tertiary {
+.colorTertiary {
   color: var(--fui-text-tertiary, $fui-text-tertiary);
 }
 
-.accent {
+// Tone paints the shared status ramp (same `*-text` stops as Badge and Text).
+.toneAccent {
   color: var(--fui-color-accent, $fui-color-accent);
 }
 
-.success {
+.toneInfo {
+  color: var(--fui-color-info-text, $fui-color-info-text);
+}
+
+.toneSuccess {
   color: var(--fui-color-success-text, $fui-color-success-text);
 }
 
-.warning {
+.toneWarning {
   color: var(--fui-color-warning-text, $fui-color-warning-text);
 }
 
-.error {
+.toneDanger {
   color: var(--fui-color-danger-text, $fui-color-danger-text);
 }

package/src/components/Icon/index.tsx

@@ -7,56 +7,56 @@ import styles from "./Icon.module.scss";
 type AnyIconComponent = React.ComponentType<any>;
 type IconComponentProps<TIcon extends AnyIconComponent> = React.ComponentPropsWithoutRef<TIcon>;
 
+export type IconSize = "xs" | "sm" | "md" | "lg" | "xl";
+export type IconTone = "accent" | "info" | "success" | "warning" | "danger";
+export type IconColor = "primary" | "secondary" | "tertiary";
+
 export type IconProps<TIcon extends AnyIconComponent = AnyIconComponent> = Omit<
   React.HTMLAttributes<HTMLSpanElement>,
   "color"
 > & {
   /** The icon component to render */
   icon: TIcon;
-  /** Size of the icon */
-  size?: "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+  /** Size of the icon. `xl` is the largest step (24px); the glyph inherits
+   * `currentColor` and the surrounding line height.
+   * @default "md" */
+  size?: IconSize;
   /** Optional style/weight hint forwarded when the icon component supports a `weight` prop */
   weight?: string;
-  /** Semantic color variant */
-  variant?:
-    | "default"
-    | "primary"
-    | "secondary"
-    | "tertiary"
-    | "accent"
-    | "success"
-    | "warning"
-    | "error";
-  /** @deprecated Use variant instead */
-  color?: "primary" | "secondary" | "tertiary" | "accent" | "success" | "warning" | "error";
+  /** Semantic colour. Reserve `success`, `warning` and `danger` for real
+   * state; `accent` is the brand spend. Omit to inherit `currentColor`. */
+  tone?: IconTone;
+  /** Text-hierarchy colour, the same axis as Text's `color`. `tone` wins when
+   * both are set. Omit to inherit `currentColor`. */
+  color?: IconColor;
   /** Additional props forwarded to the underlying icon component (typed from `icon`) */
   iconProps?: Partial<IconComponentProps<TIcon>>;
 };
 
 const iconTargets = MEASUREMENT_PROFILES.targets.icon;
-type IconSize = NonNullable<IconProps["size"]>;
+
+const TONE_CLASS: Record<IconTone, string> = {
+  accent: styles.toneAccent,
+  info: styles.toneInfo,
+  success: styles.toneSuccess,
+  warning: styles.toneWarning,
+  danger: styles.toneDanger,
+};
+
+const COLOR_CLASS: Record<IconColor, string> = {
+  primary: styles.colorPrimary,
+  secondary: styles.colorSecondary,
+  tertiary: styles.colorTertiary,
+};
 
 const IconRoot = React.forwardRef<HTMLSpanElement, IconProps>(function Icon(
-  {
-    icon: IconComponent,
-    size = "md",
-    weight = "regular",
-    variant,
-    color,
-    iconProps,
-    className,
-    style,
-    ...htmlProps
-  },
+  { icon: IconComponent, size = "md", weight = "regular", tone, color, iconProps, className, style, ...htmlProps },
   ref
 ) {
-  // Support deprecated color prop (variant takes precedence)
-  const colorVariant = variant || color;
-
   const classes = [
     styles.icon,
-    size === "2xl" ? styles.size2xl : styles[size as Exclude<IconSize, "2xl">],
-    colorVariant && colorVariant !== "default" && styles[colorVariant],
+    styles[size],
+    tone ? TONE_CLASS[tone] : color ? COLOR_CLASS[color] : undefined,
     className,
   ]
     .filter(Boolean)

package/src/components/IconButton/IconButton.contract.json

@@ -9,7 +9,7 @@
   "exportName": "IconButton",
   "propsSummary": [
     "children: node (required)",
-    "variant: ghost|subtle|outlined (default: ghost)",
+    "variant: ghost|soft|outline (default: ghost)",
     "size: sm|md|lg (default: md)",
     "pressed: boolean",
     "aria-label: string",
@@ -26,7 +26,7 @@
       "description": "Visual treatment for the icon-only action",
       "default": "ghost",
       "required": false,
-      "values": ["ghost", "subtle", "outlined"]
+      "values": ["ghost", "soft", "outline"]
     },
     "size": {
       "type": "enum",
@@ -64,7 +64,7 @@
     ],
     "guidelines": [
       "aria-label or aria-labelledby is required, every time",
-      "ghost for ordinary toolbar actions; outlined when it needs separation",
+      "ghost for ordinary toolbar actions; outline when it needs separation",
       "pressed only for real toggle state, not selection",
       "Keep icon meaning obvious, or pair it with a Tooltip"
     ],
@@ -83,22 +83,22 @@
     {
       "name": "Variants",
       "description": "Rising chrome: transparent, tinted, then bordered.",
-      "code": "import { Plus as PlusIcon } from '@phosphor-icons/react';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\">\n  <IconButton aria-label=\"Add item\" variant=\"ghost\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"subtle\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"outlined\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n</Stack>"
+      "code": "import { Plus as PlusIcon } from '@phosphor-icons/react';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\">\n  <IconButton aria-label=\"Add item\" variant=\"ghost\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"soft\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"outline\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n</Stack>"
     },
     {
       "name": "Sizes",
       "description": "sm for table rows, lg for primary chrome.",
-      "code": "import { Plus as PlusIcon } from '@phosphor-icons/react';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\">\n  <IconButton aria-label=\"Add item\" variant=\"outlined\" size=\"sm\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"outlined\" size=\"md\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"outlined\" size=\"lg\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n</Stack>"
+      "code": "import { Plus as PlusIcon } from '@phosphor-icons/react';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\">\n  <IconButton aria-label=\"Add item\" variant=\"outline\" size=\"sm\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"outline\" size=\"md\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Add item\" variant=\"outline\" size=\"lg\">\n    <PlusIcon aria-hidden />\n  </IconButton>\n</Stack>"
     },
     {
       "name": "Pressed state",
       "description": "Toggle that stays on, reported through aria-pressed.",
-      "code": "import { PushPin as PinIcon } from '@phosphor-icons/react';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\">\n  <IconButton aria-label=\"Pin item\" variant=\"outlined\">\n    <PinIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Unpin item\" variant=\"outlined\" pressed>\n    <PinIcon aria-hidden />\n  </IconButton>\n</Stack>"
+      "code": "import { PushPin as PinIcon } from '@phosphor-icons/react';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\">\n  <IconButton aria-label=\"Pin item\" variant=\"outline\">\n    <PinIcon aria-hidden />\n  </IconButton>\n  <IconButton aria-label=\"Unpin item\" variant=\"outline\" pressed>\n    <PinIcon aria-hidden />\n  </IconButton>\n</Stack>"
     },
     {
       "name": "Disabled",
       "description": "Unavailable action, out of the tab order.",
-      "code": "import { Trash as TrashIcon } from '@phosphor-icons/react';\n\n<IconButton aria-label=\"Delete row\" variant=\"outlined\" disabled>\n  <TrashIcon aria-hidden />\n</IconButton>"
+      "code": "import { Trash as TrashIcon } from '@phosphor-icons/react';\n\n<IconButton aria-label=\"Delete row\" variant=\"outline\" disabled>\n  <TrashIcon aria-hidden />\n</IconButton>"
     }
   ],
   "relations": [
@@ -116,7 +116,7 @@
   "contract": {
     "propsSummary": [
       "children: ReactNode - icon element (required)",
-      "variant: ghost|subtle|outlined - visual treatment",
+      "variant: ghost|soft|outline - visual treatment",
       "size: sm|md|lg - square control size",
       "pressed: boolean - toggle state exposed with aria-pressed",
       "aria-label or aria-labelledby - required accessible name"