@damenor/agent-docs 0.1.0

package/templates/modules/agents/.agents/skills/doc-design/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: doc-design
+description: >
+  Crea y mantiene la documentación del sistema de diseño (DESIGN.md).
+  Extrae tokens reales del código (CSS vars, Tailwind config, theme files),
+  genera documentación estructurada con YAML frontmatter para colores,
+  tipografía, espaciado, bordes, elevación y componentes.
+  TRIGGER: Cuando el usuario dice "documentar diseño", "design system",
+  "tokens de diseño", "DESIGN.md", "extraer estilos", "auditar estilos",
+  o se detectan cambios en archivos de estilos/CSS/theme.
+license: Apache-2.0
+metadata:
+  author: damenordev
+  version: "1.0"
+---
+
+# doc-design
+
+## Cuándo Usar
+
+- **Proyecto nuevo**: Se necesita crear el archivo DESIGN.md con el sistema de diseño
+- **Cambios en UI**: Se modificaron estilos, componentes o tokens de diseño
+- **Extracción de tokens**: Se quiere documentar los valores reales del código (CSS vars, Tailwind config, theme files)
+- **Auditoría de consistencia**: Se detectan inconsistencias en el diseño (colores duplicados, spacing inconsistente)
+- **Post-design-change**: Después de cambios en CSS/theme, actualizar DESIGN.md
+
+## Patrones Críticos
+
+### REGLA #1: DESIGN.md usa frontmatter YAML para tokens estructurados
+
+```yaml
+---
+created: "2024-01-15"
+status: active
+type: reference
+tags: [design-system, tokens, componentes]
+colors:
+  brand:
+    primary: "#3B82F6"
+    secondary: "#8B5CF6"
+  surface:
+    background: "#FFFFFF"
+    card: "#F9FAFB"
+    elevated: "#FFFFFF"
+  text:
+    primary: "#111827"
+    secondary: "#6B7280"
+    disabled: "#9CA3AF"
+  semantic:
+    success: "#10B981"
+    warning: "#F59E0B"
+    error: "#EF4444"
+    info: "#3B82F6"
+typography:
+  heading-xl: { font-size: "2rem", font-weight: "700", line-height: "1.2" }
+  heading-lg: { font-size: "1.5rem", font-weight: "600", line-height: "1.3" }
+  heading-md: { font-size: "1.25rem", font-weight: "600", line-height: "1.4" }
+  body-lg: { font-size: "1.125rem", font-weight: "400", line-height: "1.6" }
+  body-md: { font-size: "1rem", font-weight: "400", line-height: "1.6" }
+  body-sm: { font-size: "0.875rem", font-weight: "400", line-height: "1.5" }
+  caption: { font-size: "0.75rem", font-weight: "400", line-height: "1.4" }
+spacing:
+  scale: [0, "0.25rem", "0.5rem", "0.75rem", "1rem", "1.5rem", "2rem", "3rem", "4rem", "6rem"]
+  tokens: { xs: "0.25rem", sm: "0.5rem", md: "1rem", lg: "1.5rem", xl: "2rem", "2xl": "3rem", "3xl": "4rem" }
+rounded:
+  scale: [0, "0.25rem", "0.5rem", "0.75rem", "1rem", "1.5rem", "9999px"]
+  tokens: { none: "0", sm: "0.25rem", md: "0.5rem", lg: "0.75rem", xl: "1rem", "2xl": "1.5rem", full: "9999px" }
+elevation:
+  tiers:
+    flat: "none"
+    sm: "0 1px 2px rgba(0,0,0,0.05)"
+    md: "0 4px 6px rgba(0,0,0,0.1)"
+    lg: "0 10px 15px rgba(0,0,0,0.1)"
+    xl: "0 20px 25px rgba(0,0,0,0.15)"
+components:
+  button:
+    variants: [primary, secondary, outline, ghost, danger]
+    sizes: [sm, md, lg]
+    base: "font-weight: 600, border-radius: {rounded.md}, padding: {spacing.sm} {spacing.md}"
+  card:
+    variants: [default, outlined, elevated]
+    base: "border-radius: {rounded.lg}, padding: {spacing.lg}, background: {colors.surface.card}"
+  input:
+    variants: [default, error, disabled]
+    sizes: [sm, md, lg]
+    base: "border: 1px solid, border-radius: {rounded.md}, padding: {spacing.sm} {spacing.md}"
+responsive:
+  breakpoints: { sm: "640px", md: "768px", lg: "1024px", xl: "1280px", "2xl": "1536px" }
+---
+```
+
+### REGLA #2: Cada componente referencia tokens con notación `{sección.token}`
+
+```yaml
+components:
+  button:
+    base: "border-radius: {rounded.md}, padding: {spacing.sm} {spacing.md}"
+    # NO: border-radius: 0.5rem, padding: 0.5rem 1rem
+    # SÍ: Referenciar tokens para mantener consistencia
+```
+
+### REGLA #3: Extraer valores REALES del código
+
+NUNCA inventar valores. Extraer de:
+
+| Fuente | Qué buscar |
+|--------|------------|
+| CSS variables | `:root { --color-primary: ... }` |
+| Tailwind config | `tailwind.config.js` → `theme.extend` |
+| Theme files | `theme.ts`, `theme.json`, `tokens.json` |
+| Styled-components | `Theme` object |
+| Design tokens | Figma API, Style Dictionary |
+| Sass/Less vars | `_variables.scss`, `_variables.less` |
+
+### REGLA #4: Mantener sincronizado con el código
+
+```
+Si cambia el código de estilos → cambiar DESIGN.md
+Si cambia DESIGN.md → cambiar el código de estilos
+```
+
+La sincronización es bidireccional. Usar `doc-review` para verificar.
+
+### REGLA #5: Estructura consistente
+
+El YAML frontmatter debe seguir este orden:
+1. `colors` (brand, surface, text, semantic)
+2. `typography` (jerarquía completa con tokens)
+3. `spacing` (escala y tokens nombrados)
+4. `rounded` (escala de border-radius y tokens)
+5. `elevation` (tiers de sombra)
+6. `components` (componentes UI documentados)
+7. `responsive` (breakpoints)
+
+### REGLA #6: Sección overview en markdown
+
+Después del frontmatter, incluir una sección narrativa:
+
+```markdown
+## Visión General
+
+[Filosofía del diseño: 2-3 oraciones sobre los principios guía]
+
+## Uso de Tokens
+
+[Cómo referenciar tokens en el código — con ejemplo específico del stack]
+```
+
+## Flujo del Proceso
+
+### Paso 1: Verificar archivos de diseño existentes
+
+```
+Buscar:
+├── CSS variables → :root, [data-theme]
+├── Tailwind → tailwind.config.js/ts, tailwind.config.cjs
+├── Theme files → theme.ts, theme.json, tokens.json
+├── Sass/Less → _variables.scss, _variables.less
+├── Styled-components → Theme provider
+├── Existing DESIGN.md → NO sobreescribir sin preguntar
+└── Design tool exports → Figma, Sketch, tokens.json
+```
+
+### Paso 2: Extraer valores actuales
+
+```
+1. Leer cada archivo de estilos encontrado
+2. Extraer colores, tipografía, spacing, borders, shadows
+3. Normalizar formato (hex, rem, px → formato consistente)
+4. Identificar tokens nombrados vs valores hardcodeados
+5. Detectar duplicados e inconsistencias
+```
+
+### Paso 3: Crear/actualizar DESIGN.md
+
+```
+1. Generar frontmatter YAML con todos los tokens extraídos
+2. Documentar componentes que existen en el código
+3. Agregar sección overview en markdown
+4. Notar gaps e inconsistencias encontrados
+```
+
+### Paso 4: Agregar overview narrativo
+
+```markdown
+## Visión General
+
+Este sistema de diseño sigue un enfoque basado en tokens donde los valores
+base (colores, spacing, tipografía) se definen como variables y se referencian
+en los componentes. La jerarquía es:
+
+1. **Tokens base**: Valores crudos (colores hex, tamaños rem)
+2. **Tokens semánticos**: Tokens con propósito ({colors.semantic.error})
+3. **Tokens de componente**: Valores por defecto de cada componente
+
+## Paleta de Colores
+
+[Explicar la lógica de la paleta — no solo listar valores]
+
+## Tipografía
+
+[Explicar la jerarquía tipográfica]
+
+## Componentes
+
+[Resumen de los componentes documentados y su lógica]
+```
+
+### Paso 5: Documentar componentes existentes
+
+Para cada componente encontrado en el código:
+
+```yaml
+components:
+  button:
+    variants: [primary, secondary, outline, ghost, danger]
+    sizes: [sm, md, lg]
+    base: "font-weight: 600, border-radius: {rounded.md}"
+    primary:
+      bg: "{colors.brand.primary}"
+      text: "#FFFFFF"
+      hover: "darken 10%"
+    secondary:
+      bg: "{colors.brand.secondary}"
+      text: "#FFFFFF"
+```
+
+### Paso 6: Notar gaps e inconsistencias
+
+```markdown
+## Hallazgos
+
+### ⚠️ Inconsistencias detectadas
+- Color `#3b82f6` usado en 3 archivos como hardcoded (debería ser token)
+- Spacing inconsistente en cards: algunos usan 1rem, otros 1.25rem
+- No existe token para el shadow del modal
+
+### 📋 Pendientes
+- Migrar colores hardcodeados a CSS variables
+- Unificar spacing de cards
+- Crear tokens de elevation para modals y tooltips
+```
+
+## Comandos
+
+### Archivo principal
+
+```
+DESIGN.md — Sistema de diseño del proyecto
+```
+
+### Verificación post-creación
+
+```
+1. ¿DESIGN.md tiene frontmatter YAML con todas las secciones? → colors, typography, spacing, rounded, elevation, components
+2. ¿Los tokens referenciados existen? → {colors.brand.primary} debe estar definido
+3. ¿Los valores son reales (extraídos del código)? → No inventados
+4. ¿Hay sección overview en markdown? → Filosofía + uso de tokens
+5. ¿Se notaron gaps e inconsistencias? → Sección de hallazgos
+```
+
+## Sincronización con el Código
+
+### Detección de cambios
+
+| Archivo cambia | Qué actualizar en DESIGN.md |
+|----------------|----------------------------|
+| CSS variables | Sección `colors`, `spacing`, etc. |
+| Tailwind config | Todas las secciones de tokens |
+| Theme files | Todas las secciones |
+| Componente nuevo | Sección `components` |
+| Breakpoints | Sección `responsive` |
+
+### Formatos por stack
+
+| Stack | Fuente de tokens | Formato |
+|-------|-----------------|---------|
+| CSS puro | `:root { --token: value }` | Mapear `--color-primary` → `{colors.brand.primary}` |
+| Tailwind | `theme.extend.colors` | Mapear config directo |
+| Sass | `$color-primary: value` | Mapear variables |
+| Styled-components | `theme.colors.primary` | Mapear theme object |
+| CSS Modules | Compose from variables | Mapear composes |
+
+## Ejemplo Concreto de Extracción
+
+### Input: Proyecto con Tailwind
+
+```javascript
+// tailwind.config.ts encontrado
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        brand: { DEFAULT: '#3B82F6', dark: '#2563EB', light: '#93C5FD' },
+        surface: { DEFAULT: '#FFFFFF', muted: '#F9FAFB' },
+      },
+      fontFamily: {
+        sans: ['Inter', 'system-ui', 'sans-serif'],
+        mono: ['JetBrains Mono', 'monospace'],
+      },
+      borderRadius: { sm: '6px', md: '8px', lg: '12px', xl: '16px', full: '9999px' },
+    },
+  },
+}
+```
+
+### Output: DESIGN.md generado
+
+```yaml
+---
+created: "2026-05-07"
+updated: "2026-05-07"
+status: active
+type: design
+tags: [design-system, tokens, tailwind]
+colors:
+  brand:
+    primary: "#3B82F6"
+    primary-dark: "#2563EB"
+    primary-light: "#93C5FD"
+  surface:
+    background: "#FFFFFF"
+    muted: "#F9FAFB"
+  text:
+    primary: "#111827"
+    secondary: "#6B7280"
+  semantic:
+    error: "#EF4444"
+    success: "#10B981"
+typography:
+  heading-xl: { fontFamily: "Inter, system-ui, sans-serif", fontSize: "2rem", fontWeight: "700" }
+  heading-lg: { fontFamily: "Inter, system-ui, sans-serif", fontSize: "1.5rem", fontWeight: "600" }
+  body-md: { fontFamily: "Inter, system-ui, sans-serif", fontSize: "1rem", fontWeight: "400" }
+  body-sm: { fontFamily: "Inter, system-ui, sans-serif", fontSize: "0.875rem", fontWeight: "400" }
+  code: { fontFamily: "JetBrains Mono, monospace", fontSize: "0.875rem" }
+rounded:
+  sm: "6px"
+  md: "8px"
+  lg: "12px"
+  xl: "16px"
+  full: "9999px"
+spacing:
+  xs: "0.25rem"
+  sm: "0.5rem"
+  md: "1rem"
+  lg: "1.5rem"
+  xl: "2rem"
+  "2xl": "3rem"
+---
+
+## Visión General
+
+Design system basado en Tailwind CSS con tokens extendidos. ...
+```
+
+## Recursos
+
+- [Design System Format](references/design-system-format.md) — Esquema completo del formato YAML con ejemplos
+- Skills relacionados: `doc-write` (escribir docs), `doc-review` (auditar consistencia), `doc-maintain` (sincronizar cambios)