@usefragments/ui 1.6.0 → 1.7.0

package/src/components/Menu/Menu.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Menu",
-  "description": "Dropdown menu for actions and commands. Supports submenus, check items, radio groups, and keyboard shortcuts.",
-  "category": "feedback",
-  "tags": [
-    "menu",
-    "dropdown",
-    "actions",
-    "context-menu",
-    "commands",
-    "submenu"
-  ],
+  "description": "Drops a list of actions below a trigger, driveable entirely by keyboard.",
+  "category": "overlays",
+  "tags": ["menu", "dropdown", "actions", "context-menu", "commands", "submenu"],
   "status": "stable",
   "sourcePath": "src/components/Menu/index.tsx",
   "exportName": "Menu",
@@ -52,26 +45,23 @@
   },
   "usage": {
     "when": [
-      "Overflow actions that dont fit in the toolbar",
-      "Context menus (right-click)",
-      "User account menus",
-      "Grouped actions with separators",
-      "Nested menus with submenus"
+      "Actions that do not fit in the toolbar",
+      "Right-click context actions",
+      "Account and profile actions",
+      "Related actions that read better grouped"
     ],
     "whenNot": [
-      "Selecting from options (use Select)",
-      "Navigation (use Tabs or navigation components)",
-      "Form selection (use Select or RadioGroup)"
+      "Picking a value for a form (use Select)",
+      "Moving between pages or views (use Tabs or NavigationMenu)",
+      "One of a few visible choices (use RadioGroup)"
     ],
     "guidelines": [
-      "Group related actions with Menu.Group",
-      "Use separators to divide action categories",
-      "Include keyboard shortcuts where applicable",
-      "Use danger variant for destructive actions",
-      "Keep menu items under 10-12 for usability",
-      "Use checked prop on Menu.Item for simple selection state",
-      "Use Menu.Submenu for nested secondary options",
-      "Menu.Trigger supports asChild for links/router-link components (single valid element child required)"
+      "Group related actions and separate the rest",
+      "Show the keyboard shortcut where one exists",
+      "Mark destructive actions with the danger variant",
+      "Past a dozen rows, reach for Command instead",
+      "Nest at most one level of submenu",
+      "asChild on Trigger needs a single element child"
     ],
     "accessibility": [
       "Full keyboard navigation with arrow keys",
@@ -84,37 +74,37 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic dropdown menu",
+      "description": "Plain actions, one per row.",
       "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">Actions</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Item onSelect={() => {}}>Edit</Menu.Item>\n    <Menu.Item onSelect={() => {}}>Duplicate</Menu.Item>\n    <Menu.Separator />\n    <Menu.Item danger onSelect={() => {}}>Delete</Menu.Item>\n  </Menu.Content>\n</Menu>"
     },
     {
       "name": "With Shortcuts",
-      "description": "Menu items with keyboard shortcuts",
+      "description": "Trailing keys teach the faster path.",
       "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">Edit</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Item shortcut=\"Ctrl+Z\" onSelect={() => {}}>Undo</Menu.Item>\n    <Menu.Item shortcut=\"Ctrl+Y\" onSelect={() => {}}>Redo</Menu.Item>\n    <Menu.Separator />\n    <Menu.Item shortcut=\"Ctrl+C\" onSelect={() => {}}>Copy</Menu.Item>\n    <Menu.Item shortcut=\"Ctrl+V\" onSelect={() => {}}>Paste</Menu.Item>\n  </Menu.Content>\n</Menu>"
     },
     {
       "name": "With Groups",
-      "description": "Menu with labeled groups",
+      "description": "Labels separate unrelated actions.",
       "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">Options</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Group>\n      <Menu.GroupLabel>View</Menu.GroupLabel>\n      <Menu.Item onSelect={() => {}}>Zoom In</Menu.Item>\n      <Menu.Item onSelect={() => {}}>Zoom Out</Menu.Item>\n    </Menu.Group>\n    <Menu.Separator />\n    <Menu.Group>\n      <Menu.GroupLabel>Layout</Menu.GroupLabel>\n      <Menu.Item onSelect={() => {}}>Grid View</Menu.Item>\n      <Menu.Item onSelect={() => {}}>List View</Menu.Item>\n    </Menu.Group>\n  </Menu.Content>\n</Menu>"
     },
     {
       "name": "With Checkboxes",
-      "description": "Menu with toggleable checkbox options",
+      "description": "Rows that stay open while you toggle them.",
       "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">Display</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.CheckboxItem defaultChecked>Show Grid</Menu.CheckboxItem>\n    <Menu.CheckboxItem defaultChecked>Show Rulers</Menu.CheckboxItem>\n    <Menu.CheckboxItem>Show Guides</Menu.CheckboxItem>\n  </Menu.Content>\n</Menu>"
     },
     {
       "name": "With Checked Items",
-      "description": "Filter menu with check marks indicating active selections",
+      "description": "Ticks mark which filters are on.",
       "code": "<CheckedItemsMenuDemo />"
     },
     {
       "name": "With Submenu",
-      "description": "Menu with nested submenu for grouped secondary options",
+      "description": "Secondary options nest one level deep.",
       "code": "<Menu>\n  <Menu.Trigger asChild>\n    <Button variant=\"secondary\">File</Button>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Item onSelect={() => {}}>New File</Menu.Item>\n    <Menu.Item onSelect={() => {}}>Open</Menu.Item>\n    <Menu.Separator />\n    <Menu.Submenu>\n      <Menu.SubmenuTrigger>Export As</Menu.SubmenuTrigger>\n      <Menu.Content side=\"right\" align=\"start\">\n        <Menu.Item onSelect={() => {}}>PNG</Menu.Item>\n        <Menu.Item onSelect={() => {}}>SVG</Menu.Item>\n        <Menu.Item onSelect={() => {}}>PDF</Menu.Item>\n      </Menu.Content>\n    </Menu.Submenu>\n    <Menu.Separator />\n    <Menu.Item danger onSelect={() => {}}>Delete</Menu.Item>\n  </Menu.Content>\n</Menu>"
     },
     {
       "name": "Link Trigger",
-      "description": "Use asChild with a non-button trigger element",
+      "description": "asChild lets a link open it.",
       "code": "<Menu>\n  <Menu.Trigger asChild>\n    <a href=\"#menu-actions\">Open menu</a>\n  </Menu.Trigger>\n  <Menu.Content>\n    <Menu.Item onSelect={() => {}}>Inspect</Menu.Item>\n    <Menu.Item onSelect={() => {}}>Rename</Menu.Item>\n  </Menu.Content>\n</Menu>"
     }
   ],
@@ -140,10 +130,7 @@
       "Menu.Item shortcut: string - keyboard shortcut text",
       "Menu.Item checked: boolean - check indicator for selection state"
     ],
-    "a11yRules": [
-      "A11Y_MENU_KEYBOARD",
-      "A11Y_MENU_ROLE"
-    ]
+    "a11yRules": ["A11Y_MENU_KEYBOARD", "A11Y_MENU_ROLE"]
   },
   "ai": {
     "compositionPattern": "compound",
@@ -160,10 +147,7 @@
       "Submenu",
       "SubmenuTrigger"
     ],
-    "requiredChildren": [
-      "Trigger",
-      "Content"
-    ],
+    "requiredChildren": ["Trigger", "Content"],
     "commonPatterns": [
       "<Menu><Menu.Trigger asChild><Button>Actions</Button></Menu.Trigger><Menu.Content><Menu.Item>{action1}</Menu.Item><Menu.Separator /><Menu.Item danger>{delete}</Menu.Item></Menu.Content></Menu>"
     ]

package/src/components/Menu/Menu.module.scss

@@ -1,4 +1,5 @@
 @use "../../tokens/variables" as *;
+@use "../../recipes/layout" as layout;
 @use "../../recipes/popup" as popup;
 @use "../../recipes/typography" as typography;
 
@@ -6,23 +7,37 @@
   z-index: var(--fui-overlay-layer-anchored, 52);
   outline: none;
   pointer-events: auto;
+
+  // The popup is absolutely positioned inside the positioner whenever a
+  // Menu.Viewport is present (Base UI anchors it with top/bottom: 0). Without an
+  // explicit box the positioner collapses to zero height and any flipped
+  // (side="top") menu renders a full popup-height away from its trigger.
+  inline-size: var(--positioner-width);
+  block-size: var(--positioner-height);
 }
 
 .popup {
   @include popup.container;
 
-  min-inline-size: var(--fui-menu-min-inline, 192px);
+  min-inline-size: layout.measure("menu-min");
   margin: 0;
   list-style: none;
-  opacity: 1;
-  transform: none;
+  opacity: 0;
+  transform: scale(0.95);
   transform-origin: var(--transform-origin);
+  transition:
+    opacity var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  &[data-open] {
+    opacity: 1;
+    transform: scale(1);
+  }
 
-  &[data-open],
   &[data-starting-style],
   &[data-ending-style] {
-    opacity: 1;
-    transform: none;
+    opacity: 0;
+    transform: scale(0.95);
   }
 }
 
@@ -126,8 +141,8 @@
   block-size: 0;
   margin-inline-start: auto;
   border-style: solid;
-  border-width: var(--fui-menu-submenu-caret-block, 4px) 0 var(--fui-menu-submenu-caret-block, 4px)
-    var(--fui-menu-submenu-caret-inline, 6px);
+  border-width: var(--fui-raw-space-4, 4px) 0 var(--fui-raw-space-4, 4px)
+    var(--fui-raw-space-6, 6px);
   border-color: transparent transparent transparent var(--fui-text-secondary, $fui-text-secondary);
 }
 

package/src/components/Message/Message.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Message",
-  "description": "Individual chat message display with role-based styling",
+  "description": "Shows one chat message, styled by who sent it.",
   "category": "ai",
-  "tags": [
-    "message",
-    "chat",
-    "ai",
-    "conversation",
-    "bubble"
-  ],
+  "tags": ["message", "chat", "ai", "conversation", "bubble"],
   "status": "stable",
   "sourcePath": "src/components/Message/index.tsx",
   "exportName": "Message",
@@ -26,11 +20,7 @@
       "type": "enum",
       "description": "Message role determines styling and alignment",
       "required": true,
-      "values": [
-        "user",
-        "assistant",
-        "system"
-      ]
+      "values": ["user", "assistant", "system"]
     },
     "children": {
       "type": "node",
@@ -42,12 +32,7 @@
       "description": "Message state",
       "default": "complete",
       "required": false,
-      "values": [
-        "sending",
-        "streaming",
-        "complete",
-        "error"
-      ]
+      "values": ["sending", "streaming", "complete", "error"]
     },
     "timestamp": {
       "type": "object",
@@ -67,24 +52,24 @@
   },
   "usage": {
     "when": [
-      "Displaying individual messages in a chat interface",
-      "Building AI assistant or chatbot UIs",
-      "Need role-based message styling (user vs assistant)",
-      "Messages need actions like copy, regenerate, or feedback"
+      "Individual turns in a chat transcript",
+      "AI assistant and chatbot interfaces",
+      "User and assistant turns that must read differently",
+      "Turns carrying copy, regenerate, or feedback actions"
     ],
     "whenNot": [
-      "Simple text display without chat context (use Text)",
-      "Notification-style messages (use Alert or Toast)",
-      "Comment threads with nested replies (use Card with custom layout)"
+      "Plain text with no chat context (use Text)",
+      "Notifications (use Alert or Toast)",
+      "Threads with nested replies (use Card with a custom layout)"
     ],
     "guidelines": [
-      "Always provide a role prop to determine styling",
-      "Use status prop to show message state (sending, streaming, error)",
-      "Pass avatar={null}, or set showAvatars={false} on the parent ConversationList, to hide avatars; avatarless assistant content is flush while the user's own bubble keeps compact space-1/space-2 padding",
-      "User message bubbles are capped at 80% of the available inline measure so they remain visually distinct from assistant responses",
-      "User and assistant message chrome uses neutral surface tokens with the primary text foreground; reserve brand accent for actions or semantic state",
-      "Consider showing timestamps for longer conversations",
-      "Provide hover actions for assistant messages (copy, regenerate)"
+      "Always set role — it drives alignment, avatar, and chrome",
+      "status covers sending, streaming, and error",
+      "Hide avatars with avatar={null}, or showAvatars={false} on ConversationList",
+      "User bubbles cap at 80% of the inline measure so the two sides stay distinct",
+      "Chrome stays on neutral surfaces; reserve accent for actions and semantic state",
+      "Add timestamps once a conversation runs long",
+      "Give assistant turns hover actions such as copy and regenerate"
     ],
     "accessibility": [
       "Uses semantic HTML for message structure",
@@ -96,43 +81,43 @@
   "examples": [
     {
       "name": "User Message",
-      "description": "Message from the user (right-aligned)",
+      "description": "Right-aligned and capped at 80% of the available width.",
       "code": "<Message role=\"user\">\n  <Message.Content>\n    Hello! Can you help me with a coding question?\n  </Message.Content>\n</Message>"
     },
     {
       "name": "Assistant Message",
-      "description": "Response from the AI assistant",
+      "description": "Left-aligned with an avatar and a wider measure.",
       "code": "<Message role=\"assistant\">\n  <Message.Content>\n    Of course! I'd be happy to help. What would you like to know?\n  </Message.Content>\n</Message>"
     },
     {
       "name": "System Message",
-      "description": "System notification or context",
+      "description": "Centred and quiet, for context rather than conversation.",
       "code": "<Message role=\"system\">\n  <Message.Content>\n    Conversation started. Model: GPT-4\n  </Message.Content>\n</Message>"
     },
     {
       "name": "Streaming",
-      "description": "Message being streamed (with cursor)",
+      "description": "A blinking caret trails the text as it arrives.",
       "code": "<Message role=\"assistant\" status=\"streaming\">\n  <Message.Content>\n    I'm currently generating a response for you\n  </Message.Content>\n</Message>"
     },
     {
       "name": "With Timestamp",
-      "description": "Message with timestamp display",
+      "description": "A relative send time sits beneath the bubble.",
       "code": "<Message role=\"assistant\" timestamp={new Date(Date.now() - 300000)}>\n  <Message.Content>\n    This message was sent 5 minutes ago.\n  </Message.Content>\n  <Message.Timestamp />\n</Message>"
     },
     {
       "name": "Error State",
-      "description": "Message that failed to send",
+      "description": "A failed send turns the bubble and its border red.",
       "code": "<Message role=\"user\" status=\"error\">\n  <Message.Content>\n    This message failed to send.\n  </Message.Content>\n</Message>"
     },
     {
       "name": "Custom Avatars",
-      "description": "Messages with image-based avatars",
+      "description": "Photos replace the default glyphs on both sides.",
       "code": "<>\n  <Message\n    role=\"user\"\n    avatar={<Message.Avatar src=\"https://i.pravatar.cc/64?u=user\" alt=\"Jane\" />}\n  >\n    <Message.Content>\n      Can you help me understand this error?\n    </Message.Content>\n  </Message>\n  <Message\n    role=\"assistant\"\n    avatar={<Message.Avatar src=\"https://i.pravatar.cc/64?u=bot\" alt=\"AI Assistant\" />}\n  >\n    <Message.Content>\n      Sure! Let me take a look at that for you.\n    </Message.Content>\n  </Message>\n</>"
     },
     {
       "name": "With Actions",
-      "description": "Message with hover actions",
-      "code": "<Message\n  role=\"assistant\"\n  actions={\n    <>\n      <button style={{ padding: '4px 8px', fontSize: '12px' }}>Copy</button>\n      <button style={{ padding: '4px 8px', fontSize: '12px' }}>Regenerate</button>\n    </>\n  }\n>\n  <Message.Content>\n    Hover over this message to see the actions.\n  </Message.Content>\n</Message>"
+      "description": "Controls stay hidden until the pointer enters the row.",
+      "code": "<Message\n  role=\"assistant\"\n  actions={\n    <>\n      <Button variant=\"ghost\" size=\"xs\">\n        Copy\n      </Button>\n      <Button variant=\"ghost\" size=\"xs\">\n        Regenerate\n      </Button>\n    </>\n  }\n>\n  <Message.Content>\n    Hover over this message to see the actions.\n  </Message.Content>\n</Message>"
     }
   ],
   "relations": [
@@ -163,19 +148,11 @@
       "Avatar.src: string - image URL for avatar",
       "Avatar.alt: string - alt text for image avatar"
     ],
-    "a11yRules": [
-      "A11Y_COLOR_CONTRAST",
-      "A11Y_MOTION_PREFERENCE"
-    ]
+    "a11yRules": ["A11Y_COLOR_CONTRAST", "A11Y_MOTION_PREFERENCE"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Content",
-      "Actions",
-      "Timestamp",
-      "Avatar"
-    ]
+    "subComponents": ["Content", "Actions", "Timestamp", "Avatar"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Message/Message.module.scss

@@ -26,12 +26,16 @@
   flex-direction: row-reverse;
   margin-inline-start: auto;
 
+  // Cap against the conversation width, not the bubble's own shrink-wrapped
+  // width. On .content the percentage resolves against an already-collapsed
+  // parent and squeezes short messages until they break mid-word.
+  max-inline-size: 80%;
+
   .body {
     align-items: flex-end;
   }
 
   .content {
-    max-inline-size: 80%;
     background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
     color: var(--fui-text-primary, $fui-text-primary);
   }
@@ -58,7 +62,8 @@
 }
 
 .error .content {
-  border: var(--fui-stroke-hairline) solid var(--fui-color-danger-border, $fui-color-danger-border);
+  border: var(--fui-stroke-hairline, 1px) solid
+    var(--fui-color-danger-border, $fui-color-danger-border);
   background: var(--fui-color-danger-bg, $fui-color-danger-bg);
   color: var(--fui-color-danger-text, $fui-color-danger-text);
 }
@@ -102,7 +107,9 @@
   padding-block: layout.gap("sm");
   padding-inline: layout.gap("md");
   border-radius: var(--fui-radius-lg, $fui-radius-lg);
-  overflow-wrap: anywhere;
+  // break-word, not anywhere: `anywhere` drops min-content to a single
+  // character, collapsing every shrink-to-fit ancestor around the bubble.
+  overflow-wrap: break-word;
 
   p {
     @include prose.paragraph;
@@ -140,9 +147,9 @@
   display: inline-block;
   inline-size: 0.5em;
   block-size: 1em;
-  margin-inline-start: var(--fui-raw-space-2);
+  margin-inline-start: var(--fui-raw-space-2, 2px);
   background-color: currentColor;
-  animation: blink 1s step-end infinite;
+  animation: blink var(--fui-duration-pulse, $fui-duration-pulse) step-end infinite;
 }
 
 @keyframes blink {

package/src/components/NavigationMenu/NavigationMenu.contract.json

@@ -1,18 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "NavigationMenu",
-  "description": "Rich navigation menu for site headers with dropdown content panels, animated viewport transitions, and automatic mobile drawer. Supports structured links with titles, descriptions, and icons.",
+  "description": "Site navigation whose dropdowns become a drawer on small screens.",
   "category": "navigation",
-  "tags": [
-    "navigation",
-    "menu",
-    "header",
-    "dropdown",
-    "navbar",
-    "mobile",
-    "responsive",
-    "drawer"
-  ],
+  "tags": ["navigation", "menu", "header", "dropdown", "navbar", "mobile", "responsive", "drawer"],
   "status": "stable",
   "sourcePath": "src/components/NavigationMenu/index.tsx",
   "exportName": "NavigationMenu",
@@ -24,7 +15,8 @@
     "orientation: horizontal|vertical (default: horizontal)",
     "delayDuration: number (default: 200)",
     "skipDelayDuration: number (default: 300)",
-    "icons: object"
+    "icons: object",
+    "mobileBreakpoint: md|lg (default: md)"
   ],
   "props": {
     "children": {
@@ -53,10 +45,7 @@
       "description": "'horizontal' | 'vertical'",
       "default": "horizontal",
       "required": false,
-      "values": [
-        "horizontal",
-        "vertical"
-      ]
+      "values": ["horizontal", "vertical"]
     },
     "delayDuration": {
       "type": "number",
@@ -74,30 +63,37 @@
       "type": "object",
       "description": "Optional icon overrides for triggerChevron, mobileMenu, mobileClose, and drawerClose controls",
       "required": false
+    },
+    "mobileBreakpoint": {
+      "type": "enum",
+      "description": "Viewport breakpoint below which the mobile drawer replaces desktop navigation",
+      "default": "md",
+      "required": false,
+      "values": ["md", "lg"]
     }
   },
   "usage": {
     "when": [
-      "Site-level header navigation with rich dropdown content",
-      "Navigation with titles, descriptions, and icons in dropdowns",
-      "Responsive navigation that converts to a mobile drawer automatically",
-      "Multi-section navigation requiring animated viewport transitions"
+      "Header navigation with more than links",
+      "Dropdowns carrying titles, descriptions, or icons",
+      "Navigation that must survive a phone screen",
+      "Several sections that animate between each other"
     ],
     "whenNot": [
-      "Simple flat navigation without dropdowns (use Header.Nav)",
-      "Application menus with actions like cut/paste (use Menu)",
-      "Sidebar navigation (use Sidebar)",
-      "Breadcrumb trail navigation (use Breadcrumbs)"
+      "Flat links with no dropdowns (use Header.Nav)",
+      "Application actions like cut and paste (use Menu)",
+      "Persistent side navigation (use Sidebar)",
+      "Showing where the user already is (use Breadcrumbs)"
     ],
     "guidelines": [
-      "Place inside Header component for site-level navigation",
-      "Use NavigationMenu.Viewport for animated content panel transitions",
-      "Use NavigationMenu.MobileContent to add extra sections to the mobile drawer",
-      "Use structured links (title + description) for rich dropdown content",
-      "Use simple NavigationMenu.Link for items without dropdown content",
-      "NavigationMenu.Link asChild composes click handlers and respects event.preventDefault()",
-      "Triggers open on hover (desktop) with configurable delay",
-      "Use the icons prop to replace trigger chevrons and mobile drawer controls with icons from any package"
+      "Place it inside Header for site-level navigation",
+      "Add Viewport to animate between panels",
+      "Use MobileContent for sections that only make sense in the drawer",
+      "Title plus description for rich panels, plain Link for the rest",
+      "asChild on Link composes your handler and honours preventDefault()",
+      "Desktop triggers open on hover after a configurable delay",
+      "Point icons at your own icon package to replace the chevrons",
+      "Set mobileBreakpoint=\"lg\" when the shell drops its sidebar below 1024px"
     ],
     "accessibility": [
       "Uses disclosure pattern (not menu role) per W3C guidance",
@@ -110,27 +106,27 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Two trigger items with dropdown content and one direct link",
+      "description": "Two dropdowns beside one plain link.",
       "code": "<NavigationMenu>\n  <NavigationMenu.List>\n    <NavigationMenu.Item value=\"products\">\n      <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>\n      <NavigationMenu.Content>\n        <NavigationMenu.Link href=\"/analytics\" title=\"Analytics\" description=\"Track your metrics and KPIs.\" />\n        <NavigationMenu.Link href=\"/automation\" title=\"Automation\" description=\"Automate your workflows.\" />\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n    <NavigationMenu.Item value=\"resources\">\n      <NavigationMenu.Trigger>Resources</NavigationMenu.Trigger>\n      <NavigationMenu.Content>\n        <NavigationMenu.Link href=\"/docs\" title=\"Documentation\" description=\"Comprehensive API reference.\" />\n        <NavigationMenu.Link href=\"/blog\" title=\"Blog\" description=\"Latest news and updates.\" />\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>"
     },
     {
       "name": "With Rich Content",
-      "description": "Grid layout with icons, titles, and descriptions",
+      "description": "A grid of icons, titles, and descriptions.",
       "code": "<NavigationMenu>\n  <NavigationMenu.List>\n    <NavigationMenu.Item value=\"platform\">\n      <NavigationMenu.Trigger>Platform</NavigationMenu.Trigger>\n      <NavigationMenu.Content>\n        <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '4px', padding: '8px', minWidth: '400px' }}>\n          <NavigationMenu.Link\n            href=\"/dashboard\"\n            title=\"Dashboard\"\n            description=\"Overview of your project metrics.\"\n          />\n          <NavigationMenu.Link\n            href=\"/analytics\"\n            title=\"Analytics\"\n            description=\"Deep dive into your data.\"\n          />\n          <NavigationMenu.Link\n            href=\"/reports\"\n            title=\"Reports\"\n            description=\"Generate custom reports.\"\n          />\n          <NavigationMenu.Link\n            href=\"/settings\"\n            title=\"Settings\"\n            description=\"Configure your workspace.\"\n          />\n        </div>\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n  </NavigationMenu.List>\n  <NavigationMenu.Viewport />\n</NavigationMenu>"
     },
     {
       "name": "With Simple Links",
-      "description": "Mix of triggers with simple link lists and plain links",
+      "description": "Link lists where descriptions would be noise.",
       "code": "<NavigationMenu>\n  <NavigationMenu.List>\n    <NavigationMenu.Item value=\"company\">\n      <NavigationMenu.Trigger>Company</NavigationMenu.Trigger>\n      <NavigationMenu.Content>\n        <div style={{ display: 'flex', flexDirection: 'column', padding: '4px', minWidth: '160px' }}>\n          <NavigationMenu.Link href=\"/about\">About</NavigationMenu.Link>\n          <NavigationMenu.Link href=\"/careers\">Careers</NavigationMenu.Link>\n          <NavigationMenu.Link href=\"/contact\">Contact</NavigationMenu.Link>\n        </div>\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n    <NavigationMenu.Item>\n      <NavigationMenu.Link href=\"/blog\">Blog</NavigationMenu.Link>\n    </NavigationMenu.Item>\n    <NavigationMenu.Item>\n      <NavigationMenu.Link href=\"/docs\">Docs</NavigationMenu.Link>\n    </NavigationMenu.Item>\n  </NavigationMenu.List>\n  <NavigationMenu.Viewport />\n</NavigationMenu>"
     },
     {
       "name": "With Featured Card",
-      "description": "Highlighted featured item alongside regular links",
+      "description": "One promoted item leads the panel.",
       "code": "<NavigationMenu>\n  <NavigationMenu.List>\n    <NavigationMenu.Item value=\"learn\">\n      <NavigationMenu.Trigger>Learn</NavigationMenu.Trigger>\n      <NavigationMenu.Content>\n        <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '8px', padding: '8px', minWidth: '420px' }}>\n          <NavigationMenu.Link\n            href=\"/quickstart\"\n            title=\"Quick Start\"\n            description=\"Get up and running in 5 minutes with our getting started guide.\"\n            featured\n          />\n          <div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>\n            <NavigationMenu.Link href=\"/docs\" title=\"Documentation\" description=\"API reference and guides.\" />\n            <NavigationMenu.Link href=\"/examples\" title=\"Examples\" description=\"Browse example projects.\" />\n          </div>\n        </div>\n      </NavigationMenu.Content>\n    </NavigationMenu.Item>\n  </NavigationMenu.List>\n  <NavigationMenu.Viewport />\n</NavigationMenu>"
     },
     {
       "name": "Vertical",
-      "description": "Vertical orientation with content panels to the right",
+      "description": "Panels open to the side instead of below.",
       "code": "<div style={{ display: 'flex' }}>\n  <NavigationMenu orientation=\"vertical\">\n    <NavigationMenu.List>\n      <NavigationMenu.Item value=\"overview\">\n        <NavigationMenu.Trigger>Overview</NavigationMenu.Trigger>\n        <NavigationMenu.Content>\n          <div style={{ padding: '8px', minWidth: '200px' }}>\n            <NavigationMenu.Link href=\"/intro\" title=\"Introduction\" description=\"Learn the basics.\" />\n          </div>\n        </NavigationMenu.Content>\n      </NavigationMenu.Item>\n      <NavigationMenu.Item value=\"guides\">\n        <NavigationMenu.Trigger>Guides</NavigationMenu.Trigger>\n        <NavigationMenu.Content>\n          <div style={{ padding: '8px', minWidth: '200px' }}>\n            <NavigationMenu.Link href=\"/install\" title=\"Installation\" description=\"Get started quickly.\" />\n            <NavigationMenu.Link href=\"/config\" title=\"Configuration\" description=\"Customize your setup.\" />\n          </div>\n        </NavigationMenu.Content>\n      </NavigationMenu.Item>\n    </NavigationMenu.List>\n    <NavigationMenu.Viewport />\n  </NavigationMenu>\n</div>"
     }
   ],
@@ -163,15 +159,12 @@
       "orientation: horizontal | vertical — layout direction",
       "delayDuration: number — hover open delay (default: 200ms)",
       "icons: { triggerChevron?, mobileMenu?, mobileClose?, drawerClose? } — custom internal control icons",
+      "mobileBreakpoint: md | lg — mobile drawer breakpoint (default: md)",
       "NavigationMenu.Link: title + description + icon for structured links, or children for simple links",
       "NavigationMenu.Link asChild: composes child and menu click handlers (preventDefault keeps menu open)",
       "NavigationMenu.MobileContent: slot for extra mobile-only sections"
     ],
-    "a11yRules": [
-      "A11Y_DISCLOSURE_PATTERN",
-      "A11Y_KEYBOARD_NAV",
-      "A11Y_FOCUS_TRAP"
-    ]
+    "a11yRules": ["A11Y_DISCLOSURE_PATTERN", "A11Y_KEYBOARD_NAV", "A11Y_FOCUS_TRAP"]
   },
   "ai": {
     "compositionPattern": "compound",
@@ -187,9 +180,7 @@
       "MobileContent",
       "MobileSection"
     ],
-    "requiredChildren": [
-      "List"
-    ],
+    "requiredChildren": ["List"],
     "commonPatterns": [
       "<NavigationMenu><NavigationMenu.List><NavigationMenu.Item value=\"docs\"><NavigationMenu.Trigger>Docs</NavigationMenu.Trigger><NavigationMenu.Content><NavigationMenu.Link href=\"/guides\" title=\"Guides\" description=\"Learn the basics\" /></NavigationMenu.Content></NavigationMenu.Item></NavigationMenu.List><NavigationMenu.Viewport /></NavigationMenu>"
     ]