lucent-ui 0.1.0

package/dist-server/server/index.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+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';
+// ─── Auth stub ───────────────────────────────────────────────────────────────
+// LUCENT_API_KEY is reserved for the future paid tier.
+// When set, the server acknowledges it but does not yet enforce it.
+const apiKey = process.env['LUCENT_API_KEY'];
+if (apiKey) {
+    process.stderr.write('[lucent-mcp] Auth mode active (LUCENT_API_KEY is set).\n');
+}
+// ─── 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;
+}
+// ─── MCP Server ───────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: 'lucent-mcp',
+    version: '0.1.0',
+});
+// Tool: list_components
+server.tool('list_components', 'Lists all available Lucent UI components with their name, tier (atom/molecule), and one-line description.', {}, 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"') }, 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 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
+        .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,
+    }));
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ query, results }, null, 2),
+            },
+        ],
+    };
+});
+// ─── Start ────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist-server/server/registry.js

@@ -0,0 +1,48 @@
+// Atoms
+import { COMPONENT_MANIFEST as Avatar } from '../src/components/atoms/Avatar/Avatar.manifest.js';
+import { COMPONENT_MANIFEST as Badge } from '../src/components/atoms/Badge/Badge.manifest.js';
+import { COMPONENT_MANIFEST as Button } from '../src/components/atoms/Button/Button.manifest.js';
+import { COMPONENT_MANIFEST as Checkbox } from '../src/components/atoms/Checkbox/Checkbox.manifest.js';
+import { COMPONENT_MANIFEST as Divider } from '../src/components/atoms/Divider/Divider.manifest.js';
+import { COMPONENT_MANIFEST as Icon } from '../src/components/atoms/Icon/Icon.manifest.js';
+import { COMPONENT_MANIFEST as Input } from '../src/components/atoms/Input/Input.manifest.js';
+import { COMPONENT_MANIFEST as Radio } from '../src/components/atoms/Radio/Radio.manifest.js';
+import { COMPONENT_MANIFEST as Select } from '../src/components/atoms/Select/Select.manifest.js';
+import { COMPONENT_MANIFEST as Spinner } from '../src/components/atoms/Spinner/Spinner.manifest.js';
+import { COMPONENT_MANIFEST as Tag } from '../src/components/atoms/Tag/Tag.manifest.js';
+import { COMPONENT_MANIFEST as Text } from '../src/components/atoms/Text/Text.manifest.js';
+import { COMPONENT_MANIFEST as Textarea } from '../src/components/atoms/Textarea/Textarea.manifest.js';
+import { COMPONENT_MANIFEST as Toggle } from '../src/components/atoms/Toggle/Toggle.manifest.js';
+import { COMPONENT_MANIFEST as Tooltip } from '../src/components/atoms/Tooltip/Tooltip.manifest.js';
+// Molecules
+import { COMPONENT_MANIFEST as Alert } from '../src/components/molecules/Alert/Alert.manifest.js';
+import { COMPONENT_MANIFEST as Card } from '../src/components/molecules/Card/Card.manifest.js';
+import { COMPONENT_MANIFEST as EmptyState } from '../src/components/molecules/EmptyState/EmptyState.manifest.js';
+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';
+export const ALL_MANIFESTS = [
+    // Atoms
+    Avatar,
+    Badge,
+    Button,
+    Checkbox,
+    Divider,
+    Icon,
+    Input,
+    Radio,
+    Select,
+    Spinner,
+    Tag,
+    Text,
+    Textarea,
+    Toggle,
+    Tooltip,
+    // Molecules
+    Alert,
+    Card,
+    EmptyState,
+    FormField,
+    SearchInput,
+    Skeleton,
+];

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

@@ -0,0 +1,29 @@
+export const COMPONENT_MANIFEST = {
+    id: 'avatar',
+    name: 'Avatar',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A circular user image with initials fallback.',
+    designIntent: 'Always provide alt for accessibility — it is used to derive initials automatically when src is absent or fails. ' +
+        'Use initials prop to override auto-derived initials (e.g. for non-Latin names). ' +
+        'Size xs/sm suit table rows and compact lists; md is the default for comment threads; lg/xl for profile headers.',
+    props: [
+        { name: 'src', type: 'string', required: false, description: 'Image URL. Falls back to initials if omitted or fails to load.' },
+        { name: 'alt', type: 'string', required: true, description: 'Alt text and source for auto-derived initials.' },
+        { name: 'size', type: 'enum', required: false, default: 'md', description: 'Diameter of the avatar.', enumValues: ['xs', 'sm', 'md', 'lg', 'xl'] },
+        { name: 'initials', type: 'string', required: false, description: 'Override auto-derived initials (max 2 characters).' },
+    ],
+    usageExamples: [
+        { title: 'With image', code: `<Avatar src="/avatars/jane.jpg" alt="Jane Doe" />` },
+        { title: 'Initials fallback', code: `<Avatar alt="Jane Doe" />` },
+        { title: 'Large profile', code: `<Avatar src={user.avatar} alt={user.name} size="lg" />` },
+        { title: 'Custom initials', code: `<Avatar alt="张伟" initials="张" size="md" />` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'img',
+        ariaAttributes: ['aria-label'],
+        notes: 'When src is present, renders as <img> with alt. When showing initials, renders as <span role="img" aria-label>.',
+    },
+};

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

@@ -0,0 +1,29 @@
+export const COMPONENT_MANIFEST = {
+    id: 'badge',
+    name: 'Badge',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A small inline label for status, count, or category.',
+    designIntent: 'Badges communicate status or category at a glance. Match variant to semantic meaning — ' +
+        'never use "danger" for non-critical states or "success" for neutral counts. ' +
+        'Use dot=true when a single colour indicator is enough context (e.g. online status). ' +
+        'Keep badge text short: 1–3 words maximum.',
+    props: [
+        { name: 'variant', type: 'enum', required: false, default: 'neutral', description: 'Colour scheme conveying semantic meaning.', enumValues: ['neutral', 'success', 'warning', 'danger', 'info', 'accent'] },
+        { name: 'size', type: 'enum', required: false, default: 'md', description: 'Controls height and font size.', enumValues: ['sm', 'md'] },
+        { name: 'dot', type: 'boolean', required: false, default: 'false', description: 'Prepends a coloured dot indicator.' },
+        { name: 'children', type: 'ReactNode', required: true, description: 'Badge label.' },
+    ],
+    usageExamples: [
+        { title: 'Status', code: `<Badge variant="success" dot>Active</Badge>` },
+        { title: 'Count', code: `<Badge variant="danger">12</Badge>` },
+        { title: 'Category', code: `<Badge variant="info">Beta</Badge>` },
+        { title: 'Neutral tag', code: `<Badge>Draft</Badge>` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'status',
+        notes: 'Use aria-label on the parent element when badge meaning depends on context.',
+    },
+};

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

@@ -0,0 +1,2 @@
+// Re-export the canonical manifest from the manifest package
+export { ButtonManifest as COMPONENT_MANIFEST } from '../../../manifest/examples/button.manifest.js';

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

@@ -0,0 +1,74 @@
+export const COMPONENT_MANIFEST = {
+    id: 'checkbox',
+    name: 'Checkbox',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A binary selection control for boolean values or multi-select lists.',
+    designIntent: 'Checkboxes represent independent boolean choices — they do not affect each other. ' +
+        'Use a Checkbox for settings that take effect immediately (e.g. "Remember me") or for ' +
+        'selecting multiple items from a list. When only one option may be active at a time, use ' +
+        'Radio instead. The indeterminate state communicates a "select all" parent whose children ' +
+        'are partially checked — never use it for a third logical state.',
+    props: [
+        {
+            name: 'checked',
+            type: 'boolean',
+            required: false,
+            description: 'Controlled checked state. Pair with onChange for controlled usage.',
+        },
+        {
+            name: 'defaultChecked',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Initial checked state for uncontrolled usage.',
+        },
+        {
+            name: 'onChange',
+            type: 'function',
+            required: false,
+            description: 'Called when the checked state changes.',
+        },
+        {
+            name: 'label',
+            type: 'string',
+            required: false,
+            description: 'Visible label rendered beside the checkbox.',
+        },
+        {
+            name: 'indeterminate',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Displays a dash to indicate a partially-checked parent state.',
+        },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Prevents interaction and dims the control.',
+        },
+        {
+            name: 'size',
+            type: 'enum',
+            required: false,
+            default: 'md',
+            description: 'Size of the checkbox box.',
+            enumValues: ['sm', 'md'],
+        },
+    ],
+    usageExamples: [
+        { title: 'Controlled', code: `<Checkbox checked={agreed} onChange={e => setAgreed(e.target.checked)} label="I agree to the terms" />` },
+        { title: 'Uncontrolled', code: `<Checkbox defaultChecked label="Send me updates" />` },
+        { title: 'Indeterminate', code: `<Checkbox indeterminate label="Select all" />` },
+        { title: 'Disabled', code: `<Checkbox disabled label="Unavailable option" />` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'checkbox',
+        ariaAttributes: ['aria-checked', 'aria-disabled'],
+        keyboardInteractions: ['Space — toggles checked state'],
+    },
+};

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

@@ -0,0 +1,25 @@
+export const COMPONENT_MANIFEST = {
+    id: 'divider',
+    name: 'Divider',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A visual separator between content sections, horizontal or vertical.',
+    designIntent: 'Use horizontal Divider to separate sections in a layout. Use vertical Divider inline between sibling elements (e.g. nav links, toolbar buttons). ' +
+        'Use the label prop for "OR" separators in auth flows or form sections — never use a plain text node next to a divider for this.',
+    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.' },
+    ],
+    usageExamples: [
+        { title: 'Section separator', code: `<Divider />` },
+        { title: 'With label', code: `<Divider label="OR" />` },
+        { title: 'Vertical in nav', code: `<nav style={{ display: 'flex', alignItems: 'center' }}><a>Home</a><Divider orientation="vertical" /><a>About</a></nav>` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'separator',
+        ariaAttributes: ['aria-orientation', 'aria-label'],
+    },
+};

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

@@ -0,0 +1,54 @@
+export const COMPONENT_MANIFEST = {
+    id: 'icon',
+    name: 'Icon',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A sized, accessible wrapper for any SVG or icon-set component.',
+    designIntent: 'Icon is intentionally icon-set agnostic — pass any SVG or third-party icon as children ' +
+        'and it handles sizing and accessibility automatically. Use label for standalone icons that ' +
+        'convey meaning without adjacent text (e.g. a close button). Omit label for decorative ' +
+        'icons next to text, where the text already provides context. colour inherits from the ' +
+        'parent by default via currentColor — override only when the icon must differ from its ' +
+        'surrounding text.',
+    props: [
+        {
+            name: 'children',
+            type: 'ReactNode',
+            required: true,
+            description: 'The icon to render — any SVG element or icon-set component.',
+        },
+        {
+            name: 'size',
+            type: 'enum',
+            required: false,
+            default: 'md',
+            description: 'Constrains the icon to a fixed square (xs=12, sm=14, md=16, lg=20, xl=24).',
+            enumValues: ['xs', 'sm', 'md', 'lg', 'xl'],
+        },
+        {
+            name: 'label',
+            type: 'string',
+            required: false,
+            description: 'Accessible label (aria-label). Provide for meaningful standalone icons; omit for decorative ones.',
+        },
+        {
+            name: 'color',
+            type: 'string',
+            required: false,
+            description: 'CSS colour value. Defaults to currentColor (inherits from parent).',
+        },
+    ],
+    usageExamples: [
+        { title: 'Decorative (next to text)', code: `<Icon size="md"><SearchIcon /></Icon>` },
+        { title: 'Meaningful (standalone)', code: `<Icon size="lg" label="Close dialog"><XIcon /></Icon>` },
+        { title: 'Coloured', code: `<Icon color="var(--lucent-danger-default)"><AlertIcon /></Icon>` },
+        { title: 'Inside a button', code: `<Button leftIcon={<Icon size="sm"><PlusIcon /></Icon>}>Add item</Button>` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'img',
+        ariaAttributes: ['aria-label', 'aria-hidden'],
+        notes: 'aria-hidden="true" is applied automatically when no label is given, hiding the icon from screen readers.',
+    },
+};

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

@@ -0,0 +1,36 @@
+export const COMPONENT_MANIFEST = {
+    id: 'input',
+    name: 'Input',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A single-line text field with optional label, helper text, and error state.',
+    designIntent: 'Always pair with a visible label — never rely on placeholder text alone as it ' +
+        'disappears on input and is inaccessible. Use errorText (not helperText) to surface ' +
+        'validation failures; the component applies danger styling automatically. ' +
+        'leftElement and rightElement accept icons or small controls (e.g. currency symbol, clear button).',
+    props: [
+        { name: 'type', type: 'enum', required: false, default: 'text', description: 'HTML input type.', enumValues: ['text', 'number', 'password', 'email', 'tel', 'url', 'search'] },
+        { name: 'label', type: 'string', required: false, description: 'Visible label rendered above the input.' },
+        { name: 'helperText', type: 'string', required: false, description: 'Supplementary hint shown below the input.' },
+        { name: 'errorText', type: 'string', required: false, description: 'Validation error message. When set, input renders in error state.' },
+        { name: 'leftElement', type: 'ReactNode', required: false, description: 'Icon or adornment rendered inside the left edge.' },
+        { name: 'rightElement', type: 'ReactNode', required: false, description: 'Icon or adornment rendered inside the right edge.' },
+        { name: 'placeholder', type: 'string', required: false, description: 'Placeholder text. Use as a hint, not a label.' },
+        { name: 'disabled', type: 'boolean', required: false, default: 'false', description: 'Disables the input.' },
+        { name: 'value', type: 'string', required: false, description: 'Controlled value.' },
+        { name: 'onChange', type: 'function', required: false, description: 'Change handler.' },
+    ],
+    usageExamples: [
+        { title: 'Basic', code: `<Input label="Email" type="email" placeholder="you@example.com" />` },
+        { title: 'With helper text', code: `<Input label="Username" helperText="3–20 characters, letters and numbers only" />` },
+        { title: 'Error state', code: `<Input label="Password" type="password" value={value} errorText="Must be at least 8 characters" />` },
+        { title: 'With icon', code: `<Input label="Search" leftElement={<SearchIcon />} placeholder="Search…" />` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'textbox',
+        ariaAttributes: ['aria-invalid', 'aria-describedby', 'aria-label'],
+        keyboardInteractions: ['Tab — focuses the input'],
+    },
+};

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

@@ -0,0 +1,82 @@
+export const COMPONENT_MANIFEST = {
+    id: 'radio',
+    name: 'Radio',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A mutually exclusive selection control. Use RadioGroup to manage a set of options.',
+    designIntent: 'Radio buttons enforce a single selection from a small set of options (typically 2–6). ' +
+        'Always wrap Radio in a RadioGroup so name and selection state are shared automatically. ' +
+        'For larger option sets (7+) prefer a Select. For independent true/false choices, use a ' +
+        'Checkbox. RadioGroup orientation should match how the options relate — vertical for ' +
+        'distinct choices, horizontal for brief inline options (e.g. Yes / No).',
+    props: [
+        {
+            name: 'value',
+            type: 'string',
+            required: true,
+            description: 'The value submitted when this radio is selected.',
+        },
+        {
+            name: 'label',
+            type: 'string',
+            required: false,
+            description: 'Visible label rendered beside the radio button.',
+        },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Prevents interaction. Inherits group-level disabled when inside RadioGroup.',
+        },
+        {
+            name: 'size',
+            type: 'enum',
+            required: false,
+            default: 'md',
+            description: 'Size of the radio button circle.',
+            enumValues: ['sm', 'md'],
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Controlled RadioGroup',
+            code: `
+<RadioGroup name="plan" value={plan} onChange={setPlan}>
+  <Radio value="free" label="Free" />
+  <Radio value="pro" label="Pro" />
+  <Radio value="enterprise" label="Enterprise" />
+</RadioGroup>`.trim(),
+        },
+        {
+            title: 'Horizontal orientation',
+            code: `
+<RadioGroup name="size" value={size} onChange={setSize} orientation="horizontal">
+  <Radio value="s" label="S" />
+  <Radio value="m" label="M" />
+  <Radio value="l" label="L" />
+</RadioGroup>`.trim(),
+        },
+        {
+            title: 'Group-level disabled',
+            code: `
+<RadioGroup name="tier" value="basic" onChange={() => {}} disabled>
+  <Radio value="basic" label="Basic" />
+  <Radio value="advanced" label="Advanced" />
+</RadioGroup>`.trim(),
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'radio-group', componentName: 'RadioGroup', role: 'container', required: true },
+        { componentId: 'radio', componentName: 'Radio', role: 'item', required: true },
+    ],
+    accessibility: {
+        role: 'radio',
+        ariaAttributes: ['aria-checked', 'aria-disabled'],
+        keyboardInteractions: [
+            'Arrow keys — move selection within the group',
+            'Space — selects the focused radio',
+        ],
+    },
+};

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

@@ -0,0 +1,103 @@
+export const COMPONENT_MANIFEST = {
+    id: 'select',
+    name: 'Select',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A dropdown for choosing one option from a list.',
+    designIntent: 'Select is best for 5–15 options where showing all at once would be too noisy. ' +
+        'For fewer than 5 options, prefer RadioGroup (always-visible, faster to scan). ' +
+        'For search-filtered or async options, a Combobox (Wave 3) is more appropriate. ' +
+        'Always provide a placeholder when no default is sensible — this communicates the ' +
+        'field is required and prevents silent zero-state submissions.',
+    props: [
+        {
+            name: 'options',
+            type: 'array',
+            required: true,
+            description: 'Array of { value, label, disabled? } option objects.',
+        },
+        {
+            name: 'value',
+            type: 'string',
+            required: false,
+            description: 'Controlled selected value. Pair with onChange.',
+        },
+        {
+            name: 'onChange',
+            type: 'function',
+            required: false,
+            description: 'Called when the selected value changes.',
+        },
+        {
+            name: 'placeholder',
+            type: 'string',
+            required: false,
+            description: 'Disabled first option shown when no value is selected.',
+        },
+        {
+            name: 'label',
+            type: 'string',
+            required: false,
+            description: 'Visible label rendered above the select.',
+        },
+        {
+            name: 'helperText',
+            type: 'string',
+            required: false,
+            description: 'Supplementary hint shown below the select.',
+        },
+        {
+            name: 'errorText',
+            type: 'string',
+            required: false,
+            description: 'Validation error message. Replaces helperText and applies error styling.',
+        },
+        {
+            name: 'size',
+            type: 'enum',
+            required: false,
+            default: 'md',
+            description: 'Controls the height of the select control.',
+            enumValues: ['sm', 'md', 'lg'],
+        },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Prevents interaction.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Controlled',
+            code: `
+<Select
+  label="Country"
+  placeholder="Choose a country"
+  options={countries}
+  value={country}
+  onChange={e => setCountry(e.target.value)}
+/>`.trim(),
+        },
+        {
+            title: 'With validation error',
+            code: `<Select label="Role" options={roles} errorText="Please select a role" />`,
+        },
+        {
+            title: 'With helper text',
+            code: `<Select label="Timezone" options={timezones} helperText="Used for scheduling notifications" />`,
+        },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'combobox',
+        ariaAttributes: ['aria-invalid', 'aria-describedby'],
+        keyboardInteractions: [
+            'Enter / Space — opens the option list',
+            'Arrow keys — navigate options',
+            'Escape — closes the list',
+        ],
+    },
+};

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

@@ -0,0 +1,27 @@
+export const COMPONENT_MANIFEST = {
+    id: 'spinner',
+    name: 'Spinner',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'An animated loading indicator for async operations.',
+    designIntent: 'Use Spinner for indeterminate loading states of short duration (< 3s). ' +
+        'For full-page or skeleton-level loading, prefer Skeleton instead. ' +
+        'The label prop is visually hidden but read by screen readers — always set it to a meaningful description of what is loading.',
+    props: [
+        { name: 'size', type: 'enum', required: false, default: 'md', description: 'Spinner diameter.', enumValues: ['xs', 'sm', 'md', 'lg'] },
+        { name: 'label', type: 'string', required: false, default: 'Loading…', description: 'Visually hidden accessible label.' },
+        { name: 'color', type: 'string', required: false, description: 'Override colour (CSS value). Defaults to currentColor.' },
+    ],
+    usageExamples: [
+        { title: 'Default', code: `<Spinner />` },
+        { title: 'Inside button', code: `<Button loading><Spinner size="sm" label="Saving…" /></Button>` },
+        { title: 'Full-page overlay', code: `<div style={{ display: 'grid', placeItems: 'center', minHeight: '100vh' }}><Spinner size="lg" label="Loading dashboard…" /></div>` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'status',
+        ariaAttributes: ['aria-label'],
+        notes: 'The visible SVG is aria-hidden. The label is conveyed via a visually-hidden span inside role="status".',
+    },
+};