lucent-ui 0.37.0 → 0.39.0

package/dist-server/server/tools.js

@@ -0,0 +1,298 @@
+import { z } from 'zod';
+import { ALL_MANIFESTS } from './registry.js';
+import { ALL_PATTERNS } from './pattern-registry.js';
+import { PALETTES, SHAPES, DENSITIES, SHADOWS, COMBINED, generatePresetConfig } from './presets.js';
+import { DESIGN_RULES, DESIGN_RULES_SUMMARY } from './design-rules.js';
+import { withLogging } from './logger.js';
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function findManifest(nameOrId) {
+    const q = nameOrId.trim().toLowerCase();
+    return ALL_MANIFESTS.find((m) => m.id.toLowerCase() === q || m.name.toLowerCase() === q);
+}
+function scoreManifest(m, query) {
+    const q = query.toLowerCase();
+    let score = 0;
+    if (m.name.toLowerCase().includes(q))
+        score += 10;
+    if (m.id.toLowerCase().includes(q))
+        score += 8;
+    if (m.tier.toLowerCase().includes(q))
+        score += 5;
+    if (m.description.toLowerCase().includes(q))
+        score += 4;
+    if (m.designIntent.toLowerCase().includes(q))
+        score += 3;
+    for (const p of m.props) {
+        if (p.name.toLowerCase().includes(q))
+            score += 2;
+        if (p.description.toLowerCase().includes(q))
+            score += 1;
+    }
+    return score;
+}
+function findPattern(nameOrId) {
+    const q = nameOrId.trim().toLowerCase();
+    return ALL_PATTERNS.find((r) => r.id.toLowerCase() === q || r.name.toLowerCase() === q);
+}
+function scorePattern(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;
+}
+// ─── Tool registrations ──────────────────────────────────────────────────────
+export function registerTools(server) {
+    // Tool: list_components
+    server.tool('list_components', 'Lists all available Lucent UI components with their name, tier (atom/molecule), and one-line description.', {}, withLogging('list_components', async () => {
+        const components = ALL_MANIFESTS.map((m) => ({
+            id: m.id,
+            name: m.name,
+            tier: m.tier,
+            description: m.description,
+        }));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ components }, null, 2),
+                },
+            ],
+        };
+    }));
+    // Tool: get_component_manifest
+    server.tool('get_component_manifest', 'Returns the full manifest JSON for a Lucent UI component, including props, usage examples, design intent, and accessibility notes.', { componentName: z.string().describe('Component name or id, e.g. "Button" or "form-field"') }, withLogging('get_component_manifest', async ({ componentName }) => {
+        const manifest = findManifest(componentName);
+        if (!manifest) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `Component "${componentName}" not found.`,
+                            available: ALL_MANIFESTS.map((m) => m.name),
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(manifest, null, 2),
+                },
+            ],
+        };
+    }));
+    // Tool: search_components
+    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"') }, withLogging('search_components', 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)
+            .map(({ manifest, score }) => ({
+            id: manifest.id,
+            name: manifest.name,
+            tier: manifest.tier,
+            description: manifest.description,
+            score,
+        }));
+        const patternResults = ALL_PATTERNS
+            .map((r) => ({ pattern: r, score: scorePattern(r, query) }))
+            .filter(({ score }) => score > 0)
+            .sort((a, b) => b.score - a.score)
+            .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, patterns: patternResults }, null, 2),
+                },
+            ],
+        };
+    }));
+    // 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"'),
+    }, withLogging('get_composition_pattern', async ({ name, category }) => {
+        if (name) {
+            const pattern = findPattern(name);
+            if (!pattern) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: `Pattern "${name}" not found.`,
+                                available: ALL_PATTERNS.map((r) => ({ id: r.id, name: r.name, category: r.category })),
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(pattern, null, 2),
+                    },
+                ],
+            };
+        }
+        if (category) {
+            const cat = category.trim().toLowerCase();
+            const patterns = ALL_PATTERNS.filter((r) => r.category === cat);
+            if (patterns.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: `No patterns found in category "${category}".`,
+                                availableCategories: [...new Set(ALL_PATTERNS.map((r) => r.category))],
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ category: cat, patterns }, null, 2),
+                    },
+                ],
+            };
+        }
+        // No filter — return all patterns
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        patterns: ALL_PATTERNS.map((r) => ({
+                            id: r.id,
+                            name: r.name,
+                            category: r.category,
+                            description: r.description,
+                            components: r.components,
+                        })),
+                    }, null, 2),
+                },
+            ],
+        };
+    }));
+    // Tool: list_presets
+    server.tool('list_presets', 'Lists all available Lucent UI design presets. Returns combined presets (modern, enterprise, playful) and individual dimensions (palettes, shapes, densities, shadows) that can be mixed and matched.', {}, withLogging('list_presets', async () => {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        combined: COMBINED,
+                        palettes: PALETTES,
+                        shapes: SHAPES,
+                        densities: DENSITIES,
+                        shadows: SHADOWS,
+                    }, null, 2),
+                },
+            ],
+        };
+    }));
+    // Tool: get_preset_config
+    server.tool('get_preset_config', 'Returns the LucentProvider configuration code for a given preset selection. Pass a combined preset name OR individual dimension names to get a ready-to-use config file and provider snippet.', {
+        preset: z.string().optional().describe('Combined preset name: "modern", "enterprise", or "playful"'),
+        palette: z.string().optional().describe('Palette name: "default", "brand", "indigo", "emerald", "rose", or "ocean"'),
+        shape: z.string().optional().describe('Shape name: "sharp", "rounded", or "pill"'),
+        density: z.string().optional().describe('Density name: "compact", "default", or "spacious"'),
+        shadow: z.string().optional().describe('Shadow name: "flat", "subtle", or "elevated"'),
+    }, withLogging('get_preset_config', async ({ preset, palette, shape, density, shadow }) => {
+        const result = generatePresetConfig({ preset, palette, shape, density, shadow });
+        if ('error' in result) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        configFile: result.configFile,
+                        providerSnippet: result.providerSnippet,
+                    }, null, 2),
+                },
+            ],
+        };
+    }));
+    // Tool: get_design_rules
+    server.tool('get_design_rules', 'Returns Lucent UI design rules for spacing, typography, button pairing, layout patterns, color usage, and density. These rules ensure AI-generated layouts are aesthetically consistent. Query a specific section or get all rules.', {
+        section: z
+            .string()
+            .optional()
+            .describe('Optional section id: "spacing", "typography", "buttons", "layout", "color", or "density". Omit to get all rules.'),
+    }, withLogging('get_design_rules', async ({ section }) => {
+        if (section) {
+            const s = section.trim().toLowerCase();
+            const rule = DESIGN_RULES.find((r) => r.id === s);
+            if (!rule) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: `Section "${section}" not found.`,
+                                availableSections: DESIGN_RULES.map((r) => ({
+                                    id: r.id,
+                                    title: r.title,
+                                })),
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `## ${rule.title}\n\n${rule.body}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: DESIGN_RULES_SUMMARY,
+                },
+            ],
+        };
+    }));
+}
+export { DESIGN_RULES_SUMMARY };

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

@@ -42,8 +42,8 @@ export const COMPONENT_MANIFEST = {
             type: 'enum',
             required: false,
             default: 'div',
-            description: 'HTML element to render. Use semantic elements when appropriate (nav for navigation, form for forms).',
-            enumValues: ['div', 'section', 'nav', 'form', 'fieldset', 'ul', 'ol'],
+            description: 'HTML element to render. Use semantic elements when appropriate (nav for navigation, ul/ol for lists, section/header/footer/main/aside/article for landmarks). When rendering as ul/ol, list-style/margin/padding are auto-reset; consumers pass <li> children.',
+            enumValues: ['div', 'section', 'nav', 'header', 'footer', 'main', 'aside', 'article', 'form', 'fieldset', 'ul', 'ol'],
         },
         {
             name: 'wrap',
@@ -92,6 +92,14 @@ export const COMPONENT_MANIFEST = {
             title: 'Header with actions',
             code: `<Row justify="between">\n  <Text as="h2" size="xl" weight="semibold">Dashboard</Text>\n  <Row gap="2">\n    <Button variant="outline" size="sm">Export</Button>\n    <Button variant="primary" size="sm">New report</Button>\n  </Row>\n</Row>`,
         },
+        {
+            title: 'Semantic nav',
+            code: `<Row as="nav" gap="4" aria-label="Primary">\n  <a href="/home">Home</a>\n  <a href="/about">About</a>\n  <a href="/contact">Contact</a>\n</Row>`,
+        },
+        {
+            title: 'Horizontal list (ul)',
+            code: `<Row as="ul" gap="2" aria-label="Tags">\n  {tags.map(tag => (\n    <li key={tag}><Tag>{tag}</Tag></li>\n  ))}\n</Row>`,
+        },
     ],
     compositionGraph: [],
     accessibility: {

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

@@ -41,8 +41,8 @@ export const COMPONENT_MANIFEST = {
             type: 'enum',
             required: false,
             default: 'div',
-            description: 'HTML element to render. Use semantic elements when appropriate (nav for navigation, form for forms).',
-            enumValues: ['div', 'section', 'nav', 'form', 'fieldset', 'ul', 'ol'],
+            description: 'HTML element to render. Use semantic elements when appropriate (nav for navigation, ul/ol for lists, section/header/footer/main/aside/article for landmarks). When rendering as ul/ol, list-style/margin/padding are auto-reset; consumers pass <li> children.',
+            enumValues: ['div', 'section', 'nav', 'header', 'footer', 'main', 'aside', 'article', 'form', 'fieldset', 'ul', 'ol'],
         },
         {
             name: 'wrap',
@@ -91,6 +91,10 @@ export const COMPONENT_MANIFEST = {
             title: 'Semantic nav',
             code: `<Stack as="nav" gap="1">\n  <NavLink href="/home">Home</NavLink>\n  <NavLink href="/settings">Settings</NavLink>\n</Stack>`,
         },
+        {
+            title: 'Semantic list (ul)',
+            code: `<Stack as="ul" gap="3" aria-label="Recent notes">\n  {notes.map(note => (\n    <li key={note.id}>\n      <Text size="sm">{note.body}</Text>\n    </li>\n  ))}\n</Stack>`,
+        },
     ],
     compositionGraph: [],
     accessibility: {

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

@@ -10,7 +10,10 @@ export const COMPONENT_MANIFEST = {
         'are not needed — props tables, changelog entries, comparison grids, reference docs. ' +
         'The compound API (Table.Head, Table.Body, Table.Row, Table.Cell) maps directly to ' +
         'semantic HTML so screen readers get the full table structure. ' +
-        'Horizontal overflow is handled automatically by a scroll wrapper.',
+        'Horizontal overflow is handled automatically by a scroll wrapper. ' +
+        'The wrapper paints var(--lucent-surface) as its background so the table always sits on a ' +
+        'solid panel, regardless of parent page color; thead/tfoot/striped tints are translucent ' +
+        'color-mix overlays on top of that surface so they adapt to both light and dark modes.',
     props: [
         {
             name: 'striped',

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

@@ -31,6 +31,17 @@ export const COMPONENT_MANIFEST = {
             required: false,
             description: 'Inline style overrides for the root <nav> element.',
         },
+        {
+            name: 'LinkComponent',
+            type: 'ComponentType',
+            required: false,
+            description: 'Optional custom link component used for items with an href, enabling SPA-friendly ' +
+                'routing (react-router, Next.js, etc.) without a full-page reload. ' +
+                'Receives { href, children, style, onClick, onMouseEnter, onMouseLeave }. ' +
+                'If your link primitive uses a different prop name for the URL, wrap it in a small adapter. ' +
+                'The adapter must forward `style` to the rendered DOM element so Breadcrumb typography and ' +
+                'hover styling are preserved.',
+        },
     ],
     usageExamples: [
         {
@@ -61,6 +72,22 @@ export const COMPONENT_MANIFEST = {
     { label: 'Reports', onClick: () => navigate('/reports') },
     { label: 'Q1 Summary' },
   ]}
+/>`,
+        },
+        {
+            title: 'react-router integration (LinkComponent)',
+            code: `import { Link } from 'react-router-dom';
+
+// react-router's Link uses \`to\`, so wrap it in a small adapter that
+// maps Breadcrumb's \`href\` prop to \`to\` and forwards style/handlers.
+const RouterLink = ({ href, ...rest }) => <Link to={href} {...rest} />;
+
+<Breadcrumb
+  LinkComponent={RouterLink}
+  items={[
+    { label: 'Candidates', href: '/candidates' },
+    { label: 'Jane Doe' },
+  ]}
 />`,
         },
     ],

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

@@ -14,7 +14,9 @@ export const COMPONENT_MANIFEST = {
         'Filter → sort → paginate is the fixed pipeline order; any filter change resets the page to 0. ' +
         'Pagination is either controlled (page prop + onPageChange) or uncontrolled (internal state). ' +
         'A pageSize of 0 disables pagination entirely, useful when the parent manages windowing. ' +
-        'Row hover uses bg-subtle, not a border change, so the visual weight stays low for dense data views.',
+        'Row hover uses bg-subtle, not a border change, so the visual weight stays low for dense data views. ' +
+        'The table wrapper paints var(--lucent-surface) as its background so the component always sits on a solid panel, ' +
+        'regardless of parent page color; header tints and row hover are translucent color-mix overlays on top of that surface.',
     props: [
         {
             name: 'columns',

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

@@ -7,6 +7,8 @@ export const COMPONENT_MANIFEST = {
     description: 'A drag-and-drop file upload zone with a file list, per-file progress bars, error display, and size/type validation.',
     designIntent: 'FileUpload separates concerns between the drop zone (entry point) and the file list (status display). ' +
         'The drop zone uses a dashed border and an upload arrow icon to communicate droppability without words. ' +
+        'Its idle background and border are translucent color-mix overlays on top of var(--lucent-text-primary) (not hard-coded surface tokens), ' +
+        'so the drop zone always reads as a visible step against whatever parent background it sits on — in any theme, in any palette. ' +
         'Progress is modelled as a field on UploadFile rather than as a callback so the parent controls upload logic — this component is purely presentational for the upload state. ' +
         'The progress bar turns success-green at 100% to give clear completion feedback. ' +
         'Errors are shown inline on each file row (not as a toast) so the user knows exactly which file failed and why. ' +

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

@@ -0,0 +1,144 @@
+export const COMPONENT_MANIFEST = {
+    id: 'page-header',
+    name: 'PageHeader',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A page-level header pairing breadcrumbs, a large display title, optional subtitle, and up to one primary CTA with 0–3 secondary outline actions.',
+    designIntent: 'PageHeader is the canonical chrome for a page body. It encapsulates the action-bar pattern — ' +
+        'breadcrumbs on top, a 3xl display title with optional subtitle below, action buttons anchored ' +
+        'to the title baseline, and a divider separating the header from page content. ' +
+        'The component owns three zones: breadcrumbs (nav context), title block, and action slot. ' +
+        '\n\n' +
+        '## Multi-action support\n' +
+        'The `action` prop holds the single primary CTA (rightmost position, `variant="primary"` by ' +
+        'default). The `secondaryActions` prop accepts 0–3 additional actions that render to the left ' +
+        'of the primary action with `variant="outline"` by default, keeping them visually subordinate. ' +
+        'This covers the common detail-page need for Edit / Archive / primary-CTA triples without ' +
+        'forcing consumers to rebuild the header from primitives. Beyond 3 secondary actions, reach for ' +
+        'SplitButton or an overflow menu instead of widening the row.\n\n' +
+        '## Responsive behaviour\n' +
+        'Both the outer title/action Row and the inner action Row set `wrap` so the button group flows ' +
+        'below the title on narrow viewports instead of overflowing. `align="end"` anchors the buttons ' +
+        'to the baseline of the subtitle line when the layout is horizontal.\n\n' +
+        '## Styling\n' +
+        'All spacing, typography, and colors come from Lucent tokens — no custom values. The title uses ' +
+        'the display font family and 3xl size; the subtitle uses the base font at sm/secondary. The ' +
+        'bottom divider can be hidden via `hideDivider` when the header sits directly above another ' +
+        'bordered surface.',
+    props: [
+        {
+            name: 'title',
+            type: 'string',
+            required: true,
+            description: 'Page title rendered as an h1 in the display font at 3xl size.',
+        },
+        {
+            name: 'subtitle',
+            type: 'ReactNode',
+            required: false,
+            description: 'Optional subtitle or metadata line rendered below the title at sm/secondary.',
+        },
+        {
+            name: 'breadcrumbs',
+            type: 'array',
+            required: false,
+            description: 'Breadcrumb items rendered above the title via the Breadcrumb molecule. Provides navigation context.',
+        },
+        {
+            name: 'action',
+            type: 'object',
+            required: false,
+            description: 'Single primary CTA rendered rightmost. Shape: { label, onClick?, variant?, leftIcon?, rightIcon?, disabled?, loading? }. ' +
+                'Defaults to variant="primary". Pass `null` to explicitly omit when spreading dynamic props.',
+        },
+        {
+            name: 'secondaryActions',
+            type: 'array',
+            required: false,
+            description: '0–3 secondary actions rendered to the left of `action`. Each item uses the same PageHeaderAction shape as `action`. ' +
+                'Defaults to variant="outline" so they stay visually subordinate. For more than 3 actions, use a SplitButton or overflow menu.',
+        },
+        {
+            name: 'hideDivider',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Hide the bottom divider. Use when the header sits directly above another bordered surface.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the outer Stack wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Minimal — title only',
+            code: `<PageHeader title="Settings" />`,
+        },
+        {
+            title: 'With subtitle and single primary action',
+            code: `<PageHeader
+  title="Acme Corp"
+  subtitle="Last updated 5 minutes ago"
+  action={{ label: 'New report', onClick: () => createReport() }}
+/>`,
+        },
+        {
+            title: 'Detail view with secondary actions (Edit / Archive / Submit)',
+            code: `<PageHeader
+  title="Sana Khan"
+  subtitle="Senior Product Designer · Added 3 days ago"
+  breadcrumbs={[
+    { label: 'Home', href: '#' },
+    { label: 'Candidates', href: '#' },
+    { label: 'Sana Khan' },
+  ]}
+  secondaryActions={[
+    { label: 'Edit', onClick: () => openEdit() },
+    { label: 'Archive', onClick: () => archive() },
+  ]}
+  action={{ label: 'Submit to opportunity', onClick: () => submit() }}
+/>`,
+        },
+        {
+            title: 'Danger zone',
+            code: `<PageHeader
+  title="Danger zone"
+  subtitle="These actions are irreversible."
+  breadcrumbs={[
+    { label: 'Home', href: '#' },
+    { label: 'Settings', href: '#' },
+    { label: 'Danger zone' },
+  ]}
+  action={{ label: 'Delete project', variant: 'danger', onClick: () => confirmDelete() }}
+/>`,
+        },
+        {
+            title: 'No primary CTA, secondary actions only',
+            code: `<PageHeader
+  title="Reports"
+  secondaryActions={[
+    { label: 'Export', onClick: () => exportAll() },
+    { label: 'Filter', onClick: () => openFilter() },
+  ]}
+/>`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'breadcrumb', componentName: 'Breadcrumb', role: 'Navigation context above the title', required: false },
+        { componentId: 'stack', componentName: 'Stack', role: 'Vertical layout for title and subtitle', required: true },
+        { componentId: 'row', componentName: 'Row', role: 'Horizontal layout for title block and action slot', required: true },
+        { componentId: 'text', componentName: 'Text', role: 'Title and subtitle rendering', required: true },
+        { componentId: 'button', componentName: 'Button', role: 'Primary and secondary action buttons', required: false },
+        { componentId: 'divider', componentName: 'Divider', role: 'Separator between header chrome and page content', required: false },
+    ],
+    accessibility: {
+        notes: 'The title renders as an <h1>, providing the page heading landmark for assistive tech. ' +
+            'Breadcrumbs render inside <nav aria-label="Breadcrumb">. Action buttons inherit Button\'s ' +
+            'focus ring, keyboard activation, and aria-label forwarding — pass aria-label on each action ' +
+            'object when the label alone is insufficient (e.g. icon-only buttons).',
+    },
+};

package/dist-server/src/manifest/examples/button.manifest.js

@@ -113,9 +113,32 @@ export const ButtonManifest = {
             type: 'enum',
             required: false,
             default: 'button',
-            description: 'Native button type attribute.',
+            description: 'Native button type attribute. Ignored when `href` is set.',
             enumValues: ['button', 'submit', 'reset'],
         },
+        {
+            name: 'href',
+            type: 'string',
+            required: false,
+            description: 'When set, renders the Button as an `<a href={href}>` instead of a native `<button>`. ' +
+                'Preserves native anchor affordances (middle-click, cmd/ctrl-click, right-click "copy link address", ' +
+                'open in new tab) that an onClick handler cannot. ' +
+                'Use for `mailto:` / `tel:` quick actions, external links styled as buttons, ' +
+                'or in-app routes where users legitimately expect anchor semantics. ' +
+                'When combined with `disabled`, the anchor renders with `aria-disabled="true"` and its `href` is stripped so navigation is neutralised.',
+        },
+        {
+            name: 'target',
+            type: 'string',
+            required: false,
+            description: 'Forwarded to the rendered `<a>` when `href` is set (e.g. `"_blank"` to open in a new tab). Ignored when rendering as a button.',
+        },
+        {
+            name: 'rel',
+            type: 'string',
+            required: false,
+            description: 'Forwarded to the rendered `<a>` when `href` is set (e.g. `"noopener noreferrer"` for external links). Ignored when rendering as a button.',
+        },
     ],
     usageExamples: [
         {
@@ -167,6 +190,21 @@ export const ButtonManifest = {
             code: `<Button variant="outline" size="2xs" leftIcon={<CloseIcon />} aria-label="Close" />`,
             description: 'Omitting children auto-sizes the button as a square via aspect-ratio: 1.',
         },
+        {
+            title: 'Mailto quick action',
+            code: `<Button variant="ghost" size="sm" href="mailto:foo@example.com" leftIcon={<MailIcon />} aria-label="Email" />`,
+            description: 'Renders as <a href="mailto:..."> so middle-click, cmd/ctrl-click, and right-click "copy link" all work.',
+        },
+        {
+            title: 'External link as button',
+            code: `<Button variant="primary" href="https://example.com" target="_blank" rel="noopener noreferrer" rightIcon={<ExternalIcon />}>View docs</Button>`,
+            description: 'Use href + target + rel for external links that should look like a primary call-to-action.',
+        },
+        {
+            title: 'Disabled link',
+            code: `<Button variant="outline" href="/settings" disabled>Settings</Button>`,
+            description: 'When disabled, the anchor is rendered with aria-disabled="true" and its href is stripped.',
+        },
     ],
     compositionGraph: [],
     accessibility: {