@relipa/ai-flow-kit 0.1.0 → 0.1.1

package/custom/skills/figma-to-component/SKILL.md

@@ -1,207 +1,399 @@
----
-name: figma-to-component
-description: Read designs from Figma and generate React/Next.js/Vue components following project conventions. Supports specific frame URLs and entire pages.
-keywords: figma, design, component, ui, generate, react, nextjs, vue, frontend
----
-
-# Figma to Component
-
-## When to use
-
-- Received a Figma link from a designer and need to generate a component
-- Designer has approved the UI, developer starts implementation
-- Need to ensure pixel-perfect matching with the design
-
----
-
-## Process
-
-### Step 1: Identify input
-
-Receive one of the following from the user:
-- Figma URL frame: `https://www.figma.com/design/<fileKey>/...?node-id=<nodeId>`
-- Figma URL file: `https://www.figma.com/design/<fileKey>/...`
-- Node description: "UserCard component in file ABC"
-
-Extract `fileKey` and `nodeId` from the URL.
-
-### Step 2: Read design via Figma MCP
-
-Use Figma MCP tools to fetch design information:
-
-```
-1. Get node info: figma_get_file_nodes(fileKey, nodeIds=[nodeId])
-2. Get styles: figma_get_file_styles(fileKey)
-3. Get components: figma_get_file_components(fileKey) if needed
-4. Export image if visual reference needed: figma_get_image(fileKey, nodeId)
-```
-
-Analyze the output to extract:
-- **Layout**: flexbox direction, gap, padding, alignment
-- **Sizing**: width/height (fixed vs fill vs hug)
-- **Colors**: fills, strokes → map to Tailwind colors if available
-- **Typography**: font-size, font-weight, line-height, letter-spacing → map to Tailwind text classes
-- **Spacing**: padding, margin, gap → map to Tailwind spacing scale
-- **Border**: radius, width, color → map to Tailwind border classes
-- **Shadow**: box-shadow → map to Tailwind shadow classes
-- **States**: hover, focus, disabled, active (if variants present)
-- **Responsive**: breakpoints if multiple frames present
-
-### Step 3: Map Figma tokens → Tailwind / CSS
-
-**Color mapping:**
-```
-Figma hex #3B82F6 → Tailwind blue-500
-Figma hex #EF4444 → Tailwind red-500
-Figma rgba(0,0,0,0.5) → Tailwind black/50
-No Tailwind match → use arbitrary value [#hexcode]
-```
-
-**Spacing mapping (8px grid):**
-```
-4px  → p-1 / gap-1
-8px  → p-2 / gap-2
-12px → p-3 / gap-3
-16px → p-4 / gap-4
-24px → p-6 / gap-6
-32px → p-8 / gap-8
-No match → arbitrary value [20px]
-```
-
-**Typography mapping:**
-```
-text-xs: 12px
-text-sm: 14px
-text-base: 16px
-text-lg: 18px
-text-xl: 20px
-text-2xl: 24px
-text-3xl: 30px
-font-normal: 400
-font-medium: 500
-font-semibold: 600
-font-bold: 700
-```
-
-### Step 4: Generate component
-
-**Framework detection** — check the project's CLAUDE.md to determine the framework:
-- `reactjs` / `nextjs` → generate `.tsx` with React conventions
-- `vue-nuxt` → generate `.vue` with Vue 3 Composition API
-
-#### React/Next.js component template:
-
-```tsx
-interface [ComponentName]Props {
-  // Props extracted from Figma variants or dynamic content slots
-  className?: string;
-}
-
-export const [ComponentName] = ({ className }: [ComponentName]Props) => {
-  return (
-    <div className={cn(
-      // Layout classes
-      // Sizing classes
-      // Color classes
-      // Typography classes (if text node)
-      className
-    )}>
-      {/* Child nodes rendered recursively */}
-    </div>
-  );
-};
-```
-
-#### Vue 3 component template:
-
-```vue
-<script setup lang="ts">
-interface Props {
-  // Props extracted from Figma variants
-  class?: string;
-}
-
-const props = withDefaults(defineProps<Props>(), {});
-</script>
-
-<template>
-  <div :class="cn(
-    // Layout classes
-    // Sizing classes
-    // Color classes
-    props.class
-  )">
-    <!-- Child nodes -->
-  </div>
-</template>
-```
-
-### Step 5: Handle interactive states
-
-If Figma has variants (Default, Hover, Disabled, Active):
-
-```tsx
-// Map variants into props + conditional classes
-interface ButtonProps {
-  variant?: 'primary' | 'secondary' | 'outline';
-  size?: 'sm' | 'md' | 'lg';
-  disabled?: boolean;
-}
-
-const variantClasses = {
-  primary: 'bg-blue-600 text-white hover:bg-blue-700',
-  secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
-  outline: 'border border-gray-300 hover:bg-gray-50',
-};
-```
-
-### Step 6: Verify and output
-
-After generation, verify:
-
-- [ ] Layout matches Figma (flex direction, alignment, gap)
-- [ ] Colors mapping correct (or use arbitrary values if no Tailwind match)
-- [ ] Typography correct (size, weight, line-height)
-- [ ] Spacing correct (padding, margin, gap)
-- [ ] Component has `className` prop for external overrides
-- [ ] Use `cn()` helper for conditional/mergeable classes
-- [ ] Responsive if Figma has mobile frames
-- [ ] Props typed with TypeScript interface
-
----
-
-## Output format
-
-Always output in order:
-
-1. **Design Summary** (brief): layout structure, color palette, typography scale
-2. **Component file** with full code
-3. **Usage example**:
-   ```tsx
-   <ComponentName variant="primary" className="mt-4" />
-   ```
-4. **Notes** if anything cannot be mapped 100% accurately from Figma
-
----
-
-## Rules
-
-- **Do not hardcode** hex colors directly into className if a Tailwind equivalent exists
-- **Always use** `cn()` (clsx + twMerge) to merge classes
-- **No new CSS imports** — use Tailwind utilities only
-- **Responsive** — if Figma only has 1 breakpoint, default to mobile-first design
-- **Accessibility** — add `aria-label`, `role`, `alt` for interactive and image elements
-- **Image** — use `next/image` for Next.js, `<img>` for React, add `alt` from Figma layer name
-- **Icon** — if Figma uses SVG icons, extract SVG or map to lucide-react / heroicons
-
----
-
-## Trigger Example Commands
-
-```
-Read Figma and generate component: https://www.figma.com/design/xxxxx/App?node-id=123-456
-
-Generate UserCard component from Figma frame node-id=123-456
-
-Implement UI from this Figma link following my project: [URL]
-```
+---
+name: figma-to-component
+description: Read designs from Figma and generate React/Next.js App Router/Vue/Angular components following project conventions. Supports specific frame URLs and entire pages.
+keywords: figma, design, component, ui, generate, react, nextjs, nextjs-app-router, vue, angular, frontend
+---
+
+# Figma to Component
+
+## When to use
+
+- Received a Figma link from a designer and need to generate a component
+- Designer has approved the UI, developer starts implementation
+- Need to ensure pixel-perfect matching with the design
+
+---
+
+## Step 0: Verify Figma MCP is available
+
+Before doing anything, confirm the Figma MCP server is connected in this session:
+
+- The tool `mcp__figma__get_figma_data` (and `mcp__figma__download_figma_images`) must be available.
+- If it is **not** available, STOP and tell the developer:
+  > Figma MCP not connected. Run `aiflow init -a figma` (REST API token) or
+  > `aiflow init -a figma-desktop` (Figma Desktop), then restart the session.
+
+Do not guess design values from the URL — without the MCP server the skill cannot read the design.
+
+---
+
+## Process
+
+### Step 1: Identify input
+
+Receive one of the following from the user:
+- Figma URL frame: `https://www.figma.com/design/<fileKey>/...?node-id=<nodeId>`
+- Figma URL file: `https://www.figma.com/design/<fileKey>/...`
+- Node description: "UserCard component in file ABC"
+
+Extract `fileKey` and `nodeId` from the URL.
+
+### Step 2: Read design via Figma MCP
+
+Use Figma MCP tools to fetch design information:
+
+```
+1. Get node info, styles, and components in one call:
+   get_figma_data(fileKey, nodeId, depth=2)
+
+2. Export image if visual reference needed:
+   download_figma_images(fileKey, nodes=[{ nodeId, fileName }], localPath)
+```
+
+Note: `get_figma_data` returns layout, fills, strokes, typography, and component
+definitions in a single response. No separate style or component fetch is needed.
+
+Analyze the output to extract:
+- **Layout**: flexbox direction, gap, padding, alignment
+- **Sizing**: width/height (fixed vs fill vs hug)
+- **Colors**: fills, strokes → map to project CSS tokens / Tailwind colors if available
+- **Typography**: font-size, font-weight, line-height, letter-spacing
+- **Spacing**: padding, margin, gap
+- **Border**: radius, width, color
+- **Shadow**: box-shadow
+- **States**: hover, focus, disabled, active (if variants present)
+- **Responsive**: breakpoints if multiple frames present
+
+### Step 2.5: Image Detection & Export
+
+After receiving node data from Step 2, scan the entire node tree to detect image nodes:
+
+**Detect image nodes:**
+- Node has a `fills` array containing at least 1 fill with `type === "IMAGE"` → this is an image node
+- Node is a frame/group containing many complex layers (icon, illustration, banner) that cannot be recreated with CSS → needs image export
+- Node has `type === "VECTOR"` or `type === "BOOLEAN_OPERATION"` → always export as SVG/PNG
+
+**Export images via MCP:**
+
+For each detected image node, call MCP tool `download_figma_images`:
+
+```
+download_figma_images({
+  fileKey: "<fileKey>",
+  nodes: [
+    { nodeId: "<nodeId>", fileName: "<layerName-nodeId>.png" }
+  ],
+  localPath: "public/assets/figma/"
+})
+```
+
+- `localPath` defaults to `public/assets/figma/` (relative to the project root)
+- `fileName` follows the pattern: `<layer name in lowercase, spaces replaced with ->-<nodeId>.png`
+  - Example: layer "Banner Top" with nodeId "123-456" → `banner-top-123-456.png`
+- If MCP does not support `download_figma_images`, get the image URL via `get_figma_data`, then notify DEV to download manually and place in `public/assets/figma/`
+
+**Record the result:**
+
+After export, save the mapping for use in Step 4:
+
+```
+imageMap = {
+  "123-456": "public/assets/figma/banner-top-123-456.png",
+  "789-012": "public/assets/figma/icon-star-789-012.png"
+}
+```
+
+### Step 3: Detect CSS tooling, then map Figma tokens
+
+**Detect the project's styling approach first** (do not assume Tailwind):
+
+1. `tailwind.config.*` present → **Tailwind** — map to utility classes; extend `tailwind.config` with design tokens when a value has no built-in match
+2. `*.module.css` / `*.module.scss` files present → **CSS Modules** — emit a co-located `.module.css` and reference `styles.x`
+3. `styled-components` / `@emotion` in `package.json` → **CSS-in-JS** — emit styled components
+4. None of the above → **vanilla CSS** — emit a co-located `.css` file with CSS custom properties
+
+**Design tokens:** prefer mapping Figma Styles/Variables to existing project tokens
+(Tailwind theme keys or CSS custom properties) instead of hardcoding hex/px values.
+Only fall back to an arbitrary value when no token matches.
+
+**Tailwind reference mappings** (when Tailwind is the detected tooling):
+
+```
+Color:   #3B82F6 → blue-500 · #EF4444 → red-500 · rgba(0,0,0,0.5) → black/50
+         no match → arbitrary value [#hexcode]
+Spacing: 4→p-1/gap-1 · 8→p-2 · 12→p-3 · 16→p-4 · 24→p-6 · 32→p-8 (8px grid)
+         no match → arbitrary value [20px]
+Type:    12→text-xs · 14→text-sm · 16→text-base · 18→text-lg · 20→text-xl · 24→text-2xl · 30→text-3xl
+         400→font-normal · 500→font-medium · 600→font-semibold · 700→font-bold
+```
+
+### Step 4: Generate component
+
+**Framework detection** — check in this order:
+
+1. Read project's `CLAUDE.md` for framework identifier:
+   - `nextjs-app-router` → Next.js App Router (Server/Client Components)
+   - `reactjs` / `nextjs` → React / Next.js Pages Router `.tsx`
+   - `vue-nuxt` → Vue 3 `.vue` with Composition API
+   - `angular` → Angular `@Component` class
+2. Scan project files if CLAUDE.md is ambiguous:
+   - `app/` directory present → `nextjs-app-router`
+   - `angular.json` present → `angular`
+   - `nuxt.config.*` present → `vue-nuxt`
+3. Fallback → `nextjs` (React Pages Router)
+
+**Image node rendering rule:**
+
+Before rendering each node, check `imageMap` from Step 2.5:
+- If `nodeId` is in `imageMap` → render using `<img>` (React/Vue) or `<Image>` (Next.js), do NOT use CSS `background-image`
+- If not in `imageMap` → render normally using div + styling classes
+
+React/Next.js template for image node:
+```tsx
+{/* Image node — exported from Figma */}
+<img
+  src="/assets/figma/<fileName>.png"
+  alt="<layer name from Figma>"
+  width={<width from Figma>}
+  height={<height from Figma>}
+  className="<sizing classes if needed>"
+/>
+```
+
+Next.js with `next/image`:
+```tsx
+import Image from 'next/image';
+<Image
+  src="/assets/figma/<fileName>.png"
+  alt="<layer name from Figma>"
+  width={<width from Figma>}
+  height={<height from Figma>}
+/>
+```
+
+Vue 3 template for image node:
+```vue
+<img
+  src="/assets/figma/<fileName>.png"
+  :alt="'<layer name from Figma>'"
+  :width="<width from Figma>"
+  :height="<height from Figma>"
+/>
+```
+
+#### React/Next.js component template:
+
+```tsx
+interface [ComponentName]Props {
+  // Props extracted from Figma variants or dynamic content slots
+  className?: string;
+}
+
+export const [ComponentName] = ({ className }: [ComponentName]Props) => {
+  return (
+    <div className={cn(
+      // Layout classes
+      // Sizing classes
+      // Color classes
+      // Typography classes (if text node)
+      className
+    )}>
+      {/* Child nodes rendered recursively */}
+    </div>
+  );
+};
+```
+
+#### Next.js App Router component template:
+
+Default to **Server Component**. Add `'use client'` only when the design has
+interactive states (hover effects, click handlers, form inputs, modals).
+
+```tsx
+// Server Component — no interactivity (default)
+interface [ComponentName]Props {
+  className?: string;
+}
+
+export default async function [ComponentName]({ className }: [ComponentName]Props) {
+  return (
+    <div className={cn(
+      // Layout classes
+      // Sizing classes
+      // Color classes
+      className
+    )}>
+      {/* Child nodes */}
+    </div>
+  );
+}
+```
+
+```tsx
+// Client Component — has onClick / useState / useEffect
+'use client'
+
+import { useState } from 'react'
+
+interface [ComponentName]Props {
+  className?: string;
+}
+
+export function [ComponentName]({ className }: [ComponentName]Props) {
+  return (
+    <div className={cn(
+      // Layout classes
+      // Sizing classes
+      // Color classes
+      className
+    )}>
+      {/* Child nodes */}
+    </div>
+  );
+}
+```
+
+File path: `app/components/[ComponentName].tsx` or `components/[ComponentName].tsx`
+
+#### Vue 3 component template:
+
+```vue
+<script setup lang="ts">
+interface Props {
+  // Props extracted from Figma variants
+  class?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {});
+</script>
+
+<template>
+  <div :class="cn(
+    // Layout classes
+    // Sizing classes
+    // Color classes
+    props.class
+  )">
+    <!-- Child nodes -->
+  </div>
+</template>
+```
+
+#### Angular component template:
+
+Use Tailwind classes if `tailwind.config.*` exists in the project root.
+Otherwise use `styles` array with CSS-in-component.
+
+```typescript
+import { Component, Input } from '@angular/core';
+import { CommonModule } from '@angular/common';
+
+@Component({
+  selector: 'app-[component-name]',
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <div [class]="hostClasses">
+      <!-- Child nodes -->
+    </div>
+  `,
+  styles: []
+})
+export class [ComponentName]Component {
+  @Input() className = '';
+
+  get hostClasses(): string {
+    return [
+      // Layout classes
+      // Sizing classes
+      // Color classes
+      this.className
+    ].filter(Boolean).join(' ');
+  }
+}
+```
+
+### Step 5: Handle interactive states
+
+If Figma has variants (Default, Hover, Disabled, Active):
+
+```tsx
+// Map variants into props + conditional classes
+interface ButtonProps {
+  variant?: 'primary' | 'secondary' | 'outline';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+}
+
+const variantClasses = {
+  primary: 'bg-blue-600 text-white hover:bg-blue-700',
+  secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
+  outline: 'border border-gray-300 hover:bg-gray-50',
+};
+```
+
+### Step 6: Verify and output
+
+After generation, verify:
+
+- [ ] Layout matches Figma (flex direction, alignment, gap)
+- [ ] Colors mapping correct (project tokens, or arbitrary values if no match)
+- [ ] Typography correct (size, weight, line-height)
+- [ ] Spacing correct (padding, margin, gap)
+- [ ] Component has `className` prop for external overrides
+- [ ] Conditional/mergeable classes use the project's helper (`cn()` for Tailwind)
+- [ ] Responsive if Figma has mobile frames
+- [ ] Props typed with TypeScript interface
+- [ ] Image nodes use `<img>` / `<Image>` (do not use CSS `background-image`)
+- [ ] Image files exist in `public/assets/figma/` before submitting code
+
+---
+
+## Output format
+
+Always output in order:
+
+1. **Design Summary** (brief): layout structure, color palette, typography scale
+2. **Component file** with full code
+3. **Usage example**:
+   ```tsx
+   <ComponentName variant="primary" className="mt-4" />
+   ```
+4. **Notes** if anything cannot be mapped 100% accurately from Figma
+
+---
+
+## Rules
+
+- **Detect styling tooling first** — do not assume Tailwind; honour CSS Modules / styled-components / vanilla CSS when detected
+- **Prefer design tokens** — map Figma Styles/Variables to project tokens; only hardcode a value when no token matches
+- **Always use** the project's class-merge helper (`cn()` = clsx + twMerge for Tailwind)
+- **Responsive** — if Figma only has 1 breakpoint, default to mobile-first design
+- **Accessibility** — add `aria-label`, `role`, `alt` for interactive and image elements
+- **Image** — detect image fills in Figma node data, export via `download_figma_images` MCP, save to `public/assets/figma/`. Use `<Image>` (Next.js) or `<img>` (React/Vue) with `src` pointing to the exported file. Do NOT use CSS `background-image` for image nodes.
+- **Icon** — if Figma uses SVG icons, extract SVG or map to lucide-react / heroicons
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `mcp__figma__get_figma_data` not available | Figma MCP server not connected | Run `aiflow init -a figma` or `-a figma-desktop`, restart session |
+| `403 Forbidden` / token rejected | PAT invalid or wrong header | Re-issue a `figd_...` token; `init` sends `X-Figma-Token` (not `Bearer`) |
+| Tool call hangs / times out | Large node tree (`depth` too high) | Lower `depth` (e.g. `depth=1`), target a specific `nodeId` not the whole file |
+| `404` on node | Wrong `fileKey`/`nodeId` | Re-copy the frame URL; node-id uses `-` in URL but `:` in API |
+| Empty fills / no styles | Node is a component instance | Fetch the main component, or increase `depth` |
+| `download_figma_images` unsupported | Older MCP preset | Get image URL via `get_figma_data`, download manually to `public/assets/figma/` |
+
+---
+
+## Trigger Example Commands
+
+```
+Read Figma and generate component: https://www.figma.com/design/xxxxx/App?node-id=123-456
+
+Generate UserCard component from Figma frame node-id=123-456
+
+Implement UI from this Figma link following my project: [URL]
+```