Figma Make Workflow Guide

Project Initialization

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:

Prompting Principles

How you phrase prompts significantly impacts output quality. Follow these principles for better results.

1. Reference Your Documentation

   Always point Figma Make to existing docs. This maintains consistency and prevents drift.

   Good

   Add a new button variant. Follow patterns in CONVENTIONS.md and use values from designTokens.ts.

   Weak

   Add a new button variant.

2. Be Specific About Scope

   Define exactly what should and shouldn't change.

   Good

   Refactor the CartTile component to extract the quantity selector into its own component. Don't change any functionality or styling — just the file structure.

   Weak

   Clean up the CartTile component.

3. State the "Why"

   Context helps Figma Make make better decisions.

   Good

   Add loading states to the checkout button. Users in testing were confused when nothing happened after clicking — they need visual feedback that their action registered.

   Weak

   Add loading states to the checkout button.

4. Specify Outputs

   Tell Figma Make what you expect back.

   Good

   Create a new ProductCard component. Return:
   - The component file
   - Updated exports in index.ts
   - TypeScript interface in types.ts
   - Entry in CHANGELOG.md

   Weak

   Create a new ProductCard component.

5. One Task Per Prompt

   Complex prompts with multiple unrelated tasks often produce worse results.

   Good

   Prompt 1: "Add form validation to the email input"
   Prompt 2: "Refactor the header navigation"

   Weak

   Add form validation to the email input and also refactor the header navigation and update the colour scheme.

6. Use Consistent Terminology

   Match the language in your documentation.

   Good (if docs say "tile")

   Create a new basket tile variant.

   Inconsistent

   Create a new basket card variant.

7. Ask for Explanations When Learning

   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

Prompt Templates

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.

Phased Implementation

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.

Mid-Task Clarifications

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]

Figma Design Handoff

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.

Common Pitfalls

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

Maintenance & Cleanup

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.