Design System v4 (Brand-Configurable)

Foundation system for building styled HTML documents. All colors, typography, layout patterns, and component specs. CRITICAL: All brand tokens are configurable via brand-config.json — no hardcoded brand colors. Works for ANY brand.

Principio Rector

Un deliverable sin marca es un documento genérico. Un deliverable con marca es una experiencia profesional. El design system convierte documentos técnicos en artefactos de marca que transmiten confianza, profesionalismo, y atención al detalle. Cada color, cada tipografía, cada espaciado tiene un propósito.

Filosofía de Design System

1. Tokens, no hardcode. Todo configurable via brand-config.json. Cambiar de marca = cambiar un archivo, no reescribir CSS.
2. Consistencia > creatividad. Dentro de un engagement, todos los deliverables se ven como parte del mismo sistema. Sin sorpresas visuales.
3. Responsive y accessible. Print-ready layout, alto contraste para legibilidad, semántica HTML para screen readers.

$ARGUMENTS

$ARGUMENTS format: [action] [brand-config-path]
Examples:
  "generate template with ./brand-config.json"  → load config, produce HTML template
  "apply tokens to report.html"                 → apply design tokens to existing file
  "show component library"                      → list all available components
  "validate colors in dashboard.html"           → check all colors match token reference

• If no brand-config.json exists → use neutral defaults (shown below)
• If action missing → show available actions: template, apply, components, validate

Parámetros de Pipeline

• MODO=desatendido → genera sin pausas, valida al final
• FORMATO=dual → produce .html + .md con tokens documentados
• VARIANTE=ejecutiva → solo component quick reference + brand config, sin CSS raw

Output Format Protocol

• HTML siempre incluye Google Fonts link, print stylesheet, y skip-to-content
• Markdown incluye front-matter YAML con metadata del brand-config

Brand Configuration Schema

All brand identity lives in brand-config.json. No brand values hardcoded in skill or templates.

{
  "brand": {
    "name": "Acme Corp",
    "logo_text": "acme_",
    "primary": "#3B82F6",
    "primary_light": "#60A5FA",
    "primary_dark": "#2563EB",
    "primary_dim": "rgba(59,130,246,0.10)",
    "black": "#000000",
    "white": "#FFFFFF",
    "background": "#F5F5F5",
    "muted": "#9CA3AF"
  },
  "fonts": {
    "display": "'Inter', system-ui, sans-serif",
    "body": "'Inter', system-ui, sans-serif",
    "google_fonts_url": "https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap"
  }
}

Neutral Defaults (when no brand-config.json provided)

Mapping Rule

In ALL templates and components, reference var(--brand-primary) never a hex literal. The CSS custom properties are set from brand-config.json at generation time:

:root {
  --brand-primary: var(--from-config, #3B82F6);
  --brand-primary-light: var(--from-config, #60A5FA);
  --brand-primary-dark: var(--from-config, #2563EB);
  --brand-primary-dim: var(--from-config, rgba(59,130,246,0.10));
  --brand-black: var(--from-config, #000000);
  --brand-white: var(--from-config, #FFFFFF);
  --brand-background: var(--from-config, #F5F5F5);
  --brand-muted: var(--from-config, #9CA3AF);
}

Semantic Colors (Brand-Independent)

These are universal and do NOT change per brand:

Decorative Colors (Charts/Data Visualization Only)

Typography

Spacing & Radius

Page Structure

Layout Grid

• Max-width: 1100px, margin: 0 auto, padding: 0 2rem (1rem on mobile)
• Body background: var(--brand-background)

Standard Sections

1. Hero Header — bg: var(--brand-black), border-bottom: 8px solid var(--brand-primary), radial gradient glow. Contains: logo, meta badges, h1 with brand-primary highlight, subtitle.

2. Sticky Nav — bg: var(--brand-white), sticky top:0 z-100, border-bottom 1px solid gray-200. Links: uppercase 0.72rem, active = brand-primary border-bottom.

3. Main Container — max-width 1100px, margin 0 auto, padding 0 2rem.

4. Sections — scroll-margin-top 60px, padding 6rem 0. Section header: 60x60px black box with brand-primary number + title.

5. Footer — bg: var(--brand-black), border-top: 8px solid var(--brand-primary), white text. Two-row: (logo + badges) above (confidentiality + doc ref).

Component Quick Reference

For full component HTML snippets, read: ${CLAUDE_SKILL_DIR}/references/component-snippets.md

Generation Workflow

1. Load Config — Read brand-config.json (or use neutral defaults)
2. Plan — Define sections, required components, color usage, TOC structure
3. Generate HTML — Apply base template with brand tokens injected into :root
4. Build Hero — Logo from config, meta badges, h1 with brand-primary span, subtitle
5. Build Nav — Auto-generate from section IDs
6. Build Sections — Section headers with brand-primary numbers, content with semantic components
7. Validate — All colors match tokens (no hex literals outside :root). Severity low = yellow. Hero/footer borders = brand-primary. TOC is horizontal sticky. Semantic HTML used. WCAG AA contrast met.
8. Export — Save .html, test responsive, verify font loading, check keyboard nav

Color Usage Rules

• Brand colors (primary, black, white, background): from brand-config.json via CSS custom properties
• Semantic states (positive=yellow, warning=amber, critical=red, info=blue): universal, never change per brand
• Decorative (green, teal, violet, pink, yellow): charts and data visualization ONLY
• NEVER use hex literals in component HTML — always reference var(--token-name)

Responsive Breakpoints

• Mobile: < 768px (1rem padding)
• Tablet: 768-1024px (1.5rem padding)
• Desktop: > 1024px (2rem padding)

Accessibility

• Skip link: href="#main"
• Focus-visible: outline 2px solid var(--brand-primary)
• Contrast: WCAG AA (4.5:1 body text, 3:1 large text)
• Semantic HTML: header, nav, main, section, footer
• Alt text required on all images
• Severity medium: BLACK text on yellow bg (WCAG AA compliance)

Trade-off Matrix

Assumptions & Limits

• Requires brand-config.json for branded output; without it, uses neutral blue defaults
• Font loading depends on Google Fonts CDN availability; fallback to system fonts
• Component library covers 90% of deliverable needs; custom components follow same token system
• Responsive design targets 3 breakpoints; complex dashboards may need additional breakpoints
• WCAG AA compliance assumed; AAA requires additional contrast verification
• Mermaid diagrams render client-side via CDN; offline environments need pre-rendered SVGs
• Design system assumes single-brand per engagement; multi-brand requires separate config files

Casos Borde

Decisiones y Trade-offs

Knowledge Graph

graph TD
    subgraph Core
        DS[design-system]
    end
    subgraph Inputs
        BC[brand-config.json] --> DS
        CT[Content & Section Plan] --> DS
        DT[Document Type Decision] --> DS
    end
    subgraph Outputs
        DS --> HTML[Styled HTML Deliverable]
        DS --> TOK[Token Documentation]
        DS --> COMP[Component Library Reference]
    end
    subgraph Related Skills
        DS -.-> HB[html-brand]
        DS -.-> BV[brand-voice]
        DS -.-> ME[markdown-excellence]
        DS -.-> UW[ux-writing]
    end

Output Templates

Formato MD (default):

# Design System: {brand_name}
## Token Reference
  - Brand colors (primary, light, dark, dim)
  - Semantic colors (positive, warning, critical, info)
  - Typography scale
  - Spacing & radius
## Component Quick Reference
  - Cards, badges, callouts, tables
  - Usage guidelines per component
## Validation Checklist

Formato HTML (primary):

• Filename: D-01_Design_System_{project}_{WIP}.html
• Documento HTML self-contained con tokens inyectados en :root, branded (Design System MetodologIA v5). Incluye componentes renderizados con ejemplos interactivos, paleta de tokens visual y checklist de validación WCAG. Print stylesheet incluido, skip-to-content y WCAG AA compliance.

Formato DOCX (circulación formal):

• Filename: {fase}_{entregable}_{cliente}_{WIP}.docx
• Generado via python-docx con MetodologIA Design System v5. Portada con metadata del engagement, TOC automático, encabezados/pies de página con marca. Tablas con zebra striping, tipografía Poppins en headings (navy), Montserrat en cuerpo, acentos dorados. Para circulación formal y auditoría.

Formato XLSX (bajo demanda):

• Filename: {fase}_{entregable}_{cliente}_{WIP}.xlsx
• Via openpyxl con MetodologIA Design System v5. Headers con fondo navy y tipografía Poppins en blanco, conditional formatting por token type y estado de validación WCAG, auto-filters en todas las columnas, valores directos sin fórmulas.

Formato PPTX (bajo demanda):

• Filename: {fase}_{entregable}_{cliente}_{WIP}.pptx
• Via python-pptx con MetodologIA Design System v5. Navy gradient slide master, Poppins titles, Montserrat body, gold accents. Máx 20 slides ejecutivo / 30 técnico. Speaker notes con referencias de evidencia.

Evaluacion

Umbral minimo global: 7/10. Deliverables por debajo requieren re-work antes de entrega.

Edge Cases

Validation Gate

Before delivering design system output:

• All brand colors sourced from brand-config.json (no hardcoded hex in components)
• Semantic colors applied correctly (positive=yellow, not green)
• Hero and footer use brand-primary for 8px borders
• All text meets WCAG AA contrast ratios
• Responsive at all 3 breakpoints
• No hex literals in component HTML (only var() references)
• Font fallbacks specified for display and body
• MODO/FORMATO/VARIANTE params respected in output
• Print stylesheet present when FORMATO=html
• Mermaid diagrams render correctly if included

Cross-References

• brand-html — applies this design system to generate full HTML deliverables
• brand-voice — brand tone and messaging (complements visual system)
• markdown-excellence — writing standard for markdown output format

Output Artifact

Primary: D-01_Design_System_{project}.md (o .html si {FORMATO}=html|dual) — Design tokens, component library, usage guidelines, accessibility standards.

Diagramas incluidos:

• Component hierarchy diagram
• Token inheritance flowchart
• Responsive breakpoint matrix

Autor: Javier Montaño | Última actualización: 12 de marzo de 2026