Figma-Driven Next.js Development Skill

This is a Figma-driven Next.js development skill, combining the

vercel-react-best-practices

and

web-design-guidelines

skills, with Figma design files as the core design source.

Tech Stack

Category	Technology Selection
Frontend Framework	Next.js (App Router)
Backend Service	Supabase
Styling Solution	Tailwind CSS
Icon Library	Lucide (https://lucide.dev/)
Animation Library	Motion (https://motion.dev/)
Workflow	Figma MCP → Trae IDE

Core Principles

Figma First

All design decisions are based on Figma files, with

vercel-react-best-practices

and

web-design-guidelines

serving as supplementary guidance for code quality and best practices.

Design Token System

1. Color Specifications

Source: Strictly follow color definitions in Figma files

Implementation: Create a unified color token file

/styles/tokens/colors.ts

Dark Mode:

Automatically derive Dark mode colors (intelligently generated based on original Figma colors)
Comply with WCAG contrast standards
Only support Light/Dark dual themes, not multi-themes

Color Token Structure:

typescript

// /styles/tokens/colors.ts
export const colors = {
  light: {
    primary: '#Extracted from Figma',
    secondary: '#Extracted from Figma',
    background: '#Extracted from Figma',
    foreground: '#Extracted from Figma',
    // ... Other colors
  },
  dark: {
    primary: '#Automatically derived',
    secondary: '#Automatically derived',
    background: '#Automatically derived',
    foreground: '#Automatically derived',
    // ... Automatically generated
  }
}

Dark Mode Derivation Rules:

Background color: Reduce brightness, maintain hue
Foreground color: Increase brightness, ensure contrast ≥ 4.5:1
Accent color: Fine-tune brightness, maintain brand recognition
Border color: Reduce saturation and brightness

2. Typography Specifications

Source: Use typography specifications from Figma files

Implementation: Create a typography token file

/styles/tokens/typography.ts

Includes: Font family, font size, font weight, line height, letter spacing

typescript

// /styles/tokens/typography.ts
export const typography = {
  fontFamily: {
    sans: 'Extracted from Figma',
    serif: 'Extracted from Figma',
    mono: 'Extracted from Figma',
  },
  fontSize: {
    xs: 'Extracted from Figma',
    sm: 'Extracted from Figma',
    base: 'Extracted from Figma',
    lg: 'Extracted from Figma',
    xl: 'Extracted from Figma',
    '2xl': 'Extracted from Figma',
    // ... Other sizes
  },
  fontWeight: {
    normal: 400,
    medium: 500,
    semibold: 600,
    bold: 700,
  },
  lineHeight: {
    tight: 'Extracted from Figma',
    normal: 'Extracted from Figma',
    relaxed: 'Extracted from Figma',
  },
  letterSpacing: {
    tight: 'Extracted from Figma',
    normal: 'Extracted from Figma',
    wide: 'Extracted from Figma',
  },
}

3. Spacing Specifications

Source: Follow spacing definitions in Figma files

Implementation: Create a spacing token file

/styles/tokens/spacing.ts

Optimization: Reasonable optimization is allowed, but users must be informed of what was optimized and why

typescript

// /styles/tokens/spacing.ts
export const spacing = {
  0: '0',
  1: 'Extracted from Figma', // e.g. 4px
  2: 'Extracted from Figma', // e.g. 8px
  3: 'Extracted from Figma', // e.g. 12px
  4: 'Extracted from Figma', // e.g. 16px
  // ... Other spacing values
}

4. Shadow Specifications

Source: Extract shadow effects from Figma

Implementation: Create a shadow token file

/styles/tokens/shadows.ts

typescript

// /styles/tokens/shadows.ts
export const shadows = {
  sm: 'Extracted from Figma',
  md: 'Extracted from Figma',
  lg: 'Extracted from Figma',
  xl: 'Extracted from Figma',
}

Layout Specifications

Principles

Responsive layout first, adaptive approach

Breakpoint Strategy

Priority: Intelligently recommend breakpoints based on Figma designs
Alternative: Use industry-standard breakpoints when Figma has no clear breakpoints

Breakpoint Name	Minimum Width	Usage
`sm`	640px	Landscape mobile
`md`	768px	Portrait tablet
`lg`	1024px	Landscape tablet/small laptop
`xl`	1280px	Desktop monitor
`2xl`	1536px	Large screen monitor

Adaptive Methods

Use CSS Grid and Flexbox for adaptive layouts
Use
```
clamp()
```
function for fluid typography and spacing
Use Container Queries for component-level responsiveness
Use relative units (rem, em, vw, vh, %) instead of fixed pixel values

Figma Intelligent Recommendation Rules

Analyze Auto Layout settings in Figma
Infer responsive behavior based on Figma component Constraints
Identify designs for different breakpoints based on Figma Variants

CSS Styling Best Practices

⚠️ Global Style Pitfall (Important)

Problem: Using

selector to reset margin/padding in

globals.css

will override Tailwind utility classes

Bad Example:

css

/* ❌ Wrong: Will override all Tailwind p-*, m-*, gap-* classes */
* {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

Correct Approach:

css

/* ✅ Correct: Only set box-sizing, let Tailwind utility classes work normally */
*,
*::before,
*::after {
  box-sizing: border-box;
}

Reason: CSS selector priority rules

```
*
```
selector has priority 0
Tailwind utility classes (e.g.,
```
.p-3
```
) also have priority 0 (single class)
When priorities are the same, later-defined styles take effect
If
```
* { padding: 0 }
```
loads after Tailwind, it will override utility classes

Recommended globals.css Structure

css

@import "tailwindcss";

:root {
  --background: #F5F5F5;
  --foreground: #1D2129;
  --surface: #FFFFFF;
  --border: #E5E6EB;
  
  --text-primary: #1D2129;
  --text-secondary: #4E5969;
  --text-tertiary: #86909C;
  
  --primary: #6242FD;
  --primary-hover: #5230E0;
}

.dark {
  --background: #0F172A;
  --foreground: #F9FAFB;
  /* ... dark mode variables */
}

/* ✅ Only set box-sizing, don't reset margin/padding */
*,
*::before,
*::after {
  box-sizing: border-box;
}

html {
  scroll-behavior: smooth;
}

body {
  background: var(--background);
  color: var(--foreground);
  font-family: var(--font-sans);
  min-height: 100vh;
}

Component Width & Grid Layout

Problem: Mismatch between fixed component width and Grid container column width causes overflow

Bad Example:

tsx

// ❌ Wrong: Fixed width may exceed Grid column width
<div className="w-[218px] rounded-xl">

// Grid container
<div className="grid grid-cols-4 gap-4">
  {/* Actual column width may only be 200px */}
</div>

Correct Approach:

tsx

// ✅ Correct: Use w-full to make component adapt to Grid column width
<div className="w-full rounded-xl">

// Grid container
<div className="grid grid-cols-4 gap-4">
  {/* Component will automatically fill the column width */}
</div>

Spacing Debug Checklist

When encountering spacing issues, check in the following order:

Check globals.css: Confirm there's no
```
* { margin: 0; padding: 0; }
```
Check Tailwind classes: Confirm
```
p-*
```
,
```
m-*
```
,
```
gap-*
```
,
```
space-*
```
classes are working
Check Grid layout: Confirm component width matches Grid column width
Check parent container: Confirm parent container's
```
display
```
,
```
gap
```
,
```
padding
```
settings
Use DevTools: Check computed style values

Tailwind Spacing Class Quick Reference

Class Name	Value	Description
`p-3`	12px	padding: 12px
`px-3`	12px	padding-left/right: 12px
`py-3`	12px	padding-top/bottom: 12px
`m-3`	12px	margin: 12px
`mb-3`	12px	margin-bottom: 12px
`gap-3`	12px	gap: 12px (Grid/Flex)
`space-y-3`	12px	margin-top between child elements

Component Library Architecture

Atomic Design Methodology

/components
  /atoms          # Atomic components (Button, Input, Icon...)
  /molecules      # Molecule components (SearchBar, Card...)
  /organisms      # Organism components (Header, Footer...)
  /templates      # Template components
  /pages          # Page components

Component File Structure

/components
  /atoms
    /Button
      Button.tsx        # Component implementation
      Button.types.ts   # Type definitions
      index.ts          # Export

Component Naming Mapping Rules

Requirement: Create

/docs/component-mapping.md

file

Format:

markdown

| Figma Component Name | Code Component Name | File Path |
|-------------|-----------|---------|
| Button/Primary | Button | /components/atoms/Button |
| Button/Secondary | Button | /components/atoms/Button |
| Input/Text | Input | /components/atoms/Input |

Icon Handling

Icon Sources

Figma Icons: Custom icons exported from Figma
Lucide Icon Library: https://lucide.dev/ as supplementary icon library

Implementation Specifications

Figma Icons: SVG componentization, stored in
```
/components/icons/
```
Lucide Icons: Import on demand, Tree-shakable
Customization: Support custom size, color, stroke width

Naming Specifications

Figma exports:
```
Icon[Name].tsx
```
Lucide usage: Direct import
```
import { IconName } from 'lucide-react'
```

Icon Component Interface

tsx

interface IconProps {
  size?: number
  color?: string
  strokeWidth?: number
  className?: string
}

Animation Specifications

Animation Library

Motion: https://motion.dev/ - Production-grade animation library

Performance Optimization

Use
```
willChange
```
to hint browser for optimization
Prioritize using
```
transform
```
property
Avoid animating layout properties (width, height, top, left)

Accessibility

Support

prefers-reduced-motion

media query

Animation Types

Enter animations
Exit animations
Scroll animations
Gesture animations
Layout animations

Motion Usage Example

tsx

import { motion, AnimatePresence } from 'motion/react'

<AnimatePresence>
  {isVisible && (
    <motion.div
      initial={{ opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
      exit={{ opacity: 0, y: -20 }}
      transition={{ duration: 0.3 }}
      style={{ willChange: 'transform, opacity' }}
    />
  )}
</AnimatePresence>

Theme Switching Mechanism

Implementation

CSS Variables: Use CSS custom properties to define colors
Tailwind Dark Mode:
```
darkMode: 'class'
```
configuration
Switching Method: System preference detection + manual switch
Persistence: Store user preferences in localStorage

Theme Provider

tsx

// /components/ThemeProvider.tsx
'use client'
import { createContext, useContext, useEffect, useState } from 'react'

type Theme = 'light' | 'dark'
type ThemeContextType = {
  theme: Theme
  setTheme: (theme: Theme) => void
}

const ThemeContext = createContext<ThemeContextType | undefined>(undefined)

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>('light')
  const [mounted, setMounted] = useState(false)

  useEffect(() => {
    setMounted(true)
    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
    const savedTheme = localStorage.getItem('theme') as Theme | null
    setTheme(savedTheme || (prefersDark ? 'dark' : 'light'))
  }, [])

  useEffect(() => {
    if (mounted) {
      document.documentElement.classList.toggle('dark', theme === 'dark')
      localStorage.setItem('theme', theme)
    }
  }, [theme, mounted])

  if (!mounted) return null

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}

export const useTheme = () => {
  const context = useContext(ThemeContext)
  if (!context) throw new Error('useTheme must be used within ThemeProvider')
  return context
}

Accessibility Specifications

Follow accessibility rules in

web-design-guidelines

skill:

Category	Requirements
Semantic HTML	Use correct HTML elements
ARIA Attributes	Add aria-label, aria-describedby, etc. when necessary
Keyboard Navigation	All interactive elements are accessible via keyboard
Focus Management	Visible focus state, use focus-visible
Color Contrast	Meet WCAG AA standard (4.5:1)

Image Handling

Source: Image resources from Figma
Implementation:
- Use Next.js
```
<Image>
```
  component
- Automatic optimization and lazy loading
- Responsive images
- Provide alt text

Code Style

Category	Specifications
Language	TypeScript (strongly typed definitions)
Component Files	PascalCase (e.g., `Button.tsx` )
Utility Functions	camelCase (e.g., `formatDate.ts` )
Constants	UPPER_SNAKE_CASE (e.g., `API_BASE_URL` )

Workflow

Figma File (MCP)
      ↓
  Extract Design Tokens
  (Colors, Typography, Spacing, Components)
      ↓
  Generate Design System Files
  (tokens/*.ts)
      ↓
  Create Component Mapping File
  (component-mapping.md)
      ↓
  Create Base Components
  (Based on Figma Components)
      ↓
  Apply Best Practices
  (vercel-react-best-practices)
      ↓
  Accessibility & UX Review
  (web-design-guidelines)
      ↓
  Complete Page Implementation

Output File Checklist

When creating a project from Figma each time, the following files should be output:

```
/styles/tokens/colors.ts
```
- Color tokens (including Light/Dark)
```
/styles/tokens/typography.ts
```
- Typography tokens
```
/styles/tokens/spacing.ts
```
- Spacing tokens
```
/styles/tokens/shadows.ts
```
- Shadow tokens
```
/styles/tokens/index.ts
```
- Unified export
```
/styles/globals.css
```
- Global styles
```
/docs/component-mapping.md
```
- Component naming mapping rules
```
/components/ThemeProvider.tsx
```
- Theme provider
```
/tailwind.config.ts
```
- Tailwind configuration (including design tokens)

Trigger Conditions

This skill is automatically applied when:

Users request to create pages/components from Figma designs
Users mention "based on Figma..." or "follow the design draft..."
Users provide Figma file links or MCP data
Users request to create design tokens

Notes

Color Source: All colors must be extracted from Figma, do not use built-in colors from the skill
Spacing Optimization: If spacing optimization is needed, users must be informed of what was optimized and why
Dark Mode: Even if Figma has no Dark mode design, it must be automatically generated
Component Mapping: Component naming mapping file must be created to maintain consistency between Figma and code
Accessibility: All components must meet WCAG AA standards
⚠️ Global Styles: Never use
```
* { margin: 0; padding: 0; }
```
in globals.css, this will override all Tailwind spacing classes
Component Width: Components in Grid layouts should use
```
w-full
```
instead of fixed widths to avoid overflow issues

figma-driven-nextjs

NPX Install

Tags

SKILL.md Content (Chinese)

Figma-Driven Next.js Development Skill

Tech Stack

Core Principles

Figma First

Design Token System

1. Color Specifications

2. Typography Specifications

3. Spacing Specifications

4. Shadow Specifications

Layout Specifications

Principles

Breakpoint Strategy

Adaptive Methods

Figma Intelligent Recommendation Rules

CSS Styling Best Practices

⚠️ Global Style Pitfall (Important)

Recommended globals.css Structure

Component Width & Grid Layout

Spacing Debug Checklist

Tailwind Spacing Class Quick Reference

Component Library Architecture

Atomic Design Methodology

Component File Structure

Component Naming Mapping Rules

Icon Handling

Icon Sources

Implementation Specifications

Naming Specifications

Icon Component Interface

Animation Specifications

Animation Library

Performance Optimization

Accessibility

Animation Types

Motion Usage Example

Theme Switching Mechanism

Implementation

Theme Provider

Accessibility Specifications

Image Handling

Code Style

Workflow

Output File Checklist

Trigger Conditions

Notes