Levango7/design-md-skill

design-md · Flujo de trabajo de contratos de diseño DESIGN.md

Extrae las "decisiones de diseño" del código CSS disperso y consolídalas en DESIGN.md, un contrato de diseño legible tanto para agentes de IA como para humanos. Este skill cubre el ciclo completo:

Investigación (opcional con conexión) → Extracción → Generación → Aplicación al código → Verificación → Puerta de enlace CI

DESIGN.md es un concepto propuesto por Google Stitch: un documento de sistema de diseño en texto plano, ubicado en la raíz del proyecto, que cualquier agente de IA de codificación puede leer para producir UI visualmente consistente. AGENTS.md gestiona "cómo construir", DESIGN.md gestiona "cómo se ve".

Estructura del directorio

Ubicación	Propósito
scripts/wcag.py	Motor de contraste WCAG 2.1: analiza tokens.css / design-tokens.json, empareja automáticamente según convenciones (texto 4.5:1, UI 3:1), código de salida usable como puerta de enlace CI
scripts/extract.py	Extrae un borrador de tokens de diseño de cualquier URL (paleta de colores, tipografía, radios de borde), produce tokens-draft.json + esqueleto DESIGN.draft.md
scripts/scaffold.py	Genera desde un JSON de tokens: tokens.css (tokens duales), tailwind.extend.js, preview.html (catálogo visual), e informe de contraste
scripts/fetch_ref.py	Obtiene DESIGN.md de referencia de awesome-design-md (84 marcas, con doble canal: raw → gh api)
scripts/research.py	Investigación en línea con DeepSeek Search/Fetch (conexión directa facturada, desactivada por defecto: requiere consentimiento explícito del usuario y flag --yes-billing; la clave se lee de archivo local / variable de entorno, nunca se muestra)
references/spec.md	Especificación del archivo DESIGN.md: frontmatter + tokens YAML + 11 secciones de cuerpo + reglas de escritura
references/lessons.md	Lecciones aprendidas: tokens duales, trampas de dilución alfa, división de accent, contratos de datos, etc. (de auditorías reales de producción)
references/research.md	Uso de API DeepSeek Search/Fetch + catálogo de la biblioteca de referencia awesome-design-md (84 slugs completos)
references/verify.md	Lista de verificación + plantilla de conexión CI (npm script / GitHub Actions)
templates/design-tokens.example.json	Ejemplo de entrada ejecutable (doble tema, todo supera AA), modifícalo según necesidad

Inicio rápido

# 0) Entorno: python3 ≥ 3.9, solo biblioteca estándar
python3 scripts/wcag.py --help

# 1) Investigación (opcional): extrae borrador de tokens desde un sitio de referencia
python3 scripts/extract.py --url https://example.com --out-dir ./design-draft
#    → design-draft/tokens-draft.json + design-draft/DESIGN.draft.md

# 2) Obtén un DESIGN.md de una marca conocida como referencia (como inspiración, no plagio)
python3 scripts/fetch_ref.py --list                 # Ver los 84 slugs
python3 scripts/fetch_ref.py --slug linear.app      # → ./DESIGN.reference-linear.app.md

# 2b) (Opcional) Investigación en línea con DeepSeek — conexión directa facturada (5 yuanes/1000 solicitudes exitosas), desactivada por defecto:
#     Solo se ejecuta con --yes-billing después de consentimiento explícito del usuario; la clave la proporciona el archivo local, nunca entra en el diálogo/log
python3 scripts/research.py --yes-billing check     # Verificar clave (por defecto lee %USERPROFILE%\.deepseek\api_key)
python3 scripts/research.py --yes-billing search --query "fintech dashboard design site:dribbble.com" --count 8

# 3) Genera el proyecto completo de tokens (con tu JSON de tokens alineado como entrada)
python3 scripts/scaffold.py --tokens my-tokens.json --out ./design-out
#    → tokens.css / design-tokens.json / tailwind.extend.js / preview.html / contrast-report.txt

# 4) Verifica (ejecuta independiente o conecta a CI)
python3 scripts/wcag.py --tokens ./design-out/tokens.css     # Entrada CSS
python3 scripts/wcag.py --tokens ./design-out/design-tokens.json   # Entrada JSON
python3 scripts/wcag.py --pair "#E6E9EF:#0A0C10:4.5"         # Consulta rápida de un par hex

Flujo de trabajo estándar (orden de ejecución para el agente)

1. Definir requisitos: Lee el estado actual del proyecto (¿existe DESIGN.md / tokens / librería de componentes?), define la dirección del tema (¿oscuro primero? ¿colores de marca? ¿tono de la industria — finanzas, herramientas de desarrollo, salud…).
2. Investigar (opcional): Usa los métodos de references/research.md para hacer investigación de diseño — DeepSeek Search para encontrar sitios de referencia (conexión directa facturada y desactivada por defecto: primero muestra el costo al usuario y obtén consentimiento explícito, solo entonces con --yes-billing; sin consentimiento, siempre usa captura incorporada), DeepSeek Fetch / captura incorporada para convertir páginas a Markdown y leer en detalle; obtén 1-3 DESIGN.md de referencia de la misma industria desde awesome-design-md.
3. Extraer/Redactar: extract.py produce un borrador → según la estructura de 11 secciones de references/spec.md, asigna roles manualmente / por agente (convierte "#5e6ad2 aparece 200 veces" en "color primario de marca, usado para CTA y anillos de enfoque").
4. Generar: Organiza en un JSON de tokens conforme a la especificación → scaffold.py produce el conjunto completo de archivos de ingeniería (incluyendo página de vista previa para que el usuario vea el resultado).
5. Aplicar: Conecta tokens.css / mapeo Tailwind al proyecto; los componentes se implementan según las reglas de componentes de DESIGN.md §4.
6. Verificar: wcag.py todo verde + lista de verificación de references/verify.md punto por punto; conecta la puerta de enlace a CI (ver plantilla verify.md).
7. Iterar: Cualquier cambio de valor de color → debe volver a ejecutar wcag.py, no confíes en la percepción visual; los cambios de decisión de diseño se registran en DESIGN.md (con anotación de versión).

Reglas estrictas (debes cumplir)

1. El contraste no se basa en la percepción visual: Cualquier cambio de color debe ejecutar wcag.py. Texto ≥4.5:1, controles UI / bordes ≥3:1.
2. Tokens duales: Cada color se emite simultáneamente como --x (hex) y --x-rgb (canales), de lo contrario los modificadores de opacidad de Tailwind fallan silenciosamente (ver lessons.md #1).
3. No uses dilución alfa bg-{warn}/10 para fondos claros — los fondos claros deben ser tokens independientes (--warn-soft). La dilución empeora el contraste en temas claros según pruebas reales.
4. Divide los colores de marca en dos niveles: --accent (texto/enlaces) y --accent-solid (botones de relleno). Un mismo valor no puede satisfacer simultáneamente "texto claro sobre fondo oscuro" y "fondo oscuro debajo de texto blanco" ambos ≥4.5:1.
5. Usa --border-strong (3:1) para bordes interactivos, --border solo para separación decorativa.
6. Marca honestamente las brechas conocidas: Lo no extraído (estado de error de formulario, versión clara, sustitutos de fuentes privadas) escríbelo explícitamente en DESIGN.md, no finjas completitud.
7. Referencia ≠ copia: awesome-design-md analiza características CSS públicas de las marcas; al citar, lee su "método" (jerarquía, ritmo, compensaciones), no te hagas pasar por la marca; los proyectos comerciales deben tener en cuenta marcas registradas y licencias de fuentes.

Seguridad

• Nunca muestres ninguna clave API. Orden de resolución de clave: --key-file → variable de entorno DEEPSEEK_API_KEY → variable de entorno DEEPSEEK_API_KEY_FILE → archivo por defecto %USERPROFILE%\.deepseek\api_key (recomendado: el usuario lo crea en la terminal, la clave no pasa por el diálogo/log). research.py enmascara toda la salida de la clave como sk-***.
• Protección de facturación (desactivada por defecto, 2026-10): DeepSeek Search/Fetch son APIs de conexión directa facturadas (5 yuanes/1000 solicitudes exitosas; límite de cuenta: Search 100 QPS / Fetch 25 QPS). research.py sin --yes-billing (y variable de entorno DEEPSEEK_BILLING_CONSENT no es 1) se niega directamente a ejecutar (exit 3) — el agente debe primero explicar el costo al usuario y obtener consentimiento explícito antes de añadir el flag; entornos de pago por uso como opencode se consideran no consentidos por defecto.
• Sin clave configurada, no se asume "necesidad de conexión" como dice el docstring — extract.py usa captura local con urllib, DeepSeek es solo una mejora.
• La captura respeta robots y frecuencia de acceso; extract.py captura como máximo 5 hojas de estilo, cada una con límite de 512KB.

Relación con otras capacidades

• awesome-design-md (VoltAgent, MIT): Colección de análisis DESIGN.md de 84 sitios reales. Este skill proporciona fetch_ref.py para uso inmediato; es la "biblioteca de material de referencia", este skill es el "motor de flujo de trabajo".
• DeepSeek Search/Fetch: https://api.deepseek.com/v1/tools/search|fetch. Búsqueda en tiempo real y captura de contenido web para fase de investigación de diseño (con sintaxis site:/lang:/after:). Facturación por solicitud (5 yuanes/1000 solicitudes exitosas — solo se facturan las que devuelven 200 y resultado no vacío; fallos/timeouts/resultados vacíos no se facturan). Límite de cuenta: Search 100 QPS / Fetch 25 QPS (exceso devuelve 429, research.py retrocede y reintenta automáticamente). Este skill proporciona scripts/research.py como invocación encapsulada (clave nunca mostrada; desactivada por defecto — requiere consentimiento explícito del usuario y flag --yes-billing, ver §Seguridad).
• Lint oficial de Google Stitch (opcional): npx @google/design.md lint DESIGN.md.