lucent-ui 0.2.0 → 0.4.0

package/dist-cli/cli/figma.js

@@ -0,0 +1,41 @@
+// ─── Figma Variables API types ────────────────────────────────────────────────
+// ─── API client ───────────────────────────────────────────────────────────────
+export async function fetchFigmaVariables(figmaToken, fileKey) {
+    const url = `https://api.figma.com/v1/files/${fileKey}/variables/local`;
+    const res = await fetch(url, {
+        headers: {
+            'X-Figma-Token': figmaToken,
+        },
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`Figma API error ${res.status}: ${res.statusText}${body ? `\n${body}` : ''}`);
+    }
+    return res.json();
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/** Convert Figma RGBA (0–1 channels) to a CSS hex string. */
+export function figmaColorToHex(color) {
+    const toHex = (n) => Math.round(Math.min(1, Math.max(0, n)) * 255)
+        .toString(16)
+        .padStart(2, '0');
+    const rgb = `#${toHex(color.r)}${toHex(color.g)}${toHex(color.b)}`;
+    // Include alpha channel only when not fully opaque
+    if (color.a < 0.9999) {
+        return `${rgb}${toHex(color.a)}`;
+    }
+    return rgb;
+}
+/** True if value is a FigmaColor object (has r/g/b/a number fields). */
+export function isFigmaColor(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'r' in v &&
+        typeof v.r === 'number');
+}
+/** True if value is a VARIABLE_ALIAS reference. */
+export function isAlias(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        v.type === 'VARIABLE_ALIAS');
+}

package/dist-cli/cli/index.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * lucent-manifest init
+ *
+ * Usage:
+ *   npx lucent-manifest init --figma-token <token> --file-key <key> [options]
+ *   npx lucent-manifest init --template                              (manual fallback)
+ *
+ * Options:
+ *   --figma-token  <token>   Figma personal access token
+ *   --file-key     <key>     Figma file key (from the file URL)
+ *   --light-mode   <name>    Mode name to treat as light theme (default: "light")
+ *   --dark-mode    <name>    Mode name to treat as dark theme  (default: "dark")
+ *   --name         <name>    Design system name written into the manifest
+ *   --out          <path>    Output file path (default: lucent.manifest.json)
+ *   --template               Write an empty JSON template instead of fetching Figma
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fetchFigmaVariables } from './figma.js';
+import { mapFigmaToTokens } from './mapper.js';
+// ─── Arg parsing ──────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                args[key] = next;
+                i++;
+            }
+            else {
+                args[key] = true;
+            }
+        }
+    }
+    return args;
+}
+function required(args, key) {
+    const v = args[key];
+    if (!v || v === true) {
+        console.error(`Error: --${key} is required.`);
+        process.exit(1);
+    }
+    return v;
+}
+function optional(args, key, fallback) {
+    const v = args[key];
+    return typeof v === 'string' ? v : fallback;
+}
+// ─── Template fallback ────────────────────────────────────────────────────────
+function writeTemplate(outPath) {
+    const templateSrc = new URL('./template.manifest.json', import.meta.url);
+    fs.copyFileSync(templateSrc, outPath);
+    console.log(`Template written to ${outPath}`);
+    console.log('Fill in the token values and load it with LucentProvider.');
+}
+// ─── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const outPath = path.resolve(optional(args, 'out', 'lucent.manifest.json'));
+    if (args['template']) {
+        writeTemplate(outPath);
+        return;
+    }
+    const figmaToken = required(args, 'figma-token');
+    const fileKey = required(args, 'file-key');
+    const lightModeName = optional(args, 'light-mode', 'light');
+    const darkModeName = optional(args, 'dark-mode', 'dark');
+    const systemName = optional(args, 'name', 'My Design System');
+    console.log(`Fetching Figma variables for file ${fileKey}…`);
+    const response = await fetchFigmaVariables(figmaToken, fileKey);
+    const manifest = {
+        version: '1.0',
+        name: systemName,
+        tokens: {},
+    };
+    // Light theme
+    try {
+        const { tokens: lightTokens, unmapped: lightUnmapped } = mapFigmaToTokens(response, lightModeName);
+        manifest.tokens.light = lightTokens;
+        console.log(`Light theme: mapped ${Object.keys(lightTokens).length} token(s).`);
+        if (lightUnmapped.length > 0) {
+            console.warn(`  ${lightUnmapped.length} variable(s) didn't match a Lucent token key and were skipped:`);
+            for (const u of lightUnmapped) {
+                console.warn(`    "${u.figmaName}" → candidate "${u.candidateKey}" (value: ${u.value})`);
+            }
+        }
+    }
+    catch (err) {
+        console.warn(`Skipping light theme: ${err.message}`);
+    }
+    // Dark theme
+    try {
+        const { tokens: darkTokens, unmapped: darkUnmapped } = mapFigmaToTokens(response, darkModeName);
+        manifest.tokens.dark = darkTokens;
+        console.log(`Dark theme: mapped ${Object.keys(darkTokens).length} token(s).`);
+        if (darkUnmapped.length > 0) {
+            console.warn(`  ${darkUnmapped.length} variable(s) didn't match a Lucent token key and were skipped:`);
+            for (const u of darkUnmapped) {
+                console.warn(`    "${u.figmaName}" → candidate "${u.candidateKey}" (value: ${u.value})`);
+            }
+        }
+    }
+    catch (err) {
+        console.warn(`Skipping dark theme: ${err.message}`);
+    }
+    if (!manifest.tokens.light && !manifest.tokens.dark) {
+        console.error('No tokens were mapped. Check your --light-mode and --dark-mode names match the Figma file.');
+        process.exit(1);
+    }
+    fs.writeFileSync(outPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+    console.log(`\nManifest written to ${outPath}`);
+}
+main().catch(err => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist-cli/cli/mapper.js

@@ -0,0 +1,162 @@
+import { figmaColorToHex, isFigmaColor, isAlias, } from './figma.js';
+// ─── Token key registry ───────────────────────────────────────────────────────
+/**
+ * Every valid key in LucentTokens — used to validate candidate names produced
+ * by the name normaliser before writing them into the output manifest.
+ */
+const LUCENT_TOKEN_KEYS = new Set([
+    // SemanticColorTokens
+    'bgBase', 'bgSubtle', 'bgMuted', 'bgOverlay',
+    'surfaceDefault', 'surfaceRaised', 'surfaceOverlay',
+    'borderDefault', 'borderSubtle', 'borderStrong',
+    'textPrimary', 'textSecondary', 'textDisabled', 'textInverse', 'textOnAccent',
+    'accentDefault', 'accentHover', 'accentActive', 'accentSubtle',
+    'successDefault', 'successSubtle', 'successText',
+    'warningDefault', 'warningSubtle', 'warningText',
+    'dangerDefault', 'dangerHover', 'dangerSubtle', 'dangerText',
+    'infoDefault', 'infoSubtle', 'infoText',
+    'focusRing',
+    // TypographyTokens
+    'fontFamilyBase', 'fontFamilyMono', 'fontFamilyDisplay',
+    'fontSizeXs', 'fontSizeSm', 'fontSizeMd', 'fontSizeLg',
+    'fontSizeXl', 'fontSize2xl', 'fontSize3xl',
+    'fontWeightRegular', 'fontWeightMedium', 'fontWeightSemibold', 'fontWeightBold',
+    'lineHeightTight', 'lineHeightBase', 'lineHeightRelaxed',
+    'letterSpacingTight', 'letterSpacingBase', 'letterSpacingWide',
+    // SpacingTokens
+    'space0', 'space1', 'space2', 'space3', 'space4', 'space5',
+    'space6', 'space8', 'space10', 'space12', 'space16', 'space20', 'space24',
+    // RadiusTokens
+    'radiusNone', 'radiusSm', 'radiusMd', 'radiusLg', 'radiusXl', 'radiusFull',
+    // ShadowTokens
+    'shadowNone', 'shadowSm', 'shadowMd', 'shadowLg', 'shadowXl',
+    // MotionTokens
+    'durationFast', 'durationBase', 'durationSlow',
+    'easingDefault', 'easingEmphasized', 'easingDecelerate',
+]);
+// ─── Name normalisation ───────────────────────────────────────────────────────
+/**
+ * Top-level Figma collection category prefixes that carry no semantic meaning
+ * in the Lucent token schema and should be dropped before camelCasing.
+ */
+const CATEGORY_PREFIXES = new Set([
+    'color', 'colour', 'typography', 'type', 'spacing', 'space',
+    'radius', 'shadow', 'motion', 'animation',
+]);
+/**
+ * Convert a Figma variable name (slash-separated path, may include hyphens)
+ * into a camelCase candidate token key.
+ *
+ * Examples:
+ *   "color/bg/base"            → "bgBase"
+ *   "color/text/primary"       → "textPrimary"
+ *   "typography/font-size/xl"  → "fontSizeXl"
+ *   "spacing/space-4"          → "space4"
+ *   "radius/radius-md"         → "radiusMd"
+ *   "accentDefault"            → "accentDefault"   (no change needed)
+ */
+export function normalizeName(figmaName) {
+    // Split path segments on /
+    const segments = figmaName.split('/').map(s => s.trim()).filter(Boolean);
+    // Drop a leading category prefix if present
+    if (segments.length > 1 && CATEGORY_PREFIXES.has(segments[0].toLowerCase())) {
+        segments.shift();
+    }
+    // Further split each segment on hyphens
+    const parts = segments.flatMap(s => s.split('-').filter(Boolean));
+    if (parts.length === 0)
+        return figmaName;
+    // camelCase: lowercase first part, title-case the rest
+    return parts
+        .map((p, i) => i === 0 ? p.toLowerCase() : p.charAt(0).toUpperCase() + p.slice(1).toLowerCase())
+        .join('');
+}
+// ─── Alias resolution ─────────────────────────────────────────────────────────
+/**
+ * Resolve a variable value for a given mode, following VARIABLE_ALIAS chains.
+ * Returns `undefined` if the chain cannot be resolved (dangling alias, missing
+ * mode, non-string/non-color resolved type).
+ */
+function resolveValue(variable, modeId, allVariables, visited = new Set()) {
+    if (visited.has(variable.id))
+        return undefined; // circular alias guard
+    visited.add(variable.id);
+    const value = variable.valuesByMode[modeId];
+    if (value === undefined)
+        return undefined;
+    if (isAlias(value)) {
+        const target = allVariables[value.id];
+        if (!target)
+            return undefined;
+        // Aliases preserve their own modeId in the target collection — use the
+        // same modeId; if absent the target may use its defaultModeId but we
+        // can't determine that here without the collections map, so fall back to
+        // returning undefined rather than guessing.
+        return resolveValue(target, modeId, allVariables, visited);
+    }
+    return value;
+}
+// ─── Value → CSS string ───────────────────────────────────────────────────────
+function toCssValue(value, resolvedType) {
+    if (resolvedType === 'COLOR' && isFigmaColor(value)) {
+        return figmaColorToHex(value);
+    }
+    if (resolvedType === 'FLOAT' && typeof value === 'number') {
+        // Figma stores spacing/radius in px without units; emit as "Npx"
+        return `${value}px`;
+    }
+    if (resolvedType === 'STRING' && typeof value === 'string') {
+        return value;
+    }
+    return undefined;
+}
+/**
+ * Map a Figma Variables API response for a single named mode (e.g. "light" or
+ * "dark") into a `Partial<LucentTokens>` token override object.
+ *
+ * @param response  Full response from `fetchFigmaVariables`
+ * @param modeName  Case-insensitive mode name to extract (e.g. "Light", "dark")
+ */
+export function mapFigmaToTokens(response, modeName) {
+    const { variables, variableCollections } = response.meta;
+    // Find the modeId matching the requested name across all collections
+    const targetModeName = modeName.toLowerCase();
+    const modeIdByCollection = new Map();
+    for (const collection of Object.values(variableCollections)) {
+        const match = collection.modes.find(m => m.name.toLowerCase() === targetModeName);
+        if (match) {
+            modeIdByCollection.set(collection.id, match.modeId);
+        }
+    }
+    if (modeIdByCollection.size === 0) {
+        const available = Object.values(variableCollections)
+            .flatMap(c => c.modes.map(m => m.name))
+            .filter((v, i, a) => a.indexOf(v) === i)
+            .join(', ');
+        throw new Error(`No mode named "${modeName}" found in Figma file.\nAvailable modes: ${available || '(none)'}`);
+    }
+    const tokens = {};
+    const unmapped = [];
+    for (const variable of Object.values(variables)) {
+        // Skip booleans — no LucentTokens field uses boolean values
+        if (variable.resolvedType === 'BOOLEAN')
+            continue;
+        const modeId = modeIdByCollection.get(variable.variableCollectionId);
+        if (modeId === undefined)
+            continue;
+        const raw = resolveValue(variable, modeId, variables);
+        if (raw === undefined)
+            continue;
+        const cssValue = toCssValue(raw, variable.resolvedType);
+        if (cssValue === undefined)
+            continue;
+        const candidate = normalizeName(variable.name);
+        if (LUCENT_TOKEN_KEYS.has(candidate)) {
+            tokens[candidate] = cssValue;
+        }
+        else {
+            unmapped.push({ figmaName: variable.name, candidateKey: candidate, value: cssValue });
+        }
+    }
+    return { tokens, unmapped };
+}

package/dist-cli/cli/template.manifest.json

@@ -0,0 +1,83 @@
+{
+  "version": "1.0",
+  "name": "My Design System",
+  "description": "Optional description of your design system",
+  "tokens": {
+    "light": {
+      "bgBase": "#ffffff",
+      "bgSubtle": "#f9fafb",
+      "bgMuted": "#f3f4f6",
+      "bgOverlay": "rgb(0 0 0 / 0.4)",
+      "surfaceDefault": "#ffffff",
+      "surfaceRaised": "#ffffff",
+      "surfaceOverlay": "#ffffff",
+      "borderDefault": "#e5e7eb",
+      "borderSubtle": "#f3f4f6",
+      "borderStrong": "#9ca3af",
+      "textPrimary": "#111827",
+      "textSecondary": "#6b7280",
+      "textDisabled": "#9ca3af",
+      "textInverse": "#ffffff",
+      "textOnAccent": "#ffffff",
+      "accentDefault": "#111827",
+      "accentHover": "#1f2937",
+      "accentActive": "#374151",
+      "accentSubtle": "#f3f4f6",
+      "successDefault": "#16a34a",
+      "successSubtle": "#f0fdf4",
+      "successText": "#15803d",
+      "warningDefault": "#d97706",
+      "warningSubtle": "#fffbeb",
+      "warningText": "#b45309",
+      "dangerDefault": "#dc2626",
+      "dangerHover": "#b91c1c",
+      "dangerSubtle": "#fef2f2",
+      "dangerText": "#b91c1c",
+      "infoDefault": "#2563eb",
+      "infoSubtle": "#eff6ff",
+      "infoText": "#1d4ed8",
+      "focusRing": "#111827",
+      "fontFamilyBase": "\"Inter\", sans-serif",
+      "fontFamilyMono": "\"Fira Code\", monospace",
+      "fontFamilyDisplay": "\"Inter\", sans-serif"
+    },
+    "dark": {
+      "bgBase": "#0f172a",
+      "bgSubtle": "#1e293b",
+      "bgMuted": "#334155",
+      "bgOverlay": "rgb(0 0 0 / 0.6)",
+      "surfaceDefault": "#1e293b",
+      "surfaceRaised": "#334155",
+      "surfaceOverlay": "#1e293b",
+      "borderDefault": "#334155",
+      "borderSubtle": "#1e293b",
+      "borderStrong": "#64748b",
+      "textPrimary": "#f8fafc",
+      "textSecondary": "#94a3b8",
+      "textDisabled": "#475569",
+      "textInverse": "#0f172a",
+      "textOnAccent": "#0f172a",
+      "accentDefault": "#f8fafc",
+      "accentHover": "#e2e8f0",
+      "accentActive": "#cbd5e1",
+      "accentSubtle": "#1e293b",
+      "successDefault": "#22c55e",
+      "successSubtle": "#052e16",
+      "successText": "#4ade80",
+      "warningDefault": "#f59e0b",
+      "warningSubtle": "#431407",
+      "warningText": "#fbbf24",
+      "dangerDefault": "#ef4444",
+      "dangerHover": "#f87171",
+      "dangerSubtle": "#450a0a",
+      "dangerText": "#f87171",
+      "infoDefault": "#3b82f6",
+      "infoSubtle": "#0f1f47",
+      "infoText": "#60a5fa",
+      "focusRing": "#f8fafc",
+      "fontFamilyBase": "\"Inter\", sans-serif",
+      "fontFamilyMono": "\"Fira Code\", monospace",
+      "fontFamilyDisplay": "\"Inter\", sans-serif"
+    }
+  }
+}

package/dist-cli/cli/types.js

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

package/dist-cli/src/tokens/types.js

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

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

@@ -0,0 +1,89 @@
+export const COMPONENT_MANIFEST = {
+    id: 'command-palette',
+    name: 'CommandPalette',
+    tier: 'overlay',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A keyboard-driven modal command palette with fuzzy search, grouped results, and a built-in ⌘K / Ctrl+K global shortcut.',
+    designIntent: 'CommandPalette renders as a portal-style overlay (fixed, full-viewport) with a centred panel that animates in with a subtle scale+fade. ' +
+        'The ⌘K shortcut is registered as a global window listener so it works regardless of focus — consumers can override the key via shortcutKey prop. ' +
+        'Clicking the backdrop dismisses the palette; Escape also closes it. ' +
+        'Results are filtered client-side against label and description using simple substring match — no fuzzy library needed. ' +
+        'Navigation is purely keyboard-driven: ↑↓ move the active index, Enter selects, mouse hover syncs the active index so mouse and keyboard stay in sync. ' +
+        'Groups are derived from the group field on each CommandItem; the order of groups follows the order they first appear in the commands array. ' +
+        'The component is controlled-or-uncontrolled: pass open + onOpenChange for controlled use, or omit both to use internal state.',
+    props: [
+        {
+            name: 'commands',
+            type: 'array',
+            required: true,
+            description: 'Array of CommandItem objects. Each has id, label, onSelect, and optional description, icon, group, disabled.',
+        },
+        {
+            name: 'placeholder',
+            type: 'string',
+            required: false,
+            default: '"Search commands…"',
+            description: 'Placeholder text for the search input.',
+        },
+        {
+            name: 'shortcutKey',
+            type: 'string',
+            required: false,
+            default: '"k"',
+            description: 'Key that opens the palette when pressed with Meta (Mac) or Ctrl (Windows). Defaults to "k" for ⌘K.',
+        },
+        {
+            name: 'open',
+            type: 'boolean',
+            required: false,
+            description: 'Controlled open state. When provided, the component is fully controlled.',
+        },
+        {
+            name: 'onOpenChange',
+            type: 'function',
+            required: false,
+            description: 'Called when the palette requests an open/close state change.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the backdrop element.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Uncontrolled with ⌘K',
+            code: `<CommandPalette
+  commands={[
+    { id: 'new', label: 'New document', icon: <PlusIcon />, onSelect: () => router.push('/new') },
+    { id: 'settings', label: 'Settings', description: 'Open app settings', onSelect: () => router.push('/settings') },
+    { id: 'logout', label: 'Log out', group: 'Account', onSelect: handleLogout },
+  ]}
+/>`,
+        },
+        {
+            title: 'Controlled with custom shortcut',
+            code: `const [open, setOpen] = useState(false);
+<>
+  <Button onClick={() => setOpen(true)}>Open palette</Button>
+  <CommandPalette
+    commands={commands}
+    open={open}
+    onOpenChange={setOpen}
+    shortcutKey="p"
+  />
+</>`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'text', componentName: 'Text', role: 'Group labels, item labels, descriptions, and empty state', required: true },
+    ],
+    accessibility: {
+        role: 'dialog',
+        ariaAttributes: ['aria-label', 'aria-modal', 'aria-expanded', 'aria-selected', 'aria-disabled', 'aria-controls', 'aria-autocomplete'],
+        keyboardInteractions: ['⌘K / Ctrl+K to open', '↑↓ to navigate', 'Enter to select', 'Escape to close'],
+        notes: 'The backdrop and panel use role="dialog" with aria-modal="true". The input is role="searchbox". The result list is role="listbox" with role="option" items. Focus is moved to the search input on open.',
+    },
+};

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

@@ -0,0 +1,97 @@
+export const COMPONENT_MANIFEST = {
+    id: 'data-table',
+    name: 'DataTable',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '1.0',
+    description: 'A sortable, paginated data table with configurable columns, custom cell renderers, and keyboard-accessible pagination controls.',
+    designIntent: 'DataTable is generic over row type T so TypeScript consumers get full type safety on column keys and renderers. ' +
+        'Sorting is client-side and composable — each column opts in via sortable:true; clicking a sorted column cycles asc → desc → unsorted. ' +
+        'Pagination is either controlled (page prop + onPageChange) or uncontrolled (internal state). ' +
+        'A pageSize of 0 disables pagination entirely, useful when the parent manages windowing. ' +
+        'Column filtering is intentionally excluded here (see DataTable Filter issue #52) to keep the API focused. ' +
+        'Row hover uses bg-subtle, not a border change, so the visual weight stays low for dense data views.',
+    props: [
+        {
+            name: 'columns',
+            type: 'array',
+            required: true,
+            description: 'Column definitions. Each column has a key, header, optional render function, optional sortable flag, optional width, and optional text align.',
+        },
+        {
+            name: 'rows',
+            type: 'array',
+            required: true,
+            description: 'Array of data objects to display. The generic type T is inferred from this prop.',
+        },
+        {
+            name: 'pageSize',
+            type: 'number',
+            required: false,
+            default: '10',
+            description: 'Number of rows per page. Set to 0 to disable pagination.',
+        },
+        {
+            name: 'page',
+            type: 'number',
+            required: false,
+            description: 'Controlled current page (0-indexed). When provided, the component is fully controlled.',
+        },
+        {
+            name: 'onPageChange',
+            type: 'function',
+            required: false,
+            description: 'Called with the new page index whenever the page changes (from pagination controls or after a sort reset).',
+        },
+        {
+            name: 'emptyState',
+            type: 'ReactNode',
+            required: false,
+            description: 'Content to render when rows is empty. Defaults to a "No data" text.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides for the outer wrapper.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Basic sortable table',
+            code: `<DataTable
+  columns={[
+    { key: 'name', header: 'Name', sortable: true },
+    { key: 'role', header: 'Role', sortable: true },
+    { key: 'status', header: 'Status', render: (row) => <Badge>{row.status}</Badge> },
+  ]}
+  rows={users}
+/>`,
+        },
+        {
+            title: 'Controlled pagination',
+            code: `const [page, setPage] = useState(0);
+<DataTable
+  columns={columns}
+  rows={rows}
+  pageSize={20}
+  page={page}
+  onPageChange={setPage}
+/>`,
+        },
+        {
+            title: 'No pagination',
+            code: `<DataTable columns={columns} rows={rows} pageSize={0} />`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'text', componentName: 'Text', role: 'Row count and empty state labels', required: false },
+        { componentId: 'badge', componentName: 'Badge', role: 'Typical cell content for status columns', required: false },
+    ],
+    accessibility: {
+        role: 'table',
+        ariaAttributes: ['aria-label', 'aria-sort', 'aria-current'],
+        keyboardInteractions: ['Tab to pagination controls', 'Enter/Space to activate buttons'],
+        notes: 'Column headers with sortable:true are interactive buttons with aria-sort reflecting the current sort direction. Pagination buttons include aria-label and aria-current="page" for the active page.',
+    },
+};