specweave 0.23.18 → 0.24.1

package/plugins/specweave-figma/commands/figma-tokens.md

@@ -0,0 +1,815 @@
+# /specweave-figma:tokens
+
+Extract design tokens from Figma and generate token files for theme configuration (CSS variables, JavaScript, JSON, SCSS).
+
+You are a design token expert who automates design system token extraction and synchronization from Figma.
+
+## Your Task
+
+Extract design tokens (colors, typography, spacing, shadows, borders) from Figma and generate production-ready token files in multiple formats.
+
+### 1. Design Token Standards
+
+**W3C Design Tokens Format** (Recommended):
+```json
+{
+  "colors": {
+    "brand": {
+      "primary": {
+        "$type": "color",
+        "$value": "#0066FF",
+        "$description": "Primary brand color"
+      },
+      "secondary": {
+        "$type": "color",
+        "$value": "#00CC66"
+      }
+    }
+  },
+  "typography": {
+    "heading": {
+      "h1": {
+        "$type": "typography",
+        "$value": {
+          "fontFamily": "Inter",
+          "fontSize": "48px",
+          "fontWeight": 700,
+          "lineHeight": 1.2
+        }
+      }
+    }
+  }
+}
+```
+
+**Token Categories**:
+- Colors (brand, semantic, grayscale)
+- Typography (font families, sizes, weights, line heights)
+- Spacing (margins, paddings, gaps)
+- Border radius (corners)
+- Shadows (elevations)
+- Borders (widths, styles)
+- Breakpoints (responsive)
+- Z-index (layering)
+- Transitions (animations)
+
+### 2. Figma Token Extraction
+
+**Extract Color Tokens from Styles**:
+
+```typescript
+import { FigmaImporter } from './figma-importer';
+
+interface ColorToken {
+  name: string;
+  value: string;
+  rgba: { r: number; g: number; b: number; a: number };
+  type: 'solid' | 'gradient';
+  description?: string;
+}
+
+async function extractColorTokens(fileKey: string): Promise<ColorToken[]> {
+  const importer = new FigmaImporter({
+    accessToken: process.env.FIGMA_ACCESS_TOKEN!,
+    fileKey,
+  });
+
+  const file = await importer.fetchFile();
+  const styles = await importer.fetchStyles();
+
+  const colorTokens: ColorToken[] = [];
+
+  for (const style of styles) {
+    if (style.style_type === 'FILL') {
+      const node = findNodeById(file.document, style.node_id);
+
+      if (node?.fills?.[0]) {
+        const fill = node.fills[0];
+
+        if (fill.type === 'SOLID') {
+          colorTokens.push({
+            name: style.name,
+            value: rgbaToHex(fill.color, fill.opacity),
+            rgba: {
+              r: fill.color.r,
+              g: fill.color.g,
+              b: fill.color.b,
+              a: fill.opacity ?? 1,
+            },
+            type: 'solid',
+            description: style.description || undefined,
+          });
+        } else if (fill.type === 'GRADIENT_LINEAR') {
+          colorTokens.push({
+            name: style.name,
+            value: convertGradientToCSS(fill),
+            rgba: fill.gradientStops[0].color,
+            type: 'gradient',
+            description: style.description,
+          });
+        }
+      }
+    }
+  }
+
+  return colorTokens;
+}
+
+function rgbaToHex(color: { r: number; g: number; b: number }, opacity = 1): string {
+  const r = Math.round(color.r * 255);
+  const g = Math.round(color.g * 255);
+  const b = Math.round(color.b * 255);
+
+  if (opacity < 1) {
+    const a = Math.round(opacity * 255);
+    return `#${[r, g, b, a].map(x => x.toString(16).padStart(2, '0')).join('')}`;
+  }
+
+  return `#${[r, g, b].map(x => x.toString(16).padStart(2, '0')).join('')}`;
+}
+```
+
+**Extract Typography Tokens**:
+
+```typescript
+interface TypographyToken {
+  name: string;
+  fontFamily: string;
+  fontSize: number;
+  fontWeight: number;
+  lineHeight: number;
+  letterSpacing?: number;
+  textTransform?: 'none' | 'uppercase' | 'lowercase' | 'capitalize';
+  description?: string;
+}
+
+async function extractTypographyTokens(fileKey: string): Promise<TypographyToken[]> {
+  const importer = new FigmaImporter({
+    accessToken: process.env.FIGMA_ACCESS_TOKEN!,
+    fileKey,
+  });
+
+  const file = await importer.fetchFile();
+  const styles = await importer.fetchStyles();
+
+  const typographyTokens: TypographyToken[] = [];
+
+  for (const style of styles) {
+    if (style.style_type === 'TEXT') {
+      const node = findNodeById(file.document, style.node_id);
+
+      if (node?.style) {
+        typographyTokens.push({
+          name: style.name,
+          fontFamily: node.style.fontFamily,
+          fontSize: node.style.fontSize,
+          fontWeight: node.style.fontWeight,
+          lineHeight: node.style.lineHeightPx / node.style.fontSize,
+          letterSpacing: node.style.letterSpacing || undefined,
+          textTransform: node.style.textCase?.toLowerCase() as any,
+          description: style.description,
+        });
+      }
+    }
+  }
+
+  return typographyTokens;
+}
+```
+
+**Extract Spacing Tokens from Auto Layout**:
+
+```typescript
+interface SpacingToken {
+  name: string;
+  value: number;
+  description?: string;
+}
+
+async function extractSpacingTokens(fileKey: string): Promise<SpacingToken[]> {
+  const importer = new FigmaImporter({
+    accessToken: process.env.FIGMA_ACCESS_TOKEN!,
+    fileKey,
+  });
+
+  const file = await importer.fetchFile();
+
+  const spacingValues = new Set<number>();
+
+  // Traverse all frames with auto layout
+  traverseNodes(file.document, (node) => {
+    if (node.layoutMode) {
+      // Item spacing (gap)
+      if (node.itemSpacing) {
+        spacingValues.add(node.itemSpacing);
+      }
+
+      // Padding
+      if (node.paddingLeft) spacingValues.add(node.paddingLeft);
+      if (node.paddingRight) spacingValues.add(node.paddingRight);
+      if (node.paddingTop) spacingValues.add(node.paddingTop);
+      if (node.paddingBottom) spacingValues.add(node.paddingBottom);
+    }
+  });
+
+  // Generate semantic names (4px → xs, 8px → sm, etc.)
+  const sortedSpacing = Array.from(spacingValues).sort((a, b) => a - b);
+
+  const sizeMap = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl'];
+
+  return sortedSpacing.map((value, index) => ({
+    name: sizeMap[index] || `spacing-${index}`,
+    value,
+    description: `${value}px spacing`,
+  }));
+}
+```
+
+**Extract Shadow Tokens (Elevation)**:
+
+```typescript
+interface ShadowToken {
+  name: string;
+  value: string; // CSS box-shadow value
+  layers: Array<{
+    x: number;
+    y: number;
+    blur: number;
+    spread: number;
+    color: string;
+  }>;
+  description?: string;
+}
+
+async function extractShadowTokens(fileKey: string): Promise<ShadowToken[]> {
+  const importer = new FigmaImporter({
+    accessToken: process.env.FIGMA_ACCESS_TOKEN!,
+    fileKey,
+  });
+
+  const file = await importer.fetchFile();
+  const styles = await importer.fetchStyles();
+
+  const shadowTokens: ShadowToken[] = [];
+
+  for (const style of styles) {
+    if (style.style_type === 'EFFECT') {
+      const node = findNodeById(file.document, style.node_id);
+
+      if (node?.effects) {
+        const shadows = node.effects.filter(
+          (e: any) => e.type === 'DROP_SHADOW' || e.type === 'INNER_SHADOW'
+        );
+
+        if (shadows.length > 0) {
+          const layers = shadows.map((shadow: any) => ({
+            x: shadow.offset.x,
+            y: shadow.offset.y,
+            blur: shadow.radius,
+            spread: shadow.spread || 0,
+            color: rgbaToHex(shadow.color, shadow.color.a),
+          }));
+
+          const cssValue = layers
+            .map(
+              (layer) =>
+                `${layer.x}px ${layer.y}px ${layer.blur}px ${layer.spread}px ${layer.color}`
+            )
+            .join(', ');
+
+          shadowTokens.push({
+            name: style.name,
+            value: cssValue,
+            layers,
+            description: style.description,
+          });
+        }
+      }
+    }
+  }
+
+  return shadowTokens;
+}
+```
+
+### 3. Token Organization
+
+**Hierarchical Token Structure**:
+
+```
+tokens/
+├── global/
+│   ├── colors.json          # Brand colors, primitives
+│   ├── typography.json      # Font scales
+│   ├── spacing.json         # Spacing scale
+│   └── shadows.json         # Elevation scale
+├── semantic/
+│   ├── colors.json          # Semantic colors (success, error, warning)
+│   ├── components.json      # Component-specific tokens
+│   └── themes.json          # Light/dark theme mappings
+└── platform/
+    ├── web.json             # Web-specific tokens (CSS variables)
+    ├── ios.json             # iOS-specific (Swift)
+    └── android.json         # Android-specific (XML)
+```
+
+**Naming Convention** (BEM-inspired):
+```
+category-element-modifier-state
+
+Examples:
+- color-brand-primary
+- color-semantic-success
+- color-text-primary
+- typography-heading-h1
+- spacing-component-button-padding
+- shadow-elevation-1
+- border-radius-sm
+```
+
+### 4. Token File Formats
+
+**CSS Variables** (Most Common):
+
+```css
+/* tokens/global/colors.css */
+:root {
+  /* Brand Colors */
+  --color-brand-primary: #0066FF;
+  --color-brand-secondary: #00CC66;
+  --color-brand-tertiary: #FF6600;
+
+  /* Semantic Colors */
+  --color-semantic-success: #00CC66;
+  --color-semantic-error: #FF3333;
+  --color-semantic-warning: #FFCC00;
+  --color-semantic-info: #0066FF;
+
+  /* Grayscale */
+  --color-gray-50: #F9FAFB;
+  --color-gray-100: #F3F4F6;
+  --color-gray-200: #E5E7EB;
+  --color-gray-300: #D1D5DB;
+  --color-gray-400: #9CA3AF;
+  --color-gray-500: #6B7280;
+  --color-gray-600: #4B5563;
+  --color-gray-700: #374151;
+  --color-gray-800: #1F2937;
+  --color-gray-900: #111827;
+
+  /* Typography */
+  --font-family-sans: 'Inter', -apple-system, sans-serif;
+  --font-family-mono: 'JetBrains Mono', monospace;
+
+  --font-size-xs: 0.75rem;    /* 12px */
+  --font-size-sm: 0.875rem;   /* 14px */
+  --font-size-base: 1rem;     /* 16px */
+  --font-size-lg: 1.125rem;   /* 18px */
+  --font-size-xl: 1.25rem;    /* 20px */
+  --font-size-2xl: 1.5rem;    /* 24px */
+  --font-size-3xl: 1.875rem;  /* 30px */
+  --font-size-4xl: 2.25rem;   /* 36px */
+
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+
+  --line-height-tight: 1.25;
+  --line-height-normal: 1.5;
+  --line-height-relaxed: 1.75;
+
+  /* Spacing */
+  --spacing-xs: 0.25rem;  /* 4px */
+  --spacing-sm: 0.5rem;   /* 8px */
+  --spacing-md: 1rem;     /* 16px */
+  --spacing-lg: 1.5rem;   /* 24px */
+  --spacing-xl: 2rem;     /* 32px */
+  --spacing-2xl: 3rem;    /* 48px */
+  --spacing-3xl: 4rem;    /* 64px */
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
+  --shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1);
+
+  /* Border Radius */
+  --radius-sm: 0.25rem;   /* 4px */
+  --radius-md: 0.5rem;    /* 8px */
+  --radius-lg: 0.75rem;   /* 12px */
+  --radius-xl: 1rem;      /* 16px */
+  --radius-full: 9999px;
+
+  /* Transitions */
+  --transition-fast: 150ms;
+  --transition-base: 250ms;
+  --transition-slow: 350ms;
+}
+```
+
+**JavaScript/TypeScript**:
+
+```typescript
+// tokens/global/colors.ts
+export const colors = {
+  brand: {
+    primary: '#0066FF',
+    secondary: '#00CC66',
+    tertiary: '#FF6600',
+  },
+  semantic: {
+    success: '#00CC66',
+    error: '#FF3333',
+    warning: '#FFCC00',
+    info: '#0066FF',
+  },
+  gray: {
+    50: '#F9FAFB',
+    100: '#F3F4F6',
+    200: '#E5E7EB',
+    300: '#D1D5DB',
+    400: '#9CA3AF',
+    500: '#6B7280',
+    600: '#4B5563',
+    700: '#374151',
+    800: '#1F2937',
+    900: '#111827',
+  },
+} as const;
+
+// tokens/global/typography.ts
+export const typography = {
+  fontFamily: {
+    sans: "'Inter', -apple-system, sans-serif",
+    mono: "'JetBrains Mono', monospace",
+  },
+  fontSize: {
+    xs: '0.75rem',
+    sm: '0.875rem',
+    base: '1rem',
+    lg: '1.125rem',
+    xl: '1.25rem',
+    '2xl': '1.5rem',
+    '3xl': '1.875rem',
+    '4xl': '2.25rem',
+  },
+  fontWeight: {
+    normal: 400,
+    medium: 500,
+    semibold: 600,
+    bold: 700,
+  },
+  lineHeight: {
+    tight: 1.25,
+    normal: 1.5,
+    relaxed: 1.75,
+  },
+} as const;
+
+// tokens/index.ts
+export { colors } from './global/colors';
+export { typography } from './global/typography';
+export { spacing } from './global/spacing';
+export { shadows } from './global/shadows';
+
+// Type-safe token access
+export type ColorToken = keyof typeof colors.brand | keyof typeof colors.semantic;
+```
+
+**JSON** (W3C Design Tokens Format):
+
+```json
+{
+  "$schema": "https://design-tokens.org/schemas/v1.0.0/design-tokens.schema.json",
+  "colors": {
+    "brand": {
+      "primary": {
+        "$type": "color",
+        "$value": "#0066FF",
+        "$description": "Primary brand color used for main actions and links"
+      },
+      "secondary": {
+        "$type": "color",
+        "$value": "#00CC66",
+        "$description": "Secondary brand color for accents"
+      }
+    },
+    "semantic": {
+      "success": {
+        "$type": "color",
+        "$value": "{colors.brand.secondary}",
+        "$description": "Success state color (references brand.secondary)"
+      }
+    }
+  },
+  "typography": {
+    "heading": {
+      "h1": {
+        "$type": "typography",
+        "$value": {
+          "fontFamily": "{typography.fontFamily.sans}",
+          "fontSize": "{typography.fontSize.4xl}",
+          "fontWeight": "{typography.fontWeight.bold}",
+          "lineHeight": "{typography.lineHeight.tight}"
+        }
+      }
+    }
+  }
+}
+```
+
+**SCSS Variables**:
+
+```scss
+// tokens/global/_colors.scss
+$color-brand-primary: #0066FF;
+$color-brand-secondary: #00CC66;
+
+$color-gray-50: #F9FAFB;
+$color-gray-100: #F3F4F6;
+// ...
+
+// tokens/global/_typography.scss
+$font-family-sans: 'Inter', -apple-system, sans-serif;
+$font-size-base: 1rem;
+$font-weight-bold: 700;
+
+// tokens/_index.scss
+@forward 'global/colors';
+@forward 'global/typography';
+@forward 'global/spacing';
+```
+
+**Tailwind CSS Config**:
+
+```javascript
+// tailwind.config.js
+const { colors, typography, spacing, shadows } = require('./tokens');
+
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        brand: colors.brand,
+        semantic: colors.semantic,
+        gray: colors.gray,
+      },
+      fontFamily: typography.fontFamily,
+      fontSize: typography.fontSize,
+      fontWeight: typography.fontWeight,
+      lineHeight: typography.lineHeight,
+      spacing: spacing,
+      boxShadow: shadows,
+    },
+  },
+};
+```
+
+### 5. Token Generation Automation
+
+**Complete Pipeline**:
+
+```typescript
+import fs from 'fs/promises';
+import path from 'path';
+
+interface TokenGeneratorConfig {
+  fileKey: string;
+  outputDir: string;
+  formats: Array<'css' | 'scss' | 'js' | 'ts' | 'json' | 'tailwind'>;
+}
+
+async function generateTokens(config: TokenGeneratorConfig) {
+  const { fileKey, outputDir, formats } = config;
+
+  // 1. Extract tokens from Figma
+  const colorTokens = await extractColorTokens(fileKey);
+  const typographyTokens = await extractTypographyTokens(fileKey);
+  const spacingTokens = await extractSpacingTokens(fileKey);
+  const shadowTokens = await extractShadowTokens(fileKey);
+
+  const allTokens = {
+    colors: colorTokens,
+    typography: typographyTokens,
+    spacing: spacingTokens,
+    shadows: shadowTokens,
+  };
+
+  // 2. Create output directory
+  await fs.mkdir(outputDir, { recursive: true });
+
+  // 3. Generate formats
+  if (formats.includes('css')) {
+    const css = generateCSSVariables(allTokens);
+    await fs.writeFile(path.join(outputDir, 'tokens.css'), css);
+  }
+
+  if (formats.includes('scss')) {
+    const scss = generateSCSSVariables(allTokens);
+    await fs.writeFile(path.join(outputDir, '_tokens.scss'), scss);
+  }
+
+  if (formats.includes('js') || formats.includes('ts')) {
+    const js = generateJavaScript(allTokens);
+    const ext = formats.includes('ts') ? '.ts' : '.js';
+    await fs.writeFile(path.join(outputDir, `tokens${ext}`), js);
+  }
+
+  if (formats.includes('json')) {
+    const json = generateW3CTokens(allTokens);
+    await fs.writeFile(path.join(outputDir, 'tokens.json'), json);
+  }
+
+  if (formats.includes('tailwind')) {
+    const tailwind = generateTailwindConfig(allTokens);
+    await fs.writeFile(path.join(outputDir, 'tailwind.tokens.js'), tailwind);
+  }
+
+  console.log(`✅ Generated design tokens in ${formats.join(', ')} format(s)`);
+}
+
+function generateCSSVariables(tokens: any): string {
+  let css = ':root {\n';
+
+  // Colors
+  css += '  /* Colors */\n';
+  tokens.colors.forEach((token: any) => {
+    css += `  --color-${token.name.toLowerCase().replace(/\s+/g, '-')}: ${token.value};\n`;
+  });
+
+  // Typography
+  css += '\n  /* Typography */\n';
+  tokens.typography.forEach((token: any) => {
+    const name = token.name.toLowerCase().replace(/\s+/g, '-');
+    css += `  --font-family-${name}: ${token.fontFamily};\n`;
+    css += `  --font-size-${name}: ${token.fontSize}px;\n`;
+    css += `  --font-weight-${name}: ${token.fontWeight};\n`;
+    css += `  --line-height-${name}: ${token.lineHeight};\n`;
+  });
+
+  // Spacing
+  css += '\n  /* Spacing */\n';
+  tokens.spacing.forEach((token: any) => {
+    css += `  --spacing-${token.name}: ${token.value}px;\n`;
+  });
+
+  // Shadows
+  css += '\n  /* Shadows */\n';
+  tokens.shadows.forEach((token: any) => {
+    css += `  --shadow-${token.name.toLowerCase().replace(/\s+/g, '-')}: ${token.value};\n`;
+  });
+
+  css += '}\n';
+
+  return css;
+}
+
+function generateJavaScript(tokens: any): string {
+  const js = `
+export const colors = {
+${tokens.colors.map((t: any) => `  '${t.name}': '${t.value}',`).join('\n')}
+};
+
+export const typography = {
+${tokens.typography.map((t: any) => `  '${t.name}': {
+    fontFamily: '${t.fontFamily}',
+    fontSize: ${t.fontSize},
+    fontWeight: ${t.fontWeight},
+    lineHeight: ${t.lineHeight},
+  },`).join('\n')}
+};
+
+export const spacing = {
+${tokens.spacing.map((t: any) => `  '${t.name}': ${t.value},`).join('\n')}
+};
+
+export const shadows = {
+${tokens.shadows.map((t: any) => `  '${t.name}': '${t.value}',`).join('\n')}
+};
+`;
+
+  return js.trim();
+}
+
+// Usage
+generateTokens({
+  fileKey: 'ABC123XYZ456',
+  outputDir: './src/design-tokens',
+  formats: ['css', 'ts', 'json', 'tailwind'],
+}).catch(console.error);
+```
+
+### 6. Token Synchronization (Watch Mode)
+
+**Auto-sync on Figma Changes**:
+
+```typescript
+import { watch } from 'fs';
+
+async function watchFigmaTokens(fileKey: string, outputDir: string, pollInterval = 60000) {
+  let lastVersion: string | null = null;
+
+  setInterval(async () => {
+    const importer = new FigmaImporter({
+      accessToken: process.env.FIGMA_ACCESS_TOKEN!,
+      fileKey,
+    });
+
+    const file = await importer.fetchFile();
+
+    if (lastVersion && file.version !== lastVersion) {
+      console.log(`🔄 Figma file updated (v${file.version}). Re-generating tokens...`);
+
+      await generateTokens({
+        fileKey,
+        outputDir,
+        formats: ['css', 'ts', 'json'],
+      });
+
+      console.log('✅ Tokens synchronized!');
+    }
+
+    lastVersion = file.version;
+  }, pollInterval);
+
+  console.log(`👀 Watching Figma file for changes (polling every ${pollInterval / 1000}s)...`);
+}
+
+// Usage
+watchFigmaTokens('ABC123XYZ456', './src/design-tokens', 60000); // Check every minute
+```
+
+### 7. Theme Support (Light/Dark Mode)
+
+**Generate Theme Tokens**:
+
+```typescript
+// tokens/themes/light.ts
+export const lightTheme = {
+  colors: {
+    background: '#FFFFFF',
+    foreground: '#111827',
+    primary: '#0066FF',
+    secondary: '#6B7280',
+    border: '#E5E7EB',
+  },
+};
+
+// tokens/themes/dark.ts
+export const darkTheme = {
+  colors: {
+    background: '#111827',
+    foreground: '#F9FAFB',
+    primary: '#3B82F6',
+    secondary: '#9CA3AF',
+    border: '#374151',
+  },
+};
+
+// CSS Variables with theme support
+:root {
+  --color-background: #FFFFFF;
+  --color-foreground: #111827;
+}
+
+[data-theme="dark"] {
+  --color-background: #111827;
+  --color-foreground: #F9FAFB;
+}
+```
+
+## Workflow
+
+1. Ask about Figma file and token extraction preferences
+2. Fetch color, typography, spacing, and shadow styles from Figma
+3. Analyze and categorize tokens (brand, semantic, primitives)
+4. Ask about output formats (CSS, SCSS, JS, JSON, Tailwind)
+5. Generate hierarchical token structure
+6. Create token files in requested formats
+7. Set up theme support if needed (light/dark modes)
+8. Provide integration examples for each format
+9. Optionally set up watch mode for auto-sync
+10. Generate documentation with token usage examples
+
+## When to Use
+
+- Setting up design systems from Figma
+- Synchronizing design tokens across platforms (web, iOS, Android)
+- Migrating from hardcoded values to token-based theming
+- Implementing light/dark mode support
+- Automating design-to-code token updates
+- Standardizing design values across teams
+
+## Best Practices
+
+1. **Organization**: Use hierarchical structure (global → semantic → component)
+2. **Naming**: Follow consistent naming conventions (BEM or similar)
+3. **Formats**: Generate multiple formats for different use cases
+4. **Aliasing**: Use token references for semantic tokens (W3C format)
+5. **Documentation**: Include descriptions from Figma styles
+6. **Versioning**: Track Figma file versions in metadata
+7. **Automation**: Set up CI/CD for token synchronization
+8. **Validation**: Validate token values before deployment
+
+Extract and sync design tokens with production-ready automation!