cooper-design

cooper-design

Sistemas de diseño con criterio — auditoría, generación, documentación y sincronización de design tokens y componentes.

cooper-design fusiona dos disciplinas que rara vez conviven bien: el ojo de un director de arte y la disciplina de un ingeniero de sistemas. Un design system no es una paleta bonita ni una librería de componentes — es infraestructura que debe escalar, versionar y auditarse. cooper-design la trata con el rigor de un sistema distribuido y el criterio de una identidad de marca.

Inspirado en Muriel Cooper (MIT Media Lab), pionera en unir diseño e información computacional.

Qué es

Este repo contiene dos piezas que trabajan juntas:

• skill/ — Una Claude Skill: el "cerebro" con el conocimiento de diseño (color, tipografía, WCAG, roles semánticos), arquitectura (SOLID, CQRS, event sourcing) y metodología de auditoría.
• mcp/ — Un servidor MCP en TypeScript: el "motor" que ejecuta auditorías, verifica contraste, resuelve tokens y exporta a distintos formatos. Conectable desde Claude Desktop, Claude Code y VS Code (Copilot en modo Agente) — ver INSTALL.md.

Capacidades

Modo	Qué hace
Auditar	Puntúa un design system (0-100) en 6 dimensiones: cobertura de tokens, consistencia, completitud, accesibilidad WCAG, huérfanos y documentación.
Generar	Crea tokens con razón declarada: escalas modulares, roles semánticos, 60-30-10, WCAG AA verificado.
Documentar	Genera documentación de componentes y tokens con plantillas rigurosas.
Handoff	Genera la especificación técnica para pasar el diseño a ingeniería: tokens, contraste, contratos de componente, huecos y checklist.
Sincronizar	Extrae de Figma, hace diff contra el repo, registra cambios como eventos, genera PR y actualiza Notion.

Herramientas MCP disponibles

• audit_system — auditoría unificada de 100 puntos: combina tokens y componentes en un solo veredicto con acciones priorizadas. La herramienta principal del modo Auditar.
• audit_figma — extrae las Variables de un archivo de Figma y las audita directamente (requiere token con file_variables:read). Ver skill/reference/figma-integration.md.
• sync_to_github — extrae de Figma, calcula el diff contra el repo y abre un Pull Request con changelog (requiere tokens de Figma y GitHub).
• publish_audit_to_notion — audita un sistema y publica el reporte como página de Notion. Ver skill/reference/notion-integration.md.
• audit_tokens — audita solo los tokens (5 dimensiones).
• audit_components — audita solo la completitud de componentes.
• generate_tokens — modo Generar: escalas tipográficas modulares, espaciado, neutros perceptuales (OKLCH), paletas semánticas con WCAG AA garantizado por construcción y modo oscuro automático derivado de la paleta light. Ver skill/reference/generation.md.
• generate_handoff — modo Handoff: genera el spec técnico para pasar el diseño a ingeniería (referencia de tokens, contrato de contraste WCAG+APCA, contratos de componente, huecos, checklist). Ver skill/reference/handoff.md.
• check_contrast — verifica contraste entre dos colores HEX: ratio WCAG 2 (AA/AAA) y Lc de APCA (WCAG 3, perceptual).
• export_tokens — exporta tokens a CSS, Tailwind, Swift (iOS) o Android XML.
• export_style_dictionary — genera el bundle de pipeline de Style Dictionary v4 (tokens DTCG + config + README) para salida multi-plataforma con npx style-dictionary build.

Instalación

cd mcp && npm install && npm run build && npm run doctor

Luego conéctalo a tu cliente (VS Code, Claude Desktop o Claude Code). Los pasos exactos, con la configuración de cada uno, están en INSTALL.md.

Arquitectura

El motor aplica patrones de System Design directamente al dominio de design systems:

• SOLID — cada módulo una responsabilidad; nuevos exporters e integraciones sin tocar el núcleo.
• CQRS — lectura (queries) separada de escritura (commands).
• Event Sourcing — cada cambio de token es un evento inmutable → auditabilidad total.
• Cache Aside — no golpear la API de Figma en cada operación.

Ver docs/ARCHITECTURE.md.

Instalación (MCP)

cd mcp
npm install
npm run build

Para conectarlo a un host MCP (ej. Claude Desktop), añade a la configuración:

{
  "mcpServers": {
    "cooper-design": {
      "command": "node",
      "args": ["/ruta/a/cooper-design/mcp/dist/server/index.js"]
    }
  }
}

Desarrollo

npm run dev        # compilación en watch
npm run typecheck  # verificación de tipos
npm test           # tests (node:test)

Integraciones v1

• Figma — extracción de tokens (fuente de verdad visual)
• GitHub — sincronización y PRs (fuente de verdad de código)
• Notion — documentación automática

Contribuir

Las contribuciones son bienvenidas — con una premisa: rigor sobre volumen. Lee CONTRIBUTING.md para la filosofía y el proceso, y CODE_OF_CONDUCT.md para las normas de convivencia. Hay plantillas de issues y de PR en .github/.

Licencia

MIT © Dariel Corrales González