lucent-ui 0.14.2 → 0.16.0

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

@@ -34,6 +34,20 @@ export const COMPONENT_MANIFEST = {
             required: false,
             description: 'Array of hex color strings shown as clickable swatches. Defaults to a 16-color palette.',
         },
+        {
+            name: 'size',
+            type: 'string',
+            required: false,
+            default: '"md"',
+            description: 'Swatch trigger size. "sm" renders a 24px swatch, "md" renders 40px.',
+        },
+        {
+            name: 'inline',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Places the label beside the swatch instead of above it. Useful for compact layouts.',
+        },
         {
             name: 'disabled',
             type: 'boolean',

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

@@ -44,6 +44,14 @@ export const COMPONENT_MANIFEST = {
             default: 'false',
             description: 'Disables interaction and renders muted text. Removes href and onClick.',
         },
+        {
+            name: 'inverse',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Uses surface background with primary text instead of accent for the active state. ' +
+                'Ideal for sidebar navigation on tinted chrome where the accent highlight would be too heavy.',
+        },
         {
             name: 'onClick',
             type: 'function',

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

@@ -4,21 +4,64 @@ export const COMPONENT_MANIFEST = {
     tier: 'molecule',
     domain: 'neutral',
     specVersion: '0.1',
-    description: 'A surface container with optional header, body, and footer slots, configurable padding, shadow, and radius. Includes a CardBleed sub-component for edge-to-edge content.',
-    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.\n\n' +
-        'CardBleed is a companion component that allows specific children within the Card body to stretch ' +
-        'edge-to-edge, cancelling the horizontal padding via negative margins. Text inside CardBleed stays ' +
-        'aligned with the rest of the card content thanks to matching inner padding. Use it for dividers, ' +
-        'full-width lists, or bordered sections that need to reach the card edges.\n\n' +
-        'Token rule: Card uses surface for its background. Never use bgBase or bgSubtle on a Card — ' +
-        'those tokens are reserved for the page canvas (body, sidebar, layout regions). Content nested ' +
-        'inside a Card that needs a tinted fill (e.g. a footer, inset panel, or disabled input) should use ' +
-        'surfaceSecondary.',
+    description: 'A surface container with five elevation variants that form a visual importance hierarchy. ' +
+        'Supports optional header, body, and footer slots with configurable padding, shadow, and radius. ' +
+        'Includes a CardBleed sub-component for edge-to-edge content.',
+    designIntent: 'Card provides a configurable surface with an explicit elevation hierarchy. Each variant maps to ' +
+        'a distinct level of visual prominence, giving consumers a single prop to express how much attention ' +
+        'a surface should command relative to its surroundings.\n\n' +
+        '## Elevation hierarchy (lowest → highest)\n\n' +
+        '1. **ghost** — transparent background, no border, no shadow.\n' +
+        '   The card is invisible as a container — content floats directly against the page or parent surface. ' +
+        'Use for logical groupings that shouldn\'t compete visually: sidebar sections, form regions, or ' +
+        'layout slots where structure exists conceptually but not visually. Header/footer dividers still ' +
+        'render if those slots are used, providing minimal internal structure.\n\n' +
+        '2. **outline** (default) — transparent background with `border-default` border, no shadow.\n' +
+        '   Like ghost, the card inherits its container\'s background — the border alone defines the boundary. ' +
+        'This is the workhorse variant for lists of items, form sections, data panels, ' +
+        'and any content that needs a visible container without drawing excessive attention. Header and footer ' +
+        'slots are separated from the body by matching `border-default` dividers.\n\n' +
+        '3. **filled** — semi-transparent tinted background, no border, no shadow.\n' +
+        '   Differentiates the card from its surroundings by darkening (light mode) or lightening (dark mode) ' +
+        'whatever surface it sits on. Uses `color-mix(in srgb, textPrimary 6%, transparent)` so the tint is ' +
+        'always relative to the container — never a fixed color. Use for secondary content areas, inset panels, ' +
+        'summary blocks, or anywhere a border would feel heavy but the card needs to be visually distinct. ' +
+        'Effective for nesting (e.g., a filled card inside an elevated card creates a recessed region).\n\n' +
+        '4. **elevated** — `surface` background with medium shadow, no border.\n' +
+        '   The card lifts off the page through depth. The shadow creates a physical metaphor: this content ' +
+        'sits above the surface it rests on. Use for primary content areas, feature highlights, pricing cards, ' +
+        'or any surface that should feel physically elevated. The lack of border keeps the silhouette soft — ' +
+        'the shadow alone defines the boundary.\n\n' +
+        '5. **combo** — transparent wrapper with an elevated body inset.\n' +
+        '   The header and footer are flat — they blend into the page background as if they were part of it. ' +
+        'Only the body section is elevated: it gets `surface` background, border-radius, and shadow, appearing ' +
+        'as a raised card sitting between the flat header/footer regions. This draws the eye to the primary ' +
+        'content while keeping supporting info (header) and actions (footer) visually subordinate — they frame ' +
+        'the elevated body without competing with it. No dividers are rendered — the elevation change IS the ' +
+        'visual separator. Use for detail panels, profile cards, or settings forms where the body content is ' +
+        'the focal point.\n\n' +
+        '## Shadow override\n' +
+        'The `shadow` prop overrides whatever shadow the variant implies. This allows fine-tuning without ' +
+        'changing the variant. For example, `variant="elevated" shadow="lg"` gives an elevated card with extra ' +
+        'depth, while `variant="outline" shadow="none"` gives a flat bordered card.\n\n' +
+        '## Token rules\n' +
+        '- `elevated` and `combo` body use `surface` (the primary component surface — white in light mode).\n' +
+        '- `filled` uses a semi-transparent tint of `textPrimary` — contextually darker/lighter than its container.\n' +
+        '- `combo` wrapper is transparent (header/footer blend with page); only the body is elevated with `surface`.\n' +
+        '- `ghost` and `outline` use `transparent` — they inherit from whatever they\'re placed on. ' +
+        'The border is the only visual differentiator for `outline`.\n' +
+        '- Never use `bgBase` or `bgSubtle` on a Card — those tokens are reserved for the page canvas.\n' +
+        '- Content nested inside a Card that needs a tinted fill should use `surfaceSecondary`.',
     props: [
+        {
+            name: 'variant',
+            type: 'enum',
+            required: false,
+            default: 'outline',
+            description: 'The elevation variant. Controls background color, border, and default shadow. ' +
+                'Ordered from lowest to highest visual prominence: ghost → outline → filled → elevated → combo.',
+            enumValues: ['ghost', 'outline', 'filled', 'elevated', 'combo'],
+        },
         {
             name: 'children',
             type: 'ReactNode',
@@ -29,13 +72,15 @@ export const COMPONENT_MANIFEST = {
             name: 'header',
             type: 'ReactNode',
             required: false,
-            description: 'Content rendered in the header slot, separated from the body by a divider.',
+            description: 'Content rendered in the header slot. Separated from the body by a divider in all variants except combo, ' +
+                'where the background-color change provides the separation.',
         },
         {
             name: 'footer',
             type: 'ReactNode',
             required: false,
-            description: 'Content rendered in the footer slot, separated from the body by a divider.',
+            description: 'Content rendered in the footer slot. Separated from the body by a divider in all variants except combo, ' +
+                'where the background-color change provides the separation.',
         },
         {
             name: 'padding',
@@ -49,8 +94,8 @@ export const COMPONENT_MANIFEST = {
             name: 'shadow',
             type: 'enum',
             required: false,
-            default: 'sm',
-            description: 'Box shadow elevation.',
+            description: 'Box shadow elevation. When omitted, uses the variant\'s default: ghost=none, outline=none, filled=none, elevated=md, combo=md. ' +
+                'When set explicitly, overrides the variant\'s default.',
             enumValues: ['none', 'sm', 'md', 'lg'],
         },
         {
@@ -67,27 +112,102 @@ export const COMPONENT_MANIFEST = {
             required: false,
             description: 'Inline style overrides for the card wrapper.',
         },
+        {
+            name: 'onClick',
+            type: 'function',
+            required: false,
+            description: 'Click handler. When provided, the card renders as a <button> with hover lift, focus ring, ' +
+                'and active press states matching the Button component.',
+        },
+        {
+            name: 'href',
+            type: 'string',
+            required: false,
+            description: 'Link URL. When provided, the card renders as an <a>. Takes precedence over onClick for the element type, ' +
+                'but onClick is still attached as a handler.',
+        },
+        {
+            name: 'target',
+            type: 'string',
+            required: false,
+            description: 'Passed to <a> when href is set (e.g. "_blank").',
+        },
+        {
+            name: 'rel',
+            type: 'string',
+            required: false,
+            description: 'Passed to <a> when href is set (e.g. "noopener noreferrer").',
+        },
+        {
+            name: 'disabled',
+            type: 'boolean',
+            required: false,
+            description: 'Disables interactive behavior. Reduces opacity, removes hover/focus/active states, ' +
+                'and sets cursor to not-allowed. Only applies when onClick or href is set.',
+        },
+        {
+            name: 'status',
+            type: 'enum',
+            required: false,
+            description: 'Adds a 3px colored accent bar on the left edge of the card. Uses the corresponding status ' +
+                'token (successDefault, warningDefault, dangerDefault, infoDefault). Works with all variants.',
+            enumValues: ['success', 'warning', 'danger', 'info'],
+        },
+        {
+            name: 'selected',
+            type: 'boolean',
+            required: false,
+            description: 'Adds an inset accent ring and subtle background tint to indicate selection. Used for card grids ' +
+                'where cards act as radio/checkbox options. Pairs with onClick for toggle behavior. ' +
+                'Sets aria-pressed on interactive cards. Disabled takes precedence — ring is hidden when disabled.',
+        },
+        {
+            name: 'media',
+            type: 'ReactNode',
+            required: false,
+            description: 'Full-bleed content rendered at the top of the card (before header). No padding is applied. ' +
+                'Use for hero images, illustrations, or any edge-to-edge top content. The card\'s overflow:hidden ' +
+                'clips media to the border-radius.',
+        },
     ],
     usageExamples: [
         {
-            title: 'Simple card',
-            code: `<Card>
-  <Text>Some content here.</Text>
+            title: 'Ghost — invisible container',
+            code: `<Card variant="ghost">
+  <Text>Content sits directly on the page background.</Text>
 </Card>`,
         },
         {
-            title: 'With header and footer',
+            title: 'Outline — bordered card (default)',
             code: `<Card
   header={<Text weight="semibold">Card title</Text>}
   footer={<Button variant="primary">Save</Button>}
 >
-  <Text color="secondary">Card body content goes here.</Text>
+  <Text color="secondary">The standard card treatment with dividers.</Text>
+</Card>`,
+        },
+        {
+            title: 'Filled — color-differentiated region',
+            code: `<Card variant="filled" padding="lg">
+  <Text weight="semibold">Summary</Text>
+  <Text color="secondary" size="sm">A tinted panel that stands out through background color alone.</Text>
 </Card>`,
         },
         {
-            title: 'Flat variant',
-            code: `<Card shadow="none" radius="sm" padding="sm">
-  <Text size="sm">Compact flat card</Text>
+            title: 'Elevated — shadow-lifted surface',
+            code: `<Card variant="elevated">
+  <Text weight="semibold">Featured</Text>
+  <Text color="secondary">This card floats above the page with shadow depth.</Text>
+</Card>`,
+        },
+        {
+            title: 'Combo — two-tone card with header and footer',
+            code: `<Card
+  variant="combo"
+  header={<Text weight="semibold">Profile</Text>}
+  footer={<Button variant="primary">Update</Button>}
+>
+  <Text>The bright body is framed by the muted header and footer.</Text>
 </Card>`,
         },
         {
@@ -97,13 +217,58 @@ export const COMPONENT_MANIFEST = {
   <CardBleed style={{ borderTop: '1px solid var(--lucent-border-default)', marginTop: 'var(--lucent-space-4)' }}>
     <Text color="secondary">This section stretches to the card edges.</Text>
   </CardBleed>
+</Card>`,
+        },
+        {
+            title: 'Clickable card',
+            code: `<Card variant="elevated" onClick={() => navigate('/detail')}>
+  <Text weight="semibold">Dashboard tile</Text>
+  <Text color="secondary" size="sm">Click to view details</Text>
+</Card>`,
+        },
+        {
+            title: 'Link card',
+            code: `<Card variant="elevated" href="/docs/getting-started" target="_blank" rel="noopener noreferrer">
+  <Text weight="semibold">Documentation</Text>
+  <Text color="secondary" size="sm">Opens in a new tab</Text>
+</Card>`,
+        },
+        {
+            title: 'Status accent',
+            code: `<Card status="danger">
+  <Text weight="semibold">Payment failed</Text>
+  <Text color="secondary" size="sm">Check your card details and try again.</Text>
+</Card>`,
+        },
+        {
+            title: 'Selectable card',
+            code: `<Card
+  variant="elevated"
+  selected={isSelected}
+  onClick={() => setIsSelected(!isSelected)}
+>
+  <Text weight="semibold">Pro plan</Text>
+  <Text color="secondary" size="sm">$29/month</Text>
+</Card>`,
+        },
+        {
+            title: 'Media card with hero image',
+            code: `<Card
+  variant="elevated"
+  media={<img src="/hero.jpg" alt="Hero" style={{ width: '100%', display: 'block' }} />}
+>
+  <Text weight="semibold">Article title</Text>
+  <Text color="secondary" size="sm">A card with a full-bleed hero image.</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.',
+        notes: 'Non-interactive cards have no implicit ARIA role — wrap in <section> or <article> if needed. ' +
+            'Interactive cards with onClick render as <button> with focus ring. ' +
+            'Interactive cards with href render as <a> with focus ring. ' +
+            'Selected cards set aria-pressed on the interactive element. ' +
+            'The status accent bar is aria-hidden (decorative). ' +
+            'Media slot images should include alt text.',
     },
 };

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

@@ -5,7 +5,9 @@ export const COMPONENT_MANIFEST = {
     domain: 'neutral',
     specVersion: '0.1',
     description: 'Full-viewport shell layout with optional header, left sidebar, right panel, and footer slots arranged in a flex column/row structure.',
-    designIntent: 'PageLayout owns the outermost chrome of an application page. The body row is a flex row containing ' +
+    designIntent: 'PageLayout owns the outermost chrome of an application page. Chrome regions (header, sidebar, footer) ' +
+        'default to bgBase so the main content card feels elevated against the page canvas — especially ' +
+        'noticeable with tinted bgBase values. The body row is a flex row containing ' +
         'an optional left sidebar, a bordered main content card, and an optional right panel — all as structural ' +
         'siblings so they share the same vertical space. The header and footer sit outside the body row as ' +
         'flex children of the outer column, ensuring they span the full width. Sidebars collapse to zero width ' +
@@ -87,6 +89,16 @@ export const COMPONENT_MANIFEST = {
             default: '28',
             description: 'Footer height in px (number) or any CSS value (string). Default: 28 — sized for a compact status bar.',
         },
+        {
+            name: 'chromeBackground',
+            type: 'string',
+            required: false,
+            default: '"bgBase"',
+            description: 'Background token for chrome regions (header, sidebar, footer). ' +
+                '"bgBase" uses the page canvas color so the main content card feels elevated; ' +
+                '"bgSubtle" uses a subtle shade of bgBase for chrome distinction; ' +
+                '"surface" matches the old behavior where chrome and content share the same background.',
+        },
         {
             name: 'mainStyle',
             type: 'object',

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

@@ -0,0 +1,28 @@
+import { describe, test, expect } from 'vitest';
+import { validateManifest } from './validate.js';
+// Auto-discover all component manifests
+const manifestModules = import.meta.glob('../components/**/*.manifest.ts', { eager: true });
+const manifests = Object.entries(manifestModules).map(([path, mod]) => {
+    const m = mod;
+    const manifest = m['COMPONENT_MANIFEST'];
+    return { path, manifest };
+});
+describe('Component manifests', () => {
+    test('at least one manifest was discovered', () => {
+        expect(manifests.length).toBeGreaterThan(0);
+    });
+    for (const { path, manifest } of manifests) {
+        const label = path.replace('../components/', '').replace('.manifest.ts', '');
+        test(`${label} — exports COMPONENT_MANIFEST`, () => {
+            expect(manifest).toBeDefined();
+        });
+        test(`${label} — passes schema validation`, () => {
+            const result = validateManifest(manifest);
+            if (!result.valid) {
+                const messages = result.errors.map(e => `  ${e.field}: ${e.message}`).join('\n');
+                throw new Error(`Invalid manifest:\n${messages}`);
+            }
+            expect(result.valid).toBe(true);
+        });
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lucent-ui",
-  "version": "0.14.2",
+  "version": "0.16.0",
   "description": "An AI-first React component library with machine-readable manifests.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -25,6 +25,18 @@
     "dist-server",
     "dist-cli"
   ],
+  "scripts": {
+    "dev": "vite --config vite.dev.config.ts",
+    "build": "vite build",
+    "build:server": "tsc -p server/tsconfig.json",
+    "build:cli": "tsc -p cli/tsconfig.json && cp cli/template.manifest.json dist-cli/cli/template.manifest.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "tsc --noEmit && pnpm build && pnpm build:server && pnpm build:cli",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm prepublishOnly && changeset publish"
+  },
   "keywords": [
     "react",
     "component-library",
@@ -39,6 +51,7 @@
   },
   "author": "Rozina Szogyenyi",
   "license": "MIT",
+  "packageManager": "pnpm@10.30.3",
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
@@ -60,16 +73,5 @@
   "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",
-    "build:cli": "tsc -p cli/tsconfig.json && cp cli/template.manifest.json dist-cli/cli/template.manifest.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "pnpm prepublishOnly && changeset publish"
   }
-}
+}