lucent-ui 0.24.0 → 0.25.1

package/dist-server/src/components/atoms/Text/Text.manifest.js

@@ -86,7 +86,9 @@ export const COMPONENT_MANIFEST = {
             name: 'style',
             type: 'object',
             required: false,
-            description: 'Inline style overrides. Applied after computed token styles.',
+            description: 'Inline style overrides. Applied after computed token styles, so any property you set here wins. ' +
+                'This is the official escape hatch for one-off styling outside the token system — e.g. a custom ' +
+                'color via style={{ color: "var(--my-green)" }}. See docs/style-escape-hatch.md.',
         },
     ],
     usageExamples: [
@@ -96,6 +98,10 @@ export const COMPONENT_MANIFEST = {
         { title: 'Inline code', code: `<Text as="code" family="mono" size="sm">const x = 1;</Text>` },
         { title: 'Truncated', code: `<Text truncate style={{ maxWidth: 200 }}>Very long text that will be clipped</Text>` },
         { title: 'Status color', code: `<Text color="danger" size="xs">This field is required</Text>` },
+        {
+            title: 'Custom color via style escape hatch',
+            code: `<Text style={{ color: 'var(--chart-series-a)' }}>Revenue</Text>`,
+        },
     ],
     compositionGraph: [],
     accessibility: {

package/dist-server/src/components/molecules/Card/Card.manifest.js

@@ -102,7 +102,7 @@ export const COMPONENT_MANIFEST = {
             name: 'radius',
             type: 'enum',
             required: false,
-            default: 'md',
+            default: 'lg',
             description: 'Border radius of the card.',
             enumValues: ['none', 'sm', 'md', 'lg'],
         },
@@ -149,8 +149,10 @@ export const COMPONENT_MANIFEST = {
             name: 'status',
             type: 'enum',
             required: false,
-            description: 'Adds a 3px colored accent bar on the left edge of the card. Uses the corresponding status ' +
-                'token (successDefault, warningDefault, dangerDefault, infoDefault). Works with all variants.',
+            description: 'Adds a 3px colored inset box-shadow on the left edge of the card. Rendered as an inset shadow ' +
+                '(same technique as NavMenu inverse highlight) so it naturally follows the card\'s border-radius. ' +
+                'Uses the corresponding status token (successDefault, warningDefault, dangerDefault, infoDefault). ' +
+                'Works with all variants.',
             enumValues: ['success', 'warning', 'danger', 'info'],
         },
         {
@@ -161,13 +163,23 @@ export const COMPONENT_MANIFEST = {
                 'where cards act as radio/checkbox options. Pairs with onClick for toggle behavior. ' +
                 'Sets aria-pressed on interactive cards. Disabled takes precedence — ring is hidden when disabled.',
         },
+        {
+            name: 'hoverable',
+            type: 'boolean',
+            required: false,
+            description: 'Enables hover lift (translateY -1px) and neutral glow shadow without making the card a button or link. ' +
+                'Use when the card contains its own interactive content (e.g. a Collapsible trigger) and the whole card ' +
+                'surface should hint at interactivity. Interactive cards (onClick/href) get accent-colored hover glow; ' +
+                'hoverable-only cards get a neutral glow (12% text-primary).',
+        },
         {
             name: 'media',
             type: 'ReactNode',
             required: false,
             description: 'Full-bleed content rendered at the top of the card (before header). No padding is applied. ' +
-                'Use for hero images, illustrations, or any edge-to-edge top content. The card\'s overflow:hidden ' +
-                'clips media to the border-radius.',
+                'Use for hero images, illustrations, or any edge-to-edge top content. The media slot self-clips ' +
+                'to the card\'s top border-radius. Cards without media default to overflow:visible so nested child ' +
+                'shadows (e.g. an elevated Card inside a Collapsible) are never cut off.',
         },
     ],
     usageExamples: [
@@ -259,6 +271,24 @@ export const COMPONENT_MANIFEST = {
 >
   <Text weight="semibold">Article title</Text>
   <Text color="secondary" size="sm">A card with a full-bleed hero image.</Text>
+</Card>`,
+        },
+        {
+            title: 'CollapsibleCard recipe — outline',
+            code: `<Card variant="outline" hoverable>
+  <Collapsible trigger={<Text as="span" weight="semibold" size="sm">Filters</Text>} defaultOpen>
+    <Text size="sm" color="secondary">Card + Collapsible composed together. Collapsible auto-bleeds to card edges.</Text>
+  </Collapsible>
+</Card>`,
+        },
+        {
+            title: 'CollapsibleCard recipe — combo (filled + elevated)',
+            code: `<Card variant="filled" hoverable>
+  <Collapsible trigger={<Text as="span" weight="semibold" size="sm">Details</Text>} padded={false}>
+    <Card variant="elevated" padding="sm" style={{ margin: 'var(--lucent-space-1) var(--lucent-space-2) var(--lucent-space-2)' }}>
+      <Text size="sm" color="secondary">Two-tone: flat trigger on filled surface, content in elevated body.</Text>
+    </Card>
+  </Collapsible>
 </Card>`,
         },
     ],

package/dist-server/src/components/molecules/Collapsible/Collapsible.manifest.js

@@ -4,14 +4,26 @@ export const COMPONENT_MANIFEST = {
     tier: 'molecule',
     domain: 'neutral',
     specVersion: '0.1',
-    description: 'Animated expand/collapse container with a built-in chevron trigger and smooth height transition.',
+    description: 'Animated expand/collapse container with a built-in chevron trigger, smooth height transition, ' +
+        'and CSS-driven hover feedback.',
     designIntent: 'Collapsible hides secondary content behind a trigger button to reduce visual noise. ' +
-        'Height is animated by snapshotting scrollHeight before closing and transitioning to 0, ' +
-        'then removing the fixed height after the open transition completes so content can reflow freely. ' +
+        'Height animation uses direct DOM manipulation via useLayoutEffect to avoid React batching issues: ' +
+        'on expand, scrollHeight is snapshotted and transitioned to, then the fixed height is cleared for reflow; ' +
+        'on collapse, the current height is flushed to the DOM, a reflow is forced, then height is set to 0. ' +
+        'Content fades in/out with opacity + translateY(-4px) at 80ms, while height transitions at 180ms ' +
+        'using the easing-default token. The animated content wrapper uses overflow:hidden only during the ' +
+        'height transition and switches to overflow:visible once open, so nested child shadows (e.g. an ' +
+        'elevated Card in the combo recipe) are never clipped in the resting state.\n\n' +
         'A built-in chevron rotates 180° on open, giving clear directional affordance. ' +
+        'Hover feedback uses a CSS rule via data-lucent-collapsible-trigger (same pattern as NavMenu): ' +
+        '5% text-primary tint on the trigger background, chevron darkens to text-primary. ' +
         'The `trigger` prop accepts only label content — the chevron and button chrome are owned by the component ' +
         'so callers cannot accidentally break the expand/collapse contract. ' +
-        'The component supports controlled (open + onOpenChange) and uncontrolled (defaultOpen) modes.',
+        'The component supports controlled (open + onOpenChange) and uncontrolled (defaultOpen) modes.\n\n' +
+        '**Card-aware auto-bleed** — when placed inside a Card, Collapsible consumes CardPaddingContext and ' +
+        'applies negative margins to cancel the Card body\'s padding, so the trigger spans the full card width ' +
+        'and only the Collapsible\'s own padding applies. This means `<Card hoverable><Collapsible>` just works — ' +
+        'no `padding="none"` on Card required.',
     props: [
         {
             name: 'trigger',
@@ -44,6 +56,22 @@ export const COMPONENT_MANIFEST = {
             required: false,
             description: 'Callback fired with the new open boolean when the trigger is clicked.',
         },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Disables the trigger button. Reduces opacity, sets cursor to not-allowed, and prevents toggling.',
+        },
+        {
+            name: 'padded',
+            type: 'boolean',
+            required: false,
+            default: 'true',
+            description: 'When true (default), applies built-in content padding (space-2 top, space-4 sides, space-3 bottom). ' +
+                'Set to false when children provide their own padding — e.g. when nesting a Card inside the Collapsible ' +
+                'for the CollapsibleCard combo recipe.',
+        },
         {
             name: 'style',
             type: 'object',
@@ -72,6 +100,24 @@ export const COMPONENT_MANIFEST = {
   <Text size="sm" color="secondary">This section starts expanded.</Text>
 </Collapsible>`,
         },
+        {
+            title: 'CollapsibleCard recipe (auto-bleed)',
+            code: `<Card variant="outline" hoverable>
+  <Collapsible trigger={<Text as="span" weight="semibold" size="sm">Filters</Text>} defaultOpen>
+    <Text size="sm" color="secondary">Card + Collapsible composed together. No padding="none" needed.</Text>
+  </Collapsible>
+</Card>`,
+        },
+        {
+            title: 'CollapsibleCard combo recipe (padded={false})',
+            code: `<Card variant="filled" hoverable>
+  <Collapsible trigger={<Text as="span" weight="semibold" size="sm">Details</Text>} padded={false}>
+    <Card variant="elevated" padding="sm" style={{ margin: 'var(--lucent-space-1) var(--lucent-space-2) var(--lucent-space-2)' }}>
+      <Text size="sm" color="secondary">Nested elevated card inside a filled card.</Text>
+    </Card>
+  </Collapsible>
+</Card>`,
+        },
     ],
     compositionGraph: [],
     accessibility: {

package/dist-server/src/components/molecules/NavMenu/NavMenu.manifest.js

@@ -4,28 +4,35 @@ export const COMPONENT_MANIFEST = {
     tier: 'molecule',
     domain: 'neutral',
     specVersion: '0.1',
-    description: 'Multi-level navigation menu supporting vertical (sidebar) and horizontal (top bar) orientations with a sliding highlight pill, CSS-driven hover states, collapsible groups, and nested sub-menus.',
-    designIntent: 'NavMenu provides hierarchical navigation for sidebar and top-bar layouts. ' +
-        'A single sliding highlight pill follows the active item, driven entirely from the root via DOM measurement — ' +
-        'the root queries for data-active / data-active-parent attributes and positions an absolutely-placed pill ' +
-        'using requestAnimationFrame. MutationObserver and ResizeObserver auto-trigger re-measurement; ' +
-        'aria-hidden ancestry is used to detect collapsed items (not offsetHeight), eliminating all timeout-based coordination. ' +
-        'Hover states use a CSS rule on [data-lucent-navitem] with :not() exclusions for active, parent-active, hint, and disabled states, ' +
-        'rendering a 5% translucent text-primary tint that never conflicts with the accent pill. ' +
-        'In vertical orientation, parent items expand inline with smooth height animation (same pattern as Collapsible) ' +
-        'and children are indented by depth level. When a parent with an active child is collapsed, the pill slides ' +
-        'to the parent button with a lighter visual style (12% accent tint or surface-secondary in inverse mode) ' +
-        'so text remains readable without on-accent color. When re-expanded, the pill slides back to the child. ' +
-        'Parent items support "self-active" mode: setting isActive on a parent with no active children ' +
-        'highlights the parent with the full accent pill, useful for section-level pages that represent all children. ' +
+    description: 'Multi-level navigation menu supporting vertical (sidebar) and horizontal (top bar) orientations with a sliding highlight pill, CSS-driven hover states, collapsible section groups, and expandable tree items.',
+    designIntent: 
+    // ── Composition pattern (most important for correct usage) ──
+    'CRITICAL COMPOSITION PATTERN — There are two different nesting mechanisms that serve different purposes:\n\n' +
+        '1. NavMenu.Sub (tree nesting): Place <NavMenu.Sub> as a DIRECT CHILD of <NavMenu.Item> to make that item ' +
+        'expandable with nested children. NavMenu.Sub is a bare fragment — it accepts ONLY children, no other props ' +
+        '(no label, no icon). The parent Item auto-detects the Sub child and renders itself as a collapsible toggle ' +
+        'with expand/collapse behavior. The label, icon, and badge props all go on the parent Item, not on Sub.\n' +
+        'Example: <NavMenu.Item icon={<Gear />}>Settings<NavMenu.Sub><NavMenu.Item>General</NavMenu.Item></NavMenu.Sub></NavMenu.Item>\n\n' +
+        '2. NavMenu.Group (section grouping): Wraps multiple sibling items under an uppercase section header. ' +
+        'Groups are for visual organization — they do NOT create parent-child navigation relationships. ' +
+        'A Group with label="Admin" containing Users and Roles items means "these items are in the Admin section", ' +
+        'NOT "Admin is a parent page with Users and Roles as sub-pages". Groups have their own independent collapse.\n' +
+        'Example: <NavMenu.Group label="Admin"><NavMenu.Item>Users</NavMenu.Item><NavMenu.Item>Roles</NavMenu.Item></NavMenu.Group>\n\n' +
+        'WHEN TO USE WHICH:\n' +
+        '- Use NavMenu.Sub when an item IS a parent page with child pages (tree hierarchy, e.g. Settings → General, Team, Billing)\n' +
+        '- Use NavMenu.Group when items BELONG to a section but are all peers (flat grouping, e.g. "Admin" section containing Users, Roles)\n' +
+        '- They can be combined: a Group can contain Items that themselves have Sub children\n\n' +
+        // ── Highlight system ──
+        'SLIDING HIGHLIGHT: A single pill follows the active item, driven from the root via DOM measurement. ' +
+        'The root queries for data-active / data-active-parent attributes and positions an always-in-DOM pill ' +
+        'using requestAnimationFrame. MutationObserver + ResizeObserver auto-trigger re-measurement; ' +
+        'aria-hidden ancestry detects collapsed items. Three highlight states: ' +
+        '(1) child active — full accent pill, ' +
+        '(2) collapsed with active child — lighter pill (12% accent tint) on the parent button, ' +
+        '(3) self-active parent — full accent pill on the parent itself (isActive on parent, no active children). ' +
+        'Hover uses a CSS rule on [data-lucent-navitem] with :not() exclusions, rendering a 5% translucent tint. ' +
         'Inverse mode uses surface background with accent right-border (inset -3px) and elevation shadow. ' +
-        'The hasIcons prop controls left-padding alignment globally: when true, items use tighter padding (space-2) ' +
-        'and group headers align with icon start; sub-menu children inherit parentHasIcon via context so their ' +
-        'text aligns with the parent label text regardless of whether they have icons themselves. ' +
-        'In horizontal orientation, parent items show dropdown sub-menus on hover/click with enter/exit animation ' +
-        'and viewport collision detection. Groups are flattened in horizontal mode. ' +
-        'Three sizes (sm/md/lg) scale font, padding, gap, and icon width via a token map. ' +
-        'The compound API (NavMenu.Item, NavMenu.Group, NavMenu.Sub, NavMenu.Separator) keeps the tree declarative.',
+        'The hasIcons prop controls left-padding alignment globally for items, group headers, and sub-menu children.',
     props: [
         {
             name: 'orientation',
@@ -74,60 +81,26 @@ export const COMPONENT_MANIFEST = {
     ],
     usageExamples: [
         {
-            title: 'Vertical sidebar with icons',
-            code: `<NavMenu orientation="vertical" hasIcons>
-  <NavMenu.Item icon={<DashIcon />} href="/dashboard" isActive>Dashboard</NavMenu.Item>
-  <NavMenu.Group label="Workspace">
-    <NavMenu.Item icon={<FolderIcon />} href="/projects">Projects</NavMenu.Item>
-    <NavMenu.Item icon={<GearIcon />}>
-      Settings
-      <NavMenu.Sub>
-        <NavMenu.Item href="/settings/general" isActive>General</NavMenu.Item>
-        <NavMenu.Item href="/settings/team">Team</NavMenu.Item>
-      </NavMenu.Sub>
-    </NavMenu.Item>
-  </NavMenu.Group>
-  <NavMenu.Separator />
-  <NavMenu.Item icon={<HelpIcon />} href="/help">Help</NavMenu.Item>
-</NavMenu>`,
-            description: 'Sidebar with icons, groups, and nested sub-menu. hasIcons tightens padding so group headers align with icons ' +
-                'and sub-menu children align with parent text.',
-        },
-        {
-            title: 'Vertical sidebar without icons',
+            title: 'Expandable parent item with NavMenu.Sub (tree nesting)',
             code: `<NavMenu orientation="vertical">
   <NavMenu.Item href="/dashboard" isActive>Dashboard</NavMenu.Item>
-  <NavMenu.Group label="Workspace">
-    <NavMenu.Item href="/projects">Projects</NavMenu.Item>
-    <NavMenu.Item>
-      Settings
-      <NavMenu.Sub>
-        <NavMenu.Item href="/settings/general">General</NavMenu.Item>
-        <NavMenu.Item href="/settings/team">Team</NavMenu.Item>
-      </NavMenu.Sub>
-    </NavMenu.Item>
-  </NavMenu.Group>
-</NavMenu>`,
-            description: 'Without hasIcons, items and group headers use standard padding (space-4) for comfortable text-only layout.',
-        },
-        {
-            title: 'Horizontal top navigation',
-            code: `<NavMenu orientation="horizontal">
-  <NavMenu.Item href="/dashboard" isActive>Dashboard</NavMenu.Item>
-  <NavMenu.Item href="/projects">Projects</NavMenu.Item>
   <NavMenu.Item>
     Settings
     <NavMenu.Sub>
       <NavMenu.Item href="/settings/general">General</NavMenu.Item>
       <NavMenu.Item href="/settings/team">Team</NavMenu.Item>
+      <NavMenu.Item href="/settings/billing">Billing</NavMenu.Item>
     </NavMenu.Sub>
   </NavMenu.Item>
+  <NavMenu.Item href="/help">Help</NavMenu.Item>
 </NavMenu>`,
-            description: 'Top bar layout. Parent items show dropdown sub-menus on hover/click with viewport collision detection.',
+            description: 'NavMenu.Sub goes INSIDE a NavMenu.Item to make it expandable. The parent Item ("Settings") becomes a ' +
+                'toggle button — clicking it expands/collapses the child items. NavMenu.Sub is a bare fragment that only ' +
+                'accepts children. The label "Settings" and any icon/badge props go on the parent Item, never on Sub.',
         },
         {
-            title: 'Inverse mode with section groups',
-            code: `<NavMenu orientation="vertical" inverse>
+            title: 'Section grouping with NavMenu.Group (flat organization)',
+            code: `<NavMenu orientation="vertical">
   <NavMenu.Group label="Main">
     <NavMenu.Item href="/dashboard" isActive>Dashboard</NavMenu.Item>
     <NavMenu.Item href="/analytics">Analytics</NavMenu.Item>
@@ -138,7 +111,30 @@ export const COMPONENT_MANIFEST = {
     <NavMenu.Item href="/roles">Roles</NavMenu.Item>
   </NavMenu.Group>
 </NavMenu>`,
-            description: 'Inverse highlight: surface background with accent right-border and elevation shadow. Text stays text-primary.',
+            description: 'NavMenu.Group wraps peer items under an uppercase section header. It does NOT create a parent-child ' +
+                'navigation relationship — items inside a Group are all at the same level. Groups have their own ' +
+                'independent collapse via the label header toggle. Use Group for sections, use Sub for tree nesting.',
+        },
+        {
+            title: 'Combined: Groups containing items with Sub children',
+            code: `<NavMenu orientation="vertical" hasIcons>
+  <NavMenu.Group label="Workspace">
+    <NavMenu.Item icon={<FolderIcon />} href="/projects">Projects</NavMenu.Item>
+    <NavMenu.Item icon={<GearIcon />}>
+      Settings
+      <NavMenu.Sub>
+        <NavMenu.Item href="/settings/general" isActive>General</NavMenu.Item>
+        <NavMenu.Item href="/settings/team">Team</NavMenu.Item>
+      </NavMenu.Sub>
+    </NavMenu.Item>
+  </NavMenu.Group>
+  <NavMenu.Separator />
+  <NavMenu.Group label="Admin">
+    <NavMenu.Item icon={<UserIcon />} href="/users">Users</NavMenu.Item>
+  </NavMenu.Group>
+</NavMenu>`,
+            description: 'Groups and Sub can be combined. Here the "Workspace" Group contains a "Settings" Item with Sub children. ' +
+                'The Group provides section organization; the Sub provides tree hierarchy within an item.',
         },
         {
             title: 'Self-active parent (section-level page)',
@@ -159,16 +155,26 @@ export const COMPONENT_MANIFEST = {
     </NavMenu.Sub>
   </NavMenu.Item>
 </NavMenu>`,
-            description: 'Setting isActive on a parent with no active children gives it the full accent highlight. ' +
-                'The sub-nav expands but no child is individually selected — the parent represents all items. ' +
-                'Clicking a specific child moves the highlight to that child.',
+            description: 'Setting isActive on a parent Item (with Sub) while no child has isActive highlights the parent itself ' +
+                'with the full accent pill. The sub-nav expands but no child is individually selected — the parent ' +
+                'represents "all items in this section". Clicking a specific child moves the highlight to that child.',
+        },
+        {
+            title: 'Inverse mode',
+            code: `<NavMenu orientation="vertical" inverse>
+  <NavMenu.Group label="Main">
+    <NavMenu.Item href="/dashboard" isActive>Dashboard</NavMenu.Item>
+    <NavMenu.Item href="/analytics">Analytics</NavMenu.Item>
+  </NavMenu.Group>
+</NavMenu>`,
+            description: 'Inverse highlight: surface background with accent right-border and elevation shadow. Text stays text-primary.',
         },
         {
-            title: 'Compact sidebar (sm size)',
-            code: `<NavMenu orientation="vertical" size="sm" hasIcons>
-  <NavMenu.Item href="/dash" icon={<DashIcon />} isActive>Dashboard</NavMenu.Item>
-  <NavMenu.Item href="/projects" icon={<FolderIcon />}>Projects</NavMenu.Item>
-  <NavMenu.Item icon={<GearIcon />}>
+            title: 'Horizontal top navigation with dropdown',
+            code: `<NavMenu orientation="horizontal">
+  <NavMenu.Item href="/dashboard" isActive>Dashboard</NavMenu.Item>
+  <NavMenu.Item href="/projects">Projects</NavMenu.Item>
+  <NavMenu.Item>
     Settings
     <NavMenu.Sub>
       <NavMenu.Item href="/settings/general">General</NavMenu.Item>
@@ -176,43 +182,46 @@ export const COMPONENT_MANIFEST = {
     </NavMenu.Sub>
   </NavMenu.Item>
 </NavMenu>`,
-            description: 'Small size variant for compact sidebar layouts with tighter padding and smaller font.',
+            description: 'In horizontal orientation, Items with Sub children render as dropdown menus instead of inline expand. ' +
+                'The Sub pattern is the same — only the visual rendering changes based on orientation.',
         },
         {
-            title: 'Badges and disabled items',
+            title: 'Badges, disabled items, and polymorphic rendering',
             code: `<NavMenu orientation="vertical" hasIcons>
   <NavMenu.Item href="/inbox" icon={<InboxIcon />} badge={<Chip size="sm" variant="accent">3</Chip>}>Inbox</NavMenu.Item>
-  <NavMenu.Item href="/settings" icon={<GearIcon />} isActive>Settings</NavMenu.Item>
+  <NavMenu.Item as={Link} href="/settings" icon={<GearIcon />} isActive>Settings</NavMenu.Item>
   <NavMenu.Item href="/archive" icon={<ArchiveIcon />} disabled>Archived</NavMenu.Item>
 </NavMenu>`,
-            description: 'Items with badge counts and disabled state. Disabled items use not-allowed cursor and muted text.',
-        },
-        {
-            title: 'Polymorphic items with React Router',
-            code: `<NavMenu orientation="vertical">
-  <NavMenu.Item as={Link} href="/dashboard" isActive>Dashboard</NavMenu.Item>
-  <NavMenu.Item as={Link} href="/projects">Projects</NavMenu.Item>
-</NavMenu>`,
-            description: 'Using the "as" prop to render items as React Router Link components instead of anchor tags.',
+            description: 'Items support badge (right-aligned content), disabled state, and polymorphic rendering via the "as" prop ' +
+                '(e.g. React Router Link). Disabled items use not-allowed cursor and muted text.',
         },
     ],
     compositionGraph: [
         {
             componentId: 'nav-menu-item',
             componentName: 'NavMenu.Item',
-            role: 'Individual navigation link or parent toggle. Sets data-active when self-active, data-active-parent when collapsed with an active child. Uses data-lucent-navitem for CSS hover targeting.',
+            role: 'Navigation link or expandable parent. When it contains a NavMenu.Sub child, it automatically becomes ' +
+                'a collapsible toggle with expand/collapse behavior — the label, icon, and badge go on the Item. ' +
+                'Props: children, href, isActive, icon, badge, disabled, onClick, as, style.',
             required: true,
         },
         {
             componentId: 'nav-menu-sub',
             componentName: 'NavMenu.Sub',
-            role: 'Marker wrapper for nested sub-menu children inside a parent NavMenu.Item.',
+            role: 'Bare fragment placed as a DIRECT CHILD of NavMenu.Item to make that item expandable with nested children. ' +
+                'Accepts ONLY children — no label, icon, or other props. The parent Item detects it and switches to ' +
+                'parent-toggle rendering. In vertical orientation, children expand inline below the parent; ' +
+                'in horizontal orientation, children render as a dropdown. ' +
+                'Do NOT confuse with NavMenu.Group — Sub creates tree hierarchy, Group creates flat section organization.',
             required: false,
         },
         {
             componentId: 'nav-menu-group',
             componentName: 'NavMenu.Group',
-            role: 'Section grouping with optional uppercase label header and independent collapse. Header left padding responds to hasIcons context.',
+            role: 'Section grouping that wraps peer items under an uppercase header label. Does NOT create parent-child ' +
+                'navigation relationships — items inside are all at the same level. Has its own independent collapse. ' +
+                'Props: children, label, defaultOpen, open, onOpenChange, collapsible, style. ' +
+                'Do NOT confuse with NavMenu.Sub — Group is for flat section headers, Sub is for tree nesting inside an Item.',
             required: false,
         },
         {
@@ -226,7 +235,7 @@ export const COMPONENT_MANIFEST = {
         role: 'navigation',
         ariaAttributes: [
             'aria-label on root <nav>',
-            'aria-expanded on parent items with sub-menus',
+            'aria-expanded on parent items (Items with Sub children)',
             'aria-current="page" on active leaf items',
             'aria-disabled on disabled items',
             'aria-hidden on collapsed sub-menu content and the highlight pill',
@@ -238,7 +247,7 @@ export const COMPONENT_MANIFEST = {
             'ArrowLeft (vertical) / ArrowUp (horizontal) — collapse parent item',
             'Escape — close open sub-menu',
         ],
-        notes: 'Parent items use aria-expanded to communicate open/closed state. ' +
+        notes: 'Parent items (Items containing NavMenu.Sub) use aria-expanded to communicate open/closed state. ' +
             'Active leaf items use aria-current="page". Disabled items use aria-disabled with no click handler. ' +
             'Collapsed sections are marked aria-hidden="true", which the sliding highlight uses to detect ' +
             'visibility — items inside aria-hidden containers are skipped in favor of the parent fallback. ' +

package/dist-server/src/components/molecules/SearchInput/SearchInput.manifest.js

@@ -4,12 +4,14 @@ export const COMPONENT_MANIFEST = {
     tier: 'molecule',
     domain: 'neutral',
     specVersion: '0.1',
-    description: 'A search field with a built-in magnifier icon, clear button, and an optional results dropdown.',
+    description: 'A search field with a built-in magnifier icon, clear button, and an optional results dropdown. Use mode="filter" for a simple filter input with a funnel icon and no dropdown.',
     designIntent: 'SearchInput is intentionally dumb about filtering — the consumer passes already-filtered results ' +
         'so the component stays stateless and flexible. The clear button appears only when the input has a ' +
         'value, keeping the right side clean at rest. The results dropdown is rendered absolutely below the ' +
         'input and closes after a 150ms delay on blur to allow result clicks to register before focus is lost. ' +
-        'Spinner replaces the clear button during loading to communicate async state without layout shift.',
+        'Spinner replaces the clear button during loading to communicate async state without layout shift. ' +
+        'Use mode="filter" when you only need a text input with a funnel icon and clear button — no dropdown, ' +
+        'no results array, just a clean filter field.',
     props: [
         {
             name: 'value',
@@ -23,6 +25,14 @@ export const COMPONENT_MANIFEST = {
             required: true,
             description: 'Called with the new string value whenever the input changes.',
         },
+        {
+            name: 'mode',
+            type: 'enum',
+            required: false,
+            default: 'search',
+            description: 'Controls variant. "filter" swaps the magnifier for a funnel icon and disables the results dropdown.',
+            enumValues: ['search', 'filter'],
+        },
         {
             name: 'size',
             type: 'enum',
@@ -53,8 +63,8 @@ export const COMPONENT_MANIFEST = {
             name: 'placeholder',
             type: 'string',
             required: false,
-            default: '"Search…"',
-            description: 'Placeholder text for the input.',
+            default: '"Search…" (or "Filter…" in filter mode)',
+            description: 'Placeholder text for the input. Defaults to "Search…" in search mode and "Filter…" in filter mode.',
         },
         {
             name: 'results',
@@ -109,6 +119,10 @@ const [results, setResults] = useState([]);
   onResultSelect={(r) => console.log(r)}
 />`,
         },
+        {
+            title: 'Filter mode (no dropdown)',
+            code: `<SearchInput mode="filter" value={filter} onChange={setFilter} placeholder="Filter items…" />`,
+        },
         {
             title: 'Loading state',
             code: `<SearchInput value={query} onChange={setQuery} isLoading={isFetching} results={[]} />`,

package/dist-server/src/manifest/validate.test.js

@@ -0,0 +1,28 @@
+import { describe, test, expect } from 'vitest';
+import { validateManifest } from './validate.js';
+// Auto-discover all component manifests
+const manifestModules = import.meta.glob('../components/**/*.manifest.ts', { eager: true });
+const manifests = Object.entries(manifestModules).map(([path, mod]) => {
+    const m = mod;
+    const manifest = m['COMPONENT_MANIFEST'];
+    return { path, manifest };
+});
+describe('Component manifests', () => {
+    test('at least one manifest was discovered', () => {
+        expect(manifests.length).toBeGreaterThan(0);
+    });
+    for (const { path, manifest } of manifests) {
+        const label = path.replace('../components/', '').replace('.manifest.ts', '');
+        test(`${label} — exports COMPONENT_MANIFEST`, () => {
+            expect(manifest).toBeDefined();
+        });
+        test(`${label} — passes schema validation`, () => {
+            const result = validateManifest(manifest);
+            if (!result.valid) {
+                const messages = result.errors.map(e => `  ${e.field}: ${e.message}`).join('\n');
+                throw new Error(`Invalid manifest:\n${messages}`);
+            }
+            expect(result.valid).toBe(true);
+        });
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lucent-ui",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "An AI-first React component library with machine-readable manifests.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -25,6 +25,18 @@
     "dist-server",
     "dist-cli"
   ],
+  "scripts": {
+    "dev": "vite --config vite.dev.config.ts",
+    "build": "vite build",
+    "build:server": "tsc -p server/tsconfig.json",
+    "build:cli": "tsc -p cli/tsconfig.json && cp cli/template.manifest.json dist-cli/cli/template.manifest.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "tsc --noEmit && pnpm build && pnpm build:server && pnpm build:cli",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm prepublishOnly && changeset publish"
+  },
   "keywords": [
     "react",
     "component-library",
@@ -39,6 +51,7 @@
   },
   "author": "Rozina Szogyenyi",
   "license": "MIT",
+  "packageManager": "pnpm@10.30.3",
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
@@ -60,16 +73,5 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "zod": "^4.3.6"
-  },
-  "scripts": {
-    "dev": "vite --config vite.dev.config.ts",
-    "build": "vite build",
-    "build:server": "tsc -p server/tsconfig.json",
-    "build:cli": "tsc -p cli/tsconfig.json && cp cli/template.manifest.json dist-cli/cli/template.manifest.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "pnpm prepublishOnly && changeset publish"
   }
-}
+}