Plan Design

From the metadata, enumerate top-level sections. Record: display name, PascalCase component name, node ID, node type (frame vs instance), approximate height, visual order.

Naming: Choose the clearest display name using heading text, visual purpose, content type, or Figma layer name — whichever is most descriptive. Names must be unique.

Instance nodes: Appear as leaf nodes in metadata with no children. Their internals are only visible via get_design_context.

1.3 Parallel Section Gathering & Snapshot Caching

Batch sections into 2-3 Task agents launched in a single message. Use subagent_type="general-purpose".

Batch sections across agents as you see fit — balance parallelism with prompt size.

Each agent receives (common instructions once, then list of sections):

Analyze these Figma sections and cache their design context. Only analyze the "image" variant code path.

**Steps (per section):**
1. Call `get_design_context(nodeId="<node-id>", fileKey="<file-key>")`.
   Write the FULL raw output to `.claude/figma-snapshots/<ComponentName>.txt`.
2. If the section is >1500px tall, use `get_metadata` to split into sub-nodes and fetch each via `get_design_context`.
   Write each sub-node output to `.claude/figma-snapshots/<ComponentName>-<subNodeLabel>.txt`.
   Record the sub-node IDs in NOTES.
3. If design context has "edit"/"image" variant branching, ONLY analyze the "image" path.
4. Analyze the output using the issue detection rules below.

**Issue detection (per section):**

1. **Multi-layer image scan:** Find `<img>` tags, group by parent container. Parent ≤300px with 2+ images → BLOCKER (fragmented asset: logos, icons, badges, phone mockups). Parent >300px with multiple images → valid layout.

2. **Screenshot cross-check:** Screenshot shows a single visual but code has multiple `<img>` tags composing it → fragmented, apply scan above.

3. **Wrong-language content:** Check image assets for baked-in text (badges, banners). Store badges (App Store, Google Play) are common offenders. Wrong language → BLOCKER.

4. **Content issues:** Template text, placeholder data, wrong-industry copy → CONTENT (not a blocker).

5. **Layout notes:** Interactive elements needing "use client", complex patterns → WARNING.

**Sections to analyze:**
1. "<section-name-A>" — ComponentName: <ComponentName-A>, node: <node-id-A>
2. "<section-name-B>" — ComponentName: <ComponentName-B>, node: <node-id-B>

**Return in EXACTLY this format (repeat per section with header):**

=== <section-name> ===
IMAGES:
- [figma-asset-url] | [filename-stem] | [description] | [dimensions if known]
(Do NOT guess file extensions. Record stems only — actual types are detected during download.)

COLORS (from "image" variant only):
- [hex] | [usage]

FONTS:
- [family] | [weight] | [sizes]

ISSUES:
- BLOCKER: [what's wrong] | KEEP: [what to preserve from design] | [node ID]
- WARNING: [description]
- CONTENT: [description]
(or "None")

NOTES:
- Snapshot files written: [list of paths]
- Sub-node IDs (if section >1500px): [list]
- Needs "use client": [yes/no, why]
- Shared asset references: [any refs to shared images]
- Gotchas: [anything build agent can't see from Figma alone]
(or "None")

LAYOUT:
- [single natural-language line describing spatial structure, element groups, and reading order]

1.4 Aggregate & Build Token Maps

Parse each agent's structured output:

• Colors: Merge from all agents. Frequently used colors → semantic tokens. One-offs as arbitrary values.
• Fonts: Detect primary font from Figma. Select a complementary font for the secondary locale (e.g., Arabic design → pick clean Latin font like Inter for EN). Record both in locale-keyed fonts map.
• Shared images: Same URL in 2+ agents → shared/.
• Issues: Split by prefix — BLOCKER: gates workflow, WARNING: stored in manifest, CONTENT: stored in contentNotes[] (not shown to user).
• Shared components: When the same UI pattern appears in 2+ sections (store badges, identical CTA buttons), flag for shared component creation in Phase 2.
• Page context: Derive pageContext from the first 2 snapshot files (now cached at .claude/figma-snapshots/): section spacing, container width, heading scale, button style, card style. Snap to Tailwind scale. Include projectPurpose.

1.5 Present Comprehensive Report

Present report covering: section list, locales (always AR + EN, note which is default), tokens summary, blockers, warnings. Content issues NOT shown — record in contentNotes[] for build agents.

Wait for user to confirm sections, default locale, and resolve blockers. Re-fetch affected sections if changes were made.

Phase 2: Setup

2.1 Download Images & Verify Types

Create directory structure:

• public/images/<section-kebab>/ for each section
• public/images/shared/ for cross-section images

Download all images. Shared images first, then section images. For each:

1. Assign a codePath stem (e.g., /images/hero/hero-bg) following kebab-case naming
2. curl the figmaAssetUrl to a temp path
3. Run file <path> to detect actual type
4. Set correct extension (.png/.svg/.jpg/.webp) based on detected type
5. Move to final codePath under public/
6. For SVGs: remove preserveAspectRatio="none" and width="100%"/height="100%" attributes (Figma export artifacts)

Write resolved codePaths (with correct extensions) to the manifest. Keep figmaAssetUrl for provenance.

If a download fails (expired URL or 403), call get_design_context for that section to get fresh URLs and retry.

2.2 Create Shared Components

If shared components were flagged in Phase 1.4 (same UI pattern in 2+ sections), create the component files at components/shared/ and add sharedComponents array to the manifest.

2.3 Create Project Files

Run npm install next-intl first.

1. next.config.ts: Wrap with createNextIntlPlugin
2. i18n/routing.ts: defineRouting({ locales: ['ar', 'en'], defaultLocale: '<detected>' })
3. i18n/request.ts: getRequestConfig — loads messages/<locale>.json for the requested locale
4. middleware.ts: createMiddleware(routing) with matcher ['/', '/(ar|en)/:path*']
5. messages/ar/ and messages/en/: Empty directories (build agents write per-section files)
6. app/[locale]/layout.tsx: Dynamic lang/dir from locale param (ar=RTL, en=LTR). Load both fonts via next/font/google (one per locale). Wrap children in NextIntlClientProvider. Use generateStaticParams for all locales.
7. app/[locale]/page.tsx: Import and render all sections with setRequestLocale
8. app/globals.css: @theme block with color tokens
9. Component placeholders: One per section
10. lib/use-scroll-reveal.ts: "use client" hook that observes [data-reveal] elements and adds .visible class when they scroll into view (one-time trigger)
11. components/shared/LocaleSwitcher.tsx: Functional locale switcher using next-intl's Link

2.4 Write Manifest

Create .claude/design-manifest.json per references/manifest-schema.json.

Ensure each image entry in sections[].images and sharedImages includes both codePath and figmaAssetUrl.

2.5 Verify & Summarize

npm run dev

Verify both localhost:3000/ar and localhost:3000/en resolve. Present: section count, images (N total), token count, warnings, and: "Manifest ready. Run /build-design to start."

Rules

• NEVER get_design_context on a full page — per section or smaller only
• ALWAYS "image" variant, never "edit"
• Section names must be unique and descriptive
• Instance nodes need get_design_context to see internals
• Do NOT write component code — only placeholders
• Do NOT start building — stop after manifest