@discourser/design-system 0.15.1 → 0.18.0

package/src/figma-codex/README.md

@@ -0,0 +1,186 @@
+# figma-codex
+
+A portable manifest generator that reads `.figma.tsx` Code Connect files and produces `figma-codex.json` — a structured map of Figma design components to their code implementations.
+
+## Why It Exists
+
+Figma's Code Connect "inspect" feature (linking designs to code in Dev Mode) requires a Figma **Organization or Enterprise** plan. `figma-codex` achieves the same goal without the subscription: it reads the `.figma.tsx` connector files already in the codebase and produces a self-contained JSON manifest that AI agents can consume offline.
+
+## What It Produces
+
+`dist/figma-codex.json` contains:
+
+```json
+{
+  "version": "1.0.0",
+  "packageName": "@discourser/design-system",
+  "generatedAt": "2026-02-27T12:00:00.000Z",
+  "gitHash": "abc1234",
+  "figmaFiles": {
+    "GaHmFfmvO4loUzuZS4TgEz": { "fileKey": "GaHmFfmvO4loUzuZS4TgEz" }
+  },
+  "components": {
+    "Accordion": {
+      "name": "Accordion",
+      "type": "compound",
+      "figma": {
+        "fileKey": "GaHmFfmvO4loUzuZS4TgEz",
+        "nodeId": "38:7978",
+        "url": "https://www.figma.com/design/..."
+      },
+      "imports": {
+        "primary": "import * as Accordion from '@discourser/design-system/Accordion'",
+        "namedExports": ["Accordion.Root", "Accordion.Item"]
+      },
+      "props": [],
+      "subComponents": [
+        { "name": "Root", "element": "div" },
+        { "name": "Item", "element": "div" }
+      ],
+      "example": "<Accordion.Root>...</Accordion.Root>",
+      "sourcePath": "src/components/Accordion.tsx"
+    }
+  }
+}
+```
+
+## Component Types
+
+| Type        | Description                                                   | Example                           |
+| ----------- | ------------------------------------------------------------- | --------------------------------- |
+| `simple`    | Single named export, no compound structure                    | `Header`, `DiscourserLogo`        |
+| `compound`  | Namespace import with sub-components (`.Root`, `.Item`, etc.) | `Accordion`, `Breadcrumb`         |
+| `composite` | Named export that imports other DDS components internally     | `NavigationMenu`, `ScenarioQueue` |
+
+## Usage
+
+### Generate the manifest
+
+```bash
+# One-time generation
+pnpm codex:generate
+
+# Watch mode (re-generates when .figma.tsx files change)
+pnpm codex:watch
+```
+
+The manifest is also auto-generated at the end of `pnpm build`.
+
+### Auto-regeneration on commit
+
+When you commit a `.figma.tsx` file, lint-staged automatically runs the generator (`tsx src/figma-codex/generate.ts`) to keep the manifest in sync.
+
+### Consuming the manifest
+
+```typescript
+// In AI agent code or tooling scripts
+import codex from '@discourser/design-system/figma-codex';
+
+const accordion = codex.components['Accordion'];
+console.log(accordion.type); // 'compound'
+console.log(accordion.imports.primary); // "import * as Accordion from '@discourser/design-system/Accordion'"
+console.log(accordion.subComponents); // [{ name: 'Root', element: 'div' }, ...]
+```
+
+## Agent Workflow (Kai + Amelia)
+
+1. **Kai** (Design Engineer) loads `figma-codex.json` and uses `figma.nodeId` to look up the Figma component
+2. Kai reads `imports.primary`, `props`, and `example` to understand how to use the component in code
+3. **Amelia** (Developer Agent) uses the manifest to verify the correct import path and prop types when implementing stories
+4. Both agents benefit from `subComponents` entries when assembling compound components
+
+## Adding a New Component
+
+After creating `YourComponent.figma.tsx`, three import patterns are supported:
+
+**Pattern 1 — Named import (simple)**
+
+```tsx
+import { YourComponent } from './YourComponent';
+figma.connect(YourComponent, 'https://www.figma.com/design/...', {
+  example: () => <YourComponent />,
+});
+```
+
+**Pattern 2 — Namespace from component file (compound)**
+
+```tsx
+import * as YourComponent from './YourComponent';
+figma.connect(YourComponent.Root, 'https://www.figma.com/design/...', {
+  example: () => <YourComponent.Root />,
+});
+```
+
+**Pattern 3 — Namespace from index (compound)**
+
+```tsx
+import * as YourComponent from './YourComponent/index';
+figma.connect(YourComponent.Root, 'https://www.figma.com/design/...', {
+  example: () => <YourComponent.Root />,
+});
+```
+
+After creating the file, run `pnpm codex:generate` to update the manifest.
+
+## Porting to Another Design System
+
+1. Copy the `src/figma-codex/` directory to your repo
+2. Add `"codex:generate": "tsx src/figma-codex/generate.ts"` to `package.json` scripts
+3. Create `figma-codex.config.json` (optional, all fields have defaults):
+
+```json
+{
+  "include": ["src/components/**/*.figma.tsx"],
+  "outputPath": "dist/figma-codex.json",
+  "packageName": "@your-org/design-system"
+}
+```
+
+4. Run `pnpm codex:generate`
+
+## Schema Reference
+
+```typescript
+interface FigmaCodex {
+  version: '1.0.0';
+  packageName: string;
+  generatedAt: string; // ISO 8601
+  gitHash?: string; // short SHA
+  figmaFiles: Record<string, { fileKey: string; fileName?: string }>;
+  components: Record<string, ComponentEntry>;
+}
+
+interface ComponentEntry {
+  name: string;
+  type: 'simple' | 'compound' | 'composite';
+  figma: {
+    fileKey: string;
+    nodeId: string; // format: "123:456"
+    nodeName?: string;
+    url: string;
+  };
+  imports: {
+    primary: string; // package import path
+    namedExports: string[];
+    subpath?: string;
+  };
+  props: PropDefinition[];
+  subComponents?: SubComponentEntry[];
+  example: string; // JSX usage string from figma.connect()
+  sourcePath: string; // relative path to source .tsx file
+}
+
+interface PropDefinition {
+  name: string;
+  type: string;
+  required: boolean;
+  description?: string; // from JSDoc comment
+  defaultValue?: string;
+}
+
+interface SubComponentEntry {
+  name: string; // e.g. "Root", "Item", "Header"
+  element: string; // underlying ark element, e.g. "div"
+  description?: string;
+}
+```

package/src/figma-codex/__tests__/config.test.ts

@@ -0,0 +1,63 @@
+// @vitest-environment node
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadConfig } from '../config';
+
+describe('loadConfig', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = join(tmpdir(), `figma-codex-test-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns defaults when no config file exists', () => {
+    const config = loadConfig(tmpDir);
+    expect(config.include).toEqual(['src/components/**/*.figma.tsx']);
+    expect(config.outputPath).toBe('dist/figma-codex.json');
+    expect(config.tsconfig).toBe('tsconfig.json');
+  });
+
+  it('merges user config over defaults', () => {
+    const userConfig = {
+      include: ['src/custom/**/*.figma.tsx'],
+      outputPath: 'out/codex.json',
+    };
+    writeFileSync(
+      join(tmpDir, 'figma-codex.config.json'),
+      JSON.stringify(userConfig),
+    );
+    const config = loadConfig(tmpDir);
+    expect(config.include).toEqual(['src/custom/**/*.figma.tsx']);
+    expect(config.outputPath).toBe('out/codex.json');
+    expect(config.tsconfig).toBe('tsconfig.json'); // default preserved
+  });
+
+  it('reads packageName from package.json when not set in config', () => {
+    writeFileSync(
+      join(tmpDir, 'package.json'),
+      JSON.stringify({ name: '@my/design-system' }),
+    );
+    const config = loadConfig(tmpDir);
+    expect(config.packageName).toBe('@my/design-system');
+  });
+
+  it('prefers packageName from config over package.json', () => {
+    writeFileSync(
+      join(tmpDir, 'package.json'),
+      JSON.stringify({ name: '@my/design-system' }),
+    );
+    writeFileSync(
+      join(tmpDir, 'figma-codex.config.json'),
+      JSON.stringify({ packageName: 'override-name' }),
+    );
+    const config = loadConfig(tmpDir);
+    expect(config.packageName).toBe('override-name');
+  });
+});

package/src/figma-codex/__tests__/generate.test.ts

@@ -0,0 +1,78 @@
+// @vitest-environment node
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { generate } from '../generate';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const FIXTURES = join(__dirname, '../fixtures');
+
+describe('generate (integration)', () => {
+  let tmpOut: string;
+  let outputPath: string;
+  let manifest: Record<string, unknown>;
+
+  beforeAll(() => {
+    tmpOut = join(tmpdir(), `figma-codex-integration-${Date.now()}`);
+    mkdirSync(tmpOut, { recursive: true });
+    outputPath = join(tmpOut, 'figma-codex.json');
+
+    generate({
+      include: [`${FIXTURES}/*.figma.tsx`],
+      outputPath,
+      packageName: '@test/design-system',
+      tsconfig: 'tsconfig.json',
+      projectRoot: FIXTURES,
+    });
+
+    manifest = JSON.parse(readFileSync(outputPath, 'utf-8')) as Record<
+      string,
+      unknown
+    >;
+  });
+
+  afterAll(() => {
+    rmSync(tmpOut, { recursive: true, force: true });
+  });
+
+  it('creates the output file', () => {
+    expect(existsSync(outputPath)).toBe(true);
+  });
+
+  it('includes SimpleComponent', () => {
+    const components = manifest.components as Record<string, unknown>;
+    expect(components).toHaveProperty('SimpleComponent');
+  });
+
+  it('includes CompoundComponent', () => {
+    const components = manifest.components as Record<string, unknown>;
+    expect(components).toHaveProperty('CompoundComponent');
+  });
+
+  it('SimpleComponent is type simple', () => {
+    const components = manifest.components as Record<string, { type: string }>;
+    expect(components.SimpleComponent.type).toBe('simple');
+  });
+
+  it('CompoundComponent is type compound', () => {
+    const components = manifest.components as Record<string, { type: string }>;
+    expect(components.CompoundComponent.type).toBe('compound');
+  });
+
+  it('has valid schema version', () => {
+    expect(manifest.version).toBe('1.0.0');
+  });
+
+  it('has generatedAt timestamp', () => {
+    expect(typeof manifest.generatedAt).toBe('string');
+  });
+
+  it('has non-empty components map', () => {
+    const components = manifest.components as Record<string, unknown>;
+    expect(Object.keys(components).length).toBeGreaterThan(0);
+  });
+});

package/src/figma-codex/__tests__/parser.test.ts

@@ -0,0 +1,138 @@
+// @vitest-environment node
+import { describe, it, expect, beforeEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseFigmaFile } from '../parser';
+import type { ParsedFigmaFile } from '../parser';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const FIXTURES = join(__dirname, '../fixtures');
+
+describe('parseFigmaFile', () => {
+  describe('named import (simple/composite pattern)', () => {
+    let result: ParsedFigmaFile;
+
+    beforeEach(() => {
+      const content = readFileSync(
+        join(FIXTURES, 'SimpleComponent.figma.tsx'),
+        'utf-8',
+      );
+      result = parseFigmaFile(
+        content,
+        join(FIXTURES, 'SimpleComponent.figma.tsx'),
+      );
+    });
+
+    it('detects named import style', () => {
+      expect(result.importStyle).toBe('named');
+    });
+
+    it('extracts component name', () => {
+      expect(result.componentName).toBe('SimpleComponent');
+    });
+
+    it('extracts import source path', () => {
+      expect(result.importSource).toBe('./SimpleComponent');
+    });
+
+    it('extracts figma URL', () => {
+      expect(result.figmaUrl).toBe(
+        'https://www.figma.com/design/ABC123/TestFile?node-id=1-2',
+      );
+    });
+
+    it('extracts file key from URL', () => {
+      expect(result.figmaFileKey).toBe('ABC123');
+    });
+
+    it('extracts node ID from URL (converting dash to colon)', () => {
+      expect(result.figmaNodeId).toBe('1:2');
+    });
+
+    it('extracts example JSX as string', () => {
+      expect(result.example).toContain('SimpleComponent');
+      expect(result.example).toContain('label="Hello"');
+    });
+
+    it('returns empty props mapping when no props block', () => {
+      expect(result.propsMapping).toEqual({});
+    });
+  });
+
+  describe('namespace import (compound pattern)', () => {
+    let result: ParsedFigmaFile;
+
+    beforeEach(() => {
+      const content = readFileSync(
+        join(FIXTURES, 'CompoundComponent.figma.tsx'),
+        'utf-8',
+      );
+      result = parseFigmaFile(
+        content,
+        join(FIXTURES, 'CompoundComponent.figma.tsx'),
+      );
+    });
+
+    it('detects namespace import style', () => {
+      expect(result.importStyle).toBe('namespace');
+    });
+
+    it('extracts namespace identifier', () => {
+      expect(result.componentName).toBe('CompoundComponent');
+    });
+
+    it('extracts import source', () => {
+      expect(result.importSource).toBe('./CompoundComponent/index');
+    });
+
+    it('extracts sub-component name from connect call (e.g., Root)', () => {
+      expect(result.connectSubComponent).toBe('Root');
+    });
+
+    it('extracts node ID correctly', () => {
+      expect(result.figmaNodeId).toBe('5:10');
+    });
+
+    it('extracts multiline example JSX', () => {
+      expect(result.example).toContain('CompoundComponent.Root');
+      expect(result.example).toContain('CompoundComponent.Header');
+    });
+  });
+
+  describe('props mapping extraction', () => {
+    it('extracts prop names from figma.enum props block', () => {
+      const content = `
+import figma from '@figma/code-connect'
+import { Header } from './Header'
+figma.connect(Header, 'https://www.figma.com/design/GaHmFfmvO4loUzuZS4TgEz/File?node-id=485-4697', {
+  props: {
+    size: figma.enum('size', { xSm: 'xs', Mdm: 'md' }),
+  },
+  example: ({ size }) => <Header size={size}>Text</Header>,
+})
+      `.trim();
+      const result = parseFigmaFile(content, '/fake/Header.figma.tsx');
+      expect(result.propsMapping).toHaveProperty('size');
+    });
+  });
+
+  describe('error handling', () => {
+    it('throws ParseError for file with no figma.connect call', () => {
+      expect(() =>
+        parseFigmaFile('import React from "react"', '/fake/empty.figma.tsx'),
+      ).toThrow();
+    });
+
+    it('throws ParseError for file with no import', () => {
+      expect(() =>
+        parseFigmaFile(
+          `figma.connect(X, 'https://figma.com/design/A/F?node-id=1-2', { example: () => <X /> })`,
+          '/fake/noimport.figma.tsx',
+        ),
+      ).toThrow();
+    });
+  });
+});

package/src/figma-codex/__tests__/resolver.test.ts

@@ -0,0 +1,196 @@
+// @vitest-environment node
+import { describe, it, expect } from 'vitest';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveComponent } from '../resolver';
+import type { ParsedFigmaFile } from '../parser';
+import type { FigmaCodexConfig } from '../config';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const FIXTURES = join(__dirname, '../fixtures');
+const DDS_ROOT = join(__dirname, '../../..');
+
+const baseConfig: FigmaCodexConfig = {
+  include: [],
+  outputPath: 'dist/figma-codex.json',
+  packageName: '@discourser/design-system',
+  tsconfig: 'tsconfig.json',
+};
+
+describe('resolveComponent', () => {
+  describe('simple component', () => {
+    const parsed: ParsedFigmaFile = {
+      filePath: join(FIXTURES, 'SimpleComponent.figma.tsx'),
+      importStyle: 'named',
+      componentName: 'SimpleComponent',
+      importSource: './SimpleComponent',
+      figmaUrl: 'https://www.figma.com/design/ABC123/TestFile?node-id=1-2',
+      figmaFileKey: 'ABC123',
+      figmaNodeId: '1:2',
+      example: '<SimpleComponent label="Hello" />',
+      propsMapping: {},
+    };
+
+    it('classifies as simple', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      expect(entry.type).toBe('simple');
+    });
+
+    it('extracts named exports from source', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      expect(entry.imports.namedExports).toContain('SimpleComponent');
+    });
+
+    it('extracts prop definitions', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      expect(entry.props.length).toBeGreaterThan(0);
+      const labelProp = entry.props.find((p) => p.name === 'label');
+      expect(labelProp).toBeDefined();
+      expect(labelProp?.required).toBe(true);
+    });
+
+    it('extracts optional props', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      const sizeProp = entry.props.find((p) => p.name === 'size');
+      expect(sizeProp).toBeDefined();
+      expect(sizeProp?.required).toBe(false);
+    });
+
+    it('builds correct figma metadata', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      expect(entry.figma.fileKey).toBe('ABC123');
+      expect(entry.figma.nodeId).toBe('1:2');
+      expect(entry.figma.url).toBe(parsed.figmaUrl);
+    });
+
+    it('builds primary import statement', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      expect(entry.imports.primary).toContain('SimpleComponent');
+      expect(entry.imports.primary).toContain('@discourser/design-system');
+    });
+  });
+
+  describe('compound component', () => {
+    const parsed: ParsedFigmaFile = {
+      filePath: join(FIXTURES, 'CompoundComponent.figma.tsx'),
+      importStyle: 'namespace',
+      componentName: 'CompoundComponent',
+      importSource: './CompoundComponent/index',
+      connectSubComponent: 'Root',
+      figmaUrl: 'https://www.figma.com/design/ABC123/TestFile?node-id=5-10',
+      figmaFileKey: 'ABC123',
+      figmaNodeId: '5:10',
+      example: '<CompoundComponent.Root>...</CompoundComponent.Root>',
+      propsMapping: {},
+    };
+
+    it('classifies as compound', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      expect(entry.type).toBe('compound');
+    });
+
+    it('extracts sub-components from withContext/withProvider calls', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      expect(entry.subComponents).toBeDefined();
+      const names = entry.subComponents?.map((s) => s.name) ?? [];
+      expect(names).toContain('Root');
+      expect(names).toContain('Header');
+      expect(names).toContain('Body');
+    });
+
+    it('extracts HTML element for sub-components', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      const rootSub = entry.subComponents?.find((s) => s.name === 'Root');
+      expect(rootSub?.element).toBeTruthy();
+    });
+
+    it('builds namespace import statement', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      expect(entry.imports.primary).toContain('* as CompoundComponent');
+    });
+  });
+
+  describe('composite component detection', () => {
+    it('classifies NavigationMenu as composite (imports other DDS components)', () => {
+      const parsed: ParsedFigmaFile = {
+        filePath: join(
+          DDS_ROOT,
+          'src/components/NavigationMenu/NavigationMenu.figma.tsx',
+        ),
+        importStyle: 'named',
+        componentName: 'NavigationMenu',
+        importSource: './NavigationMenu',
+        figmaUrl:
+          'https://www.figma.com/design/GaHmFfmvO4loUzuZS4TgEz/Discourser.AI--V1?node-id=38-8485',
+        figmaFileKey: 'GaHmFfmvO4loUzuZS4TgEz',
+        figmaNodeId: '38:8485',
+        example: '<NavigationMenu sections={[]} />',
+        propsMapping: {},
+      };
+      const entry = resolveComponent(parsed, {
+        ...baseConfig,
+        packageName: '@discourser/design-system',
+      });
+      expect(entry.type).toBe('composite');
+    });
+  });
+
+  describe('missing source file', () => {
+    it('returns empty props array when source file not found', () => {
+      const parsed: ParsedFigmaFile = {
+        filePath: '/nonexistent/dir/Missing.figma.tsx',
+        importStyle: 'named',
+        componentName: 'Missing',
+        importSource: './Missing',
+        figmaUrl: 'https://www.figma.com/design/X/F?node-id=1-1',
+        figmaFileKey: 'X',
+        figmaNodeId: '1:1',
+        example: '<Missing />',
+        propsMapping: {},
+      };
+      const entry = resolveComponent(parsed, baseConfig);
+      expect(entry.props).toEqual([]);
+    });
+  });
+
+  describe('NavigationMenu multi-line prop types', () => {
+    const parsed: ParsedFigmaFile = {
+      filePath: join(
+        DDS_ROOT,
+        'src/components/NavigationMenu/NavigationMenu.figma.tsx',
+      ),
+      importStyle: 'named',
+      componentName: 'NavigationMenu',
+      importSource: './NavigationMenu',
+      figmaUrl:
+        'https://www.figma.com/design/GaHmFfmvO4loUzuZS4TgEz/Discourser.AI--V1?node-id=38-8485',
+      figmaFileKey: 'GaHmFfmvO4loUzuZS4TgEz',
+      figmaNodeId: '38:8485',
+      example: '<NavigationMenu sections={[]} />',
+      propsMapping: {},
+    };
+
+    it('extracts exactly 6 props (not leaking inner fields)', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      expect(entry.props).toHaveLength(6);
+    });
+
+    it('renderLink type contains full function signature', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      const renderLink = entry.props.find((p) => p.name === 'renderLink');
+      expect(renderLink).toBeDefined();
+      expect(renderLink?.type).toContain('=> React.ReactNode');
+      expect(renderLink?.type).toContain('href');
+    });
+
+    it('does not leak inner object fields as top-level props', () => {
+      const entry = resolveComponent(parsed, baseConfig);
+      const names = entry.props.map((p) => p.name);
+      expect(names).not.toContain('href');
+      expect(names).not.toContain('isActive');
+      expect(names).not.toContain('className');
+    });
+  });
+});