@damenor/agent-docs 0.1.1 → 0.4.0

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

@@ -1,118 +1,118 @@
 ---
 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.
+  Creates and maintains the design system documentation (DESIGN.md).
+  Extracts real tokens from code (CSS vars, Tailwind config, theme files),
+  generates structured documentation with YAML frontmatter for colors,
+  typography, spacing, borders, elevation and components.
+  TRIGGER: When the user says "document design", "design system",
+  "design tokens", "DESIGN.md", "extract styles", "audit styles",
+  or changes in style/CSS/theme files are detected.
 license: Apache-2.0
 metadata:
   author: damenordev
-  version: "1.0"
+  version: '1.0'
 ---
 
 # doc-design
 
-## Cuándo Usar
+## When to Use
 
-- **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
+- **New project**: Need to create DESIGN.md with the design system
+- **UI changes**: Styles, components or design tokens were modified
+- **Token extraction**: Want to document real values from code (CSS vars, Tailwind config, theme files)
+- **Consistency audit**: Design inconsistencies detected (duplicate colors, inconsistent spacing)
+- **Post-design-change**: After CSS/theme changes, update DESIGN.md
 
-## Patrones Críticos
+## Critical Patterns
 
-### REGLA #1: DESIGN.md usa frontmatter YAML para tokens estructurados
+### RULE #1: DESIGN.md uses YAML frontmatter for structured tokens
 
 ```yaml
 ---
-created: "2024-01-15"
+created: '2024-01-15'
 status: active
 type: reference
 tags: [design-system, tokens, componentes]
 colors:
   brand:
-    primary: "#3B82F6"
-    secondary: "#8B5CF6"
+    primary: '#3B82F6'
+    secondary: '#8B5CF6'
   surface:
-    background: "#FFFFFF"
-    card: "#F9FAFB"
-    elevated: "#FFFFFF"
+    background: '#FFFFFF'
+    card: '#F9FAFB'
+    elevated: '#FFFFFF'
   text:
-    primary: "#111827"
-    secondary: "#6B7280"
-    disabled: "#9CA3AF"
+    primary: '#111827'
+    secondary: '#6B7280'
+    disabled: '#9CA3AF'
   semantic:
-    success: "#10B981"
-    warning: "#F59E0B"
-    error: "#EF4444"
-    info: "#3B82F6"
+    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" }
+  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" }
+  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" }
+  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)"
+    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}"
+    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}"
+    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}"
+    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" }
+  breakpoints: { sm: '640px', md: '768px', lg: '1024px', xl: '1280px', '2xl': '1536px' }
 ---
 ```
 
-### REGLA #2: Cada componente referencia tokens con notación `{sección.token}`
+### RULE #2: Each component references tokens with `{section.token}` notation
 
 ```yaml
 components:
   button:
-    base: "border-radius: {rounded.md}, padding: {spacing.sm} {spacing.md}"
+    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
+### RULE #3: Extract REAL values from code
 
-NUNCA inventar valores. Extraer de:
+NEVER invent values. Extract from:
 
-| 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` |
+| Source            | What to look for                        |
+| ----------------- | --------------------------------------- |
+| 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
+### RULE #4: Keep synchronized with the code
 
 ```
 Si cambia el código de estilos → cambiar DESIGN.md
@@ -121,9 +121,10 @@ Si cambia DESIGN.md → cambiar el código de estilos
 
 La sincronización es bidireccional. Usar `doc-review` para verificar.
 
-### REGLA #5: Estructura consistente
+### RULE #5: Consistent structure
 
 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)
@@ -132,7 +133,7 @@ El YAML frontmatter debe seguir este orden:
 6. `components` (componentes UI documentados)
 7. `responsive` (breakpoints)
 
-### REGLA #6: Sección overview en markdown
+### RULE #6: Overview section in markdown
 
 Después del frontmatter, incluir una sección narrativa:
 
@@ -146,147 +147,149 @@ Después del frontmatter, incluir una sección narrativa:
 [Cómo referenciar tokens en el código — con ejemplo específico del stack]
 ```
 
-## Flujo del Proceso
+## Process Flow
 
-### Paso 1: Verificar archivos de diseño existentes
+### Step 1: Check existing design files
 
 ```
-Buscar:
+Search for:
 ├── 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
+├── Existing DESIGN.md → DO NOT overwrite without asking
 └── Design tool exports → Figma, Sketch, tokens.json
 ```
 
-### Paso 2: Extraer valores actuales
+### Step 2: Extract current values
 
 ```
-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
+1. Read each style file found
+2. Extract colors, typography, spacing, borders, shadows
+3. Normalize format (hex, rem, px → consistent format)
+4. Identify named tokens vs hardcoded values
+5. Detect duplicates and inconsistencies
 ```
 
-### Paso 3: Crear/actualizar DESIGN.md
+### Step 3: Create/update 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
+1. Generate YAML frontmatter with all extracted tokens
+2. Document components that exist in the code
+3. Add overview section in markdown
+4. Note gaps and inconsistencies found
 ```
 
-### Paso 4: Agregar overview narrativo
+### Step 4: Add narrative overview
 
 ```markdown
-## Visión General
+## Overview
 
-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:
+This design system follows a token-based approach where base values
+(colors, spacing, typography) are defined as variables and referenced
+in components. The hierarchy is:
 
-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
+1. **Base tokens**: Raw values (hex colors, rem sizes)
+2. **Semantic tokens**: Purpose-based tokens ({colors.semantic.error})
+3. **Component tokens**: Default values for each component
 
-## Paleta de Colores
+## Color Palette
 
-[Explicar la lógica de la paleta — no solo listar valores]
+[Explain palette logic — not just list values]
 
-## Tipografía
+## Typography
 
-[Explicar la jerarquía tipográfica]
+[Explain typographic hierarchy]
 
-## Componentes
+## Components
 
-[Resumen de los componentes documentados y su lógica]
+[Summary of documented components and their logic]
 ```
 
-### Paso 5: Documentar componentes existentes
+### Step 5: Document existing components
 
-Para cada componente encontrado en el código:
+For each component found in the code:
 
 ```yaml
 components:
   button:
     variants: [primary, secondary, outline, ghost, danger]
     sizes: [sm, md, lg]
-    base: "font-weight: 600, border-radius: {rounded.md}"
+    base: 'font-weight: 600, border-radius: {rounded.md}'
     primary:
-      bg: "{colors.brand.primary}"
-      text: "#FFFFFF"
-      hover: "darken 10%"
+      bg: '{colors.brand.primary}'
+      text: '#FFFFFF'
+      hover: 'darken 10%'
     secondary:
-      bg: "{colors.brand.secondary}"
-      text: "#FFFFFF"
+      bg: '{colors.brand.secondary}'
+      text: '#FFFFFF'
 ```
 
-### Paso 6: Notar gaps e inconsistencias
+### Step 6: Note gaps and inconsistencies
 
 ```markdown
-## Hallazgos
+## Findings
+
+### ⚠️ Detected Inconsistencies
 
-### ⚠️ 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
+- Color `#3b82f6` used in 3 files as hardcoded (should be token)
+- Inconsistent card spacing: some use 1rem, others 1.25rem
+- No token exists for modal shadow
 
-### 📋 Pendientes
-- Migrar colores hardcodeados a CSS variables
-- Unificar spacing de cards
-- Crear tokens de elevation para modals y tooltips
+### 📋 Pending
+
+- Migrate hardcoded colors to CSS variables
+- Unify card spacing
+- Create elevation tokens for modals and tooltips
 ```
 
-## Comandos
+## Commands
 
-### Archivo principal
+### Main file
 
 ```
-DESIGN.md — Sistema de diseño del proyecto
+DESIGN.md — Project design system
 ```
 
-### Verificación post-creación
+### Post-creation verification
 
 ```
-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
+1. Does DESIGN.md have YAML frontmatter with all sections? → colors, typography, spacing, rounded, elevation, components
+2. Do referenced tokens exist? → {colors.brand.primary} must be defined
+3. Are values real (extracted from code)? → Not invented
+4. Is there an overview section in markdown? → Philosophy + token usage
+5. Were gaps and inconsistencies noted? → Findings section
 ```
 
-## Sincronización con el Código
+## Synchronization with Code
 
-### Detección de cambios
+### Change detection
 
-| 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` |
+| File changed    | What to update in DESIGN.md        |
+| --------------- | ---------------------------------- |
+| CSS variables   | `colors`, `spacing` sections, etc. |
+| Tailwind config | All token sections                 |
+| Theme files     | All sections                       |
+| New component   | `components` section               |
+| Breakpoints     | `responsive` section               |
 
-### Formatos por stack
+### Formats by 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 |
+| Stack             | Token source               | Format                                           |
+| ----------------- | -------------------------- | ------------------------------------------------ |
+| Pure CSS          | `:root { --token: value }` | Map `--color-primary` → `{colors.brand.primary}` |
+| Tailwind          | `theme.extend.colors`      | Map config directly                              |
+| Sass              | `$color-primary: value`    | Map variables                                    |
+| Styled-components | `theme.colors.primary`     | Map theme object                                 |
+| CSS Modules       | Compose from variables     | Map composes                                     |
 
-## Ejemplo Concreto de Extracción
+## Concrete Extraction Example
 
-### Input: Proyecto con Tailwind
+### Input: Project with Tailwind
 
 ```javascript
-// tailwind.config.ts encontrado
+// tailwind.config.ts found
 module.exports = {
   theme: {
     extend: {
@@ -304,56 +307,55 @@ module.exports = {
 }
 ```
 
-### Output: DESIGN.md generado
+### Output: Generated DESIGN.md
 
 ```yaml
 ---
-created: "2026-05-07"
-updated: "2026-05-07"
+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"
+    primary: '#3B82F6'
+    primary-dark: '#2563EB'
+    primary-light: '#93C5FD'
   surface:
-    background: "#FFFFFF"
-    muted: "#F9FAFB"
+    background: '#FFFFFF'
+    muted: '#F9FAFB'
   text:
-    primary: "#111827"
-    secondary: "#6B7280"
+    primary: '#111827'
+    secondary: '#6B7280'
   semantic:
-    error: "#EF4444"
-    success: "#10B981"
+    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" }
+  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"
+  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"
+  xs: '0.25rem'
+  sm: '0.5rem'
+  md: '1rem'
+  lg: '1.5rem'
+  xl: '2rem'
+  '2xl': '3rem'
 ---
+## Overview
 
-## Visión General
-
-Design system basado en Tailwind CSS con tokens extendidos. ...
+Design system based on Tailwind CSS with extended tokens. ...
 ```
 
-## Recursos
+## Resources
 
-- [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)
+- [Design System Format](references/design-system-format.md) — Complete YAML format schema with examples
+- Related skills: `doc-write` (write docs), `doc-review` (audit consistency), `doc-maintain` (sync changes)