figma-ui-ux-consistency
Orchestrates all 7 Figma MCP plugin skills into a unified, project-aware lifecycle for achieving and maintaining UI/UX consistency — from audit through design system creation, code implementation, and
SKILL.mdskills/figma-ui-ux-consistency/SKILL.md
GitHubFigma UI/UX Consistency — Orchestration Skill
A holistic orchestration skill that sequences the 7 Figma MCP plugin sub-skills into a single, project-aware lifecycle for achieving and maintaining UI/UX consistency. This skill owns the what-to-do-when logic. It delegates how-to-do-it to the appropriate sub-skill.
This skill does not call use_figma directly. It composes the 7 plugin skills and
manages phase transitions, checkpoints, and project-specific adaptation.
Companion skills (always load together):
ui-ux-pro-max— design system spec, token structure, component patternsfrontend— implementation of design specs into codeplan-design-review— review design deliverables before implementationdesign-review— visual audit of live implementations
When Invoked
Use this skill when the user says or asks for:
- "audit the UI for consistency issues"
- "establish a design system for [project]"
- "fix the inconsistent styling across our app"
- "reconcile Figma with our codebase"
- "build a component library from our existing screens"
- "Figma-to-code governance workflow"
- Any request involving Figma + code consistency at a project or portfolio level
Skill boundaries:
- This skill orchestrates; it does not execute Figma canvas writes directly.
- For creating a design system in Figma: load
figma-generate-library. - For writing Figma screens from code: load
figma-generate-design. - For reading Figma and generating code: load
figma-implement-design. - For connecting Figma components to code: load
figma-code-connect-components. - For authoring project rules: load
figma-create-design-system-rules. - For creating a new Figma file: load
figma-create-new-file. - For any canvas write operation: load
figma-usefirst (mandatory prerequisite).
The 5-Phase Consistency Lifecycle
Phase 1: AUDIT → Extract patterns, identify inconsistencies, document gaps
Phase 2: FOUNDATIONS → Define tokens, color semantics, typography scale, spacing
Phase 3: LIBRARY → Build component library (via figma-generate-library)
Phase 4: IMPLEMENT → Implement designs in code + connect components
Phase 5: GOVERNANCE → Rules, review loops, change management
Rule: Always execute phases in order. Phase N+1 requires Phase N to be complete and approved. Skipping phases creates cascading failures that are expensive to undo.
Phase 1 — UI Audit
Goal: Understand what exists, what is consistent, and what is broken.
1a. Determine Audit Scope
Ask the user:
- Which Figma file(s) or URL(s) to audit?
- Which codebase directory or repo to cross-reference?
- Is this a new project (no existing design system) or an existing one?
If no Figma file exists yet, use generate_figma_design to capture the running
application into Figma first (web apps only), then audit the captured file.
1b. Extract Existing Patterns
Run get_design_context on key screens, then:
- Document the component inventory: list every distinct visual element by name (Button, Card, Modal, Badge, Input, NavItem, etc.)
- Document the token inventory: extract color values, spacing values, font sizes, border radii, shadow values as you encounter them
- Identify duplicates: same visual, different name or values
- Identify variants: same component family, inconsistent naming
- Identify hardcoded values: colors/spacing not using any token system
1c. Cross-Reference with Codebase
Read the project's existing design tokens or CSS variables. Document:
- Which Figma values match the code
- Which Figma values diverge from the code
- Which code values have no Figma equivalent (and vice versa)
1d. Produce the Audit Report
Present a structured report:
## UI Audit Report — [Project Name]
### Consistent Patterns (Keep)
- [Component]: [what is working, e.g. "Buttons use --primary-500 consistently"]
### Inconsistencies to Fix (Priority Order)
1. **[Issue]**: [description, e.g. "5 different border-radius values used]
- Seen in: [screens/components]
- Proposed fix: [unified value]
2. ...
### Missing Design System Elements
- [ ] Token: no spacing scale defined
- [ ] Component: no shared Badge component, 3 ad-hoc versions exist
- ...
### Code ↔ Figma Divergences
| Element | Figma Value | Code Value | Recommended |
|---------|------------|------------|-------------|
| Button bg | #3B82F6 | #2563EB | [pick one] |
### Audit Summary
- Total components found: N
- Unique visual patterns: N
- Divergences code↔Figma: N
- Recommended: [new system / incremental fix / no DS needed]
USER CHECKPOINT: Present the audit report. Await explicit approval before proceeding to Phase 2. If user says "skip audit" or "start from scratch," confirm they understand the gaps that won't be caught, then proceed.
Project-Specific Rules for Phase 1
examplecrm (brand: teal + amber, fonts: Playfair Display + Plus Jakarta Sans):
- Audit must document existing teal/amber usage as the brand anchor
- Any palette decisions must reference the teal + amber brand rule
- Typography audit must flag any non-brand font usage
Phase 2 — Design System Foundations
Goal: Establish the token system that all components will consume.
2a. Confirm Brand / Style Anchor
Before creating any tokens, confirm:
- Brand colors (e.g., teal + amber for examplecrm)
- Brand typography (e.g., Playfair Display + Plus Jakarta Sans)
- Style direction (minimal, glass, editorial, data-dense — from ui-ux-pro-max)
- Motion tier (A/B/C from ui-ux-pro-max)
2b. Define Token Architecture
Produce a token spec covering all 4 foundations:
Color:
Primitive tokens: blue/50 → blue/900, gray/50 → gray/900, white, black
Brand tokens: teal/50 → teal/900, amber/50 → amber/900 [examplecrm]
Semantic tokens: color/bg/primary, color/text/primary,
color/border/default, color/accent/primary
color/status/success, color/status/warning,
color/status/error, color/status/info
Typography:
Font families: [heading: Playfair Display], [body: Plus Jakarta Sans] [examplecrm]
Font sizes: text/xs=12, text/sm=14, text/base=16, text/lg=18,
text/xl=20, text/2xl=24, text/3xl=30, text/4xl=36
Font weights: font/regular=400, font/medium=500, font/semibold=600, font/bold=700
Line heights: leading/tight=1.2, leading/normal=1.5, leading/relaxed=1.75
Spacing:
spacing/xs=4, spacing/sm=8, spacing/md=16, spacing/lg=24,
spacing/xl=32, spacing/2xl=48, spacing/3xl=64
Radius / Shadow:
radius/none=0, radius/sm=4, radius/md=8, radius/lg=12, radius/full=9999
shadow/sm, shadow/md, shadow/lg (effect style references)
2c. Write Foundations to Project Memory
Save the token spec to:
[project]/memory/design-system-foundations.md
This file becomes the anchor that both Figma and code reference. Update it before touching Figma or code in later phases.
USER CHECKPOINT: Present the foundations spec. Await explicit approval before creating anything in Figma.
Phase 2 Anti-Patterns
- Creating tokens in Figma before writing the spec to project memory
- Defining semantic tokens that duplicate raw values instead of aliasing primitives
- Using
ALL_SCOPESon any variable - Skipping brand anchor confirmation (color, font, style)
Phase 3 — Component Library Creation
Goal: Build the Figma component library from the foundations established in Phase 2.
Load figma-generate-library and figma-use together for this phase.
This skill provides the orchestration logic; those skills provide the Plugin API
execution logic.
3a. Run Discovery (figma-generate-library Phase 0)
- Analyze codebase — extract existing UI components and their prop API
- Inspect Figma file — existing pages, variables, components, styles
- Search subscribed libraries via
search_design_system - Lock v1 scope: agree on exact token set + component list
3b. Create Foundations in Figma (figma-generate-library Phase 1)
- Variable collections (Primitives → Semantic → Spacing)
- Effect styles and text styles
- Always bind visual properties to variables — no hardcoded fills/strokes
3c. Create File Structure (figma-generate-library Phase 2)
Standard page skeleton:
Cover → Getting Started → Foundations → --- → Components → --- → Utilities
3d. Build Components One at a Time (figma-generate-library Phase 3)
For each component (in dependency order — atoms before molecules):
- Create dedicated page
- Build base component with full variable bindings
- Create variant combinations
- Add component properties
- Validate with
get_metadata+get_screenshot - USER CHECKPOINT per component
Component priority order for v1:
1. Button 6. Badge 11. Modal/Dialog
2. Input 7. Avatar 12. Table
3. Select 8. Card 13. Pagination
4. Checkbox 9. Tag/Chip 14. Toast/Snackbar
5. Toggle 10. Dropdown 15. Tabs
Phase 3 Anti-Patterns
- Building components before foundations (tokens) exist in Figma
- Hardcoding any fill/stroke/spacing/radius value
- Creating a variant per icon (use INSTANCE_SWAP instead)
- Batch-creating all components without user checkpoints
- Parallelizing
use_figmacalls (always sequential)
Phase 4 — Implementation & Code Connection
Goal: Translate the Figma library into production code, and connect Figma components to code components for bidirectional handoff.
4a. Implement Figma Designs in Code
Load figma-implement-design for this step.
For each screen/section:
- Fetch
get_design_context+get_screenshotfrom Figma - Download required assets from the Figma MCP assets endpoint
- Map Figma design tokens → project design tokens
- Reuse existing components where they match
- Implement new components using project conventions
- Validate visual parity against the Figma screenshot
Translation rules:
- Treat Figma output as design intent, not final code style
- Replace Tailwind utilities with project tokens
- Prefer project design system components over raw Figma translation
- Document deviations for accessibility or technical reasons
4b. Connect Figma to Code Components
Load figma-code-connect-components for this step.
After implementing a component in code:
- Locate the corresponding Figma component node
- Run
figma-code-connect-componentsto create a Code Connect mapping file - Verify the mapping links the correct Figma component to the correct code component
- Map all variant properties and states
4c. Create Project Figma-to-Code Rules
Load figma-create-design-system-rules for this step.
Generate project-specific rules that encode:
- Which design system conventions apply to this project
- Naming conventions for components, tokens, and variants
- When to prefer Figma vs. code as the source of truth
- How to handle conflicts between Figma and code
Output: [project]/figma-design-system-rules.md
Phase 4 Anti-Patterns
- Implementing without fetching
get_design_contextfirst - Hardcoding hex values instead of design tokens
- Creating duplicate components that already exist in the codebase
- Skipping Code Connect mappings (breaks bidirectional handoff)
Phase 5 — Governance
Goal: Ensure consistency is maintained after the initial build.
5a. Establish Design Review Gate
Add a design-review checkpoint to the team's definition of done:
- Any new screen or major UI change must be reviewed against the Figma source
- The review must validate: colors match tokens, spacing matches scale, typography matches the type ramp, no ad-hoc components created without design review
5b. Write Project-Specific Figma Rules
Generate [project]/figma-design-system-rules.md using figma-create-design-system-rules.
The rules file must capture:
- Project brand tokens (e.g., examplecrm teal + amber)
- Project font stack
- Allowed component inventory
- Naming conventions
- Forbidden patterns (ad-hoc components, hardcoded values)
- Conflict resolution: Figma wins for visual; code wins for behavior
5c. Set Up Ongoing Audit Triggers
Teach the team to re-run Phase 1 audit when:
- A new designer joins the project
- The product has undergone significant feature growth (>30% new screens)
- A user or stakeholder flags visual inconsistency
- Before a major release
5d. Track the State Ledger
For long-running or recurring consistency work:
- Maintain
[project]/memory/figma-consistency-state.jsontracking:- Last audit date
- Components created in Figma (with IDs)
- Token coverage (% of components using tokens vs. hardcoded)
- Code↔Figma divergence log
- Re-read this file at the start of every session
Phase 5 Anti-Patterns
- Changing design tokens in Figma without updating the project rules file
- Allowing "one-off" components without design review
- Skipping Code Connect on new components (starts the divergence cycle again)
Project-Specific Adaptation
examplecrm (Next.js 14 + FastAPI + Supabase, teal + amber, Playfair Display + Plus Jakarta Sans)
Brand anchor — never override without explicit user approval:
- Primary teal:
#0D9488(Tailwind:teal-600) — brand anchor - Accent amber:
#F59E0B(Tailwind:amber-500) — brand accent - Font heading:
Playfair Display(Google Fonts) - Font body:
Plus Jakarta Sans(Google Fonts)
Token naming convention for examplecrm:
color/teal/[shade] e.g., color/teal/600
color/amber/[shade] e.g., color/amber/500
color/bg/primary → teal-50 (light) / teal-900 (dark)
color/text/primary → gray-900 (light) / gray-50 (dark)
color/accent → amber-500
typography/font/heading → Playfair Display
typography/font/body → Plus Jakarta Sans
Forbidden for examplecrm:
- Using blue/purple brand colors in primary UI
- Mixing Playfair Display into body text or Plus Jakarta Sans into headings
- Using teal-700+ for backgrounds (creates accessibility issues)
- Hardcoded teal/amber hex values (must use CSS variables from the brand token system)
Other Projects
For ExampleApp:
- Detect brand colors, fonts, and style direction from the project's existing CLAUDE.md or PROJECT.md before Phase 2
- Apply the same 5-phase lifecycle with project-specific tokens
Skill Orchestration Map
| If the user wants to... | Load this skill |
|---|---|
| Run the full consistency lifecycle | figma-ui-ux-consistency |
| Execute Phase 1 (audit) | figma-ui-ux-consistency + figma-implement-design (for get_design_context) |
| Execute Phase 2 (foundations spec) | figma-ui-ux-consistency + ui-ux-pro-max |
| Execute Phase 3 (build library in Figma) | figma-ui-ux-consistency + figma-generate-library + figma-use |
| Execute Phase 4 (implement in code) | figma-implement-design + figma-code-connect-components |
| Execute Phase 4 (write project rules) | figma-create-design-system-rules |
| Create a new Figma file | figma-create-new-file |
| Perform design review | design-review |
Key Rules
- Never call
use_figmawithout loadingfigma-usefirst. - Never skip Phase 1 (audit). Starting from scratch without knowing what's broken means fixing symptoms instead of root causes.
- Never skip user checkpoints. Consistency work requires human judgment on visual priorities. Never build Phase N+1 without Phase N approval.
- Variables before components. Tokens must exist in Figma before components bind to them.
- Code↔Figma conflicts: ask the user. Never silently pick one. Document both options and their implications.
- Never parallelize
use_figmacalls. Figma state mutations are sequential. - Always validate after every Figma write. Use
get_metadatafor structure,get_screenshotfor visuals. - Persist the state ledger. For workflows spanning multiple sessions, write to disk
(
/tmp/figma-consistency-{project}-{date}.json) and re-read at session start. - For examplecrm: never override the teal+amber brand anchor without explicit user approval.