@relipa/ai-flow-kit 0.1.0-beta.0 → 0.1.1-beta.0

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

@@ -1,207 +1,294 @@
----
-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/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 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`, use `get_images` to get the URL, 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 = {
+  "<nodeId>": "public/assets/figma/<fileName>.png"
+}
+```
+
+Example:
+```
+imageMap = {
+  "123-456": "public/assets/figma/banner-top-123-456.png",
+  "789-012": "public/assets/figma/icon-star-789-012.png"
+}
+```
+
+### 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
+
+**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 + Tailwind 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>
+  );
+};
+```
+
+#### 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
+- [ ] Image nodes use `<img>` tag (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
+
+- **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** — 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
+
+---
+
+## 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]
+```