lucent-ui 0.39.0 → 0.40.0

package/dist-server/server/http.js

@@ -3,6 +3,33 @@ import { createServer } from 'node:http';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { registerTools, DESIGN_RULES_SUMMARY } from './tools.js';
+import { getRecentCalls, subscribeToCalls } from './logger.js';
+function computeAggregates(calls) {
+    const perTool = {};
+    const keySet = new Set();
+    let errors = 0;
+    let totalDuration = 0;
+    let lastMinute = 0;
+    const oneMinuteAgo = Date.now() - 60_000;
+    for (const call of calls) {
+        perTool[call.tool] = (perTool[call.tool] ?? 0) + 1;
+        if (call.key !== undefined)
+            keySet.add(call.key);
+        if (!call.ok)
+            errors += 1;
+        totalDuration += call.durationMs;
+        if (Date.parse(call.t) >= oneMinuteAgo)
+            lastMinute += 1;
+    }
+    return {
+        total: calls.length,
+        perTool,
+        uniqueKeys: keySet.size,
+        lastMinute,
+        errors,
+        avgDurationMs: calls.length > 0 ? Math.round(totalDuration / calls.length) : null,
+    };
+}
 const PORT = Number(process.env['PORT'] ?? 3000);
 const HOST = process.env['HOST'] ?? '127.0.0.1';
 const API_KEY = process.env['LUCENT_API_KEY'];
@@ -73,6 +100,48 @@ const httpServer = createServer(async (req, res) => {
         writeJson(res, 200, { status: 'ok' });
         return;
     }
+    // Usage snapshot — recent calls + aggregates for the dashboard.
+    if (url.pathname === '/usage' && req.method === 'GET') {
+        if (!checkAuth(req)) {
+            res.setHeader('WWW-Authenticate', 'Bearer');
+            writeJson(res, 401, { error: 'Unauthorized' });
+            return;
+        }
+        const calls = getRecentCalls();
+        writeJson(res, 200, {
+            calls,
+            aggregates: computeAggregates(calls),
+        });
+        return;
+    }
+    // Usage live stream — SSE, pushes each new tool call as it happens.
+    if (url.pathname === '/usage/stream' && req.method === 'GET') {
+        if (!checkAuth(req)) {
+            res.setHeader('WWW-Authenticate', 'Bearer');
+            writeJson(res, 401, { error: 'Unauthorized' });
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no', // disable proxy buffering (nginx, some CDNs)
+        });
+        // Prime the connection so clients know we're live.
+        res.write(': connected\n\n');
+        const unsubscribe = subscribeToCalls((entry) => {
+            res.write(`data: ${JSON.stringify(entry)}\n\n`);
+        });
+        // Keep-alive heartbeat every 25s so idle connections aren't dropped.
+        const heartbeat = setInterval(() => {
+            res.write(': heartbeat\n\n');
+        }, 25_000);
+        req.on('close', () => {
+            clearInterval(heartbeat);
+            unsubscribe();
+        });
+        return;
+    }
     if (url.pathname !== MCP_PATH) {
         writeJson(res, 404, { error: 'Not found' });
         return;

package/dist-server/server/logger.js

@@ -1,14 +1,19 @@
 import { createHash } from 'node:crypto';
 /**
- * Structured logging for MCP tool calls.
+ * Structured logging + in-memory ring buffer for MCP tool calls.
  *
  * One JSON line per call is written to stderr (greppable, parseable by log
- * shippers). Set `LUCENT_MCP_QUIET=1` to disable all logging.
+ * shippers), and the same entry is pushed to an in-memory ring buffer used
+ * by the `/usage` and `/usage/stream` HTTP endpoints.
  *
- * When `LUCENT_API_KEY` is set, a short hash prefix of the key is included
+ * Set `LUCENT_MCP_QUIET=1` to silence stderr — the ring buffer still fills,
+ * so the usage dashboard keeps working.
+ *
+ * When `LUCENT_API_KEY` is set, a short sha256 prefix of the key is included
  * in log entries for usage analytics. The raw key is never logged.
  */
 const QUIET = process.env['LUCENT_MCP_QUIET'] === '1';
+const BUFFER_SIZE = 500;
 /**
  * Returns the first 8 hex chars of sha256(key). Short enough to stay readable
  * in logs, safe to leak (pre-image resistant), and unique enough to distinguish
@@ -17,11 +22,27 @@ const QUIET = process.env['LUCENT_MCP_QUIET'] === '1';
 function hashKeyPrefix(key) {
     return createHash('sha256').update(key).digest('hex').slice(0, 8);
 }
+// ─── Ring buffer + subscribers ───────────────────────────────────────────────
+const recentCalls = [];
+const subscribers = new Set();
+/** Snapshot of the ring buffer, newest first. */
+export function getRecentCalls() {
+    return recentCalls.slice().reverse();
+}
+/**
+ * Subscribe to new tool calls as they happen. Returns an unsubscribe function.
+ * Used by the `/usage/stream` SSE endpoint to push live updates.
+ */
+export function subscribeToCalls(fn) {
+    subscribers.add(fn);
+    return () => {
+        subscribers.delete(fn);
+    };
+}
+// ─── Logging ─────────────────────────────────────────────────────────────────
 export function logToolCall(entry) {
-    if (QUIET)
-        return;
     const apiKey = process.env['LUCENT_API_KEY'];
-    const line = JSON.stringify({
+    const stored = {
         t: new Date().toISOString(),
         tool: entry.tool,
         params: entry.params,
@@ -29,8 +50,24 @@ export function logToolCall(entry) {
         ok: entry.ok,
         ...(entry.error !== undefined && { error: entry.error }),
         ...(apiKey !== undefined && { key: hashKeyPrefix(apiKey) }),
-    });
-    process.stderr.write(line + '\n');
+    };
+    // 1. Push to ring buffer (always, even in QUIET mode — dashboards still work).
+    recentCalls.push(stored);
+    if (recentCalls.length > BUFFER_SIZE)
+        recentCalls.shift();
+    // 2. Notify subscribers (SSE streams).
+    for (const sub of subscribers) {
+        try {
+            sub(stored);
+        }
+        catch {
+            // Never let a broken subscriber break the tool call path.
+        }
+    }
+    // 3. Write to stderr unless QUIET.
+    if (!QUIET) {
+        process.stderr.write(JSON.stringify(stored) + '\n');
+    }
 }
 /**
  * Wraps a tool handler with timing + structured logging. The returned function

package/dist-server/server/pattern-registry.js

@@ -10,6 +10,8 @@ import { PATTERN as ProductItemCard } from '../src/manifest/patterns/product-ite
 import { PATTERN as NotificationCard } from '../src/manifest/patterns/notification-card.pattern.js';
 import { PATTERN as ConfirmationDialog } from '../src/manifest/patterns/confirmation-dialog.pattern.js';
 import { PATTERN as BulkActionBar } from '../src/manifest/patterns/bulk-action-bar.pattern.js';
+import { PATTERN as ActivityFeed } from '../src/manifest/patterns/activity-feed.pattern.js';
+import { PATTERN as MetricsDashboard } from '../src/manifest/patterns/metrics-dashboard.pattern.js';
 export const ALL_PATTERNS = [
     ProfileCard,
     SettingsPanel,
@@ -23,4 +25,6 @@ export const ALL_PATTERNS = [
     NotificationCard,
     ConfirmationDialog,
     BulkActionBar,
+    ActivityFeed,
+    MetricsDashboard,
 ];

package/dist-server/src/components/charts/AreaChart/AreaChart.manifest.js

@@ -0,0 +1,35 @@
+export const COMPONENT_MANIFEST = {
+    id: 'area-chart',
+    name: 'AreaChart',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A filled line chart for time-series data with optional multi-series support.',
+    designIntent: 'Use AreaChart for continuous data over time — revenue trends, user growth, etc. ' +
+        'The translucent fill emphasises volume while the line shows direction. ' +
+        'Multi-series mode auto-assigns colors from the lucent palette. ' +
+        'Pass formatValue to customise y-axis labels (currency, percentages, etc.).',
+    props: [
+        { name: 'data', type: 'custom', required: false, description: 'Single-series data: { label, value }[].' },
+        { name: 'series', type: 'custom', required: false, description: 'Multi-series data: { id, name, data, color? }[].' },
+        { name: 'width', type: 'union', required: false, default: "'100%'", description: 'Pixel width or CSS string.' },
+        { name: 'height', type: 'number', required: false, default: '200', description: 'Pixel height.' },
+        { name: 'color', type: 'string', required: false, default: 'accent', description: 'Line/fill color for single-series.' },
+        { name: 'gridLines', type: 'boolean', required: false, default: 'true', description: 'Show horizontal grid lines.' },
+        { name: 'showDots', type: 'boolean', required: false, default: 'false', description: 'Show dots at data points.' },
+        { name: 'smooth', type: 'boolean', required: false, default: 'true', description: 'Use smooth monotone-x curves.' },
+        { name: 'fillOpacity', type: 'number', required: false, default: '0.15', description: 'Area fill opacity (0–1).' },
+        { name: 'formatValue', type: 'custom', required: false, description: 'Custom value formatter for y-axis.' },
+        { name: 'xLabelCount', type: 'number', required: false, description: 'Max x-axis labels to display.' },
+    ],
+    usageExamples: [
+        { title: 'Basic', code: `<AreaChart data={[{ label: 'Jan', value: 40 }, { label: 'Feb', value: 65 }, { label: 'Mar', value: 50 }]} />` },
+        { title: 'Multi-series', code: `<AreaChart series={[{ id: 'a', name: 'Revenue', data: [...] }, { id: 'b', name: 'Costs', data: [...] }]} />` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'img',
+        ariaAttributes: ['aria-label'],
+        notes: 'Provide ariaLabel summarising the data trend.',
+    },
+};

package/dist-server/src/components/charts/BarChart/BarChart.manifest.js

@@ -0,0 +1,32 @@
+export const COMPONENT_MANIFEST = {
+    id: 'bar-chart',
+    name: 'BarChart',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A vertical bar chart with automatic axis labels and optional grid lines.',
+    designIntent: 'Use BarChart for categorical comparisons — revenue by month, counts by category, etc. ' +
+        'Bars auto-scale to fit the data. Set showValues to display exact numbers above each bar. ' +
+        'Per-point color overrides are available for highlighting specific bars.',
+    props: [
+        { name: 'data', type: 'custom', required: true, description: 'Array of { label, value, color? } objects.' },
+        { name: 'width', type: 'union', required: false, default: "'100%'", description: 'Pixel width or CSS string.' },
+        { name: 'height', type: 'number', required: false, default: '200', description: 'Pixel height.' },
+        { name: 'color', type: 'string', required: false, default: 'accent', description: 'Bar color variant or CSS color.' },
+        { name: 'gridLines', type: 'boolean', required: false, default: 'true', description: 'Show horizontal grid lines.' },
+        { name: 'showValues', type: 'boolean', required: false, default: 'false', description: 'Show value labels above bars.' },
+        { name: 'formatValue', type: 'custom', required: false, description: 'Custom value formatter function.' },
+        { name: 'barGap', type: 'number', required: false, default: '0.3', description: 'Gap between bars (0–1 fraction of slot width).' },
+        { name: 'barRadius', type: 'number', required: false, default: '2', description: 'Corner radius on bar tops.' },
+    ],
+    usageExamples: [
+        { title: 'Basic', code: `<BarChart data={[{ label: 'Jan', value: 40 }, { label: 'Feb', value: 65 }, { label: 'Mar', value: 50 }]} />` },
+        { title: 'With values', code: `<BarChart data={[{ label: 'A', value: 120 }, { label: 'B', value: 80 }]} showValues color="success" />` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'img',
+        ariaAttributes: ['aria-label'],
+        notes: 'Provide a descriptive ariaLabel summarising the data for screen readers.',
+    },
+};

package/dist-server/src/components/charts/DonutChart/DonutChart.manifest.js

@@ -0,0 +1,29 @@
+export const COMPONENT_MANIFEST = {
+    id: 'donut-chart',
+    name: 'DonutChart',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A ring chart for displaying proportions with an optional center label.',
+    designIntent: 'Use DonutChart for part-to-whole comparisons — category breakdown, budget allocation, etc. ' +
+        'The center label slot is ideal for a total value or summary text. ' +
+        'Segment colors auto-cycle through the lucent palette; override per-segment for semantic meaning.',
+    props: [
+        { name: 'data', type: 'custom', required: true, description: 'Array of { label, value, color? } segments.' },
+        { name: 'size', type: 'number', required: false, default: '160', description: 'Overall pixel size (square).' },
+        { name: 'thickness', type: 'number', required: false, default: '0.35', description: 'Ring thickness (0–1 fraction of radius).' },
+        { name: 'segmentGap', type: 'number', required: false, default: '2', description: 'Gap between segments in degrees.' },
+        { name: 'centerLabel', type: 'custom', required: false, description: 'ReactNode displayed in the center of the ring.' },
+        { name: 'startAngle', type: 'number', required: false, default: '0', description: 'Starting angle in degrees (0 = 12 o\'clock).' },
+    ],
+    usageExamples: [
+        { title: 'Basic', code: `<DonutChart data={[{ label: 'A', value: 60 }, { label: 'B', value: 40 }]} />` },
+        { title: 'With center label', code: `<DonutChart data={[{ label: 'Used', value: 75 }, { label: 'Free', value: 25 }]} centerLabel={<Text size="lg" weight="bold">75%</Text>} />` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'img',
+        ariaAttributes: ['aria-label'],
+        notes: 'Provide ariaLabel describing the proportions for screen readers.',
+    },
+};

package/dist-server/src/components/charts/SparkLine/SparkLine.manifest.js

@@ -0,0 +1,30 @@
+export const COMPONENT_MANIFEST = {
+    id: 'sparkline',
+    name: 'SparkLine',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A compact, inline trend line for displaying data direction at a glance.',
+    designIntent: 'Use SparkLine inside KPI cards, table cells, or compact dashboard tiles to show a trend ' +
+        'without axes or labels — surrounding context provides meaning. Defaults to smooth curves ' +
+        'for a polished look; set smooth=false for raw data fidelity.',
+    props: [
+        { name: 'data', type: 'custom', required: true, description: 'Array of numeric values.' },
+        { name: 'width', type: 'union', required: false, default: "'100%'", description: 'Pixel width or CSS string.' },
+        { name: 'height', type: 'number', required: false, default: '32', description: 'Pixel height.' },
+        { name: 'color', type: 'string', required: false, default: 'accent', description: 'Color variant name or CSS color.' },
+        { name: 'filled', type: 'boolean', required: false, default: 'false', description: 'Show translucent area fill below the line.' },
+        { name: 'strokeWidth', type: 'number', required: false, default: '1.5', description: 'Line stroke width.' },
+        { name: 'smooth', type: 'boolean', required: false, default: 'true', description: 'Use smooth monotone-x curves.' },
+    ],
+    usageExamples: [
+        { title: 'Basic', code: '<SparkLine data={[4, 7, 3, 8, 5, 9, 6]} />' },
+        { title: 'Filled', code: '<SparkLine data={[4, 7, 3, 8, 5, 9, 6]} filled color="success" />' },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'img',
+        ariaAttributes: ['aria-label'],
+        notes: 'Purely decorative — ensure surrounding text provides data context.',
+    },
+};

package/dist-server/src/manifest/patterns/activity-feed.pattern.js

@@ -0,0 +1,82 @@
+export const PATTERN = {
+    id: 'activity-feed',
+    name: 'Activity Feed',
+    description: 'Timestamped event list with user attribution. Each entry shows a timestamp, avatar, action description, and optional content preview card.',
+    category: 'dashboard',
+    components: ['card', 'avatar', 'text', 'stack', 'row'],
+    structure: `
+Card (elevated, padding lg)
+└── Stack gap="4"
+    ├── Row justify="between" align="center"    ← header
+    │   ├── Text (lg, semibold)                 ← title
+    │   └── Text (xs, secondary, uppercase)     ← date label
+    └── div
+        └── ActivityItem[]
+            └── div (flex row, gap space-3)
+                ├── Text (xs, secondary, w 38px) ← timestamp
+                └── div (flex row, gap space-3)  ← avatar + content
+                    ├── Avatar (sm)              ← user avatar, 32px
+                    └── div
+                        ├── Text (sm)            ← name (bold) + action + target (bold)
+                        └── div? (surface-raised, rounded, padding)  ← content preview
+                            └── Text (sm, secondary) ← preview text
+  `.trim(),
+    code: `<Card variant="elevated" padding="lg" style={{ width: 600 }}>
+  <Stack gap="4">
+    <Row justify="between" align="center">
+      <Text size="lg" weight="semibold">Activity</Text>
+      <Text size="xs" color="secondary" weight="medium"
+        style={{ letterSpacing: '0.05em', textTransform: 'uppercase' }}>May 18, 2022</Text>
+    </Row>
+    <div>
+      {/* Event item */}
+      <div style={{ display: 'flex', gap: 'var(--lucent-space-3)', paddingBottom: 'var(--lucent-space-5)' }}>
+        <div style={{ width: 38, flexShrink: 0, paddingTop: 7 }}>
+          <Text size="xs" color="secondary">14:47</Text>
+        </div>
+        <div style={{ display: 'flex', gap: 'var(--lucent-space-3)', flex: 1, minWidth: 0, alignItems: 'start' }}>
+          <Avatar alt="Christoph Hellmuth" size="sm" />
+          <div style={{ flex: 1, minWidth: 0, paddingTop: 5 }}>
+            <Text size="sm">
+              <Text as="span" size="sm" weight="semibold">Christoph Hellmuth</Text>
+              {' '}sent message in{' '}
+              <Text as="span" size="sm" weight="semibold">#f-insights</Text>
+            </Text>
+            <div style={{
+              marginTop: 'var(--lucent-space-3)',
+              padding: 'var(--lucent-space-3) var(--lucent-space-4)',
+              background: 'var(--lucent-surface-raised)', borderRadius: 'var(--lucent-radius-md)',
+            }}>
+              <Text size="sm" color="secondary">Message preview text…</Text>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </Stack>
+</Card>`,
+    variants: [
+        {
+            title: 'Compact (no header, no previews)',
+            code: `<Card variant="outline" padding="md" style={{ width: 480 }}>
+  <div>
+    <div style={{ display: 'flex', gap: 'var(--lucent-space-2)', paddingBottom: 'var(--lucent-space-3)' }}>
+      <Text size="xs" color="secondary" style={{ width: 32, flexShrink: 0 }}>14:47</Text>
+      <Avatar alt="Alice" size="xs" style={{ flexShrink: 0 }} />
+      <Text size="xs">
+        <Text as="span" size="xs" weight="semibold">Alice</Text>
+        {' '}pushed to main
+      </Text>
+    </div>
+  </div>
+</Card>`,
+        },
+    ],
+    designNotes: 'Clean multi-column layout gives each information layer its own lane: timestamp on the left ' +
+        'for quick scanning, avatar for identity, then action text. Content previews (message ' +
+        'excerpts, comment text) sit in surface-raised cards below the action line, indented under ' +
+        'the text column so they read as subordinate detail. No timeline connector or source icons — ' +
+        'the vertical rhythm of aligned timestamps provides enough chronological structure without ' +
+        'visual clutter. The timestamp column (38px) is narrow enough to not dominate but wide enough ' +
+        'for HH:MM format.',
+};

package/dist-server/src/manifest/patterns/metrics-dashboard.pattern.js

@@ -0,0 +1,140 @@
+export const PATTERN = {
+    id: 'metrics-dashboard',
+    name: 'Metrics Dashboard',
+    description: 'KPI cards with progress indicators and tabbed time-range switching (7d / 30d / 90d). Each card shows a metric label, large value, trend chip, and progress bar.',
+    category: 'dashboard',
+    components: ['card', 'text', 'progress', 'tabs', 'chip', 'stack', 'row'],
+    structure: `
+Stack gap="5"
+├── Row gap="3" align="center" justify="between"
+│   ├── Text (xl, bold)                        ← section title
+│   └── Tabs (pills, sm)                       ← time range selector (7d / 30d / 90d)
+└── Row gap="4" wrap
+    └── Card[] (elevated, padding lg, flex 1)
+        └── Stack gap="3"
+            ├── Text (xs, secondary, medium)    ← metric label
+            ├── Row gap="2" align="baseline"
+            │   ├── Text (2xl, bold, display)   ← value
+            │   └── Chip (success/danger, sm)   ← trend delta
+            └── Progress (sm)                   ← completion bar
+  `.trim(),
+    code: `<Stack gap="5">
+  <Row gap="3" align="center" justify="between">
+    <Text size="xl" weight="bold">Overview</Text>
+    <Tabs
+      variant="pills"
+      tabs={[
+        { value: '7d', label: '7d' },
+        { value: '30d', label: '30d' },
+        { value: '90d', label: '90d' },
+      ]}
+      defaultValue="30d"
+      style={{ fontSize: 'var(--lucent-font-size-sm)' }}
+    />
+  </Row>
+  <Row gap="4" wrap>
+    <Card variant="elevated" padding="lg" style={{ flex: 1, minWidth: 220 }}>
+      <Stack gap="3">
+        <Text size="xs" color="secondary" weight="medium">Revenue</Text>
+        <Row gap="2" align="baseline">
+          <Text size="2xl" weight="bold" family="display">$48.2k</Text>
+          <Chip variant="success" size="sm" borderless>+12.5%</Chip>
+        </Row>
+        <Progress value={72} size="sm" />
+      </Stack>
+    </Card>
+    <Card variant="elevated" padding="lg" style={{ flex: 1, minWidth: 220 }}>
+      <Stack gap="3">
+        <Text size="xs" color="secondary" weight="medium">Active Users</Text>
+        <Row gap="2" align="baseline">
+          <Text size="2xl" weight="bold" family="display">2,847</Text>
+          <Chip variant="success" size="sm" borderless>+8.1%</Chip>
+        </Row>
+        <Progress value={64} size="sm" />
+      </Stack>
+    </Card>
+    <Card variant="elevated" padding="lg" style={{ flex: 1, minWidth: 220 }}>
+      <Stack gap="3">
+        <Text size="xs" color="secondary" weight="medium">Churn Rate</Text>
+        <Row gap="2" align="baseline">
+          <Text size="2xl" weight="bold" family="display">3.2%</Text>
+          <Chip variant="danger" size="sm" borderless>+0.8%</Chip>
+        </Row>
+        <Progress value={32} size="sm" variant="danger" />
+      </Stack>
+    </Card>
+    <Card variant="elevated" padding="lg" style={{ flex: 1, minWidth: 220 }}>
+      <Stack gap="3">
+        <Text size="xs" color="secondary" weight="medium">Avg. Response</Text>
+        <Row gap="2" align="baseline">
+          <Text size="2xl" weight="bold" family="display">1.4s</Text>
+          <Chip variant="success" size="sm" borderless>-18%</Chip>
+        </Row>
+        <Progress value={86} size="sm" variant="success" />
+      </Stack>
+    </Card>
+  </Row>
+</Stack>`,
+    variants: [
+        {
+            title: 'Outline cards with threshold-based progress',
+            code: `<Stack gap="5">
+  <Row gap="3" align="center" justify="between">
+    <Text size="xl" weight="bold">System Health</Text>
+    <Tabs
+      variant="pills"
+      tabs={[
+        { value: '1h', label: '1h' },
+        { value: '24h', label: '24h' },
+        { value: '7d', label: '7d' },
+      ]}
+      defaultValue="24h"
+      style={{ fontSize: 'var(--lucent-font-size-sm)' }}
+    />
+  </Row>
+  <Row gap="4" wrap>
+    <Card variant="outline" padding="lg" style={{ flex: 1, minWidth: 220 }}>
+      <Stack gap="3">
+        <Text size="xs" color="secondary" weight="medium">CPU Usage</Text>
+        <Row gap="2" align="baseline">
+          <Text size="2xl" weight="bold" family="display">67%</Text>
+          <Chip variant="warning" size="sm" borderless>+12%</Chip>
+        </Row>
+        <Progress value={67} size="sm" warnAt={60} dangerAt={85} />
+      </Stack>
+    </Card>
+    <Card variant="outline" padding="lg" style={{ flex: 1, minWidth: 220 }}>
+      <Stack gap="3">
+        <Text size="xs" color="secondary" weight="medium">Memory</Text>
+        <Row gap="2" align="baseline">
+          <Text size="2xl" weight="bold" family="display">4.2 GB</Text>
+          <Chip variant="success" size="sm" borderless>-3%</Chip>
+        </Row>
+        <Progress value={52} size="sm" warnAt={70} dangerAt={90} />
+      </Stack>
+    </Card>
+    <Card variant="outline" padding="lg" style={{ flex: 1, minWidth: 220 }}>
+      <Stack gap="3">
+        <Text size="xs" color="secondary" weight="medium">Disk I/O</Text>
+        <Row gap="2" align="baseline">
+          <Text size="2xl" weight="bold" family="display">340 MB/s</Text>
+          <Chip variant="danger" size="sm" borderless>+45%</Chip>
+        </Row>
+        <Progress value={91} size="sm" warnAt={60} dangerAt={85} />
+      </Stack>
+    </Card>
+  </Row>
+</Stack>`,
+        },
+    ],
+    designNotes: 'The header row pairs a bold title with pill-style Tabs for time-range switching — ' +
+        'pills read as a toggle group rather than navigation, which matches the "filter" intent. ' +
+        'Each KPI card uses a three-tier Stack: label (xs, secondary) anchors meaning at the top, ' +
+        'the value (2xl, display) commands attention in the middle, and a slim Progress bar at the ' +
+        'bottom gives an at-a-glance ratio without requiring the user to interpret numbers. ' +
+        'The trend Chip sits baseline-aligned next to the value so the delta reads as part of the ' +
+        'same data point. Elevated cards with flex: 1 + minWidth ensure equal sizing that wraps ' +
+        'gracefully at narrow viewports. The system-health variant demonstrates warnAt/dangerAt ' +
+        'thresholds on Progress — the bar auto-colors based on the value, removing the need ' +
+        'for manual variant assignment on each metric.',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lucent-ui",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "An AI-first React component library with machine-readable manifests.",
   "type": "module",
   "main": "./dist/index.cjs",