@usefragments/ui 1.6.0 → 1.7.0

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

@@ -1,8 +1,8 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Form",
-  "description": "Form wrapper that handles server-side error distribution to Field components. Pairs with Field for complete form validation.",
-  "category": "forms",
+  "description": "Distributes server-side validation errors to its Field components.",
+  "category": "inputs",
   "tags": ["form", "validation", "errors", "submit", "server"],
   "status": "stable",
   "sourcePath": "src/components/Form/index.tsx",
@@ -50,47 +50,47 @@
   },
   "usage": {
     "when": [
-      "Building forms that need server-side error handling",
-      "Distributing validation errors to specific fields by name",
-      "Combining client and server validation in one form"
+      "The server rejects a submission and each reason must reach its own field",
+      "Client and server validation live in the same form"
     ],
     "whenNot": [
-      "Simple forms with only client-side validation (use native form or Field alone)",
-      "Non-form layouts (use Grid or Card)"
+      "Client-side validation only (a native form plus Field is enough)",
+      "Layout without submission (use Grid or Card)"
     ],
     "guidelines": [
-      "Pass errors as Record<string, string | string[]> keyed by field name",
-      "Use onClearErrors to clear errors when fields are modified",
-      "Use onSubmit for form submission handling (onFormSubmit is deprecated alias)",
-      "Field components with matching name prop display errors automatically",
-      "Use Grid inside Form or Fieldset for multi-column layouts",
-      "Place form buttons inside Form.Actions so cancel and submit actions are consistently right-aligned"
+      "errors is keyed by field name: Record<string, string | string[]>",
+      "Clear a field's error in onClearErrors when the user edits it",
+      "Use onSubmit; onFormSubmit is a deprecated alias",
+      "A Field picks up its error by matching name",
+      "Leave Field.Error unmatched so it shows whatever the server sent",
+      "Put a Grid inside Form or Fieldset for multi-column layouts",
+      "Buttons go in Form.Actions so they stay right-aligned"
     ],
     "accessibility": [
-      "Renders semantic form element",
-      "Error messages linked to fields via aria-describedby"
+      "Renders a real form element",
+      "Errors link back to their field via aria-describedby"
     ]
   },
   "examples": [
     {
       "name": "Sign up",
-      "description": "Registration form with two-column name fields",
+      "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>"
     },
     {
       "name": "Profile settings",
-      "description": "Multi-section form with Fieldsets, switches, and radio group",
+      "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>"
     },
     {
       "name": "Contact form",
-      "description": "Contact form with select, textarea, and checkbox",
+      "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>"
     },
     {
       "name": "With server errors",
-      "description": "Form displaying server-side validation errors",
-      "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 match=\"customError\" />\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 match=\"customError\" />\n    </Field>\n  </Grid>\n  <Form.Actions>\n    <Button type=\"submit\" variant=\"primary\">Submit</Button>\n  </Form.Actions>\n</Form>"
+      "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>"
     }
   ],
   "relations": [

package/src/components/Grid/Grid.contract.json

@@ -1,14 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Grid",
-  "description": "Responsive grid layout for arranging items in columns with consistent spacing",
+  "description": "Arranges items into responsive columns with one shared gap.",
   "category": "layout",
-  "tags": [
-    "grid",
-    "layout",
-    "columns",
-    "responsive"
-  ],
+  "tags": ["grid", "layout", "columns", "responsive"],
   "status": "stable",
   "sourcePath": "src/components/Grid/index.tsx",
   "exportName": "Grid",
@@ -43,57 +38,33 @@
       "type": "string",
       "description": "Minimum width for auto-fill columns (e.g., \"16rem\", \"250px\")",
       "required": false,
-      "constraints": [
-        "Only applies when columns=\"auto\""
-      ]
+      "constraints": ["Only applies when columns=\"auto\""]
     },
     "gap": {
       "type": "union",
       "description": "Gap between grid items. Accepts string tokens or numbers (1-8) mapped to the spacing scale",
       "default": "md",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl"
-      ]
+      "values": ["none", "xs", "sm", "md", "lg", "xl"]
     },
     "alignItems": {
       "type": "enum",
       "description": "Vertical alignment of items within their cells",
       "required": false,
-      "values": [
-        "start",
-        "center",
-        "end",
-        "stretch"
-      ]
+      "values": ["start", "center", "end", "stretch"]
     },
     "justifyItems": {
       "type": "enum",
       "description": "Horizontal alignment of items within their cells",
       "required": false,
-      "values": [
-        "start",
-        "center",
-        "end",
-        "stretch"
-      ]
+      "values": ["start", "center", "end", "stretch"]
     },
     "padding": {
       "type": "enum",
       "description": "Internal padding of the grid container",
       "default": "none",
       "required": false,
-      "values": [
-        "none",
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["none", "sm", "md", "lg"]
     },
     "className": {
       "type": "string",
@@ -108,23 +79,21 @@
   },
   "usage": {
     "when": [
-      "Arranging cards, tiles, or media in a responsive grid",
-      "Building form layouts with multi-column fields",
-      "Creating dashboard layouts with widgets",
-      "Any content that should reflow across breakpoints"
+      "Cards, tiles, or media that reflow across breakpoints",
+      "Multi-column form layouts",
+      "Dashboard widget layouts"
     ],
     "whenNot": [
-      "Single-column stacked content (use a simple flex column or Stack)",
-      "Navigation bars or toolbars (use a dedicated nav component)",
-      "Content that must not wrap (use inline layout)"
+      "One-directional lists (use Stack)",
+      "Editorial mosaics with feature tiles (use BentoGrid)",
+      "Navigation bars (use Header)"
     ],
     "guidelines": [
-      "Use columns=\"auto\" with minChildWidth for grids that adapt without breakpoints",
-      "Use responsive object { base: 1, md: 2, lg: 3 } when you need explicit control per breakpoint",
-      "Use fixed column counts when exact column control is needed and responsiveness is not required",
-      "Use Grid.Item with colSpan to create asymmetric layouts within a fixed grid",
-      "Keep gap consistent within a context — md is the default and works for most cases",
-      "Pass DOM attributes (id, role, aria-*, data-*, event handlers) directly to Grid and Grid.Item roots when needed"
+      "columns=\"auto\" with minChildWidth adapts without breakpoints",
+      "Pass { base, md, lg } to columns for explicit per-breakpoint control",
+      "Numeric gaps (1-8) map to the same spacing scale as the tokens",
+      "Wrap a child in Grid.Item to span columns; colSpan=\"full\" spans the row",
+      "Keep source order equal to visual order — Grid does not reorder for screen readers"
     ],
     "accessibility": [
       "Grid is purely visual — it does not affect reading order or semantics",
@@ -134,33 +103,28 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic 3-column grid",
-      "code": "<Grid columns={3} gap=\"md\">\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Item 1</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Item 2</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Item 3</div>\n</Grid>"
+      "description": "A fixed count of equal columns.",
+      "code": "import { Box } from '@/components/Box';\nimport { Grid } from '@/components/Grid';\n\n<Box width=\"100%\">\n  <Grid columns={3} gap=\"md\">\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">One</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Two</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Three</Box>\n  </Grid>\n</Box>"
     },
     {
       "name": "Responsive",
-      "description": "1 column on mobile, 2 on tablet, 3 on desktop",
-      "code": "<Grid columns={{ base: 1, md: 2, lg: 3 }} gap=\"md\">\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 1</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 2</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 3</div>\n</Grid>"
+      "description": "Column count changes per breakpoint.",
+      "code": "import { Box } from '@/components/Box';\nimport { Grid } from '@/components/Grid';\n\n<Box width=\"100%\">\n  <Grid columns={{ base: 1, md: 2, lg: 3 }} gap=\"md\">\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 1</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 2</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 3</Box>\n  </Grid>\n</Box>"
     },
     {
       "name": "Auto-fill",
-      "description": "Responsive grid that auto-fills based on minimum child width",
-      "code": "<Grid columns=\"auto\" minChildWidth=\"12rem\" gap=\"md\">\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 1</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 2</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 3</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Card 4</div>\n</Grid>"
-    },
-    {
-      "name": "Numeric Gap",
-      "description": "Using number values (1-8) mapped to the spacing scale",
-      "code": "<Grid columns={3} gap={4}>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Gap 4</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Gap 4</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Gap 4</div>\n</Grid>"
+      "description": "Columns fit themselves to a minimum child width — no breakpoints needed.",
+      "code": "import { Box } from '@/components/Box';\nimport { Grid } from '@/components/Grid';\n\n<Box width=\"100%\">\n  <Grid columns=\"auto\" minChildWidth=\"10rem\" gap=\"md\">\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 1</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 2</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 3</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Card 4</Box>\n  </Grid>\n</Box>"
     },
     {
       "name": "With Spanning",
-      "description": "Grid items spanning multiple columns",
-      "code": "<Grid columns={4} gap=\"md\">\n  <Grid.Item colSpan={2}>\n    <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Spans 2 cols</div>\n  </Grid.Item>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>1 col</div>\n  <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>1 col</div>\n  <Grid.Item colSpan=\"full\">\n    <div style={{ padding: 'var(--fui-space-2)', background: 'var(--fui-bg-secondary)' }}>Full width</div>\n  </Grid.Item>\n</Grid>"
+      "description": "Grid.Item stretches a child across columns.",
+      "code": "import { Box } from '@/components/Box';\nimport { Grid } from '@/components/Grid';\n\n<Box width=\"100%\">\n  <Grid columns={4} gap=\"md\">\n    <Grid.Item colSpan={2}>\n      <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Spans 2 columns</Box>\n    </Grid.Item>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">1 col</Box>\n    <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">1 col</Box>\n    <Grid.Item colSpan=\"full\">\n      <Box background=\"secondary\" rounded=\"sm\" padding=\"sm\">Full width</Box>\n    </Grid.Item>\n  </Grid>\n</Box>"
     },
     {
       "name": "Form Layout",
-      "description": "Two-column form that collapses to single column on mobile",
-      "code": "<Grid columns={{ base: 1, md: 2 }} gap=\"md\">\n  <div style={{ padding: 'var(--fui-space-1)', background: 'var(--fui-bg-secondary)' }}>First Name</div>\n  <div style={{ padding: 'var(--fui-space-1)', background: 'var(--fui-bg-secondary)' }}>Last Name</div>\n  <Grid.Item colSpan=\"full\">\n    <div style={{ padding: 'var(--fui-space-1)', background: 'var(--fui-bg-secondary)' }}>Email Address</div>\n  </Grid.Item>\n</Grid>"
+      "description": "Paired fields with one full-width row.",
+      "code": "import { Box } from '@/components/Box';\nimport { Field } from '@/components/Field';\nimport { Grid } from '@/components/Grid';\nimport { Input } from '@/components/Input';\n\n<Box width=\"100%\">\n  <Grid columns={{ base: 1, md: 2 }} gap=\"md\">\n    <Field>\n      <Field.Label>First name</Field.Label>\n      <Input placeholder=\"Ada\" />\n    </Field>\n    <Field>\n      <Field.Label>Last name</Field.Label>\n      <Input placeholder=\"Lovelace\" />\n    </Field>\n    <Grid.Item colSpan=\"full\">\n      <Field>\n        <Field.Label>Email address</Field.Label>\n        <Input type=\"email\" placeholder=\"ada@example.com\" />\n      </Field>\n    </Grid.Item>\n  </Grid>\n</Box>"
     }
   ],
   "relations": [

package/src/components/Grid/index.tsx

@@ -88,10 +88,10 @@ function isResponsiveColumns(columns: GridProps["columns"]): columns is Responsi
 }
 
 const paddingClasses: Record<NonNullable<GridProps["padding"]>, string> = {
-  none: styles.paddingNone,
-  sm: styles.paddingSm,
-  md: styles.paddingMd,
-  lg: styles.paddingLg,
+  none: styles.paddingNone ?? "",
+  sm: styles.paddingSm ?? "",
+  md: styles.paddingMd ?? "",
+  lg: styles.paddingLg ?? "",
 };
 
 // ============================================
@@ -118,12 +118,12 @@ export const Grid = React.forwardRef<HTMLDivElement, GridProps>(function Grid(
   let inlineStyle: React.CSSProperties | undefined;
 
   if (columns === "auto") {
-    columnsClass = styles.columnsAuto;
+    columnsClass = styles.columnsAuto ?? "";
     if (minChildWidth) {
       inlineStyle = { "--fui-grid-min-child-width": minChildWidth } as React.CSSProperties;
     }
   } else if (isResponsiveColumns(columns)) {
-    columnsClass = styles.columnsResponsive;
+    columnsClass = styles.columnsResponsive ?? "";
     const vars: Record<string, string> = {};
     if (columns.base) vars["--fui-grid-cols"] = String(columns.base);
     if (columns.sm) vars["--fui-grid-cols-sm"] = String(columns.sm);
@@ -132,7 +132,7 @@ export const Grid = React.forwardRef<HTMLDivElement, GridProps>(function Grid(
     if (columns.xl) vars["--fui-grid-cols-xl"] = String(columns.xl);
     inlineStyle = vars as unknown as React.CSSProperties;
   } else {
-    columnsClass = styles[`columns${columns}`];
+    columnsClass = styles[`columns${columns}`] ?? "";
   }
 
   inlineStyle = {
@@ -165,9 +165,9 @@ export const Grid = React.forwardRef<HTMLDivElement, GridProps>(function Grid(
 // ============================================
 
 const subgridClasses: Record<string, string> = {
-  rows: styles.subgridRows,
-  columns: styles.subgridColumns,
-  both: styles.subgridBoth,
+  rows: styles.subgridRows ?? "",
+  columns: styles.subgridColumns ?? "",
+  both: styles.subgridBoth ?? "",
 };
 
 const GridItem = React.forwardRef<HTMLDivElement, GridItemProps>(function GridItem(

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

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Header",
-  "description": "Composable header with slots for brand, navigation, search, and actions. Supports dropdown nav groups via Header.NavMenu. Designed for use within AppShell with responsive mobile support.",
-  "category": "navigation",
-  "tags": [
-    "header",
-    "navigation",
-    "navbar",
-    "brand",
-    "layout",
-    "dropdown"
-  ],
+  "description": "Composes brand, navigation, search, and actions into one responsive app bar.",
+  "category": "layout",
+  "tags": ["header", "navigation", "navbar", "brand", "layout", "dropdown"],
   "status": "stable",
   "sourcePath": "src/components/Header/index.tsx",
   "exportName": "Header",
@@ -41,11 +34,7 @@
       "description": "Position behavior (usually controlled by AppShell)",
       "default": "static",
       "required": false,
-      "values": [
-        "static",
-        "fixed",
-        "sticky"
-      ]
+      "values": ["static", "fixed", "sticky"]
     },
     "elevatedOnScroll": {
       "type": "boolean|object",
@@ -80,37 +69,22 @@
   },
   "usage": {
     "when": [
-      "Primary site or app header inside AppShell",
-      "Navigation bar with branding (default layout)",
-      "Search and actions bar (sidebar layout)",
-      "Header with responsive mobile menu trigger",
-      "Grouping related nav items under a dropdown menu"
+      "Top-level navigation for an app or site",
+      "Inside AppShell.Header",
+      "Anywhere brand, nav, and actions share one row"
     ],
     "whenNot": [
-      "Simple page titles (use heading elements)",
-      "Footer navigation (use Footer component)",
-      "Standalone sidebar navigation (use Sidebar directly)"
+      "Section headings inside a page (use a heading)",
+      "Toolbars scoped to one panel (use Toolbar)",
+      "Sidebar-only navigation (use Sidebar)"
     ],
     "guidelines": [
-      "Use Header.SkipLink for accessibility (skip to main content)",
-      "In default layout: include Header.Brand for logo",
-      "In sidebar layout: omit Header.Brand (logo in sidebar)",
-      "Header.Trigger integrates with SidebarProvider for mobile menus",
-      "Header.Trigger composes your onClick handler with sidebar toggle behavior",
-      "Header.Nav is hidden on mobile; use sidebar for mobile navigation",
-      "Use Header.Spacer to push items apart",
-      "Use Header.NavMenu to group related nav items under a dropdown",
-      "Use Header.NavMenuItem inside Header.NavMenu for dropdown items",
-      "Header sub-components forward DOM props (id, aria-*, data-*, handlers) to their rendered elements",
-      "Header.Brand asChild composes custom link components while preserving canonical brand styling",
-      "Header.NavItem asChild composes click handlers instead of overwriting the child handler",
-      "Use elevatedOnScroll on sticky marketing headers that need a boundary after scrolling",
-      "Use navAlign=\"center\" when navigation must stay centered independently of brand and actions",
-      "Use container=\"page\" when the header should share a bounded page gutter",
-      "Use Header.MobileNavActions for the primary action row inside Header.MobileNav",
-      "Use the Header icons prop to replace internal mobile trigger and dropdown chevron icons with any icon package",
-      "For rich dropdown content (titles, descriptions, icons), use NavigationMenu instead of Header.Nav",
-      "NavigationMenu also provides an automatic mobile drawer, replacing Header.Trigger + Sidebar for mobile nav"
+      "Header.Spacer pushes the actions cluster to the right",
+      "Omit Header.Brand when the sidebar already shows the logo",
+      "container=\"page\" caps the content at page width for marketing bars",
+      "elevatedOnScroll adds a bottom border once the page scrolls",
+      "Pair Header.Trigger with Header.MobileNav for small screens",
+      "Header.SkipLink should be the first child"
     ],
     "accessibility": [
       "Include Header.SkipLink for keyboard users",
@@ -123,43 +97,38 @@
   "examples": [
     {
       "name": "For Default Layout",
-      "description": "Header with brand, nav, and actions. Use with AppShell layout=\"default\".",
-      "code": "<ThemeProvider defaultMode=\"light\">\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</ThemeProvider>"
+      "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>"
     },
     {
       "name": "Marketing Header",
-      "description": "Sticky, page-width marketing header with centered navigation, scroll elevation, custom link composition, and mobile actions.",
-      "code": "<Header position=\"sticky\" elevatedOnScroll navAlign=\"center\" container=\"page\">\n  <Header.SkipLink href=\"#main-content\" />\n  <Header.Brand asChild>\n    <a href=\"/\" aria-label=\"Home\">Logo</a>\n  </Header.Brand>\n  <Header.Nav aria-label=\"Main navigation\">\n    <Header.NavItem href=\"/docs\">Docs</Header.NavItem>\n  </Header.Nav>\n  <Header.Actions>\n    <Button size=\"sm\">Start free</Button>\n  </Header.Actions>\n  <Header.Trigger />\n  <Header.MobileNav>\n    <Header.MobileNavLink href=\"/docs\">Docs</Header.MobileNavLink>\n    <Header.MobileNavActions>\n      <Button size=\"sm\">Start free</Button>\n    </Header.MobileNavActions>\n  </Header.MobileNav>\n</Header>"
+      "description": "Sticky page-width bar that gains a border on scroll, with a mobile drawer.",
+      "code": "import { Box } from '@/components/Box';\nimport { Button } from '@/components/Button';\nimport { Header } from '@/components/Header';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header position=\"sticky\" elevatedOnScroll navAlign=\"center\" container=\"page\">\n    <Header.SkipLink href=\"#main-content\" />\n    <Header.Brand asChild>\n      <a href=\"/\" aria-label=\"Home\">Logo</a>\n    </Header.Brand>\n    <Header.Nav aria-label=\"Main navigation\">\n      <Header.NavItem href=\"/docs\">Docs</Header.NavItem>\n      <Header.NavItem href=\"/pricing\">Pricing</Header.NavItem>\n    </Header.Nav>\n    <Header.Actions>\n      <Button size=\"sm\">Start free</Button>\n    </Header.Actions>\n    <Header.Trigger />\n    <Header.MobileNav>\n      <Header.MobileNavLink href=\"/docs\">Docs</Header.MobileNavLink>\n      <Header.MobileNavLink href=\"/pricing\">Pricing</Header.MobileNavLink>\n      <Header.MobileNavActions>\n        <Button size=\"sm\">Start free</Button>\n      </Header.MobileNavActions>\n    </Header.MobileNav>\n  </Header>\n</Box>"
     },
     {
       "name": "With Dropdown Nav",
-      "description": "Header with a dropdown menu grouping related navigation links.",
-      "code": "<ThemeProvider defaultMode=\"light\">\n  <Header>\n    <Header.Brand href=\"/\">MyApp</Header.Brand>\n    <Header.Nav>\n      <Header.NavItem href=\"/components\" active>Components</Header.NavItem>\n      <Header.NavItem href=\"/blocks\">Blocks</Header.NavItem>\n      <Header.NavMenu label=\"Docs\">\n        <Header.NavMenuItem href=\"/getting-started\">Getting Started</Header.NavMenuItem>\n        <Header.NavMenuItem href=\"/cli\">CLI Reference</Header.NavMenuItem>\n        <Header.NavMenuItem href=\"/mcp\">MCP Tools</Header.NavMenuItem>\n      </Header.NavMenu>\n      <Header.NavItem href=\"/blog\">Blog</Header.NavItem>\n    </Header.Nav>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</ThemeProvider>"
+      "description": "Header.NavMenu groups related links behind one trigger.",
+      "code": "import { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\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      <Header.NavItem href=\"/components\" active>Components</Header.NavItem>\n      <Header.NavItem href=\"/blocks\">Blocks</Header.NavItem>\n      <Header.NavMenu label=\"Docs\">\n        <Header.NavMenuItem href=\"/getting-started\">Getting Started</Header.NavMenuItem>\n        <Header.NavMenuItem href=\"/cli\">CLI Reference</Header.NavMenuItem>\n        <Header.NavMenuItem href=\"/mcp\">MCP Tools</Header.NavMenuItem>\n      </Header.NavMenu>\n      <Header.NavItem href=\"/blog\">Blog</Header.NavItem>\n    </Header.Nav>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</Box>"
     },
     {
       "name": "For Sidebar Layout",
-      "description": "Header without brand (logo is in sidebar). Use with AppShell layout=\"sidebar\" or \"sidebar-floating\".",
-      "code": "<ThemeProvider defaultMode=\"light\">\n  <Header>\n    <Header.SkipLink />\n    <Header.Trigger />\n    <Header.Search>\n      <Input placeholder=\"Search...\" style={{ width: '240px' }} />\n    </Header.Search>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</ThemeProvider>"
+      "description": "No brand — the logo lives in the sidebar instead.",
+      "code": "import { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { Input } from '@/components/Input';\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.Search>\n      <Input placeholder=\"Search...\" style={{ width: '240px' }} />\n    </Header.Search>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</Box>"
     },
     {
       "name": "Minimal",
-      "description": "Clean header with just trigger and actions",
-      "code": "<ThemeProvider defaultMode=\"light\">\n  <Header>\n    <Header.Trigger />\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</ThemeProvider>"
-    },
-    {
-      "name": "With Search",
-      "description": "Header featuring a prominent search input",
-      "code": "<ThemeProvider defaultMode=\"light\">\n  <Header>\n    <Header.Brand>Docs</Header.Brand>\n    <Header.Search>\n      <div style={{\n        display: 'flex',\n        alignItems: 'center',\n        gap: '8px',\n        padding: '8px 12px',\n        background: 'var(--fui-bg-secondary)',\n        borderRadius: '6px',\n        color: 'var(--fui-text-tertiary)',\n        fontSize: '14px',\n        width: '280px'\n      }}>\n        <MagnifyingGlass size={16} /> Search documentation...\n      </div>\n    </Header.Search>\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</ThemeProvider>"
+      "description": "Just the drawer trigger and actions.",
+      "code": "import { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\nimport { ThemeToggle } from '@/components/Theme';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header>\n    <Header.Trigger />\n    <Header.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n    </Header.Actions>\n  </Header>\n</Box>"
     },
     {
       "name": "With Skip Link",
-      "description": "Accessible header with skip link for keyboard navigation",
-      "code": "<Header>\n  <Header.SkipLink href=\"#main-content\">Skip to content</Header.SkipLink>\n  <Header.Brand>Accessible App</Header.Brand>\n  <Header.Nav>\n    <Header.NavItem href=\"/\" active>Home</Header.NavItem>\n    <Header.NavItem href=\"/about\">About</Header.NavItem>\n  </Header.Nav>\n</Header>"
+      "description": "Header.SkipLink gives keyboard users a jump to main content.",
+      "code": "import { Box } from '@/components/Box';\nimport { Header } from '@/components/Header';\n\n<Box width=\"100%\" border rounded=\"md\" overflow=\"hidden\">\n  <Header>\n    <Header.SkipLink href=\"#main-content\">Skip to content</Header.SkipLink>\n    <Header.Brand>Accessible App</Header.Brand>\n    <Header.Nav>\n      <Header.NavItem href=\"/\" active>Home</Header.NavItem>\n      <Header.NavItem href=\"/about\">About</Header.NavItem>\n    </Header.Nav>\n  </Header>\n</Box>"
     },
     {
       "name": "With NavigationMenu",
-      "description": "Header using NavigationMenu for rich dropdown content panels with titles, descriptions, and automatic mobile drawer.",
-      "code": "<ThemeProvider defaultMode=\"light\">\n  <Header>\n    <Header.Brand href=\"/\">MyApp</Header.Brand>\n    <NavigationMenu aria-label=\"Site navigation\">\n      <NavigationMenu.List>\n        <NavigationMenu.Item value=\"products\">\n          <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>\n          <NavigationMenu.Content>\n            <div style={{ display: 'flex', flexDirection: 'column', padding: '4px', minWidth: '200px' }}>\n              <NavigationMenu.Link href=\"/analytics\" title=\"Analytics\" description=\"Track your metrics.\" />\n              <NavigationMenu.Link href=\"/automation\" title=\"Automation\" description=\"Automate workflows.\" />\n            </div>\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.Spacer />\n    <Header.Actions>\n      <ThemeToggle size=\"md\" />\n      <Button variant=\"primary\" size=\"sm\">Sign Up</Button>\n    </Header.Actions>\n  </Header>\n</ThemeProvider>"
+      "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>"
     }
   ],
   "relations": [
@@ -197,12 +166,7 @@
       "Header.NavMenu provides dropdown groups via Base UI Menu",
       "Header.MobileNavActions provides an action row inside the mobile drawer"
     ],
-    "a11yRules": [
-      "A11Y_HEADER_LANDMARK",
-      "A11Y_NAV_LABEL",
-      "A11Y_SKIP_LINK",
-      "A11Y_BUTTON_LABEL"
-    ]
+    "a11yRules": ["A11Y_HEADER_LANDMARK", "A11Y_NAV_LABEL", "A11Y_SKIP_LINK", "A11Y_BUTTON_LABEL"]
   },
   "ai": {
     "compositionPattern": "compound",