@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/figma-to-code.md

@@ -0,0 +1,298 @@
+---
+name: figma-to-code
+description: Figma to code workflow for auto-layout mapping, design token extraction, component mapping, responsive export, and developer handoff.
+---
+
+# Figma to Code Workflow
+
+## When to Use
+Use this workflow when translating Figma designs into production code. It covers extracting design tokens from Figma variables, mapping auto-layout to CSS flexbox/grid, converting Figma components to React components, handling responsive breakpoints, and establishing a repeatable handoff process. Apply this workflow when starting a new design system implementation or when a design team delivers new components.
+
+## How It Works
+
+### Extracting Design Tokens via Figma API
+
+```typescript
+// scripts/extract-figma-tokens.ts
+import fetch from 'node-fetch';
+
+const FIGMA_TOKEN = process.env.FIGMA_TOKEN!;
+const FILE_KEY = process.env.FIGMA_FILE_KEY!;
+
+interface FigmaColor { r: number; g: number; b: number; a: number }
+
+async function extractTokens() {
+  const res = await fetch(
+    `https://api.figma.com/v1/files/${FILE_KEY}/variables/local`,
+    { headers: { 'X-Figma-Token': FIGMA_TOKEN } }
+  );
+  const data = await res.json();
+
+  const tokens: Record<string, Record<string, string>> = { colors: {}, spacing: {}, radius: {} };
+
+  for (const variable of Object.values(data.meta.variables) as any[]) {
+    const name = variable.name.replace(/\//g, '-').toLowerCase();
+    const value = Object.values(variable.valuesByMode)[0] as any;
+
+    if (variable.resolvedType === 'COLOR') {
+      tokens.colors[name] = rgbaToHex(value as FigmaColor);
+    } else if (variable.resolvedType === 'FLOAT') {
+      if (name.includes('spacing')) tokens.spacing[name] = `${value}px`;
+      if (name.includes('radius')) tokens.radius[name] = `${value}px`;
+    }
+  }
+
+  return tokens;
+}
+
+function rgbaToHex({ r, g, b, a }: FigmaColor): string {
+  const hex = [r, g, b].map((c) => Math.round(c * 255).toString(16).padStart(2, '0')).join('');
+  return a < 1 ? `#${hex}${Math.round(a * 255).toString(16).padStart(2, '0')}` : `#${hex}`;
+}
+```
+
+### Auto-Layout to CSS Flexbox Mapping
+
+```typescript
+// Figma auto-layout properties → CSS equivalents
+
+const autoLayoutToCSS: Record<string, Record<string, string>> = {
+  // Layout direction
+  layoutMode: {
+    HORIZONTAL: 'flex-direction: row',
+    VERTICAL: 'flex-direction: column',
+  },
+  // Primary axis alignment (main axis)
+  primaryAxisAlignItems: {
+    MIN: 'justify-content: flex-start',
+    CENTER: 'justify-content: center',
+    MAX: 'justify-content: flex-end',
+    SPACE_BETWEEN: 'justify-content: space-between',
+  },
+  // Counter axis alignment (cross axis)
+  counterAxisAlignItems: {
+    MIN: 'align-items: flex-start',
+    CENTER: 'align-items: center',
+    MAX: 'align-items: flex-end',
+    BASELINE: 'align-items: baseline',
+  },
+  // Sizing
+  primaryAxisSizingMode: {
+    FIXED: 'width/height: fixed value',
+    AUTO: 'width/height: auto (fit-content)',
+  },
+  counterAxisSizingMode: {
+    FIXED: 'cross-size: fixed value',
+    AUTO: 'cross-size: auto (fit-content)',
+  },
+};
+
+// Example: Figma frame → Tailwind classes
+function figmaFrameToTailwind(frame: FigmaNode): string {
+  const classes: string[] = ['flex'];
+
+  if (frame.layoutMode === 'VERTICAL') classes.push('flex-col');
+  if (frame.itemSpacing) classes.push(`gap-${pxToTailwind(frame.itemSpacing)}`);
+  if (frame.paddingTop) classes.push(`pt-${pxToTailwind(frame.paddingTop)}`);
+  if (frame.paddingRight) classes.push(`pr-${pxToTailwind(frame.paddingRight)}`);
+  if (frame.paddingBottom) classes.push(`pb-${pxToTailwind(frame.paddingBottom)}`);
+  if (frame.paddingLeft) classes.push(`pl-${pxToTailwind(frame.paddingLeft)}`);
+
+  const alignMap: Record<string, string> = {
+    MIN: 'items-start', CENTER: 'items-center', MAX: 'items-end',
+  };
+  if (frame.counterAxisAlignItems) {
+    classes.push(alignMap[frame.counterAxisAlignItems] ?? '');
+  }
+
+  const justifyMap: Record<string, string> = {
+    MIN: 'justify-start', CENTER: 'justify-center', MAX: 'justify-end',
+    SPACE_BETWEEN: 'justify-between',
+  };
+  if (frame.primaryAxisAlignItems) {
+    classes.push(justifyMap[frame.primaryAxisAlignItems] ?? '');
+  }
+
+  return classes.filter(Boolean).join(' ');
+}
+
+function pxToTailwind(px: number): string {
+  const map: Record<number, string> = { 4: '1', 8: '2', 12: '3', 16: '4', 20: '5', 24: '6', 32: '8' };
+  return map[px] ?? `[${px}px]`;
+}
+```
+
+### Component Mapping (Figma to React)
+
+```typescript
+// Map Figma component properties to React props
+interface FigmaComponentMapping {
+  figmaName: string;
+  reactComponent: string;
+  propMapping: Record<string, { figmaProperty: string; transform?: (v: string) => string }>;
+}
+
+const componentMappings: FigmaComponentMapping[] = [
+  {
+    figmaName: 'Button',
+    reactComponent: 'Button',
+    propMapping: {
+      variant: { figmaProperty: 'Style', transform: (v) => v.toLowerCase() },
+      size: { figmaProperty: 'Size', transform: (v) => v.toLowerCase() },
+      disabled: { figmaProperty: 'State', transform: (v) => String(v === 'Disabled') },
+    },
+  },
+  {
+    figmaName: 'Input',
+    reactComponent: 'Input',
+    propMapping: {
+      label: { figmaProperty: 'Label' },
+      error: { figmaProperty: 'Error text' },
+      placeholder: { figmaProperty: 'Placeholder' },
+    },
+  },
+];
+
+// Generate React component from Figma node
+function generateComponent(node: FigmaComponentNode, mapping: FigmaComponentMapping): string {
+  const props: string[] = [];
+  for (const [reactProp, config] of Object.entries(mapping.propMapping)) {
+    const value = node.componentProperties[config.figmaProperty]?.value;
+    if (value !== undefined) {
+      const transformed = config.transform ? config.transform(String(value)) : String(value);
+      props.push(`${reactProp}="${transformed}"`);
+    }
+  }
+  return `<${mapping.reactComponent} ${props.join(' ')} />`;
+}
+```
+
+### Responsive Breakpoint Strategy
+
+```typescript
+// Map Figma frames to responsive breakpoints
+interface ResponsiveFrame {
+  name: string;
+  width: number;
+  breakpoint: string;
+  tailwindPrefix: string;
+}
+
+const responsiveFrames: ResponsiveFrame[] = [
+  { name: 'Mobile', width: 375, breakpoint: '0px', tailwindPrefix: '' },
+  { name: 'Tablet', width: 768, breakpoint: '768px', tailwindPrefix: 'md:' },
+  { name: 'Desktop', width: 1280, breakpoint: '1024px', tailwindPrefix: 'lg:' },
+  { name: 'Wide', width: 1440, breakpoint: '1280px', tailwindPrefix: 'xl:' },
+];
+
+// Generate responsive class string from multi-frame analysis
+function mergeResponsiveClasses(
+  frames: Record<string, string[]>
+): string {
+  const mobile = new Set(frames['Mobile'] ?? []);
+  const result = [...mobile];
+
+  for (const { name, tailwindPrefix } of responsiveFrames.slice(1)) {
+    const classes = frames[name] ?? [];
+    for (const cls of classes) {
+      if (!mobile.has(cls)) {
+        result.push(`${tailwindPrefix}${cls}`);
+      }
+    }
+  }
+
+  return result.join(' ');
+}
+
+// Example output: "flex flex-col gap-4 md:flex-row md:gap-8 lg:gap-12"
+```
+
+### Export Automation Script
+
+```typescript
+// scripts/figma-export.ts
+import * as Figma from 'figma-api';
+import fs from 'fs/promises';
+import path from 'path';
+
+const api = new Figma.Api({ personalAccessToken: process.env.FIGMA_TOKEN! });
+
+async function exportIcons(fileKey: string, nodeIds: string[]) {
+  const images = await api.getImage(fileKey, {
+    ids: nodeIds.join(','),
+    format: 'svg',
+    scale: 1,
+  });
+
+  for (const [nodeId, url] of Object.entries(images.images)) {
+    if (!url) continue;
+    const response = await fetch(url);
+    const svg = await response.text();
+    const name = nodeId.replace(/:/g, '-');
+    await fs.writeFile(
+      path.join('src/assets/icons', `${name}.svg`),
+      optimizeSvg(svg)
+    );
+  }
+}
+
+function optimizeSvg(svg: string): string {
+  return svg
+    .replace(/fill="[^"]*"/g, 'fill="currentColor"')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+```
+
+### Developer Handoff Checklist Generator
+
+```typescript
+// scripts/handoff-report.ts
+interface HandoffReport {
+  component: string;
+  tokens: string[];
+  variants: string[];
+  states: string[];
+  responsive: string[];
+  a11y: string[];
+}
+
+function generateHandoffReport(component: FigmaComponent): HandoffReport {
+  return {
+    component: component.name,
+    tokens: extractUsedTokens(component),
+    variants: Object.keys(component.componentPropertyDefinitions ?? {}),
+    states: ['default', 'hover', 'focus', 'disabled', 'error'].filter(
+      (state) => component.children.some((c: any) => c.name.toLowerCase().includes(state))
+    ),
+    responsive: responsiveFrames
+      .filter((f) => component.children.some((c: any) => c.name.includes(f.name)))
+      .map((f) => f.name),
+    a11y: [
+      component.children.some((c: any) => c.type === 'TEXT') ? 'Has visible label' : 'Needs aria-label',
+      'Check color contrast ratios',
+      'Verify keyboard navigation order',
+    ],
+  };
+}
+```
+
+## Examples
+
+| Figma Property | CSS Equivalent | Tailwind Class |
+|----------------|---------------|----------------|
+| Auto-layout horizontal, gap 16 | `display: flex; gap: 16px` | `flex gap-4` |
+| Auto-layout vertical, center | `flex-direction: column; align-items: center` | `flex flex-col items-center` |
+| Fill container (horizontal) | `flex: 1 1 0%` | `flex-1` |
+| Hug contents | `width: fit-content` | `w-fit` |
+| Padding 16/24 | `padding: 16px 24px` | `py-4 px-6` |
+
+## Checklist
+- [ ] Design tokens extracted from Figma variables, not hardcoded from visual inspection
+- [ ] Auto-layout properties mapped to flexbox (not absolute positioning)
+- [ ] Component variants map to React prop types with TypeScript
+- [ ] Responsive layouts checked across all Figma breakpoint frames
+- [ ] Icons exported as SVG with `currentColor` fill for theming
+- [ ] Spacing values use token scale, not arbitrary pixel values
+- [ ] Interactive states (hover, focus, disabled) accounted for in component
+- [ ] Accessibility requirements documented from Figma annotations

package/assets/skills/file-upload.md

@@ -0,0 +1,228 @@
+---
+name: file-upload
+description: File upload patterns with multipart, presigned URLs, chunked upload, progress tracking, and validation.
+---
+
+# File Upload Patterns
+
+## When to Use
+Apply when users need to upload files -- profile pictures, documents, CSVs, or videos. Direct-to-cloud uploads via presigned URLs are the standard pattern. Never stream large files through your application server. Use chunked uploads for files over 100MB and always validate file type and size on both client and server.
+
+## How It Works
+
+### Presigned URL Upload (Direct to S3/R2)
+
+The client uploads directly to cloud storage, bypassing your server:
+
+```typescript
+import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+
+const s3 = new S3Client({ region: "us-east-1" });
+
+app.post("/api/upload/presign", async (req, res) => {
+  const { filename, contentType, size } = req.body;
+
+  const allowedTypes = ["image/jpeg", "image/png", "image/webp", "application/pdf"];
+  if (!allowedTypes.includes(contentType)) {
+    return res.status(400).json({ error: "File type not allowed" });
+  }
+  if (size > 10 * 1024 * 1024) {
+    return res.status(400).json({ error: "File too large (max 10MB)" });
+  }
+
+  const key = `uploads/${req.user.id}/${crypto.randomUUID()}-${sanitize(filename)}`;
+  const command = new PutObjectCommand({
+    Bucket: process.env.S3_BUCKET,
+    Key: key,
+    ContentType: contentType,
+    Metadata: { userId: req.user.id },
+  });
+
+  const url = await getSignedUrl(s3, command, { expiresIn: 300 });
+  res.json({ uploadUrl: url, key });
+});
+```
+
+Client-side upload:
+
+```typescript
+async function uploadFile(file: File) {
+  // 1. Get presigned URL
+  const { uploadUrl, key } = await api.post("/upload/presign", {
+    filename: file.name,
+    contentType: file.type,
+    size: file.size,
+  });
+
+  // 2. Upload directly to S3
+  await fetch(uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": file.type },
+    body: file,
+  });
+
+  // 3. Confirm upload with your API
+  await api.post("/upload/confirm", { key });
+  return key;
+}
+```
+
+### Chunked Upload for Large Files
+
+For files over 100MB, split into chunks with resume support:
+
+```typescript
+const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB
+
+async function chunkedUpload(
+  file: File,
+  onProgress: (percent: number) => void
+) {
+  const { uploadId, key } = await api.post("/upload/multipart/init", {
+    filename: file.name,
+    contentType: file.type,
+  });
+
+  const totalChunks = Math.ceil(file.size / CHUNK_SIZE);
+  const parts: { ETag: string; PartNumber: number }[] = [];
+  let completed = 0;
+
+  for (let partNumber = 1; partNumber <= totalChunks; partNumber++) {
+    const start = (partNumber - 1) * CHUNK_SIZE;
+    const chunk = file.slice(start, start + CHUNK_SIZE);
+
+    const { presignedUrl } = await api.post("/upload/multipart/presign", {
+      key, uploadId, partNumber,
+    });
+
+    const res = await fetch(presignedUrl, { method: "PUT", body: chunk });
+    parts.push({ ETag: res.headers.get("etag")!, PartNumber: partNumber });
+    completed++;
+    onProgress(Math.round((completed / totalChunks) * 100));
+  }
+
+  await api.post("/upload/multipart/complete", {
+    key, uploadId,
+    parts: parts.sort((a, b) => a.PartNumber - b.PartNumber),
+  });
+  return key;
+}
+```
+
+### Progress Tracking with XMLHttpRequest
+
+```typescript
+function uploadWithProgress(
+  url: string,
+  file: File,
+  onProgress: (percent: number) => void
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open("PUT", url);
+    xhr.setRequestHeader("Content-Type", file.type);
+
+    xhr.upload.onprogress = (e) => {
+      if (e.lengthComputable) {
+        onProgress(Math.round((e.loaded / e.total) * 100));
+      }
+    };
+    xhr.onload = () => (xhr.status < 400 ? resolve() : reject(new Error(`Upload failed: ${xhr.status}`)));
+    xhr.onerror = () => reject(new Error("Network error"));
+    xhr.send(file);
+  });
+}
+```
+
+### Image Processing After Upload
+
+```typescript
+import sharp from "sharp";
+
+const variants = [
+  { suffix: "thumb", width: 150, height: 150, quality: 80 },
+  { suffix: "medium", width: 600, height: 600, quality: 85 },
+  { suffix: "large", width: 1200, height: 1200, quality: 90 },
+];
+
+async function processImage(inputKey: string): Promise<Record<string, string>> {
+  const obj = await s3.getObject({ Bucket: BUCKET, Key: inputKey });
+  const buffer = Buffer.from(await obj.Body!.transformToByteArray());
+  const results: Record<string, string> = {};
+
+  for (const v of variants) {
+    const processed = await sharp(buffer)
+      .resize(v.width, v.height, { fit: "inside", withoutEnlargement: true })
+      .webp({ quality: v.quality })
+      .toBuffer();
+
+    const outputKey = inputKey.replace(/\.[^.]+$/, `-${v.suffix}.webp`);
+    await s3.putObject({
+      Bucket: BUCKET, Key: outputKey, Body: processed,
+      ContentType: "image/webp",
+      CacheControl: "public, max-age=31536000, immutable",
+    });
+    results[v.suffix] = outputKey;
+  }
+  return results;
+}
+```
+
+### File Validation
+
+```typescript
+// Server-side validation beyond content-type header
+import { fileTypeFromBuffer } from "file-type";
+
+async function validateUpload(key: string): Promise<{ valid: boolean; reason?: string }> {
+  const obj = await s3.getObject({ Bucket: BUCKET, Key: key });
+  const buffer = Buffer.from(await obj.Body!.transformToByteArray());
+
+  // Check actual file type (not just extension or Content-Type header)
+  const type = await fileTypeFromBuffer(buffer);
+  const allowed = ["image/jpeg", "image/png", "image/webp", "application/pdf"];
+
+  if (!type || !allowed.includes(type.mime)) {
+    return { valid: false, reason: `Disallowed file type: ${type?.mime ?? "unknown"}` };
+  }
+  return { valid: true };
+}
+```
+
+### Storage Quotas
+
+```typescript
+const STORAGE_LIMITS: Record<string, number> = {
+  free: 100 * 1024 * 1024,           // 100MB
+  pro: 10 * 1024 * 1024 * 1024,      // 10GB
+  enterprise: 100 * 1024 * 1024 * 1024, // 100GB
+};
+
+async function checkStorageQuota(userId: string, fileSize: number): Promise<boolean> {
+  const user = await db.users.findById(userId);
+  const usedBytes = await db.files.sumSize({ userId });
+  const limit = STORAGE_LIMITS[user.plan] ?? STORAGE_LIMITS.free;
+  return usedBytes + fileSize <= limit;
+}
+```
+
+## Examples
+
+| File Type | Upload Pattern | Processing |
+|-----------|---------------|------------|
+| Profile picture (< 5MB) | Single presigned PUT | Resize to 3 variants, WebP |
+| CSV import (< 50MB) | Single presigned PUT | Parse in background job |
+| Video (> 100MB) | Multipart chunked | Transcode in background |
+| PDF invoice | Presigned PUT + signed URL | Virus scan, no transform |
+| Bulk images (20 files) | Parallel presigned PUTs | Concurrent pipeline |
+
+## Checklist
+- [ ] Files upload directly to S3/R2 via presigned URLs
+- [ ] Presigned URLs expire within 5-15 minutes
+- [ ] File type validated against allowlist (magic bytes, not just extension)
+- [ ] File size enforced both client-side and server-side
+- [ ] Files over 100MB use multipart/chunked upload with resume
+- [ ] Images processed asynchronously (resize, compress, WebP)
+- [ ] Processed files set `Cache-Control: immutable` for CDN
+- [ ] Per-user storage quotas prevent abuse