Figma Make Workflow Guide

01

Project Initialization

Establish production-ready structure from day one

Use this prompt when starting a new React prototype. It establishes documentation and conventions from day one, giving Figma Make complete context for all future work.

Initial Setup Prompt

Initialize this project with production-ready structure and documentation. Set up foundations that will scale as the project grows. Project Context [Describe: what it does, what you're testing, who it's for] File Structure Create a clean, scalable folder structure: - /components — reusable UI components - /pages or /views — top-level screens - /hooks — custom React hooks - /utils — helper functions - /types — TypeScript interfaces and types - /constants — configuration and design tokens Required Documentation README.md: - Project purpose and goals - What this prototype tests or demonstrates - Tech stack and dependencies - Setup instructions (install, run, build) - Folder structure overview - Links to other documentation files ARCHITECTURE.md: - Component hierarchy diagram (mermaid or ASCII) - Data flow explanation - State management approach - Event flow for key interactions - File naming conventions - Patterns for adding new features CONVENTIONS.md: - Component structure template - Prop naming standards - TypeScript patterns used - Styling approach - Event handler naming (handleClick, onChange) - Comment style and when to use them - Import ordering CHANGELOG.md: - Initial entry with project creation date - Version format explanation - Template for future entries Configuration Files designTokens.ts: - Colours (semantic naming) - Spacing scale - Typography (sizes, weights, line heights) - Border radii - Shadows - Breakpoints - Transitions config.ts: - Feature flags - API endpoints (if applicable) - Timeout values - Default states Code Foundations - One example component following all conventions - Types file with common interfaces - Utility function demonstrating code style Documentation Principles - Write as if briefing a developer who has never seen the codebase - Explain "why" behind decisions, not just "what" - Include code snippets as examples - Cross-reference between docs Start minimal but structured. Every file should follow patterns in CONVENTIONS.md.

Optional Add-ons

Include these based on project type:

User Testing Prototypes

Add VARIANT_GUIDE.md with variant system explanation, implementation steps, and testing checklist.

Design System Work

Add COMPONENTS.md with component inventory, props documentation, and accessibility requirements.

API-Connected

Add API.md with endpoint documentation, request/response shapes, and error handling patterns.

02

When you want to understand decisions, ask explicitly.

Refactor this component to improve performance. Explain what changes you made and why.

8. Request Analysis Before Implementation

For complex tasks, ask Figma Make to report back before making changes.

Report back with your analysis before implementing. Show me: - Current component structure - Your proposed changes - Any concerns or questions

03

Prompt Templates

Copy and adapt these for common tasks

Copy and adapt these for common tasks.

Adding a New Component

Create a new [ComponentName] component. Purpose: [What it does and where it's used] Requirements: - [Requirement 1] - [Requirement 2] - [Requirement 3] Follow patterns in CONVENTIONS.md. Use designTokens.ts for all styling values. Return: - Component file - TypeScript interface - Updated exports - CHANGELOG.md entry

Adding a Feature

Add [feature] to [component/area]. Context: [Why this feature is needed] Behaviour: - [How it should work] - [Edge cases to handle] - [User feedback needed] Follow existing patterns in ARCHITECTURE.md. Update documentation if this changes any established flows. Report back with your analysis before implementing.

Refactoring

Refactor [component/area] to [goal]. Current problem: [What's wrong or suboptimal] Constraints: - Preserve all existing functionality - Don't change the public API/props - Follow CONVENTIONS.md patterns Flag any technical debt discovered. Update CHANGELOG.md. Report back with your analysis before implementing.

Bug Fixing

Fix: [Description of the bug] Current behaviour: [What happens now] Expected behaviour: [What should happen] Steps to reproduce: [If relevant] Keep changes minimal — only fix the bug, don't refactor unrelated code.

Documentation Updates

Update documentation to reflect [change]. Files to review: - README.md - ARCHITECTURE.md - [Other relevant docs] Ensure docs match current implementation. Flag any inconsistencies found.

Code Review Request

Review [component/file] for: - Adherence to CONVENTIONS.md - Proper use of designTokens.ts and config.ts - Unused imports or dead code - Opportunities for improvement Don't make changes — just provide a summary of findings.

04

Phased Implementation

Break complex tasks into reviewable phases

Complex tasks should be broken into phases with review points. This reduces risk and gives you control over the process.

When to Use Phases

Refactoring that touches multiple files
Adding features that affect existing behaviour
Merging or consolidating components
Any change you're not 100% confident about

Initial Phased Prompt

[Describe the overall goal] Approach Break this into phases: - Phase 1: [First safe, reversible step] - Phase 2: [Next step, builds on Phase 1] - Phase 3: [Cleanup and documentation] Pause after each phase for review before continuing. Start with Phase 1. Report back with your analysis before implementing.

Phase Continuation Prompt

Phase [N] looks good. Proceed with Phase [N+1]. [Add any clarifications or adjustments based on what you saw]

Example: Responsive Refactor

Refactor from separate desktop/mobile layouts to responsive. Approach - Phase 1: Header & Footer consolidation - Phase 2: Main layout conversion - Phase 3: Cleanup (remove URL params, update docs) Pause after each phase for review before continuing. Start with Phase 1.

Tip

Keep phases small enough that you can review the changes in a few minutes. If a phase feels too big, split it further.

05

Mid-Task Clarifications

Catch and correct assumptions early

Figma Make will sometimes make assumptions that don't match your intent. Catch and correct these early.

Clarification Template

Before continuing, clarification on [area]: [Topic 1] [Correct the assumption. Be specific about what you want.] [Topic 2] [Another correction if needed.] Proceed with [Phase/Task] using these clarifications.

Example: Correcting Mobile Behaviour

Before Phase 2, clarification on mobile behaviour: Floating CTA (not floating basket summary) The mobile layout should NOT have a floating basket summary. Instead: - A floating CTA bar with: basket total + free delivery progress bar + checkout button - This floats at the bottom of the viewport as user scrolls - When user scrolls down to where the actual inline CTA sits on the page, the floating version disappears - This behaviour already exists in the current mobile layout — preserve it Basket Summary on Mobile - Basket summary displays inline within the page flow (not floating) - It sits below the basket items, above the footer Proceed with Phase 2 using these clarifications.

Preserve Existing Behaviour Template

When refactoring, explicitly reference existing implementation as the source of truth.

The [mobile/desktop] layout at [breakpoint/condition] should be visually identical to [the current implementation / what the old parameter produced]. If there are any differences, reference the original implementation as the source of truth and match it exactly. Preserve these existing behaviours: - [Specific behaviour 1] - [Specific behaviour 2] - [Specific behaviour 3]

06

Figma Design Handoff

Analysis first, then implementation

When you have Figma designs to implement, use a two-step process: analysis first, then paste designs.

Step 1: Request Analysis

Implement [feature] based on Figma designs. Current State [Describe what exists now] Desired Functionality [Describe the new behaviour] I will paste Figma designs for: - [Component 1] - [Component 2] - [etc.] Report back with your analysis before implementing. Show me: - Current component structure - Where the designs will be applied - Your proposed state management approach

Step 2: Paste Designs and Confirm

After reviewing the analysis, paste your Figma designs and confirm:

[Paste Figma designs here] Use these designs for: - [Component 1] styling and structure - [Component 2] styling and structure Your analysis looks correct. Proceed with implementation.

Example: Adding a New UI Element

Implement toast notification component. Current State - Inline notifications appear within page content - Show success message with "Undo" link - Persist until dismissed Desired Functionality - New toast/snackbar style as alternative - Appears at bottom of viewport - Auto-dismisses after 4 seconds - Toggle in variant UI to switch between styles I will paste Figma designs for: - Toast component styling - Success/confirmation state Report back with your analysis before implementing.

Tip

Always get the analysis first. This catches misunderstandings before any code is written and saves you from unpicking incorrect implementations.

07

Common Pitfalls

Issues encountered and how to prevent them

Issues encountered when working with Figma Make, and how to prevent or fix them.

Documentation Claims Non-Existent Features

Issue: Figma Make documents features that don't exist in code (e.g., "Variant D" when only A, B, C exist). Users encounter errors when trying to use documented features.

Prevention: Run documentation audits regularly. After any feature work, verify docs match implementation. Use the audit prompt to catch discrepancies.

Assumptions About Mobile Behaviour

Issue: When refactoring, Figma Make may reinvent mobile UX rather than preserving existing patterns (e.g., making entire summary float instead of just the CTA).

Prevention: Explicitly state which existing behaviours to preserve. Use the "Preserve Existing Behaviour" template. Test mobile view after each phase.

State Management Not Specified

Issue: Complex features get implemented without clear state structure, leading to messy or duplicated state logic.

Prevention: Include state requirements in your prompt. Ask for state management proposal in the analysis phase before implementation.

Excessive Documentation Files

Issue: Figma Make creates many dated summary files (AUDIT_DEC10.md, SUMMARY_DEC10.md, etc.) that clutter the project root.

Prevention: Periodically run: "Remove unneeded MD files. Keep only core documentation (README, ARCHITECTURE, CONVENTIONS, CHANGELOG) and current feature docs."

Scope Creep in Refactoring

Issue: A simple refactor expands to touch unrelated files or "improve" things you didn't ask about.

Prevention: Be explicit about constraints: "Only modify [specific files]. Don't change any other files. Keep changes minimal."

08

Maintenance & Cleanup

Keep the codebase healthy

Run these prompts periodically to keep the codebase healthy.

When to Run Maintenance

After adding new features
Before major version bumps
Weekly during active development
Before handoff or review sessions
When things start feeling "messy"

Maintenance Prompt

Perform a maintenance refactor of this project. Reference existing documentation to ensure code and docs remain aligned. Reference Documentation - ARCHITECTURE.md — system structure and data flow - CONVENTIONS.md — code style and patterns - designTokens.ts — single source of truth for styling - config.ts — single source of truth for configuration - [Add any project-specific docs] Code Cleanup - Remove unused imports and dead code - Replace any hardcoded values with designTokens.ts or config.ts references - Consolidate duplicate logic - Remove commented-out code blocks - Ensure all components follow patterns in CONVENTIONS.md Documentation Sync - Flag any code that contradicts documentation - Update docs if implementation has intentionally changed - Add changelog entry for any modifications made Consistency Check - Verify prop naming matches conventions - Check component structure follows ARCHITECTURE.md hierarchy - Ensure new code uses established patterns, not one-off solutions - Confirm designTokens.ts is used everywhere styling values appear Technical Debt - Flag areas needing future attention - Note any temporary solutions that should be revisited - Identify components that have grown too large File Cleanup - Remove redundant dated documentation files (e.g., SUMMARY_DEC10.md) - Keep only core docs and current feature documentation - Consolidate overlapping documentation Preserve all functionality. Document changes in CHANGELOG.md with today's date.

Documentation Audit Prompt

Use this for deeper documentation reviews — before onboarding, after major features, or quarterly clean-ups.

Perform a full audit of all project documentation. Ensure docs are accurate, consistent, and cross-referenced correctly. Documentation Files - README.md - ARCHITECTURE.md - CONVENTIONS.md - CHANGELOG.md - [Any project-specific docs, e.g., VARIANT_GUIDE.md] Accuracy Check - Verify all documented features exist in code - Verify all code patterns match what's documented - Remove references to deprecated or removed features - Update any outdated examples or code snippets Consistency Check - Ensure terminology is consistent across all docs - Check that file/component names match actual codebase - Verify prop names and APIs match current implementation - Align formatting and structure across docs Cross-Reference Audit - Ensure links between docs are valid - Check that ARCHITECTURE.md hierarchy matches actual components - Verify CONVENTIONS.md patterns match example code - Confirm CHANGELOG.md reflects all major changes Consolidation - Identify duplicated content across docs - Merge overlapping sections into single source of truth - Flag contradictions between docs - Remove redundant information - Delete unnecessary dated summary files Completeness - Flag undocumented components or patterns - Note any "TODO" or placeholder content - Identify gaps where documentation would help Provide a summary of changes made and any issues found.

Quick Cleanup Prompt

For fast cleanups between major maintenance runs.

Quick cleanup: - Remove unused imports - Delete commented-out code - Remove redundant MD files from root (keep README, ARCHITECTURE, CONVENTIONS, CHANGELOG) - Update CHANGELOG.md with today's date Don't refactor or change functionality.