# DESIGN.md Extractor: analiza el diseño de cualquier web con Claude > Guía práctica y completa sobre el skill DESIGN.md Extractor para Claude Code: extracción de tokens visuales, generación de DESIGN.md, vista previa interactiva en HTML y exportación a Tailwind CSS. ## 1. Qué es DESIGN.md Extractor y por qué extraer sistemas de diseño En el desarrollo web moderno, los sistemas de diseño suelen ser inaccesibles o encontrarse fragmentados: encerrados en archivos privados de Figma, dispersos en decenas de hojas de estilo CSS o presentes solo en la memoria del diseñador principal. Cuando un desarrollador necesita crear una interfaz inspirada en un referente visual o adoptar con rapidez la identidad gráfica del cliente, a menudo pierde horas tomando muestras con el cuentagotas en DevTools y midiendo los radios de los botones con reglas en pantalla. **DESIGN.md Extractor** es un skill especializado para Claude Code que automatiza la ingeniería inversa de interfaces web. El agente analiza una página en vivo, lee los tokens de diseño directamente del DOM y de los estilos calculados en CSS, y genera un artefacto estructurado `DESIGN.md` junto con un catálogo visual autónomo, `design-preview.html`. ```mermaid flowchart TD A["URL o nombre de marca objetivo
'stripe.com'"] --> B["Claude Code + design-md-extractor"] B --> C["DOM & CSS Parser
(Lectura de variables :root, cálculo de estilos)"] C --> D["Extracción de 4 dimensiones de tokens
(Colores, tipografía, espaciado, formas)"] D --> E["Generación de DESIGN.md
(Especificación YAML + resumen de diseño)"] D --> F["Compilación de design-preview.html
(UI kit offline basado en tokens puros)"] E & F --> G["Exportación a Tailwind CSS / Figma / Código base"] ``` ### Inspección manual frente a extracción con el skill | Fase de trabajo | Inspección manual en DevTools | Flujo con DESIGN.md Extractor | | :--- | :--- | :--- | | **Extracción de paleta** | Copiar manualmente decenas de reglas `color` y `background` | Extracción automática de la jerarquía completa (~35 tokens) desde `:root` | | **Análisis tipográfico** | Medición aislada de `font-size` en encabezados sueltos | Escala estandarizada de 7 niveles con interlineado y tracking | | **Cuadrícula y espaciado** | Estimaciones subjetivas de márgenes y rellenos | Paso matemático exacto de la cuadrícula modular (ej. base de 8px) | | **Formato de salida** | Notas desordenadas en bloc de notas o capturas de pantalla | Especificación estructurada `DESIGN.md` y UI kit interactivo en HTML | | **Tiempo de dedicación** | De 3 a 6 horas de trabajo monótono | Menos de 60 segundos por ciclo completo | > [!NOTE] > El skill interactúa con el código público del cliente y extrae los parámetros reales con los que el navegador renderiza la interfaz, eliminando suposiciones o interpretaciones inexactas. --- ## 2. Arquitectura y principio de funcionamiento: de la URL al sistema de diseño El pipeline de extracción opera a través de fases interconectadas diseñadas para garantizar la fidelidad de los datos. ### Algoritmo de análisis paso a paso 1. **Carga y renderizado de la página:** Claude accede a la URL indicada y recupera el documento HTML completo junto con sus hojas de estilo vinculadas. 2. **Lectura de variables globales `:root`:** El agente identifica las propiedades personalizadas declaradas en CSS (`--color-primary`, `--font-sans`, `--spacing-unit`, `--radius-lg`). 3. **Cálculo de Computed Styles:** Para elementos sin variables CSS explícitas, el script evalúa componentes clave (botones, títulos, campos de texto, barras de navegación) y extrae sus estilos computados reales. 4. **Normalización y estandarización:** Los valores cromáticos se convierten a formatos estándar HEX u OKLCH, mientras que las fuentes se contrastan con Google Fonts o las pilas tipográficas del sistema. 5. **Generación de artefactos:** Se genera la especificación formal `DESIGN.md` y se compila la página de vista previa autónoma `design-preview.html`. > [!TIP] > En sitios construidos con frameworks utilitarios como Tailwind CSS, el skill detecta clases como `p-4`, `rounded-xl` y `bg-slate-900` para reconstruir la configuración de tema correspondiente. --- ## 3. Cuatro dimensiones de tokens visuales: colores, tipografía, espaciado y formas DESIGN.md Extractor organiza los tokens de diseño en cuatro categorías principales, estructurando un lenguaje visual unificado. ### Paleta de colores (Colors) El extractor produce una paleta ampliada de aproximadamente 35 tokens funcionales siguiendo los patrones de Material Design 3 y Radix UI: - **Acentos de marca:** `primary`, `secondary`, `tertiary`, con sus pares de alto contraste `on-primary` y `on-secondary`. - **Superficies y contenedores:** `background`, `surface`, `surface-variant`, `surface-container` (del nivel base a modales superpuestos). - **Estados del sistema:** `error`, `warning`, `success`, `info`, junto con los textos contrastantes requeridos para accesibilidad. - **Tonos neutros:** `outline`, `outline-variant`, `scrim` y `shadow`. ### Jerarquía tipográfica (Typography) La tipografía se formaliza en siete escalas funcionales estandarizadas: | Nivel de token | Uso principal | Tamaño habitual | Altura de línea | Peso visual | | :--- | :--- | :--- | :--- | :--- | | **`headline-xl`** | Títulos principales, Hero H1 | 48px – 64px | 1.1 – 1.15 | Bold / ExtraBold | | **`headline-lg`** | Encabezados de sección H2 | 32px – 40px | 1.2 | SemiBold | | **`title-md`** | Títulos de tarjetas H3 | 20px – 24px | 1.3 | Medium / SemiBold | | **`body-lg`** | Párrafos introductorios, subtítulos | 18px | 1.5 – 1.6 | Regular | | **`body-md`** | Texto general del cuerpo | 15px – 16px | 1.5 – 1.6 | Regular | | **`label-md`** | Botones, pestañas, insignias | 13px – 14px | 1.2 – 1.4 | Medium | | **`label-sm`** | Textos de apoyo, notas al pie | 11px – 12px | 1.3 | Regular / Medium | ### Cuadrícula modular y espaciado (Spacing) El skill determina el incremento base del espaciado (habitualmente 4px u 8px) y genera una escala armónica: - `xs` (4px), `sm` (8px), `md` (16px), `lg` (24px), `xl` (32px), `2xl` (48px). - También se registran parámetros estructurales globales: ancho máximo del contenedor (`max-width: 1280px`) y márgenes laterales seguros (`gutter: 24px`). ### Geometría y elevación (Shapes & Elevation) - **Radios de borde:** Escala de curvatura desde `none` (0px) hasta `full` (9999px para avatares redondos y botones píldora). - **Sombras de elevación:** Tokens de sombreado multicapa (`shadow-sm`, `shadow-md`, `shadow-xl`) que recrean la elevación física de los componentes sobre el fondo. --- ## 4. Anatomía del artefacto DESIGN.md: especificación YAML y secciones descriptivas El archivo `DESIGN.md` es un documento híbrido: la parte superior define una estructura YAML estricta para linters y compiladores, mientras que la parte inferior contiene una guía de diseño detallada para personas y agentes de IA. ### Estructura de ejemplo del frontmatter YAML ```yaml --- name: "Acme Cloud Platform" extractedFrom: "https://acme.example.com" version: "1.0.0" colors: primary: "#4F46E5" on-primary: "#FFFFFF" primary-container: "#EEF2FF" secondary: "#06B6D4" background: "#0F172A" surface: "#1E293B" surface-variant: "#334155" on-surface: "#F8FAFC" outline: "#475569" typography: fontFamilySans: "'Inter', -apple-system, sans-serif" fontFamilyMono: "'JetBrains Mono', monospace" headline-xl: fontSize: "48px" lineHeight: "1.1" fontWeight: "800" letterSpacing: "-0.02em" body-md: fontSize: "16px" lineHeight: "1.5" fontWeight: "400" letterSpacing: "0em" spacing: base: "8px" sm: "8px" md: "16px" lg: "24px" xl: "32px" shapes: borderRadiusSm: "4px" borderRadiusMd: "8px" borderRadiusLg: "16px" borderRadiusFull: "9999px" --- ``` ### Siete secciones descriptivas en prosa Bajo el bloque YAML, el archivo incluye 7 capítulos técnicos detallados: 1. **Brand & Style Personality:** Tono de la marca (ej. *"Minimalismo de ingeniería estricto al estilo Linear"* o *"Estética fintech cálida al estilo Stripe"*). 2. **Color Palette Rationale:** Reglas de combinación de color y cumplimiento de contraste accesible WCAG AA. 3. **Typography Rhythm:** Reglas de ritmo vertical, interlineado y jerarquía de títulos. 4. **Layout & Spacing Philosophy:** Principios de cuadrícula, relleno de componentes y puntos de ruptura responsive. 5. **Elevation & Depth:** Uso de capas superpuestas, gradientes sutiles y desenfoques de fondo (backdrop-filter blur). 6. **Shape & Border Language:** Consistencia en radios de curvatura y grosores de trazo. 7. **Component Blueprints:** Patrones listos para implementar en botones, tarjetas, campos de formulario y barras de navegación. --- ## 5. Vista previa interactiva: arquitectura de design-preview.html Junto con el archivo `DESIGN.md`, el skill genera `design-preview.html`, que actúa como un escaparate visual offline e interactivo. ```mermaid flowchart LR subgraph design_preview_html["design-preview.html (Escaparate Offline)"] P["Muestras de color
(Clic copia HEX/RGB)"] T["Exhibidor tipográfico
(Vista previa con Google Fonts)"] C["UI Sandbox
(Botones, tarjetas, formularios)"] S["Pantalla demo
(Mockup sintetizado)"] end design_preview_html --> B["Apertura en cualquier navegador
(Sin node_modules ni servidor local)"] ``` ### Ventajas principales de la vista previa autónoma - **Cero dependencias:** No requiere Node.js ni empaquetadores. Se abre con doble clic directamente en el explorador de archivos. - **Recursos embebidos:** Iconos y gráficos integrados en formato Inline SVG o Base64, garantizando operatividad total sin conexión a internet. - **Copia de tokens en un clic:** Al hacer clic en cualquier muestra de color, el valor HEX o la variable CSS se copia de inmediato al portapapeles. - **Estados interactivos completos:** Todos los componentes muestran estados nativos `:hover`, `:focus-visible`, `:active` y `:disabled`. --- ## 6. Instalación y ejecución del skill en Claude Code El skill `design-md-extractor` se activa mediante lenguaje natural o llamadas directas por comando slash. ### Comandos de ejecución en terminal :::tabs @tab Por URL directa ```text /design-md-extractor https://linear.app ``` @tab Por nombre de marca ```text Create a comprehensive DESIGN.md and preview for Stripe dashboard ``` @tab Prototipo local o servidor dev ```text Analyze the design system from our prototype at http://localhost:3000 and export DESIGN.md ``` ::: ### Ciclo de ejecución del comando 1. Claude Code inicia los procedimientos de extracción de estilos. 2. El agente muestra el progreso en el terminal: lectura de variables CSS, inspección de tipografías y cálculo de dimensiones. 3. En la raíz del repositorio se crean los archivos `DESIGN.md` y `design-preview.html`. 4. Claude sugiere abrir el archivo HTML en el navegador para revisarlo (`open design-preview.html`). --- ## 7. Integración de tokens en Tailwind CSS, Figma y React Los tokens extraídos se incorporan directamente en flujos de trabajo de producción sin necesidad de adaptaciones manuales extensas. ### Exportación a la configuración de Tailwind CSS Extiende tu archivo `tailwind.config.ts` con los valores identificados: ```typescript import type { Config } from 'tailwindcss'; const config: Config = { content: ['./src/**/*.{js,ts,jsx,tsx,mdx}'], theme: { extend: { colors: { brand: { primary: '#4F46E5', 'on-primary': '#FFFFFF', surface: '#1E293B', background: '#0F172A', }, }, borderRadius: { sm: '4px', md: '8px', lg: '16px', }, fontFamily: { sans: ['Inter', 'sans-serif'], }, }, }, plugins: [], }; export default config; ``` ### Vinculación mediante variables CSS nativas También puedes declarar los valores en `globals.css`: ```css :root { --color-primary: #4f46e5; --color-on-primary: #ffffff; --color-surface: #1e293b; --radius-md: 8px; --spacing-base: 8px; } ``` ### Sincronización con Figma mediante Tokens Studio Convierte el bloque YAML en un archivo JSON estándar (`tokens.json`) para importarlo en el plugin **Tokens Studio for Figma**, creando variables nativas de Figma al instante. --- ## 8. Casos de uso prácticos y escenarios de negocio El extractor de sistemas de diseño agiliza la toma de decisiones visuales y la ingeniería de interfaces en proyectos reales. ### Cuatro aplicaciones clave 1. **Benchmarking competitivo y auditorías:** Desglosa los sistemas visuales de líderes del sector (Linear, Vercel, Apple, Stripe) antes de escribir una sola línea de CSS personalizado. 2. **Onboarding ágil en proyectos de clientes:** En lugar de esperar semanas por manuales de marca desactualizados, extrae los tokens reales de la web en producción del cliente en cuestión de minutos. 3. **Construcción de MVPs sin diseñador dedicado:** Los fundadores y equipos pequeños pueden basarse en la armonía cromática y tipográfica de productos consolidados para lanzar con acabado profesional desde el primer día. 4. **Contexto de diseño para agentes de IA:** El archivo `DESIGN.md` sirve como contexto estricto para agentes generadores de código, asegurando coherencia visual en cada nuevo componente creado. --- ## 9. Taller práctico: extracción del sistema de diseño y creación de un componente Veamos un flujo completo: desde el análisis de una web de referencia hasta la implementación de un componente en React con los tokens obtenidos. ### Paso 1. Ejecutar la extracción del sitio de referencia En la terminal de tu proyecto, escribe la siguiente instrucción en Claude Code: ```text Extract design system from https://news.ycombinator.com or your preferred inspiration website ``` Claude recopilará los estilos del DOM y compilará el archivo `DESIGN.md`. ### Paso 2. Comprobar la vitrina visual generada Abre el archivo de vista previa en tu navegador: ```bash open design-preview.html ``` Comprueba que la paleta, las proporciones tipográficas y los contrastes coincidan fielmente con la identidad del sitio de referencia. ### Paso 3. Crear un componente en React a partir de DESIGN.md Pide a Claude Code que implemente un componente siguiendo los parámetros registrados: ```text Using the tokens and component rules defined in DESIGN.md, create a responsive PricingCard component in src/components/PricingCard.tsx with primary and secondary CTA buttons. ``` Claude leerá los radios, sombras y códigos de color de `DESIGN.md` para programar un componente perfectamente integrado: ```typescript import React from 'react'; interface PricingCardProps { title: string; price: string; features: string[]; isPopular?: boolean; } export const PricingCard: React.FC = ({ title, price, features, isPopular }) => { return (

{title}

{price}
); }; ``` --- ## 10. Autoevaluación rápida y lista de verificación final Comprueba tus conocimientos sobre el flujo de extracción y aplicación de sistemas de diseño. ### Preguntas de repaso > **1. ¿De dónde extrae DESIGN.md Extractor los valores numéricos y códigos de color exactos?** > > > [!TIP] > > **Respuesta:** Obtiene las variables CSS nativas (`:root`) y los estilos calculados (*computed styles*) directamente del DOM renderizado por el navegador, garantizando precisión absoluta. > **2. ¿Cuáles son los dos archivos principales generados tras la extracción?** > > > [!TIP] > > **Respuesta:** El documento estructurado `DESIGN.md` (con cabecera YAML y siete secciones en prosa) y el catálogo visual offline `design-preview.html`. > **3. ¿Cómo potencia el archivo DESIGN.md el trabajo de otros agentes de desarrollo con Claude?** > > > [!TIP] > > **Respuesta:** Funciona como un contexto de diseño autoritativo: los agentes leen los tokens del archivo para programar componentes que respetan fielmente el sistema visual acordado. ### Lista de verificación para producción - [ ] `DESIGN.md` cuenta con una cabecera YAML válida con tokens de color, tipografía y espaciado. - [ ] Las 7 secciones en prosa documentan las particularidades del estilo analizado sin textos genéricos. - [ ] `design-preview.html` se abre localmente en el navegador sin errores en la consola. - [ ] Se validaron los contrastes de colores principales según las normas de accesibilidad WCAG AA. - [ ] Los tokens se han incorporado a `tailwind.config.ts` o a las variables de `globals.css`. - [ ] Los primeros componentes generados se han comprobado visualmente frente a la cuadrícula general.