Configurable design system for HTML deliverables with tokens, page structure, and component library. Use when the user asks to "apply design system", "generate styled HTML", "set up brand tokens", "configure brand colors", or mentions "design system", "design tokens", "component library", "brand config", "page template".
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.
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.
$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
| Parámetro | Valores | Default | Efecto |
|---|---|---|---|
MODO | piloto-auto, desatendido, supervisado, paso-a-paso | piloto-auto | Nivel de intervención humana durante generación |
FORMATO | html, markdown, dual | html | Formato de salida del deliverable |
VARIANTE | ejecutiva, técnica | técnica | Ejecutiva (~40% contenido, visual-first) vs técnica (full token docs + snippets) |
MODO=desatendido → genera sin pausas, valida al finalFORMATO=dual → produce .html + .md con tokens documentadosVARIANTE=ejecutiva → solo component quick reference + brand config, sin CSS raw| FORMATO | Estructura | Uso Principal |
|---|---|---|
html | HTML completo con tokens inyectados en :root, componentes renderizados | Deliverables finales, presentaciones a cliente |
markdown | Token tables en MD, snippets en code blocks, sin HTML renderizado | Documentación interna, wikis, READMEs |
dual | Ambos archivos generados en paralelo | Cuando el consumidor necesita ambos formatos |
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"
}
}
| Token | Default Value | Usage |
|---|---|---|
--brand-primary | #3B82F6 (blue) | Accents, borders, active states |
--brand-primary-light | #60A5FA | Hover states |
--brand-primary-dark | #2563EB | Pressed states, dark mode |
--brand-primary-dim | rgba(59,130,246,0.10) | Light backgrounds |
--brand-black | #000000 | Text, headings, hero bg |
--brand-white | #FFFFFF | Text on dark, card backgrounds |
--brand-background | #F5F5F5 | Body background |
--brand-muted | #9CA3AF | Secondary text |
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);
}
These are universal and do NOT change per brand:
| Token | Value | Usage |
|---|---|---|
--semantic-positive | #22D3EE | Success state (yellow, not green — v4 rule) |
--semantic-positive-dim | rgba(255,215,0,0.12) | Positive background tint |
--semantic-positive-border | rgba(255,215,0,0.45) | Positive border |
--semantic-positive-text | #06B6D4 | Text on positive backgrounds |
--semantic-warning | #D97706 | Warning state |
--semantic-warning-dim | rgba(217,119,6,0.08) | Warning background |
--semantic-critical | #DC2626 | Error/critical state |
--semantic-critical-dim | rgba(220,38,38,0.07) | Critical background |
--semantic-info | #2563EB | Information state |
--semantic-info-dim | rgba(37,99,235,0.07) | Info background |
| Token | Value |
|---|---|
--chart-green | #42D36F |
--chart-teal | #06C8C8 |
--chart-violet | #9747FF |
--chart-pink | #FE9CAB |
--chart-yellow | #22D3EE |
| Element | Font | Size | Weight | Line Height |
|---|---|---|---|---|
| h1 | var(--font-display) | clamp(2.5rem, 5vw, 4.2rem) | 700 | 1.1 |
| h2 | var(--font-display) | 2.2rem | 700 | 1.2 |
| h3 | var(--font-display) | 1.8rem | 700 | 1.2 |
| h4 | var(--font-display) | 1.4rem | 600 | 1.3 |
| Body | var(--font-body) | 1rem | 400 | 1.6 |
| Small | var(--font-body) | 0.875rem | 400 | 1.5 |
| Mono | Menlo, Monaco, monospace | 0.85rem | 400 | 1.4 |
| Token | Value | Usage |
|---|---|---|
--radius-sm | 6px | Small buttons |
--radius-md | 12px | Callouts, medium elements |
--radius-lg | 16px | Cards, panels |
--radius-xl | 24px | Large containers |
--shadow-sm | 0 1px 2px rgba(0,0,0,0.05) | Subtle elevation |
--shadow-md | 0 4px 12px rgba(0,0,0,0.08) | Medium elevation |
--shadow-lg | 0 12px 40px rgba(0,0,0,0.12) | Modals |
--shadow-card | 0 1px 3px rgba(0,0,0,0.04), 0 6px 16px rgba(0,0,0,0.06) | Cards |
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.
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.
Main Container — max-width 1100px, margin 0 auto, padding 0 2rem.
Sections — scroll-margin-top 60px, padding 6rem 0. Section header: 60x60px black box with brand-primary number + title.
Footer — bg: var(--brand-black), border-top: 8px solid var(--brand-primary), white text. Two-row: (logo + badges) above (confidentiality + doc ref).
| Component | Class | Notes |
|---|---|---|
| Card Base | .card | White, padded, rounded |
| Card Accent | .card-accent | Brand-primary top border |
| Card Critical | .card-critical | Red left border + red tint |
| Card Warning | .card-warning | Amber left border + amber tint |
| Card Success | .card-success | Yellow (v4) left border + yellow tint |
| Card Info | .card-info | Blue left border + blue tint |
| Card Dark | .card-dark | Black bg, white text |
| Card Grid | .card-grid-2/3/4 | Multi-column layout |
| Badge | .badge | Brand-primary bg, white text |
| Badge Outline | .badge-outline | Brand-primary border, transparent bg |
| Severity Critical | .sev-critical | Red bg, white text |
| Severity High | .sev-high | #EA580C bg, white text |
| Severity Medium | .sev-medium | Amber bg, BLACK text (WCAG) |
| Severity Low | .sev-low | Yellow bg, black text (v4) |
| Callout Info | .callout-info | Blue bg + blue border |
| Callout Warning | .callout-warning | Amber bg + amber border |
| Callout Success | .callout-success | Yellow bg + yellow border |
| Callout Critical | .callout-critical | Red bg + red border |
| Table Wrapper | .table-wrap | Overflow container |
| Diagram Box | .diagram-box | Dark monospace block |
| Progress Bar | .progress-bar | Horizontal indicator |
| Timeline | .timeline | Vertical with markers |
| Score Ring | .score-ring | Circular visualization |
For full component HTML snippets, read: ${CLAUDE_SKILL_DIR}/references/component-snippets.md
| Dimension | Opción A | Opción B | Regla de Decisión |
|---|---|---|---|
| Tokens vs Inline | CSS custom properties (tokens) | Inline styles | Siempre tokens. Inline solo para overrides puntuales en email templates |
| System fonts vs Web fonts | Rápido, sin dependencia CDN | Marca consistente, carga adicional | Web fonts para deliverables cliente; system fonts para uso interno |
| Full component lib vs Minimal | 25+ componentes, flexible | 8-10 core, rápido de aprender | Full para engagement largo; minimal para one-shot deliverables |
| Print-first vs Screen-first | Optimizado para PDF/impresión | Optimizado para pantalla interactiva | Screen-first por defecto; print-first si deliverable es para board/comité |
| Caso | Estrategia de Manejo |
|---|---|
| Brand primary extremadamente claro (#FFE0B2) que no pasa WCAG AA como texto | Auto-darken para texto usando HSL shift (-30% lightness). Usar brand-dark para borders y accents visibles. Validar contraste con herramienta automatizada antes de entregar. |
| Documento bilingue (es + en) con diferentes longitudes de texto | Usar lang attribute por seccion. Layout flexible con min-width en cards. Testear que texto largo no rompe grid en ambos idiomas. |
| Brand config con un solo color (sin secondary, sin light/dark variants) | Derivar primary-light (HSL +15% lightness) y primary-dark (HSL -15% lightness) programaticamente. Documentar colores derivados en el output para validacion del cliente. |
| Entorno offline sin acceso a Google Fonts CDN | Fallback a system-ui, -apple-system, sans-serif. Documentar degradacion visual. Ofrecer alternativa con fonts embebidas en base64 si tamano < 500KB. |
| Decision | Alternativa Descartada | Justificacion |
|---|---|---|
| CSS custom properties (tokens) sobre inline styles | Inline styles para cada elemento | Tokens permiten cambio de marca con un solo archivo. Inline requiere reescribir todo el documento. Mantenibilidad > velocidad de generacion. |
| Single-file HTML con CSS inline sobre CSS externo | CSS en archivo separado | Self-contained HTML garantiza portabilidad. El deliverable se abre en cualquier browser sin dependencias. Peso adicional (~20KB CSS) es aceptable vs. riesgo de archivo faltante. |
| Yellow para success states sobre green convencional | Green (#22C55E) para estados positivos | Green introduce tono frio que choca con paleta calida MetodologIA (indigo/dark). Yellow mantiene coherencia de marca. Diferenciador visual vs. competidores. |
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
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):
D-01_Design_System_{project}_{WIP}.html: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):
{fase}_{entregable}_{cliente}_{WIP}.docxFormato XLSX (bajo demanda):
{fase}_{entregable}_{cliente}_{WIP}.xlsxFormato PPTX (bajo demanda):
{fase}_{entregable}_{cliente}_{WIP}.pptx| Dimension | Peso | Criterio | Umbral Minimo |
|---|---|---|---|
| Trigger Accuracy | 10% | El skill se activa correctamente ante menciones de design system, tokens, brand config, styled HTML | 7/10 |
| Completeness | 25% | Todos los tokens documentados, componentes con snippets, responsive y accessibility cubiertos | 7/10 |
| Clarity | 20% | Mapping rules sin ambiguedad, cada token con uso definido, anti-patterns documentados | 7/10 |
| Robustness | 20% | Edge cases de color, RTL, print, dark mode cubiertos con fallbacks funcionales | 7/10 |
| Efficiency | 10% | Output generado sin tokens duplicados, CSS optimizado, single-file bajo 500KB | 7/10 |
| Value Density | 15% | Cada componente entrega snippet listo para copiar, no solo descripcion teorica | 7/10 |
Umbral minimo global: 7/10. Deliverables por debajo requieren re-work antes de entrega.
| Scenario | Adaptation |
|---|---|
| No brand-config.json | Use neutral defaults (blue primary, gray background) |
| Brand primary is very light (e.g., #FFE0B2) | Auto-darken for text; use brand-dark for borders |
| Brand primary is very dark (e.g., #1A1A2E) | Use brand-light for hover states; ensure contrast on dark hero |
| Print/PDF output | Remove sticky nav, reduce shadows, use high-contrast borders |
| Dark mode requested | Invert background tokens; keep semantic colors unchanged |
| RTL language brand | Mirror layout, flip border-left to border-right on accent cards |
| Brand with no secondary color | Derive primary-light and primary-dark programmatically from primary |
| Multiple brand configs in one project | Namespace tokens per brand; generate separate CSS bundles |
Before delivering design system output:
brand-html — applies this design system to generate full HTML deliverablesbrand-voice — brand tone and messaging (complements visual system)markdown-excellence — writing standard for markdown output formatPrimary: D-01_Design_System_{project}.md (o .html si {FORMATO}=html|dual) — Design tokens, component library, usage guidelines, accessibility standards.
Diagramas incluidos:
Autor: Javier Montaño | Última actualización: 12 de marzo de 2026