Flujo de Trabajo Autónomo de Figma a React

Resumen

Este skill orquesta el pipeline completo para convertir diseños de Figma en aplicaciones React listas para producción. Extrae sistemas de diseño (colores, tipografía, espaciado, efectos) de Figma, los transforma en configuración de Tailwind CSS y propiedades personalizadas CSS, luego genera componentes React funcionales en TypeScript que reproducen fielmente el diseño fuente.

El flujo de trabajo opera en cuatro fases: descubrimiento interactivo, andamiaje TDD, ejecución autónoma y entrega verificada. El resultado es un conjunto de componentes React, páginas y un sistema de tokens de diseño listo para integrarse en proyectos Next.js, Vite o Remix, verificados con precisión a nivel de píxel contra la fuente de Figma.

Principios Clave:

TDD es obligatorio — los tests se escriben antes que los componentes, nunca después
Cada componente es un componente funcional de TypeScript con interfaces de props explícitas
Todo el estilo usa clases de utilidad de Tailwind respaldadas por tokens de diseño de Figma
Sin valores de color codificados, tamaños de fuente o espaciado — todo referencia al sistema de tokens
Las imágenes usan importaciones adecuadas o referencias del directorio público, nunca rutas rotas
La salida es consciente del framework (Next.js App Router, Vite SPA, rutas de Remix)
Verificación de píxel perfecto — bucle de diferencias automatizado con pixelmatch, no comparación manual
Consciente del tipo de aplicación — las extensiones de Chrome, las PWAs y las aplicaciones web reciben estrategias de test apropiadas

Cuándo Usar

Usa este skill cuando:

Conviertas un archivo de diseño de Figma en una aplicación React
Extraigas un sistema de diseño de Figma en configuración de Tailwind
Generes una biblioteca de componentes a partir de conjuntos de componentes de Figma
Reconstruyas una UI existente a partir de un rediseño de Figma
Inicies un nuevo proyecto React a partir de un prototipo de Figma

Frases de activación:

"Convierte este diseño de Figma a React"
"Genera componentes React a partir de Figma"
"Extrae tokens de diseño de Figma"
"Construye una aplicación React a partir de este archivo Figma"
"Figma a Next.js"
"Figma a Vite"

Fase 1: Descubrimiento (Interactivo)

Esta fase requiere entrada del usuario. No procedas de forma autónoma hasta que el usuario confirme el plan.

Verificación de Integración del Pipeline

Antes de hacer cualquier pregunta, verifica si existen artefactos anteriores:

1. Verificar: .claude/plans/build-spec.json
   → Si existe: OMITIR todas las preguntas de descubrimiento. Cargar la especificación directamente.
   → Registrar: "build-spec.json encontrado de figma-intake — omitiendo descubrimiento"

2. Verificar: src/styles/design-tokens.lock.json
   → Si existe: OMITIR extracción de tokens en Fase 2. Usar valores del lockfile.
   → Registrar: "design-tokens.lock.json encontrado — usando valores de tokens bloqueados"

Si build-spec.json existe, salta directamente a la Fase 2 con el framework, componentes y opciones de la especificación precargados.

Paso 1.1: Recopilar Contexto de Figma

Usa el MCP de Figma para inspeccionar el archivo de diseño.

1. get_metadata        — Nombre del archivo, páginas, última modificación, conteos de componentes
2. get_variable_defs   — Tokens de diseño (colores, tipografía, espaciado, efectos)
3. get_design_context  — Estructura de diseño, jerarquía de componentes, configuraciones de auto-layout
4. get_screenshot      — Referencia visual para cada página/frame

Paso 1.2: Extraer Tokens de Diseño

Mapea las variables y estilos de Figma a una estructura de tokens:

Tokens de Diseño
├── Colores
│   ├── Primitivos (blue-500, gray-100, etc.)
│   ├── Semánticos (primary, secondary, destructive, muted)
│   └── Específicos de componentes (card-bg, button-primary, input-border)
├── Tipografía
│   ├── Familias de fuentes (con stacks de respaldo)
│   ├── Tamaños de fuente (escala: xs hasta 5xl)
│   ├── Pesos de fuente
│   ├── Alturas de línea
│   └── Espaciado de letras
├── Espaciado
│   ├── Unidad base
│   └── Escala (0.5 a 96)
├── Radio de Borde
│   ├── Escala (sm, md, lg, xl, full)
│   └── Anulaciones específicas de componentes
├── Sombras / Efectos
│   ├── Sombras de caja (sm, md, lg, xl)
│   └── Sombras de gota
└── Puntos de Corte
    └── Móvil, tableta, escritorio, ancho

Paso 1.3: Inspeccionar Componentes

Identifica todos los componentes de Figma y mapealos a componentes React:

Componente Figma	Componente React	Categoría
Button/Primary	`<Button variant="primary">`	Primitivos
Card	`<Card>`	Contenedores
Navigation/Header	`<Header>`	Diseño
Hero Section	`<HeroSection>`	Secciones
Input/Text	`<Input type="text">`	Formularios

Paso 1.4: Confirmar Destino de Salida

Pide al usuario que confirme:

Framework: Next.js (App Router), Next.js (Pages Router), Vite o Remix
Enfoque de estilo: Tailwind CSS (predeterminado), CSS Modules o styled-components
Base de biblioteca de componentes: shadcn/ui, Radix UI, Headless UI o ninguno
Gestión de estado: Estado React, Zustand, Jotai o ninguno
Directorio de salida: p.ej., src/components/, app/, etc.

Presenta el inventario de componentes y el resumen de tokens para la aprobación del usuario antes de proceder.

Fase 2: Ejecución (Autónoma)

Una vez que el usuario aprueba el plan de descubrimiento, procede de forma autónoma a través de todos los pasos.

Restricción del Lockfile de Tokens

Si src/styles/design-tokens.lock.json existe, TODO el código generado DEBE referenciar los valores del lockfile:

Colores: Usa clases de Tailwind mapeadas en el lockfile, nunca valores hex aproximados
Tipografía: Usa familias de fuentes, tamaños y pesos exactos del lockfile
Espaciado: Usa valores de escala de espaciado del lockfile
Contenido de texto: Usa cadenas exactas de lockfile.textContent

Nunca aproximes o adivines valores cuando exista un lockfile. Si un valor no está en el lockfile, agrégalo al lockfile primero, luego refiérete a él.

Puerta de Primero los Tests (OBLIGATORIO)

TDD está forzado. La implementación del componente NO DEBE comenzar hasta que existan archivos de test. Esta es una puerta estricta, no una sugerencia.

ANTES de escribir cualquier implementación de componente:

  1. Ejecutar: ./scripts/verify-test-coverage.sh
     → Si código de salida 1: DETENER. Invocar primero el skill tdd-from-figma.
     → Si código de salida 0: Proceder a la implementación.

  2. Para cada componente a generar:
     a. REQUERIR: src/components/**/{ComponentName}.test.tsx existe
        → Si falta: DETENER. Escribir el test primero (invocar tdd-from-figma).
        → Esto no es opcional. Ningún componente se envía sin tests preexistentes.
     b. Leer el archivo de test para entender el comportamiento esperado
     c. La implementación DEBE hacer que todos los tests pasen
     d. Ejecutar: pnpm vitest run {test-file} después de escribir el componente
     e. Si el test falla: arreglar el componente, NO el test

  3. Después de que todos los componentes de un lote estén escritos:
     → Ejecutar: pnpm vitest run --reporter=verbose
     → TODOS los tests deben pasar (fase Verde) antes de proceder
     → Si alguno falla: arreglar los componentes hasta que estén en verde. No proceder a la Fase 3.

  4. Verificar que la cobertura de tests cumpla con el umbral:
     → Ejecutar: pnpm vitest run --coverage
     → Debe cumplir: pipeline.config.json → tdd.coverageThreshold (predeterminado: 80%)

Por qué existe esta puerta: Los tests codifican valores exactos del lockfile (contenido de texto, roles ARIA, estructura del componente). Sin tests preescritos, no hay mecanismo para verificar que la implementación coincida con el diseño. Los tests son el contrato entre el diseño de Figma y el código React.

Paso 2.1: Generar Configuración de Tailwind

Crear o extender tailwind.config.ts con los tokens extraídos:

// tailwind.config.ts
import type { Config } from "tailwindcss";

const config: Config = {
  content: ["./src/**/*.{ts,tsx}", "./app/**/*.{ts,tsx}"],
  theme: {
    extend: {
      colors: {
        // Tokens semánticos mapeados desde variables de Figma
        primary: {
          DEFAULT: "var(--color-primary)",
          foreground: "var(--color-primary-foreground)",
          // ... escala completa
        },
        // ... todos los tokens de color
      },
      fontFamily: {
        sans: ["var(--font-sans)", "system-ui", "sans-serif"],
        heading: ["var(--font-heading)", "system-ui", "sans-serif"],
      },
      fontSize: {
        // Mapeado desde estilos de tipografía de Figma
      },
      spacing: {
        // Mapeado desde variables de espaciado de Figma
      },
      borderRadius: {
        // Mapeado desde tokens de radio de esquina de Figma
      },
      boxShadow: {
        // Mapeado desde estilos de efecto de Figma
      },
    },
  },
  plugins: [],
};

export default config;

Generar un archivo CSS acompañante con propiedades personalizadas:

/* src/styles/tokens.css */
:root {
  /* Colores - Primitivos */
  --color-blue-500: #3b82f6;
  /* ... */

  /* Colores - Semánticos */
  --color-primary: var(--color-blue-500);
  --color-primary-foreground: #ffffff;
  /* ... */

  /* Tipografía */
  --font-sans: "Inter", system-ui, sans-serif;
  --font-heading: "Plus Jakarta Sans", system-ui, sans-serif;
  /* ... */
}

Paso 2.2: Generar Componentes React

Para cada componente identificado en la Fase 1, generar:

Estructura de archivos por componente:

src/components/
├── ui/
│   ├── button.tsx          # Componentes primitivos
│   ├── input.tsx
│   ├── card.tsx
│   └── ...
├── layout/
│   ├── header.tsx          # Componentes de diseño
│   ├── footer.tsx
│   └── ...
├── sections/
│   ├── hero-section.tsx    # Secciones de página
│   ├── features-grid.tsx
│   └── ...
└── pages/                  # Composiciones de página completa (o app/ para Next.js)
    ├── home-page.tsx
    └── ...

Plantilla de componente:

// src/components/ui/button.tsx
import { type ButtonHTMLAttributes, forwardRef } from "react";
import { cn } from "@/lib/utils";

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary" | "outline" | "ghost";
  size?: "sm" | "md" | "lg";
}

const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant = "primary", size = "md", ...props }, ref) => {
    return (
      <button
        ref={ref}
        className={cn(
          "inline-flex items-center justify-center rounded-md font-medium transition-colors",
          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary",
          "disabled:pointer-events-none disabled:opacity-50",
          {
            "bg-primary text-primary-foreground hover:bg-primary/90": variant === "primary",
            "bg-secondary text-secondary-foreground hover:bg-secondary/90": variant === "secondary",
            "border border-input bg-transparent hover:bg-accent": variant === "outline",
            "hover:bg-accent hover:text-accent-foreground": variant === "ghost",
          },
          {
            "h-8 px-3 text-sm": size === "sm",
            "h-10 px-4 text-sm": size === "md",
            "h-12 px-6 text-base": size === "lg",
          },
          className
        )}
        {...props}
      />
    );
  }
);
Button.displayName = "Button";

export { Button, type ButtonProps };

Reglas para la generación de componentes:

Todos los componentes son funcionales con forwardRef cuando sea apropiado
Cada componente tiene una interfaz de TypeScript explícita para props
Todo el estilo usa clases de Tailwind que referencian valores de tokens
Los componentes aceptan una prop className para composición
Usa la función cn() (clsx + tailwind-merge) para fusionar clases
Incluye atributos ARIA apropiados para elementos interactivos
Exporta tanto el componente como su tipo de props

Paso 2.3: Generar Composiciones de Página

Compone componentes de sección en páginas completas que coincidan con los frames de Figma:

// app/page.tsx (Next.js App Router)
import { Header } from "@/components/layout/header";
import { HeroSection } from "@/components/sections/hero-section";
import { FeaturesGrid } from "@/components/sections/features-grid";
import { Footer } from "@/components/layout/footer";

export default function HomePage() {
  return (
    <div className="flex min-h-screen flex-col">
      <Header />
      <main className="flex-1">
        <HeroSection />
        <FeaturesGrid />
      </main>
      <Footer />
    </div>
  );
}

Paso 2.4: Manejar Imágenes y Recursos

Para imágenes estáticas de Figma:

// Next.js - usar next/image
import Image from "next/image";
import heroImage from "@/assets/images/hero.webp";

<Image src={heroImage} alt="Ilustración de héroe" width={1200} height={600} priority />

// Vite - usar importaciones estándar
import heroImage from "@/assets/images/hero.webp";

<img src={heroImage} alt="Ilustración de héroe" width={1200} height={600} loading="eager" />

Reglas:

Exportar imágenes de Figma a 1x y 2x para retina
Usar formato WebP con respaldo JPEG/PNG
Colocar en public/images/ o src/assets/images/
Cada <img> debe tener un atributo alt significativo
Las imágenes de héroe/sobre el pliegue usan priority (Next.js) o loading="eager"
Las imágenes bajo el pliegue usan loading="lazy"

Paso 2.5: Generar Archivos de Utilidad

src/lib/
├── utils.ts          # Ayudante cn(), formateadores
└── fonts.ts          # Carga de fuentes (Next.js: next/font, Vite: @fontsource)

Paso 2.6: Ejecutar Tests (si existen archivos de test)

Después de generar todos los componentes, si los archivos de test fueron escritos por tdd-from-figma:

pnpm vitest run --reporter=verbose

Si los tests fallan: Arreglar la implementación del componente para que coincida con las expectativas del test. Los tests son autoritativos — codifican valores exactos del lockfile. No modificar los tests para que coincidan con la implementación.

Iterar hasta que todos los tests pasen (fase Verde de TDD).

Paso 2.7: Generar Historias de Storybook (No Bloqueante)

Una vez que los componentes están construidos y sus tests unitarios pasan, generar automáticamente historias de Storybook y documentación MDX. Invocar el skill storybook-story-generation (o ejecutar el script directamente). Esto es la Fase 4.5 del pipeline y es no bloqueante — un fallo aquí registra una advertencia y el pipeline continúa.

# Generar .stories.tsx + .mdx para cada componente (omite los que ya tienen historias)
./scripts/generate-stories.sh

# Vista previa sin escribir, o regeneración forzada

…

[truncado para traducción]

PMDevSolutions/Aurelius

¿Qué es Aurelius?

Preguntar en tu IA favorita

Documentación