@damenor/agent-docs 0.1.0

package/templates/modules/agents/.agents/skills/doc-design/references/design-system-format.md

@@ -0,0 +1,550 @@
+---
+created: "2024-01-15"
+status: active
+type: reference
+tags: [design-system, tokens, formato, yaml]
+---
+
+# Design System Format — Referencia Completa
+
+## Esquema YAML Completo
+
+### Sección: colors
+
+```yaml
+colors:
+  brand:
+    primary: "#3B82F6"       # Color principal de la marca
+    secondary: "#8B5CF6"     # Color secundario
+    accent: "#EC4899"        # Color de acento
+  surface:
+    background: "#FFFFFF"    # Fondo principal
+    card: "#F9FAFB"          # Fondo de cards
+    elevated: "#FFFFFF"      # Fondo de elementos elevados
+    overlay: "rgba(0,0,0,0.5)" # Fondo de overlays
+  text:
+    primary: "#111827"       # Texto principal
+    secondary: "#6B7280"     # Texto secundario
+    tertiary: "#9CA3AF"      # Texto terciario
+    disabled: "#D1D5DB"      # Texto deshabilitado
+    inverse: "#FFFFFF"       # Texto sobre fondo oscuro
+  semantic:
+    success: "#10B981"       # Éxito
+    success-light: "#D1FAE5" # Éxito (fondo)
+    warning: "#F59E0B"       # Advertencia
+    warning-light: "#FEF3C7" # Advertencia (fondo)
+    error: "#EF4444"         # Error
+    error-light: "#FEE2E2"   # Error (fondo)
+    info: "#3B82F6"          # Información
+    info-light: "#DBEAFE"    # Información (fondo)
+  dark:
+    background: "#1F2937"    # Fondo en modo oscuro
+    card: "#374151"          # Card en modo oscuro
+    text: "#F9FAFB"          # Texto en modo oscuro
+```
+
+#### Ejemplo mínimo de colores
+
+```yaml
+colors:
+  brand:
+    primary: "#3B82F6"
+    secondary: "#8B5CF6"
+  surface:
+    background: "#FFFFFF"
+    card: "#F9FAFB"
+  text:
+    primary: "#111827"
+    secondary: "#6B7280"
+  semantic:
+    success: "#10B981"
+    warning: "#F59E0B"
+    error: "#EF4444"
+    info: "#3B82F6"
+```
+
+---
+
+### Sección: typography
+
+```yaml
+typography:
+  font-family:
+    sans: "Inter, system-ui, -apple-system, sans-serif"
+    mono: "JetBrains Mono, Fira Code, monospace"
+    display: "Cal Sans, Inter, sans-serif"
+  heading-xl:
+    font-size: "2.5rem"
+    font-weight: "800"
+    line-height: "1.1"
+    letter-spacing: "-0.02em"
+  heading-lg:
+    font-size: "2rem"
+    font-weight: "700"
+    line-height: "1.2"
+    letter-spacing: "-0.01em"
+  heading-md:
+    font-size: "1.5rem"
+    font-weight: "600"
+    line-height: "1.3"
+  heading-sm:
+    font-size: "1.25rem"
+    font-weight: "600"
+    line-height: "1.4"
+  body-lg:
+    font-size: "1.125rem"
+    font-weight: "400"
+    line-height: "1.75"
+  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: "500"
+    line-height: "1.4"
+    letter-spacing: "0.02em"
+    text-transform: "uppercase"
+  overline:
+    font-size: "0.625rem"
+    font-weight: "700"
+    line-height: "1.4"
+    letter-spacing: "0.08em"
+    text-transform: "uppercase"
+```
+
+#### Ejemplo mínimo de tipografía
+
+```yaml
+typography:
+  font-family:
+    sans: "Inter, system-ui, sans-serif"
+    mono: "JetBrains Mono, monospace"
+  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" }
+  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" }
+```
+
+---
+
+### Sección: spacing
+
+```yaml
+spacing:
+  scale: [0, "0.125rem", "0.25rem", "0.5rem", "0.75rem", "1rem", "1.5rem", "2rem", "3rem", "4rem", "6rem", "8rem"]
+  tokens:
+    "0": "0"
+    "0.5": "0.125rem"
+    "1": "0.25rem"
+    "1.5": "0.375rem"
+    "2": "0.5rem"
+    "3": "0.75rem"
+    "4": "1rem"
+    "5": "1.25rem"
+    "6": "1.5rem"
+    "8": "2rem"
+    "10": "2.5rem"
+    "12": "3rem"
+    "16": "4rem"
+    "20": "5rem"
+    "24": "6rem"
+    "32": "8rem"
+```
+
+#### Ejemplo mínimo de spacing
+
+```yaml
+spacing:
+  tokens: { xs: "0.25rem", sm: "0.5rem", md: "1rem", lg: "1.5rem", xl: "2rem", "2xl": "3rem", "3xl": "4rem" }
+```
+
+---
+
+### Sección: rounded
+
+```yaml
+rounded:
+  scale: [0, "0.125rem", "0.25rem", "0.375rem", "0.5rem", "0.75rem", "1rem", "1.5rem", "2rem", "9999px"]
+  tokens:
+    none: "0"
+    sm: "0.25rem"
+    md: "0.5rem"
+    lg: "0.75rem"
+    xl: "1rem"
+    "2xl": "1.5rem"
+    "3xl": "2rem"
+    full: "9999px"
+```
+
+---
+
+### Sección: elevation
+
+```yaml
+elevation:
+  tiers:
+    none: "none"
+    xs: "0 1px 2px rgba(0, 0, 0, 0.05)"
+    sm: "0 1px 3px rgba(0, 0, 0, 0.1), 0 1px 2px rgba(0, 0, 0, 0.06)"
+    md: "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)"
+    lg: "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)"
+    xl: "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)"
+    "2xl": "0 25px 50px -12px rgba(0, 0, 0, 0.25)"
+    inner: "inset 0 2px 4px rgba(0, 0, 0, 0.06)"
+```
+
+---
+
+### Sección: components
+
+#### Formato de componente
+
+```yaml
+components:
+  [component-name]:
+    description: "Descripción breve del componente"
+    variants: [variant1, variant2, variant3]
+    sizes: [sm, md, lg]
+    states: [default, hover, active, focus, disabled]
+    base: "Propiedades base del componente usando tokens"
+    [variant-name]:
+      bg: "{colors.xxx}"
+      text: "{colors.xxx}"
+      border: "valor"
+      shadow: "{elevation.xxx}"
+    tokens:
+      radius: "{rounded.md}"
+      padding-sm: "{spacing.sm} {spacing.md}"
+      padding-md: "{spacing.md} {spacing.lg}"
+      padding-lg: "{spacing.lg} {spacing.xl}"
+```
+
+#### Ejemplo: Button
+
+```yaml
+components:
+  button:
+    description: "Botón interactivo para acciones primarias y secundarias"
+    variants: [primary, secondary, outline, ghost, danger]
+    sizes: [sm, md, lg]
+    states: [default, hover, active, focus, disabled]
+    base: "font-weight: 600, border-radius: {rounded.md}, transition: all 150ms"
+    primary:
+      bg: "{colors.brand.primary}"
+      text: "#FFFFFF"
+      hover-bg: "#2563EB"
+      active-bg: "#1D4ED8"
+    secondary:
+      bg: "{colors.brand.secondary}"
+      text: "#FFFFFF"
+      hover-bg: "#7C3AED"
+    outline:
+      bg: "transparent"
+      text: "{colors.brand.primary}"
+      border: "2px solid {colors.brand.primary}"
+      hover-bg: "{colors.brand.primary}"
+      hover-text: "#FFFFFF"
+    ghost:
+      bg: "transparent"
+      text: "{colors.text.secondary}"
+      hover-bg: "{colors.surface.card}"
+    danger:
+      bg: "{colors.semantic.error}"
+      text: "#FFFFFF"
+      hover-bg: "#DC2626"
+    tokens:
+      radius: "{rounded.md}"
+      padding-sm: "{spacing.2} {spacing.3}"
+      padding-md: "{spacing.2} {spacing.4}"
+      padding-lg: "{spacing.3} {spacing.6}"
+      font-sm: "{typography.body-sm}"
+      font-md: "{typography.body-md}"
+      font-lg: "{typography.body-lg}"
+```
+
+#### Ejemplo: Card
+
+```yaml
+components:
+  card:
+    description: "Contenedor de contenido con opciones de elevación"
+    variants: [default, outlined, elevated, interactive]
+    base: "border-radius: {rounded.lg}, padding: {spacing.6}, background: {colors.surface.card}"
+    default:
+      border: "1px solid #E5E7EB"
+      shadow: "{elevation.none}"
+    outlined:
+      border: "1px solid #D1D5DB"
+      shadow: "{elevation.none}"
+    elevated:
+      border: "none"
+      shadow: "{elevation.md}"
+    interactive:
+      border: "1px solid #E5E7EB"
+      shadow: "{elevation.sm}"
+      hover-shadow: "{elevation.md}"
+      cursor: "pointer"
+    tokens:
+      radius: "{rounded.lg}"
+      padding: "{spacing.6}"
+```
+
+#### Ejemplo: Input
+
+```yaml
+components:
+  input:
+    description: "Campo de entrada de texto"
+    variants: [default, error, success, disabled]
+    sizes: [sm, md, lg]
+    base: "border: 1px solid #D1D5DB, border-radius: {rounded.md}, background: #FFFFFF, transition: border-color 150ms"
+    default:
+      border: "1px solid #D1D5DB"
+      focus-border: "{colors.brand.primary}"
+      focus-ring: "0 0 0 3px rgba(59,130,246,0.1)"
+    error:
+      border: "1px solid {colors.semantic.error}"
+      focus-ring: "0 0 0 3px rgba(239,68,68,0.1)"
+    success:
+      border: "1px solid {colors.semantic.success}"
+    disabled:
+      bg: "#F3F4F6"
+      text: "{colors.text.disabled}"
+      cursor: "not-allowed"
+    tokens:
+      radius: "{rounded.md}"
+      padding-sm: "{spacing.1} {spacing.2}"
+      padding-md: "{spacing.2} {spacing.3}"
+      padding-lg: "{spacing.3} {spacing.4}"
+      font-sm: "{typography.body-sm}"
+      font-md: "{typography.body-md}"
+      font-lg: "{typography.body-lg}"
+```
+
+#### Ejemplo: Navigation
+
+```yaml
+components:
+  nav:
+    description: "Barra de navegación principal"
+    variants: [default, fixed, transparent]
+    base: "padding: {spacing.4} {spacing.6}, display: flex, align-items: center"
+    default:
+      bg: "#FFFFFF"
+      border-bottom: "1px solid #E5E7EB"
+      shadow: "{elevation.none}"
+    fixed:
+      position: "fixed"
+      z-index: "50"
+      shadow: "{elevation.sm}"
+    transparent:
+      bg: "transparent"
+      border: "none"
+    tokens:
+      height: "4rem"
+      padding: "{spacing.4} {spacing.6}"
+      logo-height: "2rem"
+```
+
+---
+
+### Sección: responsive
+
+```yaml
+responsive:
+  breakpoints:
+    xs: "475px"     # Mobile landscape
+    sm: "640px"     # Tablet portrait
+    md: "768px"     # Tablet landscape
+    lg: "1024px"    # Desktop
+    xl: "1280px"    # Desktop large
+    "2xl": "1536px" # Desktop extra large
+  containers:
+    sm: "640px"
+    md: "768px"
+    lg: "1024px"
+    xl: "1280px"
+  strategy: "mobile-first"
+  media-queries:
+    mobile: "@media (max-width: 639px)"
+    tablet: "@media (min-width: 640px) and (max-width: 1023px)"
+    desktop: "@media (min-width: 1024px)"
+```
+
+---
+
+## Sincronización con Código
+
+### CSS Variables → DESIGN.md
+
+```css
+:root {
+  --color-primary: #3B82F6;
+  --spacing-md: 1rem;
+}
+```
+
+→ Mapear a:
+```yaml
+colors:
+  brand:
+    primary: "#3B82F6"
+spacing:
+  tokens:
+    md: "1rem"
+```
+
+### Tailwind Config → DESIGN.md
+
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        primary: '#3B82F6',
+      },
+      spacing: {
+        '128': '32rem',
+      }
+    }
+  }
+}
+```
+
+→ Mapear config completo a secciones correspondientes.
+
+### DESIGN.md → CSS Variables
+
+```yaml
+colors:
+  brand:
+    primary: "#3B82F6"
+```
+
+→ Generar:
+```css
+:root {
+  --color-brand-primary: #3B82F6;
+}
+```
+
+### DESIGN.md → Tailwind Config
+
+```yaml
+colors:
+  brand:
+    primary: "#3B82F6"
+```
+
+→ Generar:
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          primary: '#3B82F6',
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Ejemplo Completo de DESIGN.md
+
+```yaml
+---
+created: "2024-03-15"
+status: active
+type: reference
+tags: [design-system, tokens, componentes]
+colors:
+  brand:
+    primary: "#3B82F6"
+    secondary: "#8B5CF6"
+  surface:
+    background: "#FFFFFF"
+    card: "#F9FAFB"
+  text:
+    primary: "#111827"
+    secondary: "#6B7280"
+  semantic:
+    success: "#10B981"
+    warning: "#F59E0B"
+    error: "#EF4444"
+    info: "#3B82F6"
+typography:
+  font-family:
+    sans: "Inter, system-ui, sans-serif"
+    mono: "JetBrains Mono, monospace"
+  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" }
+  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:
+  tokens: { xs: "0.25rem", sm: "0.5rem", md: "1rem", lg: "1.5rem", xl: "2rem", "2xl": "3rem" }
+rounded:
+  tokens: { none: "0", sm: "0.25rem", md: "0.5rem", lg: "0.75rem", xl: "1rem", full: "9999px" }
+elevation:
+  tiers:
+    none: "none"
+    sm: "0 1px 3px rgba(0,0,0,0.1)"
+    md: "0 4px 6px rgba(0,0,0,0.1)"
+    lg: "0 10px 15px rgba(0,0,0,0.1)"
+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" }
+  card:
+    variants: [default, elevated]
+    base: "border-radius: {rounded.lg}, padding: {spacing.lg}, background: {colors.surface.card}"
+  input:
+    variants: [default, error, disabled]
+    base: "border: 1px solid #D1D5DB, border-radius: {rounded.md}"
+responsive:
+  breakpoints: { sm: "640px", md: "768px", lg: "1024px", xl: "1280px" }
+---
+
+## Visión General
+
+Sistema de diseño basado en tokens con jerarquía de tres niveles:
+1. **Tokens base**: Valores crudos (colores hex, tamaños rem)
+2. **Tokens semánticos**: Valores con propósito (success, error)
+3. **Tokens de componente**: Valores por defecto de cada componente
+
+## Paleta de Colores
+
+La paleta se organiza en 4 categorías:
+- **Brand**: Identidad visual de la marca
+- **Surface**: Fondos y superficies
+- **Text**: Jerarquía de texto
+- **Semantic**: Estados y feedback
+
+## Uso de Tokens
+
+En CSS:
+```css
+.button-primary {
+  background: var(--color-brand-primary);
+  border-radius: var(--rounded-md);
+  padding: var(--spacing-sm) var(--spacing-md);
+}
+```
+
+En Tailwind:
+```html
+<button class="bg-primary rounded-md px-4 py-2">
+```
+```