handoff-app 1.1.3 → 1.2.0-0

package/src/declarations/index.ts

@@ -0,0 +1,19 @@
+export {
+  defineComponent,
+  defineCsfComponent,
+  defineHandlebarsComponent,
+  definePattern,
+  defineReactComponent
+} from './helpers';
+
+export type {
+  CsfDeclarationConfig,
+  DeclarationPreview,
+  GenericDeclarationConfig,
+  GenericPatternDeclarationConfig,
+  HandlebarsDeclarationConfig,
+  PatternComponentRef,
+  ReactDeclarationConfig,
+  RendererKind
+} from './types';
+

package/src/declarations/types.ts

@@ -0,0 +1,70 @@
+import type React from 'react';
+import type { ComponentObject } from '../transformers/preview/types';
+
+export type RendererKind = 'react' | 'handlebars' | 'csf';
+
+export type DeclarationPreview<TArgs = Record<string, any>> = {
+  title: string;
+  args?: TArgs;
+  values?: TArgs;
+  url?: string;
+  usage?: string;
+};
+
+type BaseDeclarationEntries = NonNullable<ComponentObject['entries']> & {
+  component?: string;
+  story?: string;
+  templates?: string;
+};
+
+type OptionalComponentMetadata = Partial<Omit<ComponentObject, 'previews' | 'entries' | 'title' | 'should_do' | 'should_not_do'>>;
+
+export type BaseDeclarationConfig = OptionalComponentMetadata & {
+  id?: string;
+  name: string;
+  renderer?: RendererKind;
+  entries?: BaseDeclarationEntries;
+  previews?: Record<string, DeclarationPreview>;
+  shouldDo?: string[];
+  shouldNotDo?: string[];
+};
+
+export type ReactDeclarationConfig<TProps> = Omit<BaseDeclarationConfig, 'renderer' | 'entries' | 'previews'> & {
+  entries: BaseDeclarationEntries & { component: string };
+  previews: Record<string, DeclarationPreview<Partial<TProps>>>;
+};
+
+export type HandlebarsDeclarationConfig = Omit<BaseDeclarationConfig, 'renderer' | 'entries'> & {
+  entries: BaseDeclarationEntries & { template: string };
+};
+
+export type CsfDeclarationConfig = Omit<BaseDeclarationConfig, 'renderer' | 'entries'> & {
+  entries: BaseDeclarationEntries & { story: string };
+};
+
+export type GenericDeclarationConfig = Omit<BaseDeclarationConfig, 'renderer'> & {
+  renderer: RendererKind;
+};
+
+export type ReactComponentType<TProps = any> = React.ComponentType<TProps>;
+
+// ---------------------------------------------------------------------------
+// Pattern declarations
+// ---------------------------------------------------------------------------
+
+export type PatternComponentRef = {
+  id: string;
+  preview?: string;
+  args?: Record<string, any>;
+};
+
+export type BasePatternDeclarationConfig = {
+  id?: string;
+  name: string;
+  description?: string;
+  group?: string;
+  tags?: string[];
+  components: PatternComponentRef[];
+};
+
+export type GenericPatternDeclarationConfig = BasePatternDeclarationConfig;

package/src/index.ts

@@ -5,11 +5,12 @@ import path from 'path';
 import buildApp, { devApp, watchApp } from './app-builder';
 import { ejectConfig, ejectPages, ejectTheme } from './cli/eject';
 import { makeComponent, makePage, makeTemplate } from './cli/make';
-import { initConfig, initRuntimeConfig, validateConfig } from './config';
-import pipeline, { buildComponents } from './pipeline';
+import { initConfigWithMetadata, initRuntimeConfig, validateConfig } from './config';
+import pipeline, { buildComponents, buildPatterns } from './pipeline';
 import processComponents, { ComponentSegment } from './transformers/preview/component/builder';
-import { Config, RuntimeConfig } from './types/config';
+import { Config, ConfigFileEntry, RuntimeConfig } from './types/config';
 import { Logger } from './utils/logger';
+import { normalizePathForCompare } from './utils/path';
 import { generateFilesystemSafeId } from './utils/path';
 
 class Handoff {
@@ -29,6 +30,8 @@ class Handoff {
 
   private _initialArgs: { debug?: boolean; force?: boolean; config?: Partial<Config> } = {};
   private _configFilePaths: string[] = [];
+  private _configFileIndex: Map<string, ConfigFileEntry> = new Map();
+  private _mainConfigFilePath?: string;
   private _documentationObjectCache?: CoreTypes.IDocumentationObject;
   private _handoffRunner?: ReturnType<typeof HandoffRunner> | null;
 
@@ -47,11 +50,13 @@ class Handoff {
   }
 
   init(configOverride?: Partial<Config>): Handoff {
-    const config = initConfig(configOverride ?? {});
+    const configResult = initConfigWithMetadata(configOverride ?? {});
+    const config = configResult.config;
     this.config = config;
+    this._mainConfigFilePath = configResult.configPath;
     this.exportsDirectory = config.exportsOutputDirectory ?? this.exportsDirectory;
     this.sitesDirectory = config.sitesOutputDirectory ?? this.exportsDirectory;
-    [this.runtimeConfig, this._configFilePaths] = initRuntimeConfig(this);
+    [this.runtimeConfig, this._configFilePaths, this._configFileIndex] = initRuntimeConfig(this);
     if(this.config.app.base_path && !process.env.HANDOFF_APP_BASE_PATH) {
       process.env.HANDOFF_APP_BASE_PATH = this.config.app.base_path ?? '';
     }
@@ -92,6 +97,12 @@ class Handoff {
     return this;
   }
 
+  async pattern(): Promise<Handoff> {
+    this.preRunner();
+    await buildPatterns(this);
+    return this;
+  }
+
   async build(skipComponents?: boolean): Promise<Handoff> {
     this.preRunner();
     await buildApp(this, skipComponents);
@@ -271,7 +282,19 @@ class Handoff {
    * @returns {string[]} Array of absolute paths to config files
    */
   getConfigFilePaths(): string[] {
-    return this._configFilePaths;
+    const combined = this._mainConfigFilePath ? [this._mainConfigFilePath, ...this._configFilePaths] : this._configFilePaths;
+    return Array.from(new Set(combined));
+  }
+
+  /**
+   * Gets the selected main config file path if one exists.
+   */
+  getMainConfigFilePath(): string | undefined {
+    return this._mainConfigFilePath;
+  }
+
+  getConfigFileEntry(configPath: string): ConfigFileEntry | undefined {
+    return this._configFileIndex.get(normalizePathForCompare(configPath));
   }
 
   /**
@@ -298,6 +321,24 @@ class Handoff {
 
 export type { ComponentObject as Component } from './transformers/preview/types';
 export type { Config, RegisterHandlebarsHelpersContext } from './types/config';
+export { defineConfig } from './config';
+export {
+  defineComponent,
+  defineCsfComponent,
+  defineHandlebarsComponent,
+  definePattern,
+  defineReactComponent,
+} from './declarations';
+export type {
+  CsfDeclarationConfig,
+  DeclarationPreview,
+  GenericDeclarationConfig,
+  GenericPatternDeclarationConfig,
+  HandlebarsDeclarationConfig,
+  PatternComponentRef,
+  ReactDeclarationConfig,
+  RendererKind,
+} from './declarations';
 
 // Export transformers and types from handoff-core
 export { Transformers as CoreTransformers, TransformerUtils as CoreTransformerUtils, Types as CoreTypes } from 'handoff-core';

package/src/pipeline/index.ts

@@ -9,6 +9,7 @@ import { validateHandoffRequirements } from './validation';
 // Re-exports used by other modules
 export { readPrevJSONFile, zip, zipAssets } from './archive';
 export { buildComponents } from './components';
+export { buildPatterns } from './patterns';
 
 /**
  * Run the entire Figma data pipeline:

package/src/pipeline/patterns.ts

@@ -0,0 +1,10 @@
+import Handoff from '..';
+import { processPatterns } from '../transformers/preview/pattern/builder';
+
+/**
+ * Builds pattern previews by composing pre-built component preview HTML.
+ * Must be called AFTER buildComponents.
+ */
+export const buildPatterns = async (handoff: Handoff) => {
+  await processPatterns(handoff);
+};

package/src/transformers/README.md

@@ -10,9 +10,9 @@ transformers/
 │   ├── component/      # Component builder, CSS/JS bundling, SSR rendering, validation
 │   ├── component.ts    # Component transformer entry point, shared styles processing
 │   └── types.ts        # Preview/component type definitions
-├── plugins/            # Build plugins (SSR render, Handlebars previews, CSF render)
+├── plugins/            # Build plugins (SSR render, Handlebars previews, CSF render with per-preview/story usage generation)
 ├── docgen/             # React component documentation generation
-├── utils/              # Build utilities (handlebars, schema, HTML, SVG sprites, Vite logger)
+├── utils/              # Build utilities (handlebars, schema, HTML, SVG sprites, Vite logger, usage snippet helpers)
 ├── plugins.ts          # Barrel re-exports for plugins
 ├── vite-config.ts      # Shared Vite configuration
 └── types.ts            # Transformer-level type definitions

package/src/transformers/docgen/index.ts

@@ -261,8 +261,19 @@ export const enrichPropertiesWithDocgen = (
 export const generateDocsArtifact = async (entry: string, handoff: any): Promise<GeneratedDocs | null> => {
   try {
     const tsconfigPath = path.resolve(handoff.workingPath, 'tsconfig.json');
-    if (!fs.existsSync(tsconfigPath)) {
-      Logger.warn(`TypeScript config not found at ${tsconfigPath}, using default resolution`);
+    const hasTsconfig = fs.existsSync(tsconfigPath);
+    const entryExtension = path.extname(entry).toLowerCase();
+    const isJavaScriptEntry = ['.js', '.jsx', '.cjs', '.mjs'].includes(entryExtension);
+
+    if (!hasTsconfig) {
+      // For JS-only projects, handoff-docgen currently expects a tsconfig and will fail noisily.
+      // Skip docgen gracefully in this case.
+      if (isJavaScriptEntry) {
+        Logger.debug(`Skipping handoff-docgen for ${entry}: no tsconfig.json found in ${handoff.workingPath}`);
+        return null;
+      }
+      Logger.warn(`TypeScript config not found at ${tsconfigPath}; skipping docs generation for ${entry}.`);
+      return null;
     }
 
     const componentDirectory = path.dirname(path.resolve(entry));

package/src/transformers/plugins/csf-render.ts

@@ -4,32 +4,24 @@ import { startCase } from 'lodash';
 import path from 'path';
 import React from 'react';
 import ReactDOMServer from 'react-dom/server';
+import reactElementToJSXString from 'react-element-to-jsx-string';
 import { Plugin } from 'vite';
 import Handoff from '../..';
 import { Logger } from '../../utils/logger';
+import { generateDocsArtifact, getPropertiesForComponentFromDocs } from '../docgen';
 import { SlotMetadata, SlotType } from '../preview/component';
 import { TransformComponentTokensResult } from '../preview/types';
 import { formatHtml, trimPreview } from '../utils/html';
 import { buildAndEvaluateModule } from '../utils/module';
 import { ensureIds } from '../utils/schema';
+import { extractComponentName, generateUsageSnippet } from '../utils/usage';
+import { createCsfStoryPreviews, CsfMeta, getCsfStoryEntries, StoryObject } from '../utils/csf';
 import { createViteLogger } from '../utils/vite-logger';
-import { generateDocsArtifact, getPropertiesForComponentFromDocs } from '../docgen';
 
-type StoryObject = {
-  name?: string;
-  args?: Record<string, any>;
-  argTypes?: Record<string, any>;
-  render?: (args: Record<string, any>) => any;
+type ComponentImportInfo = {
+  componentName: string;
+  importStatement: string;
 };
-
-type CsfMeta = {
-  title?: string;
-  component?: React.ComponentType<any>;
-  args?: Record<string, any>;
-  argTypes?: Record<string, any>;
-  render?: (args: Record<string, any>) => any;
-};
-
 const PLUGIN_CONSTANTS = {
   PLUGIN_NAME: 'vite-plugin-csf-render',
   SCRIPT_ID: 'script',
@@ -78,15 +70,6 @@ function createSlotMetadata(
   };
 }
 
-function getStoryEntries(moduleExports: Record<string, any>): Array<[string, StoryObject]> {
-  return Object.entries(moduleExports).filter(([key, value]) => {
-    if (key === 'default' || key === '__esModule') return false;
-    if (typeof value === 'function') return true;
-    if (value && typeof value === 'object') return true;
-    return false;
-  }) as Array<[string, StoryObject]>;
-}
-
 function toReactElement(
   renderResult: any,
   meta: CsfMeta,
@@ -107,28 +90,179 @@ function toReactElement(
   return React.createElement('pre', null, JSON.stringify(args, null, 2));
 }
 
+/**
+ * Produces the React element for a story, mirroring Storybook's resolution order:
+ * story render > meta render > meta.component > JSON fallback.
+ */
+function getStoryElement(
+  meta: CsfMeta,
+  story: StoryObject | ((args: Record<string, any>) => any) | undefined,
+  args: Record<string, any>
+): React.ReactElement {
+  const storyRender = typeof story === 'function' ? story : story?.render;
+  const render = storyRender || meta.render;
+
+  if (render) {
+    return toReactElement(render(args), meta, args);
+  }
+
+  if (meta.component) {
+    return React.createElement(meta.component, args);
+  }
+
+  return React.createElement('pre', null, JSON.stringify(args, null, 2));
+}
+
 function safeRenderToHtml(
   meta: CsfMeta,
-  story: StoryObject | ((args: Record<string, any>) => any),
+  story: StoryObject | ((args: Record<string, any>) => any) | undefined,
   args: Record<string, any>
 ): string {
   try {
-    const storyRender = typeof story === 'function' ? story : story.render;
-    const render = storyRender || meta.render;
+    return ReactDOMServer.renderToString(getStoryElement(meta, story, args));
+  } catch (error) {
+    Logger.warn(`SSR render failed for story, falling back to static placeholder: ${error}`);
+    return `<div style="padding:1rem;color:#b91c1c;font-family:monospace;font-size:13px">Render error: ${String(error)}</div>`;
+  }
+}
+
+/**
+ * Converts a story's React element into a JSX source string using the same
+ * approach as Storybook's Docs addon.
+ */
+function reactElementToUsage(element: React.ReactElement): string | null {
+  try {
+    return reactElementToJSXString(element, {
+      sortProps: false,
+      useBooleanShorthandSyntax: true,
+      useFragmentShortSyntax: true,
+      maxInlineAttributesLineLength: 80,
+    });
+  } catch (error) {
+    Logger.warn(`Failed to convert React element to JSX string: ${error}`);
+    return null;
+  }
+}
+
+function findMatchingBrace(source: string, openIndex: number): number {
+  let depth = 0;
 
-    if (render) {
-      return ReactDOMServer.renderToString(toReactElement(render(args), meta, args));
+  for (let i = openIndex; i < source.length; i += 1) {
+    const char = source[i];
+    if (char === '{') depth += 1;
+    if (char === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        return i;
+      }
     }
+  }
+
+  return -1;
+}
+
+function extractMetaObjectBody(sourceCode: string): string | null {
+  // TODO: Regex-based CSF meta parsing can miss complex inline `satisfies` cases.
+  // Move this to a TS-AST resolver in handoff-docgen and consume the normalized import info here.
+  const inlineMetaMatch = sourceCode.match(/export\s+default\s+({[\s\S]*?})\s*(?:satisfies\s+[^{;\n]+|as\s+[^{;\n]+)?\s*;/m);
+  if (inlineMetaMatch?.[1]) {
+    return inlineMetaMatch[1];
+  }
 
-    if (meta.component) {
-      return ReactDOMServer.renderToString(React.createElement(meta.component, args));
+  const exportedMetaRef = sourceCode.match(/export\s+default\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*;/m);
+  if (!exportedMetaRef?.[1]) {
+    return null;
+  }
+
+  const metaVarName = exportedMetaRef[1];
+  const declarationPatterns = [
+    new RegExp(`(?:const|let|var)\\s+${metaVarName}\\s*=\\s*`, 'm'),
+    new RegExp(`(?:const|let|var)\\s+${metaVarName}\\s*=\\s*[^\\n;]*?\\b(?:satisfies|as)\\b[^\\n;]*?`, 'm'),
+  ];
+
+  for (const pattern of declarationPatterns) {
+    const match = pattern.exec(sourceCode);
+    if (!match) continue;
+    const openIndex = sourceCode.indexOf('{', match.index);
+    if (openIndex === -1) continue;
+    const closeIndex = findMatchingBrace(sourceCode, openIndex);
+    if (closeIndex === -1) continue;
+    return sourceCode.slice(openIndex, closeIndex + 1);
+  }
+
+  return null;
+}
+
+function resolveComponentImportInfo(sourceCode: string): ComponentImportInfo | null {
+  const metaBody = extractMetaObjectBody(sourceCode);
+  if (!metaBody) {
+    return null;
+  }
+
+  const componentMatch = metaBody.match(/\bcomponent\s*:\s*([A-Za-z_$][A-Za-z0-9_$]*)\b/m);
+  if (!componentMatch?.[1]) {
+    return null;
+  }
+
+  const localName = componentMatch[1];
+
+  const defaultImportMatch = sourceCode.match(
+    new RegExp(`import\\s+${localName}\\s+from\\s+['"]([^'"]+)['"]`, 'm')
+  );
+  if (defaultImportMatch?.[1]) {
+    return {
+      componentName: localName,
+      importStatement: `import ${localName} from '${defaultImportMatch[1]}';`,
+    };
+  }
+
+  const namedImportRegex = /import\s*{\s*([^}]+)\s*}\s*from\s*['"]([^'"]+)['"]/gm;
+  for (const match of sourceCode.matchAll(namedImportRegex)) {
+    const specifiers = match[1]
+      .split(',')
+      .map((specifier) => specifier.trim())
+      .filter(Boolean);
+    const moduleSpecifier = match[2];
+
+    for (const specifier of specifiers) {
+      const aliasMatch = specifier.match(/^([A-Za-z_$][A-Za-z0-9_$]*)\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)$/);
+      if (aliasMatch && aliasMatch[2] === localName) {
+        return {
+          componentName: localName,
+          importStatement: `import { ${aliasMatch[1]} as ${localName} } from '${moduleSpecifier}';`,
+        };
+      }
+
+      if (specifier === localName) {
+        return {
+          componentName: localName,
+          importStatement: `import { ${localName} } from '${moduleSpecifier}';`,
+        };
+      }
     }
+  }
 
-    return ReactDOMServer.renderToString(React.createElement('pre', null, JSON.stringify(args, null, 2)));
-  } catch (error) {
-    Logger.warn(`SSR render failed for story, falling back to static placeholder: ${error}`);
-    return `<div style="padding:1rem;color:#b91c1c;font-family:monospace;font-size:13px">Render error: ${String(error)}</div>`;
+  return null;
+}
+
+function buildUsageSnippet(
+  componentName: string,
+  importStatement: string,
+  element: React.ReactElement | null,
+  properties: Record<string, SlotMetadata>,
+  previewValues: Record<string, any>
+): string {
+  const usageBody = element ? reactElementToUsage(element) : null;
+  if (usageBody) {
+    return `${importStatement}\n\n${usageBody}`;
   }
+
+  return generateUsageSnippet({
+    componentName,
+    properties,
+    previewValues,
+    importStatement,
+  });
 }
 
 function createHtmlDocument(componentId: string, previewTitle: string, renderedHtml: string): string {
@@ -189,7 +323,8 @@ export function csfRenderPlugin(
       }
 
       const meta = (moduleExports.default || {}) as CsfMeta;
-      const stories = getStoryEntries(moduleExports);
+      const stories = getCsfStoryEntries(moduleExports);
+      const storyMap = Object.fromEntries(stories);
 
       if (stories.length === 0) {
         Logger.warn(`No named stories found in CSF file for ${componentId}: ${templatePath}`);
@@ -198,9 +333,16 @@ export function csfRenderPlugin(
 
       const explicitProperties = componentData.properties || {};
       const generatedProperties: Record<string, SlotMetadata> = { ...explicitProperties };
+      const incomingPreviews = { ...(componentData.previews || {}) };
+      const patternPreviews = Object.fromEntries(
+        Object.entries(incomingPreviews).filter(([key]) => key.startsWith('__pattern_'))
+      );
 
-      // Include all named stories as previews and infer properties from args/argTypes
-      componentData.previews = {};
+      // Include all named stories as previews and preserve injected pattern previews.
+      componentData.previews = {
+        ...createCsfStoryPreviews(moduleExports),
+        ...patternPreviews,
+      };
 
       for (const [storyKey, storyValue] of stories) {
         const storyObj = (typeof storyValue === 'function' ? {} : storyValue) as StoryObject;
@@ -213,12 +355,6 @@ export function csfRenderPlugin(
           ...(storyObj.argTypes || {}),
         };
 
-        componentData.previews[storyKey] = {
-          title: storyObj.name || startCase(storyKey),
-          values: mergedArgs,
-          url: '',
-        };
-
         for (const [argKey, argValue] of Object.entries(mergedArgs)) {
           if (!generatedProperties[argKey]) {
             generatedProperties[argKey] = createSlotMetadata(argKey, mergedArgTypes[argKey], argValue);
@@ -236,6 +372,10 @@ export function csfRenderPlugin(
       const generatedDocs = await generateDocsArtifact(templatePath, handoff);
       const componentName =
         (meta.component as any)?.displayName || (meta.component as any)?.name;
+      const componentImportInfo = resolveComponentImportInfo(sourceCode);
+      const usageComponentName = componentImportInfo?.componentName || componentName || extractComponentName(templatePath);
+      const usageImportStatement =
+        componentImportInfo?.importStatement || `import ${usageComponentName} from './${usageComponentName}';`;
       if (generatedDocs && componentName) {
         const docgenProperties = getPropertiesForComponentFromDocs(
           generatedDocs,
@@ -285,11 +425,15 @@ export function csfRenderPlugin(
       componentData.properties = ensureIds(generatedProperties);
 
       let lastHtml = '';
-      for (const [storyKey, storyValue] of stories) {
-        const preview = componentData.previews[storyKey];
-        const rendered = safeRenderToHtml(meta, storyValue, preview.values || {});
+      for (const [previewKey, preview] of Object.entries(componentData.previews)) {
+        const storyKey = preview.sourcePreview && storyMap[preview.sourcePreview]
+          ? preview.sourcePreview
+          : (storyMap[previewKey] ? previewKey : undefined);
+        const storyValue = storyKey ? storyMap[storyKey] : undefined;
+        const storyArgs = preview.values || {};
+        const rendered = safeRenderToHtml(meta, storyValue, storyArgs);
         const html = await formatHtml(createHtmlDocument(componentId, preview.title, rendered));
-        const fileName = `${componentId}-${storyKey}.html`;
+        const fileName = `${componentId}-${previewKey}.html`;
 
         this.emitFile({
           type: 'asset',
@@ -298,10 +442,26 @@ export function csfRenderPlugin(
         });
         this.emitFile({
           type: 'asset',
-          fileName: `${componentId}-${storyKey}${PLUGIN_CONSTANTS.INSPECT_SUFFIX}.html`,
+          fileName: `${componentId}-${previewKey}${PLUGIN_CONSTANTS.INSPECT_SUFFIX}.html`,
           source: html,
         });
 
+        // Capture JSX usage for each story so docs can switch usage by selected preview.
+        let storyElement: React.ReactElement | null = null;
+        try {
+          storyElement = getStoryElement(meta, storyValue, storyArgs);
+        } catch {
+          // Fall back to schema-based generation below.
+        }
+
+        preview.usage = buildUsageSnippet(
+          usageComponentName,
+          usageImportStatement,
+          storyElement,
+          componentData.properties || {},
+          storyArgs
+        );
+
         preview.url = fileName;
         lastHtml = html;
       }
@@ -310,6 +470,13 @@ export function csfRenderPlugin(
       componentData.preview = '';
       componentData.code = trimPreview(sourceCode);
       componentData.html = trimPreview(lastHtml);
+
+      // Keep top-level usage for backwards compatibility (first preview usage).
+      const storyKeys = Object.keys(componentData.previews);
+      const firstStoryKey = storyKeys[0];
+      if (firstStoryKey) {
+        componentData.usage = componentData.previews[firstStoryKey].usage || '';
+      }
     },
   };
 }

package/src/transformers/plugins/ssr-render.ts

@@ -8,10 +8,10 @@ import { Plugin, normalizePath } from 'vite';
 import Handoff from '../..';
 import { Logger } from '../../utils/logger';
 import {
-  enrichPropertiesWithDocgen,
-  generateDocsArtifact,
-  generatePropertiesFromDocgen,
-  getPropertiesFromGeneratedDocs,
+    enrichPropertiesWithDocgen,
+    generateDocsArtifact,
+    generatePropertiesFromDocgen,
+    getPropertiesFromGeneratedDocs,
 } from '../docgen';
 import { SlotMetadata } from '../preview/component';
 import { TransformComponentTokensResult } from '../preview/types';
@@ -20,6 +20,7 @@ import { formatHtml, trimPreview } from '../utils/html';
 import { buildAndEvaluateModule } from '../utils/module';
 import { loadSchemaFromComponent, loadSchemaFromFile } from '../utils/schema-loader';
 import { slugify } from '../utils/string';
+import { extractComponentName, generateUsageSnippet } from '../utils/usage';
 import { createViteLogger } from '../utils/vite-logger';
 
 /**
@@ -204,8 +205,6 @@ export function ssrRenderPlugin(
         documentationComponents = {};
       }
 
-      const generatedPreviews: { [key: string]: string } = {};
-
       // Process component instances from documentation
       // Use figmaComponentId if provided, otherwise skip implicit matching
       if (componentData.figmaComponentId) {
@@ -219,6 +218,7 @@ export function ssrRenderPlugin(
               title: variationId,
               url: '',
               values: instanceValues,
+              usage: '',
             };
           }
         }
@@ -294,8 +294,13 @@ export function ssrRenderPlugin(
           source: finalHtml,
         });
 
-        generatedPreviews[previewKey] = finalHtml;
         componentData.previews[previewKey].url = `${componentId}-${previewKey}.html`;
+        componentData.previews[previewKey].usage = generateUsageSnippet({
+          componentName: extractComponentName(componentPath),
+          properties: componentData.properties || {},
+          previewValues: previewProps || {},
+          templateFileName: path.basename(componentPath),
+        });
       }
 
       // Format final HTML and update component data
@@ -304,6 +309,17 @@ export function ssrRenderPlugin(
       componentData.preview = '';
       componentData.code = trimPreview(componentSourceCode);
       componentData.html = trimPreview(finalHtml);
+
+      // Generate usage snippet from the first preview's values
+      const previewKeys = Object.keys(componentData.previews);
+      const firstPreviewValues = previewKeys.length > 0 ? componentData.previews[previewKeys[0]].values : {};
+      const componentName = extractComponentName(componentPath);
+      componentData.usage = generateUsageSnippet({
+        componentName,
+        properties: componentData.properties || {},
+        previewValues: firstPreviewValues,
+        templateFileName: path.basename(componentPath),
+      });
     },
   };
 }