// Use when the user wants to turn a Figma design into SwiftUI code with TCA Store integration — building new screens, redesigning existing features, updating a screen to match a new design, or extracting reusable components. Trigger when the user shares a Figma URL (figma.com/design/...) or asks to implement, build, convert, update, or redesign a screen into SwiftUI, even if they just say "build this screen", "the design changed", "update this feature to match Figma", or paste a link without naming Figma explicitly. Also trigger for asset extraction, component decomposition, and design-to-code comparison tasks. Do NOT trigger for widget designs (use widget skill) or TCA features without a Figma link (use tca-feature skill).
Use when the user wants to turn a Figma design into SwiftUI code with TCA Store integration — building new screens, redesigning existing features, updating a screen to match a new design, or extracting reusable components. Trigger when the user shares a Figma URL (figma.com/design/...) or asks to implement, build, convert, update, or redesign a screen into SwiftUI, even if they just say "build this screen", "the design changed", "update this feature to match Figma", or paste a link without naming Figma explicitly. Also trigger for asset extraction, component decomposition, and design-to-code comparison tasks. Do NOT trigger for widget designs (use widget skill) or TCA features without a Figma link (use tca-feature skill).
argument-hint
<figma-url> <FeatureName>
compatibility
Requires Figma MCP server (claude.ai Figma) and macOS with sips for image scaling.
Read 2–3 existing View files — SwiftUI conventions: @Bindable vs let, background pattern, sub-view organization, font/button styles.
Catalog UIComponents (or shared UI module) — list every reusable component with its parameters.
Identify theme system — ColorPalette, Color extensions, design tokens, font conventions.
Catalog the Extensions target — check if an Extensions module exists in Package.swift with shared utilities like Color(hex:), custom modifiers, helper types. If it exists, import it (import Extensions) in generated code — NEVER duplicate these into feature targets. If it doesn't exist, create it as a new SPM target containing shared Swift extensions (e.g., Color+Hex.swift) and add it as a dependency to feature targets.
Catalog SharedResources — list all shared assets (fonts, common icons) already available via SharedResources.bundle to avoid duplicating into feature targets.
Catalog SharedComponents (if it exists) — list all shared UI components already available across features to avoid duplicating. Also scan ALL feature targets' Components/ directories and flag any duplicates (same-named files across different targets).
Check Swift concurrency settings — look for SWIFT_DEFAULT_ACTOR_ISOLATION and SWIFT_STRICT_CONCURRENCY in project.yml, project.base.yml, or Package.swift. If MainActor isolation or complete concurrency is enabled, generated code must use nonisolated where needed and @Sendable closures.
Check SharedResources for existing fonts — if PoppinsFont.swift or similar font helpers already exist, reuse them. Never create duplicate font registrations per feature.
Autonomous mode: When processing multiple screens in batch, CONFIRM gates in Phases 2-3 are skipped. See references/autonomous-mode.md.
Step 1: Extract the design
Use mcp__claude_ai_Figma__get_design_context with the extracted fileKey and nodeId. Also call mcp__claude_ai_Figma__get_screenshot for visual reference.
Handle node types: sections (extract child frame IDs, call individually), frames (process directly). See references/figma-extraction.md for full details.
Step 2: Determine scope
Use mcp__claude_ai_Figma__get_metadata dimensions:
Full screen (width ~375-430, height ~812-932): full workflow. Check if target already exists — if so, this is a redesign (see references/component-workflow.md).
Child component (smaller): single View file in <TargetDir>/Components/. Skip Phase 3.
Step 3: Detect state variants
When multiple Figma links or sibling frames represent the same screen in different states, these are state variants of one feature, not separate screens. See references/state-variants.md for detection and implementation.
Call mcp__claude_ai_Figma__get_variable_defs to map color/spacing tokens to the project's theme. See references/design-tokens.md.
Call mcp__claude_ai_Figma__get_code_connect_map to discover component mappings. Reuse mapped components directly.
Step 5: Download ALL assets
Mandatory. Download every vector, image, and font from the Figma response.
Subagent option:agents/asset-processor.md — run in background, parallel with Step 6.
If not using a subagent, follow references/figma-extraction.md for the complete asset download procedure (SVG sanitization, PNG multi-scale, font handling, naming conventions, xcassets catalog setup).
Step 6: Decompose into components (bottom-up)
Break the design into atomic → molecule → organism → screen composition layers. For each component, extract: colors, spacing, corner radius, font, assets, interactive vs decorative.
Component variants: Map Figma variant properties to Swift enums/Bools. See references/swiftui-mapping.md.
Tab bar: Belongs to AppFeature, NOT the current feature. See references/tab-bar-handling.md.
Shared components: If used by 2+ targets, must move to SharedComponents. See references/component-workflow.md.
Redesign diffing: Use agents/component-differ.md if the target already exists.
Step 7: Match against project catalog
Cross-reference components against Phase 0 discoveries — reuse existing UIComponents, extensions, theme types. Never duplicate.
Phase 2 — Component Analysis & Confirmation
CONFIRM GATE — Present the component breakdown:
## Target
[existing target name] — [path]
(or: NEW target [name])
## Screen Overview
Type: [paged / list / detail / form / ...]
Pages/States: [count and names]
## Redesign diff (if applicable):
### Kept: [list]
### Modified: [list with changes]
### Added: [list]
### Removed: [list]
## Components (bottom-up)
### Reuse from project: [list]
### New components to create: [list with descriptions]
### Shared components detected: [list or "None"]
### Tab bar detected: [YES/NO]
## Screen composition: [how components assemble]
## Interactive elements -> TCA Actions: [mapping]
## Fonts: [list with status]
## Design Tokens: Mapped [list] / Raw values [list]
## Appearance Variants: [Light+Dark / Single]
## Downloaded Assets: SharedResources [list] / Feature-local [list]
## Skipped Assets: [list with reasons]
Does this look right? Any corrections?
STOP here. Do NOT proceed until user confirms.
Phase 3 — State Modeling
Design the TCA Store based on confirmed components. See references/tca-codegen.md for patterns and common mistakes.
CONFIRM GATE — Present State + Actions:
## State
- propertyName: Type = defaultValue — [description]
## Actions
- onAppear — [trigger]
- buttonTapped — [behavior]
- delegate(Delegate) — [parent communication]
## Bindings
[YES — list controls / NO]
## Effects
- onAppear → fetch via client
- buttonTapped → navigate via delegate
Does this look right? Any corrections?
STOP here.
Phase 4 — Code Generation (component-first)
Generate code bottom-up: components first, then screen composition.
Generate new components — one View per file in <TargetDir>/Components/. See references/component-workflow.md for extraction rules.
Generate the TCA Store — use templates/store-template.swift and examples/OnboardingStore.swift or examples/DetailStore.swift.
Generate the main View — use templates/view-template.swift and examples/OnboardingView.swift or examples/DetailView.swift.
Each component in its own file inside <TargetDir>/Components/. Before creating, check if the component already exists (inline or in Components/) — see references/component-workflow.md for the full decision tree and extraction rules.
Rules for component files — one SwiftUI View struct per file, public access on all types/init/body (see checklist below), use project's existing extensions via import Extensions (NEVER duplicate Color(hex:) or other shared utilities into feature targets), each file imports only what it needs.
Do NOT redraw downloaded vectors with SwiftUI shapes, paths, or Canvas. The downloaded asset IS the source of truth.
Step 2: Generate the TCA Store
Use template: ${CLAUDE_SKILL_DIR}/templates/store-template.swift
Use example: ${CLAUDE_SKILL_DIR}/examples/OnboardingStore.swift
Step 3: Generate the main View
Compose downloaded assets and components into the full screen layout.
Use template: ${CLAUDE_SKILL_DIR}/templates/view-template.swift
Use example: ${CLAUDE_SKILL_DIR}/examples/OnboardingView.swift
Reference components by name, don't inline everything.
Code quality checklist
No unused imports
All Views, structs, init(), and body are public
Correct Sendable conformances
Effects use send correctly; state mutations in reducer, not effects
NEVER withAnimation in Reducer — use .send(.action, animation: .default)
NEVER wrap store.send() in withAnimation — use store.send(.action, animation: .default)
BindableAction only when View uses $store.property
No ZStack used purely for backgrounds, fills, strokes, or decorative overlays — use .background(...) and .overlay(...) modifiers instead.ZStack is only for two or more peer content layers that each need their own position in a shared coordinate space. See references/swiftui-mapping.md "Prefer .background / .overlay over ZStack".
No duplicate utilities — use import Extensions for shared helpers like Color(hex:). NEVER create per-feature ColorExtension.swift files
Shared assets use bundle: SharedResources.bundle, feature-local use bundle: .module
No duplicate assets across targets
No duplicate font files or font helpers — fonts live only in SharedResources
No SwiftUI shape/path/Canvas reimplementations of downloaded assets
PNG assets have all 3 scales; SVGs have single universal file
No orphaned assets; no duplicate components across feature targets
Phase 4.5 — Self-Critique
Review generated code for unnecessary complexity. Apply: "If removing X produces the same visual result, remove it."
See references/self-critique.md for the full checklist (structural simplicity, redundant modifiers, component decomposition, Spacer vs padding, TCA cleanup).
Phase 5 — Integration
Wire everything together. See references/integration.md for the complete guide.
Present a brief summary:
## Integration Summary
- Package.swift: [updated/created target]
- Dependencies added: [list or "none"]
- SharedComponents: [created/updated / not needed]
- AppFeature: [tab wired / not applicable]
- Resources verified: [N imagesets, fonts in SharedResources]
See references/integration.md for the complete guide covering:
Package.swift patterns (existing vs new target)
Extensions target — every new feature target MUST depend on "Extensions". This target contains shared Swift extensions (Color(hex:), custom modifiers, etc.). NEVER create per-feature extension files — add import Extensions to source files instead. If a new shared extension is needed, add it to the Extensions target source directory.
Fall back to Mode B (REST API via scripts/figma_extract.py) or Mode C (Playwright screenshots). See references/figma-extraction.md.
For section nodes with "sparse metadata", extract child frame IDs and call get_design_context on each child individually.
Asset downloads fail (expired CDN URLs)
Figma CDN URLs expire after ~7 days. Re-call get_design_context to get fresh URLs.
If repeated failures, use scripts/figma_extract.py with a Figma API token for direct REST calls.
Build fails after 3 retries
Present the remaining errors to the user. Common root causes: missing public access modifiers, Sendable conformance issues, missing import statements, ObjC naming conflicts (e.g., Category clashes with objc_category).
See references/tca-codegen.md (Common Mistakes) for the full list.
Project has no Package.swift (XcodeGen-only)
Look for project.yml / project.base.yml instead. Adapt target creation to XcodeGen format.
Resources and xcassets setup is the same; only the target declaration format differs.
SVGs render blank in Xcode
Almost always caused by unsanitized CSS custom properties (var(--name, fallback)). Re-run scripts/process_asset.sh on the SVG.
Visual score stays below 60
Stop automated refinement. The layout may need fundamental design decisions. Present the corrections list to the user and ask for guidance.
Scope & Limitations
iPhone portrait only. iPad layouts, landscape orientations, and adaptive layouts are not handled. If the Figma design targets iPad, notify the user that manual adaptation will be needed.
No Lottie/animation generation. Animated elements are marked with TODO comments.
No runtime locale switching. Static strings only; use the localize skill for i18n.
