lucent-ui 0.25.1 → 0.27.0

package/dist-cli/cli/mapper.js

@@ -9,13 +9,12 @@ const LUCENT_TOKEN_KEYS = new Set([
     'bgBase', 'bgSubtle', 'bgOverlay',
     'surface', 'surfaceSecondary', 'surfaceRaised', 'surfaceOverlay',
     'borderDefault', 'borderSubtle', 'borderStrong',
-    'textPrimary', 'textSecondary', 'textDisabled', 'textInverse', 'textOnAccent',
-    'accentDefault', 'accentHover', 'accentActive', 'accentSubtle',
+    'textPrimary', 'textSecondary', 'textDisabled', 'textInverse',
+    'accentDefault', 'accentHover', 'accentSubtle', 'accentBorder', 'accentFg',
     'successDefault', 'successSubtle', 'successText',
     'warningDefault', 'warningSubtle', 'warningText',
     'dangerDefault', 'dangerHover', 'dangerSubtle', 'dangerText',
     'infoDefault', 'infoSubtle', 'infoText',
-    'focusRing',
     // TypographyTokens
     'fontFamilyBase', 'fontFamilyMono', 'fontFamilyDisplay',
     'fontSizeXs', 'fontSizeSm', 'fontSizeMd', 'fontSizeLg',

package/dist-server/server/index.js

@@ -3,6 +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 { PALETTES, SHAPES, DENSITIES, SHADOWS, COMBINED, generatePresetConfig } from './presets.js';
 // ─── Auth stub ───────────────────────────────────────────────────────────────
 // LUCENT_API_KEY is reserved for the future paid tier.
@@ -37,6 +38,29 @@ function scoreManifest(m, query) {
     }
     return score;
 }
+function findRecipe(nameOrId) {
+    const q = nameOrId.trim().toLowerCase();
+    return ALL_RECIPES.find((r) => r.id.toLowerCase() === q || r.name.toLowerCase() === q);
+}
+function scoreRecipe(r, query) {
+    const q = query.toLowerCase();
+    let score = 0;
+    if (r.name.toLowerCase().includes(q))
+        score += 10;
+    if (r.id.toLowerCase().includes(q))
+        score += 8;
+    if (r.category.toLowerCase().includes(q))
+        score += 5;
+    if (r.description.toLowerCase().includes(q))
+        score += 4;
+    if (r.designNotes.toLowerCase().includes(q))
+        score += 3;
+    for (const c of r.components) {
+        if (c.toLowerCase().includes(q))
+            score += 2;
+    }
+    return score;
+}
 // ─── MCP Server ───────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'lucent-mcp',
@@ -86,8 +110,8 @@ server.tool('get_component_manifest', 'Returns the full manifest JSON for a Luce
     };
 });
 // Tool: search_components
-server.tool('search_components', 'Searches Lucent UI components by description or concept. Returns matching components ranked by relevance.', { query: z.string().describe('Natural language or keyword query, e.g. "loading indicator" or "form validation"') }, async ({ query }) => {
-    const results = ALL_MANIFESTS
+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 }) => {
+    const componentResults = ALL_MANIFESTS
         .map((m) => ({ manifest: m, score: scoreManifest(m, query) }))
         .filter(({ score }) => score > 0)
         .sort((a, b) => b.score - a.score)
@@ -98,11 +122,96 @@ server.tool('search_components', 'Searches Lucent UI components by description o
         description: manifest.description,
         score,
     }));
+    const recipeResults = ALL_RECIPES
+        .map((r) => ({ recipe: r, score: scoreRecipe(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,
+        score,
+    }));
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({ query, results }, null, 2),
+                text: JSON.stringify({ query, components: componentResults, recipes: recipeResults }, 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"'),
+}, async ({ name, category }) => {
+    if (name) {
+        const recipe = findRecipe(name);
+        if (!recipe) {
+            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 })),
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(recipe, null, 2),
+                },
+            ],
+        };
+    }
+    if (category) {
+        const cat = category.trim().toLowerCase();
+        const recipes = ALL_RECIPES.filter((r) => r.category === cat);
+        if (recipes.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))],
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ category: cat, recipes }, null, 2),
+                },
+            ],
+        };
+    }
+    // No filter — return all recipes
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    recipes: ALL_RECIPES.map((r) => ({
+                        id: r.id,
+                        name: r.name,
+                        category: r.category,
+                        description: r.description,
+                        components: r.components,
+                    })),
+                }, null, 2),
             },
         ],
     };

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

@@ -0,0 +1,16 @@
+import { RECIPE as ProfileCard } from '../src/manifest/recipes/profile-card.recipe.js';
+import { RECIPE as SettingsPanel } from '../src/manifest/recipes/settings-panel.recipe.js';
+import { RECIPE as StatsRow } from '../src/manifest/recipes/stats-row.recipe.js';
+import { RECIPE as ActionBar } from '../src/manifest/recipes/action-bar.recipe.js';
+import { RECIPE as FormLayout } from '../src/manifest/recipes/form-layout.recipe.js';
+import { RECIPE as EmptyStateCard } from '../src/manifest/recipes/empty-state-card.recipe.js';
+import { RECIPE as CollapsibleCard } from '../src/manifest/recipes/collapsible-card.recipe.js';
+export const ALL_RECIPES = [
+    ProfileCard,
+    SettingsPanel,
+    StatsRow,
+    ActionBar,
+    FormLayout,
+    EmptyStateCard,
+    CollapsibleCard,
+];

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

@@ -10,7 +10,7 @@ export const COMPONENT_MANIFEST = {
     props: [
         { name: 'orientation', type: 'enum', required: false, default: 'horizontal', description: 'Direction of the divider line.', enumValues: ['horizontal', 'vertical'] },
         { name: 'label', type: 'string', required: false, description: 'Optional centered label (horizontal only). Common use: "OR", "AND", section titles.' },
-        { name: 'spacing', type: 'string', required: false, default: 'var(--lucent-space-4)', description: 'Margin on the axis perpendicular to the line.' },
+        { name: 'spacing', type: 'string', required: false, default: '0', description: 'Margin on the axis perpendicular to the line. Defaults to 0 so parent gap-based layouts (Stack, Row) control spacing. Pass an explicit value like "var(--lucent-space-4)" for standalone use outside flex/grid containers.' },
     ],
     usageExamples: [
         { title: 'Section separator', code: `<Divider />` },

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

@@ -17,13 +17,13 @@ export const COMPONENT_MANIFEST = {
             type: 'boolean',
             required: false,
             default: 'false',
-            description: 'Applies alternating surfaceSecondary backgrounds to even tbody rows.',
+            description: 'Applies alternating tinted backgrounds to even tbody rows via color-mix(transparent).',
         },
         {
             name: 'Table.Head',
             type: 'component',
             required: false,
-            description: 'Renders <thead> with surfaceSecondary background. Accepts Table.Row children.',
+            description: 'Renders <thead> with a subtle tinted background. Accepts Table.Row children.',
         },
         {
             name: 'Table.Body',
@@ -35,7 +35,7 @@ export const COMPONENT_MANIFEST = {
             name: 'Table.Foot',
             type: 'component',
             required: false,
-            description: 'Renders <tfoot> with surfaceSecondary background.',
+            description: 'Renders <tfoot> with a subtle tinted background.',
         },
         {
             name: 'Table.Row',

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

@@ -51,7 +51,7 @@ export const COMPONENT_MANIFEST = {
         '- `ghost` and `outline` use `transparent` — they inherit from whatever they\'re placed on. ' +
         'The border is the only visual differentiator for `outline`.\n' +
         '- Never use `bgBase` or `bgSubtle` on a Card — those tokens are reserved for the page canvas.\n' +
-        '- Content nested inside a Card that needs a tinted fill should use `surfaceSecondary`.',
+        '- Content nested inside a Card that needs a tinted fill should use `color-mix(in srgb, var(--lucent-text-primary) 5%, transparent)` for accent-neutral insets.',
     props: [
         {
             name: 'variant',

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

@@ -39,7 +39,7 @@ export const COMPONENT_MANIFEST = {
         '## Selected state\n' +
         'MenuItem accepts a `selected` prop that renders a trailing accent-colored checkmark. The selected item ' +
         'gets a `color-mix(in srgb, accent-default 12%, surface-overlay)` background with `shadow-sm` elevation, ' +
-        'making it visually stronger than the hover state (`surface-secondary`). Uses `role="menuitemcheckbox"` ' +
+        'making it visually stronger than the hover state (subtle `color-mix` tint). Uses `role="menuitemcheckbox"` ' +
         'with `aria-checked` for accessibility.\n\n' +
         '## Animation\n' +
         'Both entrance and exit use a subtle scale + fade (`scale(0.97) ↔ 1`, `opacity 0 ↔ 1`) over 120ms. ' +

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

@@ -97,7 +97,8 @@ export const COMPONENT_MANIFEST = {
             description: 'Background token for chrome regions (header, sidebar, footer). ' +
                 '"bgBase" uses the page canvas color so the main content card feels elevated; ' +
                 '"bgSubtle" uses a subtle shade of bgBase for chrome distinction; ' +
-                '"surface" matches the old behavior where chrome and content share the same background.',
+                '"surface" matches the old behavior where chrome and content share the same background; ' +
+                '"surfaceSecondary" uses the tinted fill token for a more visible chrome/stage separation.',
         },
         {
             name: 'mainStyle',

package/dist-server/src/manifest/recipes/action-bar.recipe.js

@@ -0,0 +1,91 @@
+export const RECIPE = {
+    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.',
+    category: 'action',
+    components: ['text', 'button', 'row', 'stack', 'breadcrumb', 'divider', 'card'],
+    structure: `
+Page header:
+Stack gap="4"
+├── 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"                          ← actions
+│       ├── Button (outline, sm)
+│       └── Button (primary, sm)
+└── Divider
+
+Card header:
+Row justify="between" align="start"
+├── Stack gap="1"
+│   ├── Text (xs, secondary, uppercase, tight) ← category label
+│   └── Text (md, semibold, tight)            ← section title
+└── Row gap="1"                              ← compact actions (top-aligned)
+    └── Button[] (ghost, xs)
+  `.trim(),
+    code: `<Stack gap="4">
+  <Breadcrumb items={[
+    { label: 'Home', href: '#' },
+    { label: 'Projects', href: '#' },
+    { label: 'Acme Corp' },
+  ]} />
+  <Row justify="between" align="end">
+    <Stack gap="1">
+      <Text as="h1" size="3xl" weight="bold" family="display">Acme Corp</Text>
+      <Text size="sm" color="secondary">Last updated 5 minutes ago</Text>
+    </Stack>
+    <Row gap="2">
+      <Button variant="outline" size="sm">Export</Button>
+      <Button variant="primary" size="sm">New report</Button>
+    </Row>
+  </Row>
+  <Divider />
+</Stack>`,
+    variants: [
+        {
+            title: 'Page header — danger zone',
+            code: `<Stack gap="4">
+  <Breadcrumb items={[
+    { label: 'Home', href: '#' },
+    { label: 'Settings', href: '#' },
+    { label: 'Danger zone' },
+  ]} />
+  <Row justify="between" align="end">
+    <Stack gap="1">
+      <Text as="h1" size="3xl" weight="bold" family="display">Danger zone</Text>
+      <Text size="sm" color="secondary">These actions are irreversible.</Text>
+    </Stack>
+    <Button variant="danger" size="sm">Delete project</Button>
+  </Row>
+  <Divider />
+</Stack>`,
+        },
+        {
+            title: 'Card header (compact with label)',
+            code: `<Card variant="outline" padding="md" style={{ width: 400 }}>
+  <Stack gap="4">
+    <Row justify="between" align="start">
+      <Stack gap="1">
+        <Text size="xs" color="secondary" weight="medium" style={{ letterSpacing: 'var(--lucent-letter-spacing-tight)', textTransform: 'uppercase' }}>Activity</Text>
+        <Text size="md" weight="semibold" style={{ letterSpacing: 'var(--lucent-letter-spacing-base)' }}>Recent activity</Text>
+      </Stack>
+      <Row gap="1">
+        <Button variant="ghost" size="xs">Filter</Button>
+        <Button variant="ghost" size="xs">Export</Button>
+      </Row>
+    </Row>
+    <Text size="xs" color="secondary">No activity to show yet.</Text>
+  </Stack>
+</Card>`,
+        },
+    ],
+    designNotes: 'Page headers and card headers have very different scales. Page headers use 3xl ' +
+        'display font for the title, Breadcrumb for navigation context, and a Divider to ' +
+        'separate the header from page content below. align="end" on the Row anchors the ' +
+        'buttons to the baseline of the title block so they sit level with the subtitle. ' +
+        'Card headers are compact: sm semibold text with xs/ghost buttons that recede ' +
+        'visually. The primary action is always rightmost following natural reading order. ' +
+        'Both patterns use justify="between" to push title and actions to opposite edges.',
+};

package/dist-server/src/manifest/recipes/collapsible-card.recipe.js

@@ -0,0 +1,100 @@
+export const RECIPE = {
+    id: 'collapsible-card',
+    name: 'Collapsible Card',
+    description: 'Card with an expandable/collapsible section using smooth height animation, available in all card variants.',
+    category: 'card',
+    components: ['card', 'collapsible', 'text'],
+    structure: `
+Card (padding="none", hoverable)
+└── Collapsible
+    ├── trigger: Text (sm, semibold)         ← clickable header
+    └── children                             ← collapsible body
+        └── Text (sm, secondary)             ← content
+  `.trim(),
+    code: `<Card variant="outline" padding="none" hoverable style={{ width: 360 }}>
+  <Collapsible
+    trigger={<Text as="span" weight="semibold" size="sm">Details</Text>}
+    defaultOpen
+  >
+    <Text size="sm" color="secondary">
+      The Collapsible auto-detects its Card parent and bleeds the trigger
+      full-width. Content inherits the card's padding.
+    </Text>
+  </Collapsible>
+</Card>`,
+    variants: [
+        {
+            title: 'Ghost variant',
+            code: `<Card variant="ghost" padding="none" hoverable style={{ width: 360 }}>
+  <Collapsible trigger={<Text as="span" weight="semibold" size="sm">FAQ item</Text>}>
+    <Text size="sm" color="secondary">
+      Transparent container — content floats directly on the page surface.
+    </Text>
+  </Collapsible>
+</Card>`,
+        },
+        {
+            title: 'Elevated variant',
+            code: `<Card variant="elevated" padding="none" hoverable style={{ width: 360 }}>
+  <Collapsible trigger={<Text as="span" weight="semibold" size="sm">Advanced options</Text>}>
+    <Text size="sm" color="secondary">
+      Elevated cards cast a shadow — use for prominent collapsible sections.
+    </Text>
+  </Collapsible>
+</Card>`,
+        },
+        {
+            title: 'Combo (two-tone nested cards)',
+            code: `<Card variant="filled" padding="none" hoverable style={{ width: 360 }}>
+  <Collapsible
+    padded={false}
+    trigger={<Text as="span" weight="semibold" size="sm">Combo layout</Text>}
+  >
+    <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 layout — flat trigger surface, elevated body.
+      </Text>
+    </Card>
+  </Collapsible>
+</Card>`,
+        },
+        {
+            title: 'With localStorage persistence',
+            code: `function CollapsibleSection({ id, title, children }) {
+  const storageKey = \`collapsible-\${id}\`;
+  const [open, setOpen] = React.useState(() => {
+    const saved = localStorage.getItem(storageKey);
+    return saved !== null ? saved === 'true' : true;
+  });
+
+  const handleChange = (next) => {
+    setOpen(next);
+    localStorage.setItem(storageKey, String(next));
+  };
+
+  return (
+    <Card variant="outline" padding="none" hoverable>
+      <Collapsible
+        open={open}
+        onOpenChange={handleChange}
+        trigger={<Text as="span" weight="semibold" size="sm">{title}</Text>}
+      >
+        {children}
+      </Collapsible>
+    </Card>
+  );
+}`,
+        },
+    ],
+    designNotes: 'Card uses padding="none" because the Collapsible auto-detects its Card parent ' +
+        'via CardPaddingContext and bleeds the trigger full-width while applying card ' +
+        'padding to the body content. The hoverable prop gives hover lift feedback ' +
+        'without making the card itself interactive — the Collapsible trigger handles ' +
+        'clicks. For the combo variant, padded={false} on Collapsible removes its built-in ' +
+        'content padding so the nested elevated Card can control its own spacing with ' +
+        'custom margin. This creates a two-tone visual: flat trigger + elevated body.',
+};

package/dist-server/src/manifest/recipes/empty-state-card.recipe.js

@@ -0,0 +1,72 @@
+export const RECIPE = {
+    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.',
+    category: 'card',
+    components: ['card', 'empty-state', 'icon', 'button'],
+    structure: `
+Card (outline, padding="lg")
+└── EmptyState
+    ├── illustration: Icon (xl)              ← decorative SVG
+    ├── title: string                        ← heading
+    ├── description: string                  ← explanatory text
+    └── action: Button (secondary / primary) ← CTA
+  `.trim(),
+    code: `<Card variant="outline" padding="lg" style={{ width: 400 }}>
+  <EmptyState
+    illustration={
+      <Icon size="xl">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round">
+          <circle cx={11} cy={11} r={8} />
+          <path d="M21 21l-4.35-4.35" />
+        </svg>
+      </Icon>
+    }
+    title="No results found"
+    description="Try adjusting your search or filters to find what you're looking for."
+    action={<Button variant="secondary" size="sm">Clear filters</Button>}
+  />
+</Card>`,
+    variants: [
+        {
+            title: 'Getting started empty state',
+            code: `<Card variant="elevated" padding="lg" style={{ width: 400 }}>
+  <EmptyState
+    illustration={
+      <Icon size="xl">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round">
+          <path d="M12 5v14M5 12h14" />
+        </svg>
+      </Icon>
+    }
+    title="No projects yet"
+    description="Create your first project to get started."
+    action={<Button variant="primary" size="sm">Create project</Button>}
+  />
+</Card>`,
+        },
+        {
+            title: 'Error empty state with retry',
+            code: `<Card variant="outline" padding="lg" style={{ width: 400 }}>
+  <EmptyState
+    illustration={
+      <Icon size="xl">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round">
+          <circle cx={12} cy={12} r={10} />
+          <path d="M12 8v4M12 16h.01" />
+        </svg>
+      </Icon>
+    }
+    title="Something went wrong"
+    description="We couldn't load your data. Please try again."
+    action={<Button variant="outline" size="sm">Retry</Button>}
+  />
+</Card>`,
+        },
+    ],
+    designNotes: 'EmptyState handles internal centering and spacing — no need for manual Stack/Row ' +
+        'layout inside it. The illustration uses Icon at xl size for visual weight without ' +
+        'overwhelming the text. Card variant should match the context: outline for inline ' +
+        'empty states (e.g. a table with no rows), elevated for standalone pages. The ' +
+        'action button uses size="sm" to avoid competing with the heading for attention.',
+};

package/dist-server/src/manifest/recipes/form-layout.recipe.js

@@ -0,0 +1,98 @@
+export const RECIPE = {
+    id: 'form-layout',
+    name: 'Form Layout',
+    description: 'Stacked form with grouped sections, FormField labels, validation hints, and a submit/cancel footer.',
+    category: 'form',
+    components: ['card', 'text', 'input', 'select', 'textarea', 'checkbox', 'button', 'stack', 'row', 'divider', 'form-field'],
+    structure: `
+Card (elevated, padding="lg")
+└── Stack as="form" gap="6"
+    ├── Stack gap="1"                        ← section header
+    │   ├── Text (lg, semibold)              ← form title
+    │   └── Text (sm, secondary)             ← description
+    ├── Stack gap="4"                        ← field group 1
+    │   ├── Row gap="4"                      ← side-by-side fields
+    │   │   ├── FormField (label, required)
+    │   │   │   └── Input
+    │   │   └── FormField (label, required)
+    │   │       └── Input
+    │   ├── FormField (label)
+    │   │   └── Input
+    │   └── FormField (label)
+    │       └── Select
+    ├── Divider
+    ├── Stack gap="4"                        ← field group 2
+    │   ├── FormField (label)
+    │   │   └── Textarea
+    │   └── Checkbox (contained)
+    └── Row gap="2" justify="end"            ← actions
+        ├── Button (ghost)
+        └── Button (primary)
+  `.trim(),
+    code: `<Card variant="elevated" padding="lg" style={{ width: 480 }}>
+  <Stack as="form" gap="6">
+    <Stack gap="1">
+      <Text as="h2" size="lg" weight="semibold">Create project</Text>
+      <Text size="sm" color="secondary">
+        Fill in the details to set up your new project.
+      </Text>
+    </Stack>
+    <Stack gap="4">
+      <Row gap="4">
+        <FormField label="First name" htmlFor="fname" required style={{ flex: 1 }}>
+          <Input id="fname" placeholder="Jane" />
+        </FormField>
+        <FormField label="Last name" htmlFor="lname" required style={{ flex: 1 }}>
+          <Input id="lname" placeholder="Doe" />
+        </FormField>
+      </Row>
+      <FormField label="Email" htmlFor="email" helperText="We'll never share your email.">
+        <Input id="email" type="email" placeholder="jane@example.com" />
+      </FormField>
+      <FormField label="Role" htmlFor="role">
+        <Select
+          id="role"
+          placeholder="Select a role..."
+          options={[
+            { value: 'admin', label: 'Admin' },
+            { value: 'editor', label: 'Editor' },
+            { value: 'viewer', label: 'Viewer' },
+          ]}
+        />
+      </FormField>
+    </Stack>
+    <Divider />
+    <Stack gap="4">
+      <FormField label="Bio" htmlFor="bio">
+        <Textarea id="bio" placeholder="Tell us about yourself..." rows={3} />
+      </FormField>
+      <Checkbox label="I agree to the terms" contained />
+    </Stack>
+    <Row gap="2" justify="end">
+      <Button variant="ghost">Cancel</Button>
+      <Button variant="primary">Create</Button>
+    </Row>
+  </Stack>
+</Card>`,
+    variants: [
+        {
+            title: 'Inline form (no card)',
+            code: `<Stack as="form" gap="4" style={{ maxWidth: 400 }}>
+  <FormField label="Username" htmlFor="user" required helperText="Letters and numbers only, 3–20 chars.">
+    <Input id="user" placeholder="yourname" />
+  </FormField>
+  <FormField label="Password" htmlFor="pass" required>
+    <Input id="pass" type="password" />
+  </FormField>
+  <Button variant="primary">Sign in</Button>
+</Stack>`,
+        },
+    ],
+    designNotes: 'The form uses Stack as="form" to render a semantic <form> element while keeping ' +
+        'token-based vertical spacing. gap="6" between sections provides clear visual ' +
+        'grouping; gap="4" within a section keeps fields tightly related. Side-by-side ' +
+        'fields use Row with flex: 1 on each FormField so they share width equally. ' +
+        'The Divider separates logical sections (identity fields vs. profile fields). ' +
+        'Actions are right-aligned (justify="end") following the convention that the ' +
+        'primary action is the rightmost button.',
+};

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

@@ -0,0 +1,7 @@
+export { RECIPE as ProfileCard } from './profile-card.recipe.js';
+export { RECIPE as SettingsPanel } from './settings-panel.recipe.js';
+export { RECIPE as StatsRow } from './stats-row.recipe.js';
+export { RECIPE as ActionBar } from './action-bar.recipe.js';
+export { RECIPE as FormLayout } from './form-layout.recipe.js';
+export { RECIPE as EmptyStateCard } from './empty-state-card.recipe.js';
+export { RECIPE as CollapsibleCard } from './collapsible-card.recipe.js';