lucent-ui 0.1.0

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

@@ -0,0 +1,93 @@
+export const COMPONENT_MANIFEST = {
+    id: 'form-field',
+    name: 'FormField',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'Wraps any form control (Input, Select, Textarea) with a label, helper text, and validation message.',
+    designIntent: 'FormField standardises the vertical rhythm around form controls. A label is linked to the control ' +
+        'via htmlFor so screen readers announce it correctly. The required asterisk is decorative (aria-hidden) ' +
+        'because the actual required state should be communicated on the input via aria-required. Helper text ' +
+        'provides proactive guidance; errorMessage replaces it when validation fails, using danger color to ' +
+        'draw attention. The gap between elements uses space-2 to create a tight but breathable stack.',
+    props: [
+        {
+            name: 'label',
+            type: 'string',
+            required: false,
+            description: 'Label text rendered above the control as a <label> element.',
+        },
+        {
+            name: 'htmlFor',
+            type: 'string',
+            required: false,
+            description: 'ID of the form control this label describes. Forwarded to the label htmlFor attribute.',
+        },
+        {
+            name: 'required',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Appends a danger-colored asterisk after the label text.',
+        },
+        {
+            name: 'helperText',
+            type: 'string',
+            required: false,
+            description: 'Secondary text below the control providing guidance. Hidden when errorMessage is set.',
+        },
+        {
+            name: 'errorMessage',
+            type: 'string',
+            required: false,
+            description: 'Validation error shown in danger color below the control. Replaces helperText when set.',
+        },
+        {
+            name: 'children',
+            type: 'ReactNode',
+            required: true,
+            description: 'The form control to wrap — typically Input, Select, or Textarea.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the outer wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Basic field',
+            code: `<FormField label="Email" htmlFor="email">
+  <Input id="email" placeholder="you@example.com" />
+</FormField>`,
+        },
+        {
+            title: 'Required with helper',
+            code: `<FormField label="Username" htmlFor="username" required helperText="Letters and numbers only">
+  <Input id="username" />
+</FormField>`,
+        },
+        {
+            title: 'With validation error',
+            code: `<FormField label="Password" htmlFor="pw" errorMessage="Must be at least 8 characters">
+  <Input id="pw" type="password" />
+</FormField>`,
+        },
+        {
+            title: 'Wrapping a Select',
+            code: `<FormField label="Country" htmlFor="country">
+  <Select id="country" options={countryOptions} />
+</FormField>`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'text', componentName: 'Text', role: 'Label, helper text, and error message', required: false },
+    ],
+    accessibility: {
+        ariaAttributes: ['aria-required', 'aria-describedby'],
+        notes: 'Link the wrapped control to an error message using aria-describedby on the control and a matching id ' +
+            'on the error element for full screen reader support. The required asterisk is aria-hidden; ' +
+            'set aria-required="true" on the control itself.',
+    },
+};

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

@@ -0,0 +1,102 @@
+export const COMPONENT_MANIFEST = {
+    id: 'search-input',
+    name: 'SearchInput',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A search field with a built-in magnifier icon, clear button, and an optional results dropdown.',
+    designIntent: 'SearchInput is intentionally dumb about filtering — the consumer passes already-filtered results ' +
+        'so the component stays stateless and flexible. The clear button appears only when the input has a ' +
+        'value, keeping the right side clean at rest. The results dropdown is rendered absolutely below the ' +
+        'input and closes after a 150ms delay on blur to allow result clicks to register before focus is lost. ' +
+        'Spinner replaces the clear button during loading to communicate async state without layout shift.',
+    props: [
+        {
+            name: 'value',
+            type: 'string',
+            required: true,
+            description: 'Controlled input value.',
+        },
+        {
+            name: 'onChange',
+            type: 'function',
+            required: true,
+            description: 'Called with the new string value whenever the input changes.',
+        },
+        {
+            name: 'placeholder',
+            type: 'string',
+            required: false,
+            default: '"Search…"',
+            description: 'Placeholder text for the input.',
+        },
+        {
+            name: 'results',
+            type: 'array',
+            required: false,
+            default: '[]',
+            description: 'Pre-filtered list of SearchResult objects ({ id, label }) to display in the dropdown.',
+        },
+        {
+            name: 'onResultSelect',
+            type: 'function',
+            required: false,
+            description: 'Called with the selected SearchResult when a dropdown item is clicked.',
+        },
+        {
+            name: 'isLoading',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Shows a spinner in the right slot to indicate async search in progress.',
+        },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Disables the input.',
+        },
+        {
+            name: 'id',
+            type: 'string',
+            required: false,
+            description: 'HTML id forwarded to the underlying input element.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the outer wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Basic controlled search',
+            code: `const [query, setQuery] = useState('');
+const [results, setResults] = useState([]);
+
+<SearchInput
+  value={query}
+  onChange={(v) => { setQuery(v); setResults(filter(v)); }}
+  results={results}
+  onResultSelect={(r) => console.log(r)}
+/>`,
+        },
+        {
+            title: 'Loading state',
+            code: `<SearchInput value={query} onChange={setQuery} isLoading={isFetching} results={[]} />`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'input', componentName: 'Input', role: 'Search text field with icon slots', required: true },
+        { componentId: 'spinner', componentName: 'Spinner', role: 'Loading indicator in the right slot', required: false },
+    ],
+    accessibility: {
+        role: 'combobox',
+        ariaAttributes: ['aria-expanded', 'aria-haspopup', 'aria-label'],
+        keyboardInteractions: ['Enter to select focused result', 'Escape to close dropdown'],
+        notes: 'The results list uses role="listbox" with role="option" items. For full keyboard navigation ' +
+            '(arrow keys to move between results), wire up onKeyDown on the Input and manage an activeIndex state.',
+    },
+};

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

@@ -0,0 +1,93 @@
+export const COMPONENT_MANIFEST = {
+    id: 'skeleton',
+    name: 'Skeleton',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'Animated placeholder that matches the shape of content while it loads.',
+    designIntent: 'Skeleton uses a shimmer animation to communicate that content is loading without showing a spinner. ' +
+        'The three variants (text, circle, rectangle) cover the most common content shapes: inline text, ' +
+        'avatars/thumbnails, and generic content blocks. The text variant with lines > 1 mimics a paragraph ' +
+        'by stacking multiple text skeletons and shortening the last line to 70%, which is a widely recognised ' +
+        'convention for body copy placeholders. The shimmer gradient uses bg-muted and bg-subtle so it adapts ' +
+        'correctly in both light and dark themes without hard-coded colors.',
+    props: [
+        {
+            name: 'variant',
+            type: 'enum',
+            required: false,
+            default: 'rectangle',
+            description: 'Shape of the skeleton — text (1em tall), circle (equal width/height), or rectangle.',
+            enumValues: ['text', 'circle', 'rectangle'],
+        },
+        {
+            name: 'width',
+            type: 'string',
+            required: false,
+            default: '"100%"',
+            description: 'Width of the skeleton. Accepts any CSS value or a number (interpreted as px).',
+        },
+        {
+            name: 'height',
+            type: 'string',
+            required: false,
+            description: 'Height of the skeleton. Defaults: text=1em, circle=40px, rectangle=40px.',
+        },
+        {
+            name: 'lines',
+            type: 'number',
+            required: false,
+            default: '1',
+            description: 'Number of stacked text lines to render. Only applies to the text variant.',
+        },
+        {
+            name: 'animate',
+            type: 'boolean',
+            required: false,
+            default: 'true',
+            description: 'Enables the shimmer animation. Set to false to render a static placeholder.',
+        },
+        {
+            name: 'radius',
+            type: 'string',
+            required: false,
+            description: 'Override the default border-radius for the variant.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Paragraph placeholder',
+            code: `<Skeleton variant="text" lines={3} />`,
+        },
+        {
+            title: 'Avatar placeholder',
+            code: `<Skeleton variant="circle" width={40} height={40} />`,
+        },
+        {
+            title: 'Card placeholder',
+            code: `<Card>
+  <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+    <Skeleton variant="rectangle" height={160} />
+    <Skeleton variant="text" lines={2} />
+    <Skeleton variant="text" width="40%" />
+  </div>
+</Card>`,
+        },
+        {
+            title: 'Static (no animation)',
+            code: `<Skeleton variant="rectangle" width={200} height={32} animate={false} />`,
+        },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        ariaAttributes: ['aria-busy', 'aria-label'],
+        notes: 'Wrap loading regions with aria-busy="true" on the container so screen readers know content ' +
+            'is loading. Individual Skeleton elements are presentational and do not need ARIA attributes themselves.',
+    },
+};

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

@@ -0,0 +1,116 @@
+export const ButtonManifest = {
+    id: 'button',
+    name: 'Button',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A clickable control that triggers an action. The primary interactive primitive in Lucent UI.',
+    designIntent: 'Buttons communicate available actions. Variant conveys hierarchy: use "primary" for the ' +
+        'single most important action in a view, "secondary" for supporting actions, "ghost" for ' +
+        'low-emphasis actions in dense UIs, and "danger" exclusively for destructive or irreversible ' +
+        'operations. Size should match surrounding content density — prefer "md" as the default and ' +
+        'reserve "sm" for toolbars or tables.',
+    props: [
+        {
+            name: 'variant',
+            type: 'enum',
+            required: false,
+            default: 'primary',
+            description: 'Visual style conveying action hierarchy.',
+            enumValues: ['primary', 'secondary', 'ghost', 'danger'],
+        },
+        {
+            name: 'size',
+            type: 'enum',
+            required: false,
+            default: 'md',
+            description: 'Controls height and padding.',
+            enumValues: ['sm', 'md', 'lg'],
+        },
+        {
+            name: 'children',
+            type: 'ReactNode',
+            required: true,
+            description: 'Button label or content.',
+        },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Prevents interaction and applies disabled styling.',
+        },
+        {
+            name: 'loading',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Shows a spinner and prevents interaction while an async action is in progress.',
+        },
+        {
+            name: 'fullWidth',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Stretches the button to fill its container width.',
+        },
+        {
+            name: 'leftIcon',
+            type: 'ReactNode',
+            required: false,
+            description: 'Icon element rendered before the label.',
+        },
+        {
+            name: 'rightIcon',
+            type: 'ReactNode',
+            required: false,
+            description: 'Icon element rendered after the label.',
+        },
+        {
+            name: 'onClick',
+            type: 'function',
+            required: false,
+            description: 'Called when the button is clicked and not disabled or loading.',
+        },
+        {
+            name: 'type',
+            type: 'enum',
+            required: false,
+            default: 'button',
+            description: 'Native button type attribute.',
+            enumValues: ['button', 'submit', 'reset'],
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Primary action',
+            code: `<Button variant="primary" onClick={handleSave}>Save changes</Button>`,
+        },
+        {
+            title: 'Destructive action',
+            code: `<Button variant="danger" onClick={handleDelete}>Delete account</Button>`,
+        },
+        {
+            title: 'Loading state',
+            code: `<Button variant="primary" loading={isSaving}>Save changes</Button>`,
+        },
+        {
+            title: 'With icon',
+            code: `<Button variant="secondary" leftIcon={<PlusIcon />}>Add member</Button>`,
+        },
+        {
+            title: 'Ghost in toolbar',
+            code: `<Button variant="ghost" size="sm">Edit</Button>`,
+        },
+        {
+            title: 'Full-width submit',
+            code: `<Button variant="primary" type="submit" fullWidth>Sign in</Button>`,
+        },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'button',
+        ariaAttributes: ['aria-disabled', 'aria-busy'],
+        keyboardInteractions: ['Enter — activates the button', 'Space — activates the button'],
+    },
+};

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

@@ -0,0 +1,3 @@
+export { validateManifest, assertManifest, isValidPropDescriptor, } from './validate.js';
+export { ButtonManifest } from './examples/button.manifest.js';
+export const MANIFEST_SPEC_VERSION = '0.1';

package/dist-server/src/manifest/types.js

@@ -0,0 +1 @@
+export {};

package/dist-server/src/manifest/validate.js

@@ -0,0 +1,102 @@
+function err(field, message) {
+    return { field, message };
+}
+/**
+ * Validates a ComponentManifest object at runtime.
+ * Returns a result object — does not throw.
+ *
+ * @example
+ * const result = validateManifest(ButtonManifest);
+ * if (!result.valid) console.error(result.errors);
+ */
+export function validateManifest(manifest) {
+    const errors = [];
+    if (typeof manifest !== 'object' || manifest === null) {
+        return { valid: false, errors: [err('manifest', 'Must be a non-null object')] };
+    }
+    const m = manifest;
+    // Required string fields
+    const requiredStrings = ['id', 'name', 'description', 'designIntent', 'specVersion'];
+    for (const field of requiredStrings) {
+        if (typeof m[field] !== 'string' || m[field].trim() === '') {
+            errors.push(err(field, `Must be a non-empty string`));
+        }
+    }
+    // id: kebab-case
+    if (typeof m['id'] === 'string' && !/^[a-z][a-z0-9-]*$/.test(m['id'])) {
+        errors.push(err('id', 'Must be kebab-case (e.g. "button", "form-field")'));
+    }
+    // tier
+    const validTiers = ['atom', 'molecule', 'block', 'flow', 'overlay'];
+    if (!validTiers.includes(m['tier'])) {
+        errors.push(err('tier', `Must be one of: ${validTiers.join(', ')}`));
+    }
+    // domain
+    if (typeof m['domain'] !== 'string' || m['domain'].trim() === '') {
+        errors.push(err('domain', 'Must be a non-empty string'));
+    }
+    // props
+    if (!Array.isArray(m['props'])) {
+        errors.push(err('props', 'Must be an array'));
+    }
+    else {
+        m['props'].forEach((prop, i) => {
+            const p = prop;
+            const prefix = `props[${i}]`;
+            if (typeof p['name'] !== 'string' || p['name'] === '')
+                errors.push(err(`${prefix}.name`, 'Must be a non-empty string'));
+            if (typeof p['type'] !== 'string' || p['type'] === '')
+                errors.push(err(`${prefix}.type`, 'Must be a non-empty string'));
+            if (typeof p['required'] !== 'boolean')
+                errors.push(err(`${prefix}.required`, 'Must be a boolean'));
+            if (typeof p['description'] !== 'string' || p['description'] === '')
+                errors.push(err(`${prefix}.description`, 'Must be a non-empty string'));
+        });
+    }
+    // usageExamples
+    if (!Array.isArray(m['usageExamples'])) {
+        errors.push(err('usageExamples', 'Must be an array'));
+    }
+    else if (m['usageExamples'].length === 0) {
+        errors.push(err('usageExamples', 'Must have at least one example'));
+    }
+    else {
+        m['usageExamples'].forEach((ex, i) => {
+            const e = ex;
+            const prefix = `usageExamples[${i}]`;
+            if (typeof e['title'] !== 'string' || e['title'] === '')
+                errors.push(err(`${prefix}.title`, 'Must be a non-empty string'));
+            if (typeof e['code'] !== 'string' || e['code'] === '')
+                errors.push(err(`${prefix}.code`, 'Must be a non-empty string'));
+        });
+    }
+    // compositionGraph
+    if (!Array.isArray(m['compositionGraph'])) {
+        errors.push(err('compositionGraph', 'Must be an array (empty array is fine for atoms)'));
+    }
+    // specVersion
+    if (typeof m['specVersion'] === 'string' && !/^\d+\.\d+$/.test(m['specVersion'])) {
+        errors.push(err('specVersion', 'Must be "MAJOR.MINOR" format, e.g. "0.1"'));
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Asserts a manifest is valid. Throws a descriptive error if not.
+ * Use in tests or at component module load time.
+ */
+export function assertManifest(manifest) {
+    const result = validateManifest(manifest);
+    if (!result.valid) {
+        const messages = result.errors.map(e => `  ${e.field}: ${e.message}`).join('\n');
+        throw new Error(`Invalid ComponentManifest:\n${messages}`);
+    }
+}
+export function isValidPropDescriptor(prop) {
+    if (typeof prop !== 'object' || prop === null)
+        return false;
+    const p = prop;
+    return (typeof p['name'] === 'string' &&
+        typeof p['type'] === 'string' &&
+        typeof p['required'] === 'boolean' &&
+        typeof p['description'] === 'string');
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "lucent-ui",
+  "version": "0.1.0",
+  "description": "An AI-first React component library with machine-readable manifests.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./styles": "./dist/index.css"
+  },
+  "bin": {
+    "lucent-mcp": "./dist-server/server/index.js"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "dist-server"
+  ],
+  "keywords": [
+    "react",
+    "component-library",
+    "design-system",
+    "mcp",
+    "ai"
+  ],
+  "author": "Rozina Szogyenyi",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react": "^4.7.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.9.3",
+    "vite": "^6.4.1",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "dev": "vite --config vite.dev.config.ts",
+    "build": "vite build",
+    "build:server": "tsc -p server/tsconfig.json"
+  }
+}