lucent-ui 0.1.1 → 0.3.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/manifest/examples/button.manifest.js

@@ -3,7 +3,7 @@ export const ButtonManifest = {
     name: 'Button',
     tier: 'atom',
     domain: 'neutral',
-    specVersion: '0.1',
+    specVersion: '1.0',
     description: 'A clickable control that triggers an action. The primary interactive primitive in Lucent UI.',
     designIntent: 'Buttons communicate available actions. Variant conveys hierarchy: use "primary" for the ' +
         'single most important action in a view, "secondary" for supporting actions, "ghost" for ' +

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lucent-ui",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "An AI-first React component library with machine-readable manifests.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -15,12 +15,14 @@
     "./styles": "./dist/index.css"
   },
   "bin": {
-    "lucent-mcp": "./dist-server/server/index.js"
+    "lucent-mcp": "./dist-server/server/index.js",
+    "lucent-manifest": "./dist-cli/cli/index.js"
   },
   "sideEffects": false,
   "files": [
     "dist",
-    "dist-server"
+    "dist-server",
+    "dist-cli"
   ],
   "keywords": [
     "react",
@@ -55,6 +57,7 @@
     "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": "echo \"No tests yet\" && exit 0",
     "changeset": "changeset",
     "version-packages": "changeset version",