lucent-ui 0.1.0

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

@@ -0,0 +1,62 @@
+export const COMPONENT_MANIFEST = {
+    id: 'tag',
+    name: 'Tag',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A dismissible label for applied filters, selected values, or categorisation.',
+    designIntent: 'Tags represent user-applied selections that can be removed — filters, multi-select ' +
+        'values, categories. They differ from Badge in that they are interactive: provide ' +
+        'onDismiss when the user should be able to remove the tag. Without onDismiss they render ' +
+        'as a static pill (identical to Badge in purpose). Use semantic variants to match meaning; ' +
+        'default to neutral for user-generated content where no semantic applies.',
+    props: [
+        {
+            name: 'children',
+            type: 'ReactNode',
+            required: true,
+            description: 'Tag label content.',
+        },
+        {
+            name: 'variant',
+            type: 'enum',
+            required: false,
+            default: 'neutral',
+            description: 'Colour scheme conveying semantic meaning.',
+            enumValues: ['neutral', 'accent', 'success', 'warning', 'danger', 'info'],
+        },
+        {
+            name: 'size',
+            type: 'enum',
+            required: false,
+            default: 'md',
+            description: 'Controls height and font size.',
+            enumValues: ['sm', 'md'],
+        },
+        {
+            name: 'onDismiss',
+            type: 'function',
+            required: false,
+            description: 'When provided, renders an × button that calls this handler on click.',
+        },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Dims the tag and prevents the dismiss action.',
+        },
+    ],
+    usageExamples: [
+        { title: 'Dismissible filter', code: `<Tag onDismiss={() => removeFilter('react')}>React</Tag>` },
+        { title: 'Multi-select value', code: `<Tag variant="accent" onDismiss={() => deselect(id)}>Jane Doe</Tag>` },
+        { title: 'Static category', code: `<Tag variant="info">Beta</Tag>` },
+        { title: 'Danger (removable)', code: `<Tag variant="danger" onDismiss={handleRemove}>Blocked</Tag>` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'group',
+        notes: 'The dismiss button has aria-label="Dismiss" and is keyboard-focusable.',
+        keyboardInteractions: ['Enter / Space — activates the dismiss button when focused'],
+    },
+};

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

@@ -0,0 +1,106 @@
+export const COMPONENT_MANIFEST = {
+    id: 'text',
+    name: 'Text',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'Polymorphic typography primitive that maps semantic HTML elements to design-system type scales.',
+    designIntent: 'Text is the single source of truth for typography in Lucent UI. Rather than hard-coding font sizes ' +
+        'and colors directly in components, every piece of rendered text should pass through this atom. ' +
+        'The `as` prop controls the HTML element (and therefore semantic meaning), while `size`, `weight`, ' +
+        '`color`, and `lineHeight` control appearance independently — decoupling semantics from style. ' +
+        'Use `truncate` only in constrained-width containers where overflow must be prevented; it applies ' +
+        'overflow: hidden + text-overflow: ellipsis. The `family` prop enables inline code or monospaced ' +
+        'content without switching components.',
+    props: [
+        {
+            name: 'as',
+            type: 'enum',
+            required: false,
+            default: 'p',
+            description: 'HTML element to render. Controls semantic meaning independently of visual style.',
+            enumValues: ['p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'span', 'div', 'label', 'strong', 'em', 'code'],
+        },
+        {
+            name: 'size',
+            type: 'enum',
+            required: false,
+            default: 'md',
+            description: 'Font size from the type scale. Maps to the corresponding --lucent-font-size-* token.',
+            enumValues: ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'],
+        },
+        {
+            name: 'weight',
+            type: 'enum',
+            required: false,
+            default: 'regular',
+            description: 'Font weight. Maps to --lucent-font-weight-* tokens.',
+            enumValues: ['regular', 'medium', 'semibold', 'bold'],
+        },
+        {
+            name: 'color',
+            type: 'enum',
+            required: false,
+            default: 'primary',
+            description: 'Semantic text color. All values adapt automatically in light and dark themes.',
+            enumValues: ['primary', 'secondary', 'disabled', 'inverse', 'onAccent', 'success', 'warning', 'danger', 'info'],
+        },
+        {
+            name: 'align',
+            type: 'enum',
+            required: false,
+            default: 'left',
+            description: 'Text alignment.',
+            enumValues: ['left', 'center', 'right'],
+        },
+        {
+            name: 'lineHeight',
+            type: 'enum',
+            required: false,
+            default: 'base',
+            description: 'Line height. tight=1.25, base=1.5, relaxed=1.75.',
+            enumValues: ['tight', 'base', 'relaxed'],
+        },
+        {
+            name: 'family',
+            type: 'enum',
+            required: false,
+            default: 'base',
+            description: 'Font family. Use mono for code or tabular data. Use display (Unbounded) for headings and marketing copy.',
+            enumValues: ['base', 'mono', 'display'],
+        },
+        {
+            name: 'truncate',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Clips overflow text with an ellipsis. Requires the container to have a constrained width.',
+        },
+        {
+            name: 'children',
+            type: 'ReactNode',
+            required: true,
+            description: 'The text content to render.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides. Applied after computed token styles.',
+        },
+    ],
+    usageExamples: [
+        { title: 'Heading', code: `<Text as="h1" size="3xl" weight="bold">Page title</Text>` },
+        { title: 'Body paragraph', code: `<Text size="md" color="secondary">Supporting copy goes here.</Text>` },
+        { title: 'Label', code: `<Text as="label" size="sm" weight="medium" htmlFor="email">Email</Text>` },
+        { title: 'Inline code', code: `<Text as="code" family="mono" size="sm">const x = 1;</Text>` },
+        { title: 'Truncated', code: `<Text truncate style={{ maxWidth: 200 }}>Very long text that will be clipped</Text>` },
+        { title: 'Status color', code: `<Text color="danger" size="xs">This field is required</Text>` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        notes: 'The rendered element determines the implicit ARIA role. Use heading elements (h1–h6) for document ' +
+            'headings so screen readers can navigate the page structure. Use `as="label"` with `htmlFor` to ' +
+            'associate labels with form controls. Decorative text needs no additional ARIA.',
+    },
+};

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

@@ -0,0 +1,35 @@
+export const COMPONENT_MANIFEST = {
+    id: 'textarea',
+    name: 'Textarea',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A multi-line text input with optional auto-resize and character count.',
+    designIntent: 'Use autoResize for open-ended fields (bio, description) where content length is unpredictable. ' +
+        'Use maxLength + showCount for fields with hard limits (tweet-style). ' +
+        'Behaves identically to Input for label/helper/error patterns.',
+    props: [
+        { name: 'label', type: 'string', required: false, description: 'Visible label above the textarea.' },
+        { name: 'helperText', type: 'string', required: false, description: 'Hint text shown below.' },
+        { name: 'errorText', type: 'string', required: false, description: 'Validation error. Triggers error styling.' },
+        { name: 'autoResize', type: 'boolean', required: false, default: 'false', description: 'Grows with content, disables manual resize handle.' },
+        { name: 'maxLength', type: 'number', required: false, description: 'Character limit. Displays counter when set.' },
+        { name: 'showCount', type: 'boolean', required: false, default: 'false', description: 'Always show character counter even without maxLength.' },
+        { name: 'value', type: 'string', required: false, description: 'Controlled value.' },
+        { name: 'onChange', type: 'function', required: false, description: 'Change handler.' },
+        { name: 'placeholder', type: 'string', required: false, description: 'Placeholder text.' },
+        { name: 'disabled', type: 'boolean', required: false, default: 'false', description: 'Disables the textarea.' },
+    ],
+    usageExamples: [
+        { title: 'Basic', code: `<Textarea label="Bio" placeholder="Tell us about yourself…" />` },
+        { title: 'Auto-resize', code: `<Textarea label="Description" autoResize value={value} onChange={e => setValue(e.target.value)} />` },
+        { title: 'With character count', code: `<Textarea label="Tweet" maxLength={280} showCount value={value} onChange={e => setValue(e.target.value)} />` },
+        { title: 'Error state', code: `<Textarea label="Notes" errorText="Required" value="" />` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'textbox',
+        ariaAttributes: ['aria-multiline', 'aria-invalid', 'aria-describedby'],
+        keyboardInteractions: ['Tab — focuses the textarea'],
+    },
+};

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

@@ -0,0 +1,67 @@
+export const COMPONENT_MANIFEST = {
+    id: 'toggle',
+    name: 'Toggle',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A sliding switch for immediately-applied binary settings.',
+    designIntent: 'Toggles are for settings that take effect the moment they are flipped — no Save button ' +
+        'needed. If the action requires a confirmation step or only applies on form submit, use a ' +
+        'Checkbox instead. The "on" state is visually represented by the accent colour so the ' +
+        'meaning is clear without relying on text alone. Keep the label short (2–4 words) and ' +
+        'phrase it as the enabled state (e.g. "Dark mode", not "Enable dark mode").',
+    props: [
+        {
+            name: 'checked',
+            type: 'boolean',
+            required: false,
+            description: 'Controlled on/off state. Pair with onChange for controlled usage.',
+        },
+        {
+            name: 'defaultChecked',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Initial state for uncontrolled usage.',
+        },
+        {
+            name: 'onChange',
+            type: 'function',
+            required: false,
+            description: 'Called when the toggle is flipped.',
+        },
+        {
+            name: 'label',
+            type: 'string',
+            required: false,
+            description: 'Visible label rendered beside the toggle.',
+        },
+        {
+            name: 'size',
+            type: 'enum',
+            required: false,
+            default: 'md',
+            description: 'Controls the track and thumb size.',
+            enumValues: ['sm', 'md', 'lg'],
+        },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Prevents interaction and dims the control.',
+        },
+    ],
+    usageExamples: [
+        { title: 'Controlled', code: `<Toggle checked={darkMode} onChange={e => setDarkMode(e.target.checked)} label="Dark mode" />` },
+        { title: 'Uncontrolled', code: `<Toggle defaultChecked label="Email notifications" />` },
+        { title: 'Sizes', code: `<Toggle size="sm" label="Compact" />\n<Toggle size="md" label="Default" />\n<Toggle size="lg" label="Large" />` },
+        { title: 'Disabled', code: `<Toggle disabled label="Unavailable setting" />` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'switch',
+        ariaAttributes: ['aria-checked', 'aria-disabled'],
+        keyboardInteractions: ['Space — toggles the switch state'],
+    },
+};

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

@@ -0,0 +1,54 @@
+export const COMPONENT_MANIFEST = {
+    id: 'tooltip',
+    name: 'Tooltip',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A transient label that appears on hover or focus to explain an element.',
+    designIntent: 'Tooltips surface supplementary context that would clutter the UI if shown permanently — ' +
+        'keyboard shortcut hints, icon button labels, truncated text expansions. They must never ' +
+        'contain critical information (errors, required actions) because they are invisible until ' +
+        'hovered. Keep content to one short phrase; avoid wrapping. Use placement to avoid viewport ' +
+        'edges — "top" is the default and works in most cases.',
+    props: [
+        {
+            name: 'content',
+            type: 'ReactNode',
+            required: true,
+            description: 'Text or element shown inside the tooltip. Keep it short (under 80 chars).',
+        },
+        {
+            name: 'children',
+            type: 'ReactNode',
+            required: true,
+            description: 'The element that triggers the tooltip on hover/focus.',
+        },
+        {
+            name: 'placement',
+            type: 'enum',
+            required: false,
+            default: 'top',
+            description: 'Position of the tooltip relative to the trigger.',
+            enumValues: ['top', 'bottom', 'left', 'right'],
+        },
+        {
+            name: 'delay',
+            type: 'number',
+            required: false,
+            default: '300',
+            description: 'Milliseconds before the tooltip appears. Prevents flicker on fast cursor movement.',
+        },
+    ],
+    usageExamples: [
+        { title: 'Icon button label', code: `<Tooltip content="Copy to clipboard"><IconButton icon={<CopyIcon />} /></Tooltip>` },
+        { title: 'Keyboard shortcut hint', code: `<Tooltip content="⌘K"><Button variant="ghost">Search</Button></Tooltip>` },
+        { title: 'Bottom placement', code: `<Tooltip content="Opens in a new tab" placement="bottom"><a href="…">Link</a></Tooltip>` },
+        { title: 'No delay (instant)', code: `<Tooltip content="Delete" delay={0}><Button variant="ghost">🗑</Button></Tooltip>` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'tooltip',
+        ariaAttributes: ['role="tooltip"'],
+        notes: 'The tooltip is shown on both hover and focus, making it accessible to keyboard users. Content is exposed via role="tooltip".',
+    },
+};

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

@@ -0,0 +1,81 @@
+export const COMPONENT_MANIFEST = {
+    id: 'alert',
+    name: 'Alert',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'An inline feedback banner with info, success, warning, and danger variants, optional title, and dismiss button.',
+    designIntent: 'Alert uses role="alert" so screen readers announce the message immediately when it appears. ' +
+        'Each variant has a built-in icon that communicates intent visually; the icon can be overridden ' +
+        'for custom scenarios. Title and body are both optional — you can show either, both, or just an ' +
+        'icon with a body. The dismiss button is only rendered when onDismiss is provided, keeping the ' +
+        'layout clean for non-dismissible alerts. All colors use status semantic tokens so they adapt ' +
+        'correctly between light and dark themes.',
+    props: [
+        {
+            name: 'variant',
+            type: 'enum',
+            required: false,
+            default: 'info',
+            description: 'Visual and semantic variant of the alert.',
+            enumValues: ['info', 'success', 'warning', 'danger'],
+        },
+        {
+            name: 'title',
+            type: 'string',
+            required: false,
+            description: 'Bold title line rendered above the body.',
+        },
+        {
+            name: 'children',
+            type: 'ReactNode',
+            required: false,
+            description: 'Alert body content — typically a short sentence or ReactNode.',
+        },
+        {
+            name: 'onDismiss',
+            type: 'function',
+            required: false,
+            description: 'When provided, renders a dismiss (×) button and calls this handler on click.',
+        },
+        {
+            name: 'icon',
+            type: 'ReactNode',
+            required: false,
+            description: 'Custom icon to replace the built-in variant icon.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the alert wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Info with body',
+            code: `<Alert variant="info">Your changes have been saved as a draft.</Alert>`,
+        },
+        {
+            title: 'With title and dismiss',
+            code: `<Alert variant="danger" title="Payment failed" onDismiss={() => setVisible(false)}>
+  Check your card details and try again.
+</Alert>`,
+        },
+        {
+            title: 'Success confirmation',
+            code: `<Alert variant="success" title="Order placed!">
+  You'll receive a confirmation email shortly.
+</Alert>`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'text', componentName: 'Text', role: 'Title and body content', required: false },
+    ],
+    accessibility: {
+        role: 'alert',
+        ariaAttributes: ['aria-label'],
+        notes: 'role="alert" causes screen readers to announce the content immediately when rendered. ' +
+            'For non-urgent status messages, consider using role="status" instead by overriding via style/wrapper.',
+    },
+};

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

@@ -0,0 +1,92 @@
+export const COMPONENT_MANIFEST = {
+    id: 'card',
+    name: 'Card',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A surface container with optional header, body, and footer slots, configurable padding, shadow, and radius.',
+    designIntent: 'Card provides a consistent elevated surface for grouping related content. The header and footer slots ' +
+        'are separated from the body by a border-default divider, giving visual structure without requiring ' +
+        'the consumer to manage spacing. Padding, shadow, and radius are all configurable to accommodate ' +
+        'flat/ghost cards, modal-like surfaces, and compact data-dense layouts. The overflow: hidden ensures ' +
+        'children respect the border-radius without needing additional clipping.',
+    props: [
+        {
+            name: 'children',
+            type: 'ReactNode',
+            required: true,
+            description: 'The card body content.',
+        },
+        {
+            name: 'header',
+            type: 'ReactNode',
+            required: false,
+            description: 'Content rendered in the header slot, separated from the body by a divider.',
+        },
+        {
+            name: 'footer',
+            type: 'ReactNode',
+            required: false,
+            description: 'Content rendered in the footer slot, separated from the body by a divider.',
+        },
+        {
+            name: 'padding',
+            type: 'enum',
+            required: false,
+            default: 'md',
+            description: 'Inner padding applied equally to header, body, and footer.',
+            enumValues: ['none', 'sm', 'md', 'lg'],
+        },
+        {
+            name: 'shadow',
+            type: 'enum',
+            required: false,
+            default: 'sm',
+            description: 'Box shadow elevation.',
+            enumValues: ['none', 'sm', 'md', 'lg'],
+        },
+        {
+            name: 'radius',
+            type: 'enum',
+            required: false,
+            default: 'md',
+            description: 'Border radius of the card.',
+            enumValues: ['none', 'sm', 'md', 'lg'],
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the card wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Simple card',
+            code: `<Card>
+  <Text>Some content here.</Text>
+</Card>`,
+        },
+        {
+            title: 'With header and footer',
+            code: `<Card
+  header={<Text weight="semibold">Card title</Text>}
+  footer={<Button variant="primary">Save</Button>}
+>
+  <Text color="secondary">Card body content goes here.</Text>
+</Card>`,
+        },
+        {
+            title: 'Flat variant',
+            code: `<Card shadow="none" radius="sm" padding="sm">
+  <Text size="sm">Compact flat card</Text>
+</Card>`,
+        },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        notes: 'Card has no implicit ARIA role. If the card represents a landmark, wrap it in a <section> or <article> ' +
+            'and provide an aria-label. For interactive cards (clickable), make the wrapper a <button> or <a> and ' +
+            'ensure focus styles are visible.',
+    },
+};

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

@@ -0,0 +1,79 @@
+export const COMPONENT_MANIFEST = {
+    id: 'empty-state',
+    name: 'EmptyState',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A centered placeholder shown when a list or page has no content, with an optional illustration, title, description, and CTA.',
+    designIntent: 'EmptyState communicates the absence of data in a constructive way. The illustration slot accepts any ' +
+        'ReactNode — an Icon atom, a custom SVG, or an image — and constrains it to a 64px square to maintain ' +
+        'visual consistency. Title is required to ensure the state is always named; description is optional for ' +
+        'additional context. The action slot accepts any ReactNode (typically a Button) so the consumer controls ' +
+        'variant and label without prescribing them. The entire layout is center-aligned and padded to sit ' +
+        'naturally inside a Card or page section.',
+    props: [
+        {
+            name: 'title',
+            type: 'string',
+            required: true,
+            description: 'Short headline naming the empty state (e.g. "No results found").',
+        },
+        {
+            name: 'illustration',
+            type: 'ReactNode',
+            required: false,
+            description: 'Icon, SVG, or image rendered above the title. Constrained to a 64px container.',
+        },
+        {
+            name: 'description',
+            type: 'string',
+            required: false,
+            description: 'Secondary text below the title providing context or next steps.',
+        },
+        {
+            name: 'action',
+            type: 'ReactNode',
+            required: false,
+            description: 'Call-to-action rendered below the description — typically a Button.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the outer wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'No search results',
+            code: `<EmptyState
+  illustration={<Icon size="xl"><SearchIcon /></Icon>}
+  title="No results found"
+  description="Try adjusting your search or filter to find what you're looking for."
+  action={<Button variant="secondary" onClick={clearSearch}>Clear search</Button>}
+/>`,
+        },
+        {
+            title: 'Empty list with CTA',
+            code: `<EmptyState
+  title="No projects yet"
+  description="Create your first project to get started."
+  action={<Button variant="primary">New project</Button>}
+/>`,
+        },
+        {
+            title: 'Inside a Card',
+            code: `<Card>
+  <EmptyState title="Nothing here" description="Add items to see them listed." />
+</Card>`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'text', componentName: 'Text', role: 'Title and description', required: true },
+    ],
+    accessibility: {
+        notes: 'The title renders as an h3 by default. If EmptyState appears inside a section with its own heading ' +
+            'hierarchy, override by passing a Text component as part of a custom layout. Ensure the action element ' +
+            'has a descriptive label for screen readers.',
+    },
+};