figma-code-agent 1.0.0

package/skills/ref-layout/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: ref-layout
+description: "Reference: Interpret Figma Auto Layout properties and generate correct CSS Flexbox. Use this skill when the user has Figma Auto Layout JSON data (layoutMode, sizing modes, alignment, spacing, wrap, constraints) and needs the corresponding CSS Flexbox output with accurate sizing mode handling."
+---
+
+@knowledge/design-to-code-layout.md
+
+## Objective
+
+Interpret Figma Auto Layout properties from node data and produce correct, production-grade CSS Flexbox. This skill handles the full pipeline: container detection, flex direction, alignment mapping, sizing modes (FIXED/HUG/FILL), gap and padding, wrap mode, min/max constraints, absolute positioning, non-Auto-Layout frames, and responsive multi-frame merging.
+
+## Input
+
+The user provides Figma node data as `$ARGUMENTS`. This may be:
+
+- Raw Figma REST API JSON (a node or subtree with Auto Layout properties)
+- Extracted Auto Layout properties (layoutMode, primaryAxisAlignItems, counterAxisAlignItems, itemSpacing, padding, layoutSizingHorizontal, layoutSizingVertical, layoutWrap, etc.)
+- A description of the Figma Auto Layout configuration in plain language
+- A screenshot or paste of Figma's design panel showing layout settings
+
+If the input is incomplete, ask the user for the missing properties before generating CSS. At minimum you need: `layoutMode`, child sizing modes, and spacing.
+
+## Process
+
+Follow these steps in order. Consult `knowledge/design-to-code-layout.md` for all mapping tables and edge cases.
+
+### Step 1: Detect Container Type
+
+- Check if the node has `layoutMode` set to `HORIZONTAL` or `VERTICAL` (Auto Layout container).
+- If `layoutMode` is `NONE` or absent, treat as non-Auto-Layout frame. Use absolute positioning with constraints (see Section 7 of the layout knowledge module).
+- If the node is a `GROUP`, use absolute positioning with coordinate adjustment (subtract group position for child coordinates).
+
+### Step 2: Map Container Properties
+
+For Auto Layout containers, generate the base flex properties:
+
+- `layoutMode: HORIZONTAL` -> `display: flex; flex-direction: row;`
+- `layoutMode: VERTICAL` -> `display: flex; flex-direction: column;`
+- `primaryAxisAlignItems` -> `justify-content` (MIN/CENTER/MAX/SPACE_BETWEEN)
+- `counterAxisAlignItems` -> `align-items` (MIN/CENTER/MAX/BASELINE)
+- Container sizing: `primaryAxisSizingMode` and `counterAxisSizingMode` determine if the container itself has explicit dimensions or hugs content.
+
+### Step 3: Map Gap and Padding
+
+- `itemSpacing` -> CSS `gap` (NOT padding -- this is spacing BETWEEN children)
+- `counterAxisSpacing` -> only applies when `layoutWrap: WRAP`. Maps to `row-gap` or `column-gap` depending on direction.
+- When both primary and counter gaps are equal, use `gap` shorthand. When different, use separate `row-gap` and `column-gap`.
+- `paddingTop/Right/Bottom/Left` -> CSS `padding` with shorthand optimization.
+- If any spacing or padding value has a variable binding, generate `var()` reference. External library variables get pixel fallbacks.
+
+### Step 4: Handle Sizing Modes (CRITICAL)
+
+This is the most error-prone step. For EACH child in the Auto Layout parent:
+
+1. Determine which axis is PRIMARY (same as parent flex-direction) and which is COUNTER.
+   - Parent `HORIZONTAL` -> horizontal = primary, vertical = counter
+   - Parent `VERTICAL` -> vertical = primary, horizontal = counter
+
+2. PRIMARY AXIS sizing:
+   - `FILL` -> `flex-grow: 1; flex-basis: 0;` (BOTH required -- never omit `flex-basis: 0`)
+   - `FIXED` -> `flex-shrink: 0;` + explicit dimension from bounds
+   - `HUG` -> omit sizing CSS, let content determine size
+
+3. COUNTER AXIS sizing:
+   - `FILL` -> `align-self: stretch;`
+   - `FILL` + max constraint on counter dimension -> `width: 100%` / `height: 100%` + `max-width`/`max-height` (NOT `align-self: stretch`)
+   - `FIXED` -> explicit dimension from bounds
+   - `HUG` -> omit, let content determine size
+
+4. Check for `layoutAlign` overrides on individual children -> `align-self`
+
+### Step 5: Handle Wrap Mode
+
+- `layoutWrap: WRAP` -> `flex-wrap: wrap;`
+- `counterAxisAlignContent` -> `align-content` (AUTO -> `flex-start`, SPACE_BETWEEN -> `space-between`)
+- Counter axis gap becomes relevant only in wrap mode.
+
+### Step 6: Handle Min/Max Constraints
+
+- `minWidth` (if > 0) -> `min-width`
+- `maxWidth` (if < Infinity) -> `max-width`
+- `minHeight` (if > 0) -> `min-height`
+- `maxHeight` (if < Infinity) -> `max-height`
+- These apply to both containers and children.
+
+### Step 7: Handle Absolute Children
+
+- If any child has `layoutPositioning: ABSOLUTE`, add `position: relative` to the parent.
+- Absolute children get `position: absolute` with offset values from constraints.
+- These children do not participate in flex flow or gap distribution.
+
+### Step 8: Responsive Multi-Frame (if applicable)
+
+If multiple frames represent breakpoints (detected via `#mobile`/`#tablet`/`#desktop` suffix or variant properties):
+
+- Smallest frame provides base styles (no media query).
+- Larger frames contribute override styles in `@media (min-width: ...)` blocks.
+- Only emit properties that differ from the base.
+- Reset layout properties (`align-self: auto`, `flex-grow: 0`, `flex-shrink: 1`, `flex-basis: auto`) when they exist in base but not in the larger breakpoint.
+- Transform fixed pixel widths in responsive overrides to `width: 100%; max-width: Npx` for fluid behavior.
+
+## Output
+
+Generate CSS with explanatory comments showing the Figma-to-CSS mapping:
+
+```css
+/* Container: layoutMode=HORIZONTAL, primaryAxis=SPACE_BETWEEN, counterAxis=CENTER */
+.component-name {
+  display: flex;
+  flex-direction: row;
+  justify-content: space-between;
+  align-items: center;
+  gap: 16px;              /* itemSpacing: 16 */
+  padding: 24px 16px;     /* paddingTop/Bottom: 24, paddingLeft/Right: 16 */
+}
+
+/* Child: sizingH=FILL (primary), sizingV=HUG (counter) */
+.component-name__content {
+  flex-grow: 1;
+  flex-basis: 0;
+}
+
+/* Child: sizingH=FIXED (primary, 200px), sizingV=FILL (counter) */
+.component-name__sidebar {
+  width: 200px;
+  flex-shrink: 0;
+  align-self: stretch;
+}
+```
+
+When variable bindings are present, use CSS custom properties:
+
+```css
+.component-name {
+  gap: var(--spacing-md);           /* Variable: spacing/md */
+  padding: var(--spacing-lg, 24px); /* External variable with fallback */
+}
+```
+
+### Output Checklist
+
+Before returning CSS, verify:
+
+- [ ] Every FILL on primary axis has BOTH `flex-grow: 1` AND `flex-basis: 0`
+- [ ] STRETCH only appears on counter axis (never primary)
+- [ ] `itemSpacing` maps to `gap`, not padding
+- [ ] GROUP children use absolute positioning with adjusted coordinates
+- [ ] FILL counter-axis + max constraint uses `width: 100%`/`height: 100%` instead of `align-self: stretch`
+- [ ] Responsive overrides include layout property resets where needed
+- [ ] Variable references use `var()` with fallbacks for external library variables

package/skills/ref-payload-block/SKILL.md

@@ -0,0 +1,415 @@
+---
+name: ref-payload-block
+description: "Reference: Map a Figma component to a PayloadCMS block definition with config, renderer, types, and CSS Module. Use this skill when the user has a Figma component (JSON data, component description, or REST API node) and needs a complete PayloadCMS block implementation following the container-first architecture."
+---
+
+@knowledge/payload-blocks.md
+@knowledge/payload-figma-mapping.md
+@knowledge/payload-visual-builder.md
+@knowledge/css-strategy.md
+
+## Objective
+
+Map a Figma component to a complete PayloadCMS block implementation: a block config (`.ts`), a React renderer (`.tsx`), TypeScript types, and a CSS Module (`.module.css`). The skill uses multi-signal confidence scoring to identify the correct block type from the 18-type catalog, maps component properties to PayloadCMS fields, generates container nesting rules, and produces CSS that follows the three-layer architecture (Tailwind layout + CSS Custom Properties tokens + CSS Modules visual skin).
+
+## Input
+
+The user provides Figma component data as `$ARGUMENTS`. This may be:
+
+- **Figma REST API JSON** -- A component or component set node with properties, variants, children, fills, text content
+- **Plugin API extracted data** -- Component properties, variant details, child nodes
+- **Component description** -- Plain language description of the Figma component (structure, properties, variants, content)
+- **Screenshot or design spec** -- Visual reference of the component with noted properties
+
+If the input is insufficient, ask for:
+- Component name and variant properties
+- Child element structure (text nodes, images, buttons, nested components)
+- Layout mode (Auto Layout direction, spacing, padding)
+- Visual properties (colors, border radius, shadows)
+
+## Process
+
+Follow these steps in order. Consult the referenced knowledge modules for all mapping rules, field types, and architectural patterns.
+
+### Step 1: Analyze Figma Component Structure
+
+Identify the component's structure and classify its elements:
+
+- **Root node**: component boundary, layout mode (Auto Layout direction), dimensions
+- **Variant properties**: boolean toggles, enum options (size, style, impact level)
+- **Text layers**: heading text, body text, labels, captions
+- **Image fills/frames**: background images, thumbnails, avatars, icons
+- **Interactive children**: button instances, link text, form inputs
+- **Nested component instances**: child components that may map to separate blocks
+- **Layout structure**: spacing, padding, alignment, wrap mode
+- **Visual properties**: fills, strokes, effects, corner radius
+
+### Step 2: Determine Block Type via Confidence Scoring
+
+Consult `knowledge/payload-figma-mapping.md` Section 2 for the complete decision tree.
+
+Apply multi-signal confidence scoring using two complementary strategies:
+
+**Name-based detection (higher priority):**
+- Check if component/frame name contains recognized keywords: hero, card, button, nav, accordion, tabs, stat, testimonial, carousel, cta, media, video, form, etc.
+
+**Structure-based detection (fallback for generic names):**
+- Analyze children, dimensions, properties, and layout patterns against block type heuristics
+
+**18-type block catalog:**
+
+| Block Type | Slug | Key Signals |
+|-----------|------|-------------|
+| Hero | `hero` | Full-width, bg image/color, large heading, CTA buttons |
+| Card | `card` | Bounded width, image + heading + body, optional CTA, radius/shadow |
+| Button | `button` | Small dimensions, bg fill, single text label, radius |
+| Navigation | `subnavigation` | Horizontal layout, multiple link children, compact |
+| Accordion | `accordion` | Vertical layout, repeating header + content, toggle icon |
+| Tabs | `tabs` | Tab bar + content panel, active/inactive states |
+| Stats | `stats` | Large numeric text, label below, compact |
+| Testimonial | `testimonial` | Quote text, author info, optional avatar |
+| Carousel | `carousel` | Horizontal overflow, nav dots/arrows, card children |
+| CallToAction | `callToAction` | Full-width, strong background, title + description |
+| Media | `media` | Single image, no text children |
+| Video | `video` | Play button overlay, 16:9 ratio, thumbnail |
+| Form | `form` | Input fields, submit button, labels |
+| RichText | `richText` | Primarily text content, styled segments |
+| Container | `container` | Auto Layout wrapper containing block-type children |
+| Grid | `grid` | Grid-like child layout, uniform child sizes |
+| Code | `code` | Code/monospace content |
+| StickyCTA | `stickyCTA` | Fixed/sticky positioning, compact CTA |
+
+**Confidence thresholds:**
+- 0.9+ -- Auto-map, high confidence
+- 0.8-0.89 -- Auto-map, flag for optional review
+- 0.7-0.79 -- Moderate confidence, flag for human review
+- Below 0.7 -- Require human confirmation
+
+Report the matched block type and confidence score to the user.
+
+### Step 3: Map Component Properties to Block Fields
+
+Consult `knowledge/payload-figma-mapping.md` Section 3 and `knowledge/payload-blocks.md` Section 2.
+
+Apply these property-to-field mapping rules:
+
+| Figma Property Type | PayloadCMS Field Type | Mapping Rule |
+|--------------------|----------------------|--------------|
+| Text layer (heading) | `richText` (Lexical) | Extract text content into Lexical document structure |
+| Text layer (single line) | `text` | Direct string mapping |
+| Boolean variant | `checkbox` | `true`/`false` toggle |
+| Enum variant (2-4 options) | `radio` | Radio buttons with variant option values |
+| Enum variant (5+ options) | `select` | Dropdown with variant option values |
+| Instance swap slot | `relationship` or `blocks` | Reference to another block type or media |
+| Image fill / image frame | `upload` with `relationTo: 'media'` | Image upload field via `imageFields` factory |
+| Color property | Token reference | Map to CSS Custom Property, not a hardcoded color field |
+| Number property | `number` | Numeric input for dimensions, counts |
+| URL/link text | `group` with link fields | Link group factory (type, url, label, newTab) |
+| Button instance(s) | `array` of link groups | Button/CTA array using `linkGroup` factory |
+
+**Field organization follows tab-based pattern:**
+1. **Content tab** (named `content`): richText, text fields, arrays of content items
+2. **Media/Image tab**: image upload fields via `imageFields` factory
+3. **CTA tab**: button/link groups when the block has call-to-action elements
+4. **Settings tab** (unnamed): className, layoutMeta, type/variant selection, HTML tag
+
+### Step 4: Map Variants to CVA Configuration
+
+If the component has enum variants that affect visual presentation (e.g., size: sm/md/lg, style: primary/secondary, impact: high/medium/low):
+
+- Map variant property name to block settings field (radio or select)
+- Generate CVA (class-variance-authority) configuration for the renderer:
+
+```typescript
+import { cva } from 'class-variance-authority';
+
+const heroVariants = cva(styles.hero, {
+  variants: {
+    type: {
+      highImpact: styles['hero--high-impact'],
+      mediumImpact: styles['hero--medium-impact'],
+      lowImpact: styles['hero--low-impact'],
+    },
+  },
+  defaultVariants: {
+    type: 'highImpact',
+  },
+});
+```
+
+### Step 5: Handle Container Nesting
+
+Consult `knowledge/payload-blocks.md` and `knowledge/payload-figma-mapping.md` Section 4.
+
+**Maximum nesting: 2 levels** (Container > NestedContainer).
+
+- If the Figma component contains structural wrappers around other block-type children, map outer wrapper to `Container` and inner wrappers to a restricted nested container.
+- Container block uses the `blocks` field type to hold child blocks.
+- Map Figma Auto Layout properties to Container settings:
+  - `layoutMode: HORIZONTAL` --> `settings.layout = 'row'`
+  - `layoutMode: VERTICAL` --> `settings.layout = 'col'`
+  - `primaryAxisAlignItems` --> `settings.justifyContent` (Tailwind utility string)
+  - `counterAxisAlignItems` --> `settings.alignItems` (Tailwind utility string)
+  - `itemSpacing` --> `settings.gap` (snap to nearest option)
+- Settings are stored as Tailwind utility class strings (Layer 1 of CSS architecture).
+
+**Nesting rules:**
+- Container (level 1) can contain any block type including NestedContainer
+- NestedContainer (level 2) can contain content blocks but NOT another container
+- Never nest deeper than 2 levels -- flatten if the Figma structure goes deeper
+
+### Step 6: Configure Lexical Rich Text
+
+Consult `knowledge/payload-blocks.md` for Lexical configuration patterns.
+
+Restrict Lexical editor features based on block type:
+
+| Block Type | Lexical Features Allowed |
+|-----------|------------------------|
+| Hero | Heading (h1-h2), paragraph, bold, italic, link, text color |
+| Card | Heading (h3-h4), paragraph, bold, italic, link |
+| RichText | Full feature set (all headings, lists, blockquote, code, media) |
+| Button | None (use `text` field, not richText) |
+| Stats | Heading (h2-h3), paragraph, bold |
+| Testimonial | Paragraph, bold, italic |
+| CallToAction | Heading (h2-h3), paragraph, bold, italic, link |
+| Default | Paragraph, bold, italic, link |
+
+### Step 7: Generate Block Config
+
+Produce the PayloadCMS block config `.ts` file:
+
+```typescript
+import { Block } from 'payload';
+import { imageFields } from '@/admin/fields/imageFields';
+import { linkGroup } from '@/admin/fields/linkGroup';
+import { settingTabs } from './settingTabs';
+
+export const Hero: Block = {
+  slug: 'hero',
+  labels: {
+    singular: 'Hero',
+    plural: 'Heroes',
+  },
+  fields: [
+    {
+      type: 'tabs',
+      tabs: [
+        {
+          label: 'Content',
+          name: 'content',
+          fields: [
+            {
+              name: 'richText',
+              type: 'richText',
+              label: false,
+              // Lexical config with restricted features
+            },
+            ...linkGroup({ appearances: ['default', 'outline'] }),
+          ],
+        },
+        {
+          label: 'Media',
+          fields: [...imageFields()],
+        },
+        settingTabs,
+      ],
+    },
+  ],
+};
+```
+
+**Config conventions:**
+- Export as named constant matching block name (PascalCase)
+- Use `slug` in camelCase
+- Organize fields in tabs (Content, Media, CTA, Settings)
+- Use field factories (`imageFields`, `linkGroup`, `layoutMeta`) for reusable patterns
+- Settings tab fields are stored at block root (no `name` on the tab)
+
+### Step 8: Generate React Renderer
+
+Produce the renderer `.tsx` file:
+
+```tsx
+import React from 'react';
+import styles from './Hero.module.css';
+import { RichText } from '@/components/RichText';
+import { Media } from '@/components/Media';
+import { CMSLink } from '@/components/Link';
+import type { HeroBlock } from './types';
+
+export function HeroRenderer({ block }: { block: HeroBlock }) {
+  const { content, image, settings } = block;
+
+  return (
+    <section
+      className={`flex flex-col items-center justify-center gap-6 p-8 ${styles.hero} ${styles[`hero--${settings?.type}`] || ''}`}
+    >
+      {image?.image && (
+        <div className={`absolute inset-0 ${styles.hero__media}`}>
+          <Media resource={image.image} fill />
+        </div>
+      )}
+      <div className={`relative z-10 flex flex-col items-center gap-4 ${styles.hero__content}`}>
+        {content?.richText && <RichText data={content.richText} />}
+        {content?.buttonGroup?.length > 0 && (
+          <div className="flex gap-4">
+            {content.buttonGroup.map((btn, i) => (
+              <CMSLink key={i} {...btn.link} />
+            ))}
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}
+```
+
+**Renderer conventions:**
+- Named export (not default) with `{BlockName}Renderer` naming
+- Tailwind classes for layout (Layer 1)
+- CSS Module classes for visual styling (Layer 3)
+- CSS Custom Properties consumed via CSS Module (Layer 2)
+- Null-safe access for all optional fields
+- Semantic HTML elements based on block type
+
+### Step 9: Generate CSS Module
+
+Produce the `.module.css` file following the three-layer architecture:
+
+```css
+/* Hero Block — Visual Skin (Layer 3) */
+/* Layout handled by Tailwind in JSX */
+/* Tokens consumed from tokens.css (Layer 2) */
+
+.hero {
+  background-color: var(--color-surface);
+  min-height: 60vh;
+  position: relative;
+  overflow: hidden;
+}
+
+.hero--highImpact {
+  min-height: 80vh;
+}
+
+.hero--mediumImpact {
+  min-height: 60vh;
+}
+
+.hero--lowImpact {
+  min-height: 40vh;
+}
+
+.hero__media {
+  opacity: 0.3;
+}
+
+.hero__content {
+  max-width: 48rem;
+  text-align: center;
+}
+
+.hero__content h1,
+.hero__content h2 {
+  color: var(--color-text-primary);
+  font-family: var(--font-heading);
+}
+
+.hero__content p {
+  color: var(--color-text-secondary);
+  font-size: var(--text-lg);
+}
+```
+
+**CSS Module rules:**
+- Only visual properties (colors, backgrounds, borders, effects, typography skin)
+- All color values via `var()` references to CSS Custom Properties (never hardcoded)
+- BEM-style naming within the module (flat: `.block__element`, never `.block__element__sub`)
+- Variant modifiers as `.block--variant` classes
+- Layout (flexbox, gap, padding, sizing) stays in Tailwind classes in JSX
+
+### Step 10: Generate TypeScript Types
+
+```typescript
+import type { Media as MediaType } from '@/payload-types';
+
+export interface HeroBlock {
+  blockType: 'hero';
+  content?: {
+    richText?: any; // Lexical root node
+    buttonGroup?: Array<{
+      link: {
+        type: 'reference' | 'custom';
+        url?: string;
+        reference?: { relationTo: 'pages'; value: string };
+        label: string;
+        newTab?: boolean;
+        appearance?: 'default' | 'outline';
+      };
+    }>;
+  };
+  image?: {
+    image?: string | MediaType;
+  };
+  settings?: {
+    type?: 'highImpact' | 'mediumImpact' | 'lowImpact';
+    className?: string;
+    layoutMeta?: {
+      marginTop?: string;
+      marginBottom?: string;
+      paddingTop?: string;
+      paddingBottom?: string;
+    };
+  };
+}
+```
+
+## Output
+
+Generate four files for the mapped block:
+
+### 1. `config.ts` -- PayloadCMS Block Definition
+
+- Block slug, labels, tab-based field organization
+- Field factories for reusable patterns (imageFields, linkGroup, layoutMeta)
+- Lexical editor restricted per block type
+- Settings fields with variant options stored as Tailwind utility strings
+
+### 2. `Renderer.tsx` -- React Renderer Component
+
+- Named export with `{BlockName}Renderer` naming
+- Tailwind layout classes in JSX (Layer 1)
+- CSS Module visual classes from companion `.module.css` (Layer 3)
+- Null-safe field access
+- Semantic HTML elements
+
+### 3. `{BlockName}.module.css` -- CSS Module
+
+- Visual skin only (colors, backgrounds, effects, typography overrides)
+- All values via `var()` CSS Custom Property references (Layer 2)
+- BEM naming (flat hierarchy, no deep nesting)
+- Variant modifier classes
+
+### 4. `types.ts` -- TypeScript Interfaces
+
+- Block interface with `blockType` discriminant
+- Optional fields for all non-required content
+- Proper Media and reference types
+
+### Output Checklist
+
+Before returning the block implementation, verify:
+
+- [ ] Block type matches with stated confidence score
+- [ ] Container nesting does not exceed 2 levels
+- [ ] Settings fields use Tailwind utility class strings (not raw CSS values)
+- [ ] Lexical editor features are restricted appropriately for the block type
+- [ ] Field factories are used for reusable patterns (not duplicated field definitions)
+- [ ] CSS Module contains only visual properties (no layout)
+- [ ] All color values use `var()` references (no hardcoded colors)
+- [ ] BEM class names are flat (never `block__element__sub`)
+- [ ] Renderer handles null/undefined for all optional fields
+- [ ] Tab organization follows convention: Content, Media, CTA, Settings
+- [ ] Block slug is camelCase and unique
+- [ ] Variant mapping uses CVA pattern when applicable