816 lines
20 KiB
Markdown
816 lines
20 KiB
Markdown
# /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!
|