lucent-ui 0.29.0 → 0.31.0

package/dist-server/server/index.js

@@ -3,7 +3,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { ALL_MANIFESTS } from './registry.js';
-import { ALL_RECIPES } from './recipe-registry.js';
+import { ALL_PATTERNS } from './pattern-registry.js';
 import { PALETTES, SHAPES, DENSITIES, SHADOWS, COMBINED, generatePresetConfig } from './presets.js';
 // ─── Auth stub ───────────────────────────────────────────────────────────────
 // LUCENT_API_KEY is reserved for the future paid tier.
@@ -38,11 +38,11 @@ function scoreManifest(m, query) {
     }
     return score;
 }
-function findRecipe(nameOrId) {
+function findPattern(nameOrId) {
     const q = nameOrId.trim().toLowerCase();
-    return ALL_RECIPES.find((r) => r.id.toLowerCase() === q || r.name.toLowerCase() === q);
+    return ALL_PATTERNS.find((r) => r.id.toLowerCase() === q || r.name.toLowerCase() === q);
 }
-function scoreRecipe(r, query) {
+function scorePattern(r, query) {
     const q = query.toLowerCase();
     let score = 0;
     if (r.name.toLowerCase().includes(q))
@@ -110,7 +110,7 @@ server.tool('get_component_manifest', 'Returns the full manifest JSON for a Luce
     };
 });
 // Tool: search_components
-server.tool('search_components', 'Searches Lucent UI components and composition recipes by description or concept. Returns matching components and recipes ranked by relevance.', { query: z.string().describe('Natural language or keyword query, e.g. "loading indicator", "form validation", or "profile card"') }, async ({ query }) => {
+server.tool('search_components', 'Searches Lucent UI components and composition patterns by description or concept. Returns matching components and patterns ranked by relevance.', { query: z.string().describe('Natural language or keyword query, e.g. "loading indicator", "form validation", or "profile card"') }, async ({ query }) => {
     const componentResults = ALL_MANIFESTS
         .map((m) => ({ manifest: m, score: scoreManifest(m, query) }))
         .filter(({ score }) => score > 0)
@@ -122,41 +122,41 @@ server.tool('search_components', 'Searches Lucent UI components and composition
         description: manifest.description,
         score,
     }));
-    const recipeResults = ALL_RECIPES
-        .map((r) => ({ recipe: r, score: scoreRecipe(r, query) }))
+    const patternResults = ALL_PATTERNS
+        .map((r) => ({ pattern: r, score: scorePattern(r, query) }))
         .filter(({ score }) => score > 0)
         .sort((a, b) => b.score - a.score)
-        .map(({ recipe, score }) => ({
-        id: recipe.id,
-        name: recipe.name,
-        category: recipe.category,
-        description: recipe.description,
+        .map(({ pattern, score }) => ({
+        id: pattern.id,
+        name: pattern.name,
+        category: pattern.category,
+        description: pattern.description,
         score,
     }));
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({ query, components: componentResults, recipes: recipeResults }, null, 2),
+                text: JSON.stringify({ query, components: componentResults, patterns: patternResults }, null, 2),
             },
         ],
     };
 });
-// Tool: get_composition_recipe
-server.tool('get_composition_recipe', 'Returns a full composition recipe with structure tree, working JSX code, variants, and design notes. Query by recipe name/id or by category to get all recipes in that category.', {
-    name: z.string().optional().describe('Recipe name or id, e.g. "Profile Card" or "settings-panel"'),
-    category: z.string().optional().describe('Recipe category: "card", "form", "nav", "dashboard", "settings", or "action"'),
+// Tool: get_composition_pattern
+server.tool('get_composition_pattern', 'Returns a full composition pattern with structure tree, working JSX code, variants, and design notes. Query by pattern name/id or by category to get all patterns in that category.', {
+    name: z.string().optional().describe('Pattern name or id, e.g. "Profile Card" or "settings-panel"'),
+    category: z.string().optional().describe('Pattern category: "card", "form", "nav", "dashboard", "settings", or "action"'),
 }, async ({ name, category }) => {
     if (name) {
-        const recipe = findRecipe(name);
-        if (!recipe) {
+        const pattern = findPattern(name);
+        if (!pattern) {
             return {
                 content: [
                     {
                         type: 'text',
                         text: JSON.stringify({
-                            error: `Recipe "${name}" not found.`,
-                            available: ALL_RECIPES.map((r) => ({ id: r.id, name: r.name, category: r.category })),
+                            error: `Pattern "${name}" not found.`,
+                            available: ALL_PATTERNS.map((r) => ({ id: r.id, name: r.name, category: r.category })),
                         }),
                     },
                 ],
@@ -167,22 +167,22 @@ server.tool('get_composition_recipe', 'Returns a full composition recipe with st
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify(recipe, null, 2),
+                    text: JSON.stringify(pattern, null, 2),
                 },
             ],
         };
     }
     if (category) {
         const cat = category.trim().toLowerCase();
-        const recipes = ALL_RECIPES.filter((r) => r.category === cat);
-        if (recipes.length === 0) {
+        const patterns = ALL_PATTERNS.filter((r) => r.category === cat);
+        if (patterns.length === 0) {
             return {
                 content: [
                     {
                         type: 'text',
                         text: JSON.stringify({
-                            error: `No recipes found in category "${category}".`,
-                            availableCategories: [...new Set(ALL_RECIPES.map((r) => r.category))],
+                            error: `No patterns found in category "${category}".`,
+                            availableCategories: [...new Set(ALL_PATTERNS.map((r) => r.category))],
                         }),
                     },
                 ],
@@ -193,18 +193,18 @@ server.tool('get_composition_recipe', 'Returns a full composition recipe with st
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify({ category: cat, recipes }, null, 2),
+                    text: JSON.stringify({ category: cat, patterns }, null, 2),
                 },
             ],
         };
     }
-    // No filter — return all recipes
+    // No filter — return all patterns
     return {
         content: [
             {
                 type: 'text',
                 text: JSON.stringify({
-                    recipes: ALL_RECIPES.map((r) => ({
+                    patterns: ALL_PATTERNS.map((r) => ({
                         id: r.id,
                         name: r.name,
                         category: r.category,

package/dist-server/server/pattern-registry.js

@@ -0,0 +1,18 @@
+import { PATTERN as ProfileCard } from '../src/manifest/patterns/profile-card.pattern.js';
+import { PATTERN as SettingsPanel } from '../src/manifest/patterns/settings-panel.pattern.js';
+import { PATTERN as StatsRow } from '../src/manifest/patterns/stats-row.pattern.js';
+import { PATTERN as ActionBar } from '../src/manifest/patterns/action-bar.pattern.js';
+import { PATTERN as FormLayout } from '../src/manifest/patterns/form-layout.pattern.js';
+import { PATTERN as EmptyStateCard } from '../src/manifest/patterns/empty-state-card.pattern.js';
+import { PATTERN as CollapsibleCard } from '../src/manifest/patterns/collapsible-card.pattern.js';
+import { PATTERN as SearchFilterBar } from '../src/manifest/patterns/search-filter-bar.pattern.js';
+export const ALL_PATTERNS = [
+    ProfileCard,
+    SettingsPanel,
+    StatsRow,
+    ActionBar,
+    FormLayout,
+    EmptyStateCard,
+    CollapsibleCard,
+    SearchFilterBar,
+];

package/dist-server/server/registry.js

@@ -22,6 +22,10 @@ import { COMPONENT_MANIFEST as EmptyState } from '../src/components/molecules/Em
 import { COMPONENT_MANIFEST as FormField } from '../src/components/molecules/FormField/FormField.manifest.js';
 import { COMPONENT_MANIFEST as SearchInput } from '../src/components/molecules/SearchInput/SearchInput.manifest.js';
 import { COMPONENT_MANIFEST as Skeleton } from '../src/components/molecules/Skeleton/Skeleton.manifest.js';
+import { COMPONENT_MANIFEST as FilterSearch } from '../src/components/molecules/FilterSearch/FilterSearch.manifest.js';
+import { COMPONENT_MANIFEST as FilterSelect } from '../src/components/molecules/FilterSelect/FilterSelect.manifest.js';
+import { COMPONENT_MANIFEST as FilterMultiSelect } from '../src/components/molecules/FilterMultiSelect/FilterMultiSelect.manifest.js';
+import { COMPONENT_MANIFEST as FilterDateRange } from '../src/components/molecules/FilterDateRange/FilterDateRange.manifest.js';
 export const ALL_MANIFESTS = [
     // Atoms
     Avatar,
@@ -47,4 +51,8 @@ export const ALL_MANIFESTS = [
     FormField,
     SearchInput,
     Skeleton,
+    FilterSearch,
+    FilterSelect,
+    FilterMultiSelect,
+    FilterDateRange,
 ];

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

@@ -274,7 +274,7 @@ export const COMPONENT_MANIFEST = {
 </Card>`,
         },
         {
-            title: 'CollapsibleCard recipe — outline',
+            title: 'CollapsibleCard pattern — 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>
@@ -282,7 +282,7 @@ export const COMPONENT_MANIFEST = {
 </Card>`,
         },
         {
-            title: 'CollapsibleCard recipe — combo (filled + elevated)',
+            title: 'CollapsibleCard pattern — 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)' }}>

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

@@ -13,7 +13,7 @@ export const COMPONENT_MANIFEST = {
         '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' +
+        'elevated Card in the combo pattern) 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. ' +
@@ -70,7 +70,7 @@ export const COMPONENT_MANIFEST = {
             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.',
+                'for the CollapsibleCard combo pattern.',
         },
         {
             name: 'style',
@@ -101,7 +101,7 @@ export const COMPONENT_MANIFEST = {
 </Collapsible>`,
         },
         {
-            title: 'CollapsibleCard recipe (auto-bleed)',
+            title: 'CollapsibleCard pattern (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>
@@ -109,7 +109,7 @@ export const COMPONENT_MANIFEST = {
 </Card>`,
         },
         {
-            title: 'CollapsibleCard combo recipe (padded={false})',
+            title: 'CollapsibleCard combo pattern (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)' }}>

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

@@ -0,0 +1,46 @@
+export const COMPONENT_MANIFEST = {
+    id: 'filter-date-range',
+    name: 'FilterDateRange',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A compact date range filter button that opens a dual-calendar DateRangePicker popover. Shows the formatted range in the trigger when active.',
+    designIntent: 'FilterDateRange wraps DateRangePicker with a Button trigger instead of the default input-style trigger. ' +
+        'When no range is selected, the button shows the label prop. When a range is set, it shows "start → end" dates. ' +
+        'The outline variant starts as an outlined button and upgrades to secondary when a range is selected. ' +
+        'Use in filter bars alongside FilterSearch, FilterSelect, and FilterMultiSelect for date-based filtering.',
+    props: [
+        { name: 'label', type: 'string', required: false, default: '"Date range"', description: 'Text shown on the trigger button when no range is selected.' },
+        { name: 'value', type: 'object', required: false, description: 'Controlled DateRange value ({ start: Date, end: Date }).' },
+        { name: 'defaultValue', type: 'object', required: false, description: 'Initial range for uncontrolled usage.' },
+        { name: 'onChange', type: 'function', required: false, description: 'Called with the selected DateRange.' },
+        { name: 'variant', type: 'enum', required: false, default: 'secondary', description: 'Button style. "outline" switches to "secondary" when a range is selected.', enumValues: ['secondary', 'outline'] },
+        { name: 'size', type: 'enum', required: false, default: 'sm', description: 'Controls button height and calendar scale.', enumValues: ['sm', 'md', 'lg'] },
+        { name: 'min', type: 'object', required: false, description: 'Earliest selectable date.' },
+        { name: 'max', type: 'object', required: false, description: 'Latest selectable date.' },
+        { name: 'disabled', type: 'boolean', required: false, default: 'false', description: 'Disables the trigger button.' },
+        { name: 'style', type: 'object', required: false, description: 'Inline style overrides.' },
+    ],
+    usageExamples: [
+        { title: 'Basic', code: `<FilterDateRange label="Date added" />` },
+        {
+            title: 'Controlled',
+            code: `const [range, setRange] = useState<DateRange | undefined>();
+<FilterDateRange label="Date range" value={range} onChange={setRange} />`,
+        },
+        { title: 'Outline variant', code: `<FilterDateRange label="Date range" variant="outline" />` },
+        {
+            title: 'With min/max',
+            code: `<FilterDateRange label="Period" min={new Date(2026, 0, 1)} max={new Date(2026, 11, 31)} />`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'button', componentName: 'Button', role: 'Trigger button with chevron', required: true },
+        { componentId: 'date-range-picker', componentName: 'DateRangePicker', role: 'Dual-calendar popover', required: true },
+    ],
+    accessibility: {
+        role: 'group',
+        keyboardInteractions: ['Enter / Space to open calendar', 'Escape to close', 'Arrow keys to navigate calendar days'],
+        notes: 'Delegates to DateRangePicker for full calendar keyboard navigation and aria-haspopup="dialog".',
+    },
+};

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

@@ -0,0 +1,66 @@
+export const COMPONENT_MANIFEST = {
+    id: 'filter-multi-select',
+    name: 'FilterMultiSelect',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A compact multi-select filter button with a dropdown panel of checkbox items, accent count badge, optional color swatches, and a "Clear all" footer.',
+    designIntent: 'FilterMultiSelect encapsulates the full multi-select filter pattern into a single component. ' +
+        'The trigger button shows the label plus an accent Chip with the selection count when items are active. ' +
+        'The dropdown stays open on toggle so users can check multiple items without reopening. ' +
+        'Each option renders a Checkbox for selection state; when a swatch color is provided, the label renders as a Chip with a colored dot. ' +
+        'An always-visible "Clear all" footer (disabled when nothing is selected) lets users reset without an external button. ' +
+        'The outline variant starts as an outlined button and upgrades to secondary when items are checked. ' +
+        'This replaces the verbose pattern of manually wiring Menu open state, keepOpen hacks, and count badges.',
+    props: [
+        { name: 'label', type: 'string', required: true, description: 'Text shown on the trigger button.' },
+        { name: 'options', type: 'array', required: true, description: 'Array of { value, label, swatch?, disabled? } option objects.' },
+        { name: 'value', type: 'array', required: false, description: 'Controlled array of selected values.' },
+        { name: 'defaultValue', type: 'array', required: false, default: '[]', description: 'Initial selected values for uncontrolled usage.' },
+        { name: 'onChange', type: 'function', required: false, description: 'Called with the updated array of selected values on each change.' },
+        { name: 'variant', type: 'enum', required: false, default: 'secondary', description: 'Button style. "outline" switches to "secondary" when items are selected.', enumValues: ['secondary', 'outline'] },
+        { name: 'size', type: 'enum', required: false, default: 'sm', description: 'Controls button, checkbox, and chip size.', enumValues: ['sm', 'md', 'lg'] },
+        { name: 'disabled', type: 'boolean', required: false, default: 'false', description: 'Disables the trigger button.' },
+        { name: 'icon', type: 'ReactNode', required: false, description: 'Icon rendered before the label via leftIcon on the trigger button.' },
+        { name: 'style', type: 'object', required: false, description: 'Inline style overrides for the outer wrapper.' },
+    ],
+    usageExamples: [
+        {
+            title: 'Tags with swatches',
+            code: `<FilterMultiSelect label="Tags" options={[
+  { value: 'react', label: 'React', swatch: '#3b82f6' },
+  { value: 'devops', label: 'DevOps', swatch: '#10b981' },
+  { value: 'data', label: 'Data Science', swatch: '#6366f1' },
+]} />`,
+        },
+        {
+            title: 'Plain labels',
+            code: `<FilterMultiSelect label="Status" options={[
+  { value: 'active', label: 'Active' },
+  { value: 'archived', label: 'Archived' },
+  { value: 'on-hold', label: 'On hold' },
+]} />`,
+        },
+        {
+            title: 'Outline variant',
+            code: `<FilterMultiSelect label="Tags" variant="outline" options={tagOptions} />`,
+        },
+        {
+            title: 'Controlled',
+            code: `const [tags, setTags] = useState<string[]>([]);
+<FilterMultiSelect label="Tags" value={tags} onChange={setTags} options={tagOptions} />`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'button', componentName: 'Button', role: 'Trigger button with chevron and count badge', required: true },
+        { componentId: 'chip', componentName: 'Chip', role: 'Count badge in trigger and swatch labels in dropdown', required: true },
+        { componentId: 'checkbox', componentName: 'Checkbox', role: 'Selection indicator per option row', required: true },
+        { componentId: 'text', componentName: 'Text', role: 'Plain option labels and Clear all footer', required: true },
+    ],
+    accessibility: {
+        role: 'listbox',
+        ariaAttributes: ['aria-multiselectable', 'aria-selected', 'aria-disabled', 'aria-label'],
+        keyboardInteractions: ['↑↓ to navigate options', 'Enter / Space to toggle selection', 'Escape to close'],
+        notes: 'The dropdown panel has role="listbox" with aria-multiselectable. Each option has role="option" with aria-selected.',
+    },
+};

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

@@ -0,0 +1,37 @@
+export const COMPONENT_MANIFEST = {
+    id: 'filter-search',
+    name: 'FilterSearch',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A collapsible search button that expands into a text input on click and collapses back when blurred empty.',
+    designIntent: 'FilterSearch saves toolbar space by rendering as a compact square icon button until the user needs it. ' +
+        'Clicking expands to a full Input with autofocus. Blurring with an empty value collapses it back. ' +
+        'If a value is present the input stays expanded so the user can see their active search. ' +
+        'Use in filter bars above DataTables and lists where search is secondary to structured filters.',
+    props: [
+        { name: 'value', type: 'string', required: false, description: 'Controlled search value.' },
+        { name: 'defaultValue', type: 'string', required: false, default: '""', description: 'Initial value for uncontrolled usage.' },
+        { name: 'onChange', type: 'function', required: false, description: 'Called with the current input value on each keystroke.' },
+        { name: 'placeholder', type: 'string', required: false, default: '"Search…"', description: 'Placeholder shown in the expanded input.' },
+        { name: 'variant', type: 'enum', required: false, default: 'secondary', description: 'Button style when collapsed.', enumValues: ['secondary', 'outline'] },
+        { name: 'size', type: 'enum', required: false, default: 'sm', description: 'Controls button and input height.', enumValues: ['sm', 'md', 'lg'] },
+        { name: 'width', type: 'number', required: false, default: '260', description: 'Width of the expanded input in pixels.' },
+        { name: 'disabled', type: 'boolean', required: false, default: 'false', description: 'Disables the button and input.' },
+        { name: 'style', type: 'object', required: false, description: 'Inline style overrides.' },
+    ],
+    usageExamples: [
+        { title: 'Basic', code: `<FilterSearch placeholder="Search candidates…" />` },
+        { title: 'Controlled', code: `const [q, setQ] = useState('');\n<FilterSearch value={q} onChange={setQ} />` },
+        { title: 'Outline variant', code: `<FilterSearch variant="outline" />` },
+    ],
+    compositionGraph: [
+        { componentId: 'button', componentName: 'Button', role: 'Collapsed icon trigger', required: true },
+        { componentId: 'input', componentName: 'Input', role: 'Expanded text field', required: true },
+    ],
+    accessibility: {
+        role: 'search',
+        keyboardInteractions: ['Enter / Space on icon button expands to input', 'Escape or blur with empty value collapses back'],
+        notes: 'The collapsed button has aria-label="Search". The expanded input receives autofocus.',
+    },
+};

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

@@ -0,0 +1,58 @@
+export const COMPONENT_MANIFEST = {
+    id: 'filter-select',
+    name: 'FilterSelect',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A compact single-select filter button that opens a Menu dropdown. Shows the selected label in the trigger and a "Clear" footer when active.',
+    designIntent: 'FilterSelect wraps Button + Menu into a self-contained single-select filter. ' +
+        'The trigger shows the label prop when nothing is selected and switches to the selected option label when active. ' +
+        'A "Clear" footer appears when a value is selected so the user can reset without an external clear button. ' +
+        'The outline variant starts as an outlined button and upgrades to secondary when a value is picked, ' +
+        'giving a visual signal that the filter is active. ' +
+        'Use for sort controls, single-category filters, and any exclusive-choice filter in a toolbar.',
+    props: [
+        { name: 'label', type: 'string', required: true, description: 'Text shown on the trigger button when no value is selected.' },
+        { name: 'options', type: 'array', required: true, description: 'Array of { value, label, disabled? } option objects.' },
+        { name: 'value', type: 'string', required: false, description: 'Controlled selected value.' },
+        { name: 'defaultValue', type: 'string', required: false, description: 'Initial value for uncontrolled usage.' },
+        { name: 'onChange', type: 'function', required: false, description: 'Called with the selected value, or undefined when cleared.' },
+        { name: 'variant', type: 'enum', required: false, default: 'secondary', description: 'Button style. "outline" switches to "secondary" when a value is selected.', enumValues: ['secondary', 'outline'] },
+        { name: 'size', type: 'enum', required: false, default: 'sm', description: 'Controls button and menu item size.', enumValues: ['sm', 'md', 'lg'] },
+        { name: 'disabled', type: 'boolean', required: false, default: 'false', description: 'Disables the trigger button.' },
+        { name: 'icon', type: 'ReactNode', required: false, description: 'Icon rendered before the label via leftIcon on the trigger button.' },
+        { name: 'style', type: 'object', required: false, description: 'Inline style overrides for the Menu wrapper.' },
+    ],
+    usageExamples: [
+        {
+            title: 'Sort control',
+            code: `<FilterSelect label="Newest first" icon={<SortIcon />} options={[
+  { value: 'newest', label: 'Newest first' },
+  { value: 'oldest', label: 'Oldest first' },
+  { value: 'name', label: 'Name A–Z' },
+]} />`,
+        },
+        {
+            title: 'Outline variant',
+            code: `<FilterSelect label="Availability" variant="outline" options={[
+  { value: 'available', label: 'Available' },
+  { value: 'unavailable', label: 'Unavailable' },
+]} />`,
+        },
+        {
+            title: 'Controlled',
+            code: `const [sort, setSort] = useState<string | undefined>();
+<FilterSelect label="Sort" value={sort} onChange={setSort} options={sortOptions} />`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'button', componentName: 'Button', role: 'Trigger button with chevron', required: true },
+        { componentId: 'menu', componentName: 'Menu', role: 'Dropdown popover', required: true },
+        { componentId: 'text', componentName: 'Text', role: 'Clear footer label', required: true },
+    ],
+    accessibility: {
+        role: 'listbox',
+        keyboardInteractions: ['Arrow keys to navigate', 'Enter / Space to select', 'Escape to close'],
+        notes: 'Delegates to Menu for full WAI-ARIA menu button keyboard navigation.',
+    },
+};

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

@@ -0,0 +1,115 @@
+export const COMPONENT_MANIFEST = {
+    id: 'stepper',
+    name: 'Stepper',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A step indicator for multi-step flows — onboarding, wizards, checkout. Supports horizontal and vertical orientations with animated transitions.',
+    designIntent: 'Use Stepper to visualise progress through a sequence of discrete steps. ' +
+        'Steps can be simple strings or objects with label, description, and custom icon. ' +
+        'Completed steps show an animated checkmark (spring scale 0→1.2→1), the current step ' +
+        'is highlighted with accent, and future steps are subdued. In horizontal mode the connector ' +
+        'track runs behind all circles as a continuous bar; the filled portion animates smoothly ' +
+        'between steps. First/last labels align left/right; middle labels center under their circles. ' +
+        'Enable numbered to show "STEP N" prefixes and showStatus for Completed/In Progress/Pending ' +
+        'Chip badges (success/accent/neutral variants). The vertical orientation suits sidebar layouts ' +
+        'and forms with longer descriptive steps. ' +
+        'Unlike Progress, Stepper is for discrete named stages, not continuous percentages.',
+    props: [
+        {
+            name: 'steps',
+            type: 'array',
+            required: true,
+            description: 'Step definitions. Each element is either a string (used as label) or an object ' +
+                '{ label: string, description?: string, icon?: ReactNode }. Custom icons override ' +
+                'the default number/checkmark in the circle.',
+        },
+        { name: 'current', type: 'number', required: true, description: 'Zero-based index of the active step. Steps before this index show as completed; steps after show as pending.' },
+        { name: 'size', type: 'enum', required: false, default: 'md', description: 'Controls circle diameter (sm=24, md=32, lg=40), checkmark size, connector thickness, and label font size.', enumValues: ['sm', 'md', 'lg'] },
+        { name: 'orientation', type: 'enum', required: false, default: 'horizontal', description: 'Layout direction. Horizontal shows circles in a row with a connector track behind them; vertical stacks them with a connector column on the left.', enumValues: ['horizontal', 'vertical'] },
+        { name: 'numbered', type: 'boolean', required: false, default: 'false', description: 'Show uppercase "STEP N" prefix above each step label.' },
+        { name: 'showStatus', type: 'boolean', required: false, default: 'false', description: 'Show a Chip badge below each label — "Completed" (success), "In Progress" (accent), or "Pending" (neutral).' },
+        { name: 'style', type: 'object', required: false, description: 'Inline style overrides for the root container.' },
+    ],
+    usageExamples: [
+        {
+            title: 'Basic horizontal',
+            code: `<Stepper steps={['Profile', 'Preferences', 'Confirm']} current={1} />`,
+            description: 'Minimal stepper — string labels, no extras.',
+        },
+        {
+            title: 'Numbered with status badges',
+            code: `<Stepper
+  steps={['Basic Details', 'Company Details', 'Subscription', 'Payment']}
+  current={2}
+  numbered
+  showStatus
+/>`,
+            description: 'STEP N prefixes and Completed/In Progress/Pending chips.',
+        },
+        {
+            title: 'Large size',
+            code: `<Stepper steps={['Cart', 'Shipping', 'Payment']} current={2} size="lg" showStatus />`,
+            description: 'Larger circles and text for prominent placement.',
+        },
+        {
+            title: 'Vertical with descriptions',
+            code: `<Stepper
+  orientation="vertical"
+  numbered
+  showStatus
+  size="lg"
+  current={1}
+  steps={[
+    { label: 'Basic Details', description: 'Name, email, and contact info' },
+    { label: 'Company Details', description: 'Organization and team size' },
+    { label: 'Subscription Plan', description: 'Choose your plan and billing' },
+    { label: 'Payment Details', description: 'Card information and billing address' },
+  ]}
+/>`,
+            description: 'Vertical layout with step descriptions for sidebar or form flows.',
+        },
+        {
+            title: 'Custom icons',
+            code: `<Stepper
+  current={1}
+  steps={[
+    { label: 'Cart', icon: <CartIcon /> },
+    { label: 'Shipping', icon: <TruckIcon /> },
+    { label: 'Payment', icon: <CreditCardIcon /> },
+  ]}
+/>`,
+            description: 'Custom icon per step overrides the default number/checkmark.',
+        },
+        {
+            title: 'In onboarding flow',
+            code: `const [step, setStep] = useState(0);
+
+<Card variant="elevated" padding="lg">
+  <Stack gap="6">
+    <Stepper steps={['Profile', 'Preferences', 'Confirm']} current={step} />
+    <Divider />
+    {/* Step content */}
+    <Row justify="between">
+      <Button variant="ghost" size="sm" onClick={() => setStep(s => s - 1)} disabled={step === 0}>Back</Button>
+      <Button variant="primary" size="sm" onClick={() => setStep(s => s + 1)}>Continue</Button>
+    </Row>
+  </Stack>
+</Card>`,
+            description: 'Stepper paired with step content and navigation buttons inside a Card.',
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'chip', componentName: 'Chip', role: 'Status badge for each step (Completed/In Progress/Pending)', required: false },
+    ],
+    accessibility: {
+        role: 'group',
+        ariaAttributes: ['aria-label', 'aria-current'],
+        keyboardInteractions: [],
+        notes: 'Root element has role="group" with aria-label="Progress steps". ' +
+            'The current step circle receives aria-current="step" so screen readers ' +
+            'can identify which step is active. Step labels are visible text, not aria-only. ' +
+            'The checkmark animation uses prefers-reduced-motion: the spring scale is purely ' +
+            'decorative and does not affect content comprehension.',
+    },
+};