Extraer Sistema de Diseño desde Código Frontend

¿Qué hace Extraer Sistema de Diseño desde Código Frontend?

Analiza el código fuente frontend para extraer un documento de sistema de diseño completo (DESIGN.md) que capture el lenguaje visual del proyecto — colores, tipografía, espaciado, patrones de componentes y principios de layout — directamente desde los archivos fuente, sin necesidad de construir o renderizar la aplicación.

Por Qué Existe

La habilidad design-md funciona a partir de HTML renderizado. Pero a menudo tienes un código base y quieres entender su sistema de diseño antes de poder ejecutar la aplicación — tal vez faltan dependencias, la compilación está rota, o simplemente quieres una auditoría rápida. Esta habilidad lee los propios archivos fuente: hojas de estilo, archivos de componentes, configuraciones de tema y configuraciones de Tailwind. Es más rápida y funciona en cualquier lugar.

Cuándo Usar

• El usuario tiene un código base frontend y quiere extraer o documentar su sistema de diseño
• El usuario quiere migrar la identidad visual de un proyecto a Stitch
• El usuario pide "auditar el estilo" o "entender el lenguaje de diseño" de un repositorio
• El usuario quiere crear un DESIGN.md a partir del código fuente existente
• La aplicación no se puede construir/renderizar pero el código fuente está disponible
• El usuario quiere unificar o conciliar estilos inconsistentes en un código base

Prerrequisitos

• Acceso al directorio fuente del proyecto frontend
• No se necesitan dependencias de compilación o tiempo de ejecución — esta habilidad solo lee archivos fuente

---

Flujo de Trabajo

Fase 1: Descubrimiento del Proyecto

Comienza por entender con qué estás trabajando. Esto determina qué patrones de extracción usar.

1. Detectar el Framework y el Stack

Escanea la raíz del proyecto en busca de archivos reveladores:

Archivo Señal	Framework / Herramienta
package.json con react	React / Next.js
package.json con vue	Vue / Nuxt
package.json con svelte	Svelte / SvelteKit
package.json con @angular/core	Angular
tailwind.config.js/ts	Tailwind CSS
postcss.config.js	Pipeline PostCSS
styled-components o @emotion en dependencias	CSS-in-JS
Solo archivos .css / .scss / .less	CSS / SASS plano
theme.js / theme.ts / tokens.js	Archivos de tokens de diseño

Lee primero package.json — revela el framework, las herramientas CSS y cualquier biblioteca de tokens de diseño (por ejemplo, style-dictionary, @chakra-ui/react, @mui/material, ant-design). Este contexto te dice dónde buscar información de estilo.

2. Mapear el Árbol de Fuentes

Identifica los directorios y archivos clave que analizarás:

src/
├── components/     ← Estilos a nivel de componentes
├── styles/         ← Hojas de estilo globales
├── theme/          ← Definiciones de tema, tokens
├── assets/         ← Fuentes, imágenes
├── app.css         ← Estilos raíz
└── index.css       ← CSS de entrada

También verifica:

• tailwind.config.js / tailwind.config.ts — Colores, fuentes, espaciado personalizados
• globals.css / global.css — Propiedades personalizadas CSS (variables)
• Archivos theme.* o tokens.*
• Configuración de bibliotecas de componentes (por ejemplo, chakra-theme.ts, vuetify.config.ts)

3. Leer la Guía Específica del Framework

Consulta la referencia apropiada para patrones de extracción:

• React / Next.js / Tailwind → references/react-tailwind.md
• Vue / Nuxt → references/vue.md
• Svelte / SvelteKit → references/svelte.md
• Angular → references/angular.md
• CSS Plano / SASS / Less → references/plain-css.md

Estas referencias contienen patrones específicos del framework para localizar colores, tipografía, espaciado y estilos de componentes. Lee la que coincida antes de proceder.

---

Fase 2: Extracción Profunda

Trabaja a través de cada dimensión de diseño de manera sistemática. Para cada una, recopila datos brutos de los archivos fuente, luego sintetízalos en lenguaje descriptivo.

El objetivo no es volcar cada propiedad CSS — es entender la intención detrás de las elecciones de estilo y describirlas en lenguaje humano y editorial que otro diseñador (o Stitch) pueda usar para recrear la misma sensación visual.

1. Tema Visual y Atmósfera

Lee primero los estilos más amplios para entender el estado de ánimo general:

• Fondo raíz: ¿Cuál es el fondo del body o elemento raíz? Crema claro (rango #f) indica aireado/limpio; oscuro (rango #0-#2) indica melancólico/dramático.
• Filosofía del espacio en blanco: ¿Los valores de espaciado son generosos (32px+) o ajustados? Verifica los valores de padding/margin en contenedores raíz, envoltorios de sección y componentes de tarjeta.
• Densidad: Cuenta los componentes por página/sección. Pocos con espacio = minimalista; muchos apretados = denso en información.
• Temperatura de color: ¿Los neutros son cálidos (cremas, tostados) o fríos (grises azulados, pizarras)?
• Sensación general: Sintetiza en 1-2 frases ricas que capturen el estado de ánimo.

Busca estas señales en el código fuente:

Ubicación de la Fuente	Qué Te Dice
background-color raíz o bg-* de Tailwind en layouts	Luminosidad/oscuridad general
Escala de espaciado en configuración de Tailwind o variables CSS	Filosofía del espacio en blanco
Número de componentes vs. padding del envoltorio	Densidad
Nomenclatura de propiedades personalizadas (--warm-* vs --cool-*)	Intención de temperatura de color
Comentarios en archivos de tema	Intención de diseño en palabras del desarrollador

2. Paleta de Colores y Roles

Extrae cada color único del código base y asigna roles funcionales. Busca en todas las capas:

Dónde encontrar colores:

Capa	Qué Buscar
Propiedades personalizadas CSS	--color-*, --primary, --bg-*
Configuración de Tailwind	theme.extend.colors
Archivos de tema/tokens	Objetos de color, paletas
Estilos de componentes	background-color, color, border-color
Estilos en línea / scoped	Clases bg-*, text-* en plantillas
Objetos de tema CSS-in-JS	Claves colors, palette

Cómo organizar: Agrupa los colores por función, no por matiz:

1. Fundación Primaria — Colores de fondo y superficie
2. Acento e Interactivo — Botones CTA, estados activos, enlaces
3. Tipografía y Jerarquía de Texto — Texto primario, secundario, terciario
4. Estados Funcionales — Éxito, error, advertencia, información

Para cada color, crea un nombre descriptivo que evoque el carácter del color en lugar de su valor hexadecimal bruto:

• ❌ #294056 → "Azul"
• ✅ #294056 → "Azul Marino Teal Apagado Profundo" — CTA primario, navegación activa

La deduplicación importa. Los códigos base a menudo tienen colores casi duplicados (por ejemplo, #333 y #2C2C2C). Consolídalos bajo un nombre que mejor represente el color previsto.

3. Reglas Tipográficas

Extrae el sistema tipográfico completo:

Familias de fuentes:

• Verifica CSS font-family, fontFamily de Tailwind, enlaces de Google Fonts o declaraciones @font-face locales.
• Nota el carácter de cada fuente: geométrico vs. humanista, serif vs. sans, la sensación que evoca.

Escala tipográfica (jerarquía):

• Encuentra cada nivel de encabezado (H1-H6) y texto del cuerpo, anotando:
  • font-size (en rem o px)
  • font-weight (valor numérico + nombre descriptivo)
  • letter-spacing (y por qué — elegancia? compacidad?)
  • line-height (generoso para legibilidad? ajustado para display?)
• Mapa de uso en componentes: ¿Qué nivel de encabezado usan las tarjetas de producto? ¿Y las secciones de héroe?

Principios de espaciado:

• ¿Cómo se relaciona el espaciado del texto con la escala de espaciado general?
• Patrones de interletraje en encabezados vs. cuerpo
• Filosofía de altura de línea (generosa/relajada para cuerpo, más ajustada para display)

4. Estilizaciones de Componentes

Analiza los 4-5 primitivas de UI más importantes:

Botones:

• Radio de esquina (y qué comunica — divertido? profesional? minimalista?)
• Esquema de colores para variantes primaria, secundaria y ghost
• Estados hover/focus/active y temporización de transiciones
• Relaciones de padding (horizontal vs. vertical)

Tarjetas / Contenedores:

• Radio de esquina (a menudo diferente de los botones — ligeramente más redondeado)
• Estrategia de sombra: plana, sombras sutiles en hover, o siempre elevado?
• Tratamiento de bordes: bordes finos, acentos de color o ninguno?
• Padding interno (generoso o compacto?)
• Tratamiento de imágenes dentro de tarjetas (a sangre completa, con padding, redondeadas?)

Navegación:

• Patrón de layout (barra horizontal, barra lateral vertical, cajón)
• Tratamiento tipográfico (mayúsculas, interletraje, peso)
• Indicadores de estado activo/hover (subrayado, color, fondo)
• Comportamiento móvil (hamburguesa, navegación inferior, cajón)

Entradas y Formularios:

• Estilo de borde y comportamiento del estado focus
• Consistencia del radio de esquina con los botones
• Tamaño de padding y objetivo táctil

Componentes Específicos del Dominio:

• Identifica 1-2 componentes únicos de este proyecto (por ejemplo, tarjetas de producto, widgets de tablero, burbujas de chat) y describe sus patrones de estilo.

5. Principios de Layout

Extrae el sistema estructural:

Cuadrícula y Estructura:

• Ancho máximo de contenido (de max-width en contenedores)
• Sistema de columnas (CSS Grid, patrones Flexbox, puntos de interrupción definidos)
• Puntos de interrupción responsivos (de media queries o configuración de Tailwind)

Estrategia de Espacio en Blanco:

• Unidad base de espaciado (¿cuadrícula de 8px? ¿4px? ¿personalizada?)
• Márgenes de sección (cuánto espacio entre secciones principales)
• Padding de borde (márgenes de página en diferentes puntos de interrupción)

Alineación y Equilibrio Visual:

• Patrones de alineación de texto (héroes centrados, cuerpo alineado a la izquierda)
• Proporciones de imagen a texto
• Distribución del peso visual

Comportamiento Responsivo:

• ¿Móvil primero o escritorio primero?
• ¿Cómo colapsan las cuadrículas? ¿Escala de padding?
• Tamaño de objetivo táctil

6. Notas de Generación para Stitch

Sintetiza la extracción en prompts accionables para Stitch:

• Lenguaje de atmósfera: Traduce el estado de ánimo en descriptores naturales
• Referencias de color: Lista colores por nombre descriptivo + hexadecimal
• Prompts de componentes: Escribe 2-3 ejemplos de prompts que recrearían componentes clave en Stitch
• Guía de iteración: Consejos para refinar pantallas en este sistema de diseño

---

Fase 3: Escribir el DESIGN.md

Ensambla todo en el formato estándar de DESIGN.md. Colócalo en .stitch/DESIGN.md en el directorio del proyecto (crea el directorio .stitch/ si no existe).

[!IMPORTANTE] DEBES incluir el frontmatter YAML al principio del archivo con el mapeo de name y colors, exactamente como se muestra en el ejemplo en examples/DESIGN.md. Estos datos estructurados son necesarios para que otras habilidades interpreten el sistema de diseño.

No incluir este bloque YAML con al menos los tokens de color principales es un fallo al usar esta habilidad correctamente.

Usa el formato del ejemplo en examples/DESIGN.md como plantilla. El archivo debe comenzar con el bloque YAML, seguido de las secciones markdown:

# Sistema de Diseño: [Nombre del Proyecto]
**ID del Proyecto:** [Si se conoce, de lo contrario omitir]

## 1. Tema Visual y Atmósfera
[Descripción rica de 2 párrafos sobre el estado de ánimo, filosofía y características clave]

## 2. Paleta de Colores y Roles
### Fundación Primaria
### Acento e Interactivo
### Tipografía y Jerarquía de Texto
### Estados Funcionales

## 3. Reglas Tipográficas
### Jerarquía y Pesos
### Principios de Espaciado

## 4. Estilizaciones de Componentes
### Botones
### Tarjetas y [Contenedores Específicos del Dominio]
### Navegación
### Entradas y Formularios
### [Componentes Específicos del Dominio]

## 5. Principios de Layout
### Cuadrícula y Estructura
### Estrategia de Espacio en Blanco
### Alineación y Equilibrio Visual
### Comportamiento Responsivo y Táctil

## 6. Notas del Sistema de Diseño para la Generación en Stitch
### Lenguaje a Usar
### Referencias de Color
### Prompts de Componentes
### Iteración Incremental

---

Fase 4: Integración (Opcional)

Si el usuario quiere enviar el sistema de diseño a Stitch:

1. Pasa el control a la habilidad manage-design-system para las llamadas de creación/actualización MCP
2. El DESIGN.md que escribiste es la entrada — la habilidad manage-design-system maneja la integración con la API de Stitch

Si el usuario solo quiere el documento, has terminado después de la Fase 3.

---

Lista de Verificación de Calidad

Antes de entregar el DESIGN.md, verifica:

• Cada color tiene un nombre descriptivo, código hexadecimal y rol funcional
• La tipografía incluye familia de fuentes, descripción del carácter y jerarquía completa
• Los estilos de componentes describen forma, color, estados y transiciones
• El layout incluye ancho máximo, cuadrícula, puntos de interrupción y estrategia de espaciado
• Las notas de generación de Stitch usan lenguaje natural, no sintaxis CSS
• La sección de atmósfera se lee como texto editorial, no como documentación técnica
• Los colores casi duplicados están consolidados
• El documento captura la intención detrás del estilo, no solo valores brutos

Consejos para una Mejor Extracción

• Lee comentarios y mensajes de commit. Los desarrolladores a menudo documentan la intención de diseño en comentarios de código (/* sección hero — respirable */) y mensajes de commit. Son oro para entender el por qué.
• Verifica bibliotecas de tokens de diseño. Si el proyecto usa style-dictionary, @tokens-studio o similar, estos archivos son la fuente más autorizada de valores de diseño.
• Los archivos de tema tienen mayor señal que los estilos de componentes. Un theme.ts que define una paleta te dice el sistema de diseño previsto; los estilos en línea dispersos en componentes te dicen lo que realmente se envió. Ambos importan, pero empieza por el tema.
• La configuración de Tailwind es un sistema de diseño. Si un proyecto tiene un tailwind.config.js personalizado, ese es el sistema de diseño — extrae de él primero, luego verifica puntualmente los componentes para detectar anulaciones.
• Las propiedades personalizadas CSS son intencionales. Si un desarrollador definió --brand-primary, te está diciendo que esto es un token de diseño. Respeta eso.