lucent-ui 0.30.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/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/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.',
+    },
+};

package/dist-server/src/manifest/{recipes/action-bar.recipe.js → patterns/action-bar.pattern.js}

@@ -1,4 +1,4 @@
-export const RECIPE = {
+export const PATTERN = {
     id: 'action-bar',
     name: 'Action Bar',
     description: 'Page-level or card-level header pairing a title with action buttons. Page headers use breadcrumb, large display title, and a divider below; card headers are compact with small text.',

package/dist-server/src/manifest/{recipes/collapsible-card.recipe.js → patterns/collapsible-card.pattern.js}

@@ -1,4 +1,4 @@
-export const RECIPE = {
+export const PATTERN = {
     id: 'collapsible-card',
     name: 'Collapsible Card',
     description: 'Card with an expandable/collapsible section using smooth height animation, available in all card variants.',

package/dist-server/src/manifest/patterns/dashboard-header.pattern.js

@@ -0,0 +1,98 @@
+export const PATTERN = {
+    id: 'dashboard-header',
+    name: 'Dashboard Header',
+    description: 'Full dashboard header combining breadcrumb navigation, page title with action buttons, and a row of KPI stat cards with trend indicators.',
+    category: 'dashboard',
+    components: ['text', 'button', 'chip', 'card', 'stack', 'row', 'breadcrumb', 'divider'],
+    structure: `
+Stack gap="5"
+├── Stack gap="4"                             ← action bar
+│   ├── Breadcrumb                            ← navigation context
+│   ├── Row justify="between" align="end"
+│   │   ├── Stack gap="1"
+│   │   │   ├── Text (h1, 3xl, bold, display) ← page title
+│   │   │   └── Text (sm, secondary)          ← subtitle
+│   │   └── Row gap="2"
+│   │       ├── Button (outline, sm, leftIcon) ← Export
+│   │       └── Button (primary, sm, leftIcon) ← New report
+│   └── Divider
+└── Row gap="3" wrap                          ← stats row
+    └── Card[] (outline, padding="md", flex=1)
+        └── Stack gap="3"
+            ├── Text (xs, secondary, medium)   ← metric label
+            ├── Text (2xl, bold, display)      ← value
+            └── Row gap="2" align="center"
+                ├── Chip (success/danger, sm, borderless) ← trend
+                └── Text (xs, secondary)       ← comparison
+  `.trim(),
+    code: `<Stack gap="5" style={{ maxWidth: 860 }}>
+  <Stack gap="4">
+    <Breadcrumb items={[
+      { label: 'Home', href: '#' },
+      { label: 'Analytics', href: '#' },
+      { label: 'Overview' },
+    ]} />
+    <Row justify="between" align="end">
+      <Stack gap="1">
+        <Text as="h1" size="3xl" weight="bold" family="display">Analytics Overview</Text>
+        <Text size="sm" color="secondary">Last updated 5 minutes ago</Text>
+      </Stack>
+      <Row gap="2">
+        <Button variant="outline" size="sm" leftIcon={<DownloadIcon />}>Export</Button>
+        <Button variant="primary" size="sm" leftIcon={<PlusIcon />}>New report</Button>
+      </Row>
+    </Row>
+    <Divider />
+  </Stack>
+  <Row gap="3" wrap>
+    <Card variant="outline" padding="md" style={{ flex: 1, minWidth: 180 }}>
+      <Stack gap="3">
+        <Text size="xs" color="secondary" weight="medium">Total Visitors</Text>
+        <Text size="2xl" weight="bold" family="display">24.8k</Text>
+        <Row gap="2" align="center">
+          <Chip variant="success" size="sm" borderless>+18%</Chip>
+          <Text size="xs" color="secondary">20.9k last month</Text>
+        </Row>
+      </Stack>
+    </Card>
+    <Card variant="outline" padding="md" style={{ flex: 1, minWidth: 180 }}>
+      <Stack gap="3">
+        <Text size="xs" color="secondary" weight="medium">Conversion Rate</Text>
+        <Text size="2xl" weight="bold" family="display">3.24%</Text>
+        <Row gap="2" align="center">
+          <Chip variant="success" size="sm" borderless>+0.4%</Chip>
+          <Text size="xs" color="secondary">2.84% last month</Text>
+        </Row>
+      </Stack>
+    </Card>
+    <Card variant="outline" padding="md" style={{ flex: 1, minWidth: 180 }}>
+      <Stack gap="3">
+        <Text size="xs" color="secondary" weight="medium">Avg. Session</Text>
+        <Text size="2xl" weight="bold" family="display">4m 32s</Text>
+        <Row gap="2" align="center">
+          <Chip variant="danger" size="sm" borderless>-12%</Chip>
+          <Text size="xs" color="secondary">5m 08s last month</Text>
+        </Row>
+      </Stack>
+    </Card>
+    <Card variant="outline" padding="md" style={{ flex: 1, minWidth: 180 }}>
+      <Stack gap="3">
+        <Text size="xs" color="secondary" weight="medium">Revenue</Text>
+        <Text size="2xl" weight="bold" family="display">$48.2k</Text>
+        <Row gap="2" align="center">
+          <Chip variant="success" size="sm" borderless>+24%</Chip>
+          <Text size="xs" color="secondary">$38.9k last month</Text>
+        </Row>
+      </Stack>
+    </Card>
+  </Row>
+</Stack>`,
+    designNotes: 'This composition combines two common dashboard patterns: the ActionBar and StatsRow. ' +
+        'The breadcrumb provides navigation context above the title. align="end" on the ' +
+        'title row anchors the action buttons to the baseline of the subtitle. Button ' +
+        'leftIcon props add visual affordance to Export (download icon) and New report ' +
+        '(plus icon). The Divider separates the header chrome from the metric content below. ' +
+        'Stat cards use flex: 1 with minWidth: 180 for responsive equal sizing. Display font ' +
+        'on metric values creates instant visual hierarchy. Trend chips use success/danger ' +
+        'variants with borderless styling so they read as inline metadata, not interactive tags.',
+};

package/dist-server/src/manifest/{recipes/empty-state-card.recipe.js → patterns/empty-state-card.pattern.js}

@@ -1,4 +1,4 @@
-export const RECIPE = {
+export const PATTERN = {
     id: 'empty-state-card',
     name: 'Empty State Card',
     description: 'Centered empty state with illustration icon, heading, description, and call-to-action button inside a card.',

package/dist-server/src/manifest/{recipes/form-layout.recipe.js → patterns/form-layout.pattern.js}

@@ -1,4 +1,4 @@
-export const RECIPE = {
+export const PATTERN = {
     id: 'form-layout',
     name: 'Form Layout',
     description: 'Stacked form with grouped sections, FormField labels, validation hints, and a submit/cancel footer.',

package/dist-server/src/manifest/patterns/index.js

@@ -0,0 +1,12 @@
+export { PATTERN as ProfileCard } from './profile-card.pattern.js';
+export { PATTERN as SettingsPanel } from './settings-panel.pattern.js';
+export { PATTERN as StatsRow } from './stats-row.pattern.js';
+export { PATTERN as ActionBar } from './action-bar.pattern.js';
+export { PATTERN as FormLayout } from './form-layout.pattern.js';
+export { PATTERN as EmptyStateCard } from './empty-state-card.pattern.js';
+export { PATTERN as CollapsibleCard } from './collapsible-card.pattern.js';
+export { PATTERN as SearchFilterBar } from './search-filter-bar.pattern.js';
+export { PATTERN as PricingTable } from './pricing-table.pattern.js';
+export { PATTERN as NotificationFeed } from './notification-feed.pattern.js';
+export { PATTERN as OnboardingFlow } from './onboarding-flow.pattern.js';
+export { PATTERN as DashboardHeader } from './dashboard-header.pattern.js';

package/dist-server/src/manifest/patterns/notification-feed.pattern.js

@@ -0,0 +1,91 @@
+export const PATTERN = {
+    id: 'notification-feed',
+    name: 'Notification Feed',
+    description: 'Scrollable list of notification items with avatar, message, timestamp, type chip, and contextual action buttons. Unread items are visually distinct.',
+    category: 'card',
+    components: ['card', 'avatar', 'text', 'chip', 'button', 'stack', 'row'],
+    structure: `
+Card (elevated, padding via style)
+└── Stack gap="3"
+    ├── Row justify="between" align="center"  ← header
+    │   ├── Row gap="2" align="center"
+    │   │   ├── Text (lg, semibold)           ← title
+    │   │   └── Chip (accent, sm)             ← unread count
+    │   └── Button (ghost, xs)                ← mark all read
+    └── Stack gap="2"                         ← notification list
+        └── Card[] (filled for unread, ghost for read)
+            └── Row gap="3" align="start" justify="between"
+                ├── Row gap="3" align="start"
+                │   ├── Avatar (sm)
+                │   └── Stack gap="1"
+                │       ├── Text (sm)         ← message with bold name + target
+                │       └── Row gap="2"
+                │           ├── Chip (type-colored, sm, borderless)
+                │           └── Text (xs, secondary) ← timestamp
+                └── Row gap="1"               ← actions
+                    ├── Button? (primary/outline, xs) ← contextual
+                    └── Button (ghost, xs)     ← dismiss
+  `.trim(),
+    code: `<Card variant="elevated" padding="none" style={{ width: 520, padding: 'var(--lucent-space-4)' }}>
+  <Stack gap="3">
+    <Row justify="between" align="center" style={{ padding: '0 var(--lucent-space-2)' }}>
+      <Row gap="2" align="center">
+        <Text size="lg" weight="semibold">Notifications</Text>
+        <Chip variant="accent" size="sm">3 new</Chip>
+      </Row>
+      <Button variant="ghost" size="xs">Mark all read</Button>
+    </Row>
+    <Stack gap="2">
+      <Card variant="filled" padding="md" style={{ borderLeft: '3px solid var(--lucent-accent-default)' }}>
+        <Row gap="3" align="start" justify="between">
+          <Row gap="3" align="start" style={{ flex: 1, minWidth: 0 }}>
+            <Avatar alt="Alice Chen" size="sm" />
+            <Stack gap="1" style={{ flex: 1, minWidth: 0 }}>
+              <Text size="sm">
+                <Text as="span" size="sm" weight="semibold">Alice Chen</Text>
+                {' '}mentioned you in{' '}
+                <Text as="span" size="sm" weight="medium">Design system roadmap</Text>
+              </Text>
+              <Row gap="2" align="center">
+                <Chip variant="accent" size="sm" borderless>Mention</Chip>
+                <Text size="xs" color="secondary">2 min ago</Text>
+              </Row>
+            </Stack>
+          </Row>
+          <Button variant="ghost" size="xs">Dismiss</Button>
+        </Row>
+      </Card>
+      <Card variant="ghost" padding="md">
+        <Row gap="3" align="start" justify="between">
+          <Row gap="3" align="start" style={{ flex: 1, minWidth: 0 }}>
+            <Avatar alt="Carol Park" size="sm" />
+            <Stack gap="1" style={{ flex: 1, minWidth: 0 }}>
+              <Text size="sm">
+                <Text as="span" size="sm" weight="semibold">Carol Park</Text>
+                {' '}requested your review on{' '}
+                <Text as="span" size="sm" weight="medium">PR #139: Add Slider atom</Text>
+              </Text>
+              <Row gap="2" align="center">
+                <Chip variant="warning" size="sm" borderless>Review</Chip>
+                <Text size="xs" color="secondary">1 hour ago</Text>
+              </Row>
+            </Stack>
+          </Row>
+          <Row gap="1">
+            <Button variant="primary" size="xs">Review</Button>
+            <Button variant="ghost" size="xs">Dismiss</Button>
+          </Row>
+        </Row>
+      </Card>
+    </Stack>
+  </Stack>
+</Card>`,
+    designNotes: 'Unread notifications use Card variant="filled" with an accent left border to create ' +
+        'a visual distinction from read items (variant="ghost"). The accent border is a ' +
+        'familiar "unread indicator" pattern. Each notification item is a self-contained Row ' +
+        'with the avatar and message on the left (flex: 1, minWidth: 0 for text truncation) ' +
+        'and contextual actions on the right. Type chips (mention, comment, review, invite) ' +
+        'use semantic variant colors (accent, info, warning, success) with borderless styling ' +
+        'so they read as metadata, not interactive elements. Action buttons are contextual: ' +
+        'review requests get a primary "Review" button, invites get "Accept", others just "Dismiss".',
+};