ckm:design-system

Visión general

¿Qué es ckm:design-system?

ckm:design-system es una skill de design system que combina arquitectura de design tokens, especificaciones de componentes y generación de slides de presentación en un flujo de trabajo único y reutilizable.

Se basa en un modelo de tokens de tres capas (primitive → semantic → component), con referencias y scripts de apoyo para:

• Sistemas de variables CSS
• Escalas de espaciado y tipografía
• Estados y variantes de componentes
• Configuración de temas en Tailwind
• Diseños sistemáticos de slides y pitch decks

La skill incluye tablas de datos y plantillas con una opinión fuerte para fondos de slides, lógica de color, fórmulas de texto, layouts y estrategias narrativas, además de scripts para generar y validar tokens y estructuras de slides.

¿Para quién es esta skill?

ckm:design-system está orientada a:

• Líderes de design system y diseñadores UI/UX que quieren una arquitectura de tokens clara y una referencia de specs de componentes.
• Desarrolladores frontend y React/Tailwind que necesitan un pipeline sólido de tokens (variables CSS, validadores, pistas de integración con Tailwind).
• Founders, PMs y personas de marketing que crean pitch decks con frecuencia y prefieren marcos de slides repetibles y coherentes con la marca en lugar de empezar desde cero cada vez.

Si buscas conectar el pensamiento de diseño tipo Figma con tokens listos para implementación y un sistema de slides reutilizable, esta skill encaja muy bien.

¿Qué problemas resuelve?

ckm:design-system te ayuda a:

• Estandarizar design tokens con una estratificación documentada primitive → semantic → component.
• Generar tokens CSS desde JSON y validar su uso en tu código.
• Planificar temas en Tailwind usando la misma arquitectura de tokens.
• Definir specs de componentes incluyendo estados y variantes para mantener la UI consistente entre pantallas.
• Diseñar presentaciones coherentes con la marca usando layouts de slides predefinidos, recomendaciones de gráficos, lógica de color y emoción, y fórmulas de copy.

Te da una forma estructurada de pensar tanto tu UI como tus slides como sistemas, no como piezas aisladas.

¿Cuándo encaja bien ckm:design-system?

Usa esta skill cuando:

• Estás introduciendo o refactorizando un design system y quieres capas de tokens explícitas.
• Necesitas orientación sobre variables CSS y Tailwind conectada a la arquitectura de tokens.
• Quieres generar y validar design tokens en lugar de gestionarlos a mano.
• Creas pitch decks, presentaciones comerciales o demos de producto de forma habitual y quieres una estructura de slides repetible.

Es menos adecuada si solo necesitas un único mock estático de UI o si no usas tokens ni variables CSS en absoluto.

Cómo usarla

Instalación y configuración básica

1. Instala la skill ckm:design-system

Instala la skill en tu entorno de Agent/skills:

npx skills add https://github.com/nextlevelbuilder/ui-ux-pro-max-skill --skill design-system

Esto descarga la skill design-system del repositorio nextlevelbuilder/ui-ux-pro-max-skill a tu directorio local de skills.

2. Explora los archivos principales

Tras la instalación, abre la carpeta de la skill y empieza por:

• SKILL.md – Visión general, cuándo usar la skill, arquitectura de tokens y comandos de arranque rápido.
• references/ – Documentación conceptual sobre tokens, componentes, variantes e integración con Tailwind.
• data/ – Archivos CSV que codifican fondos de slides, lógica de color, fórmulas de copy, layouts, tipografía y estrategias.
• scripts/ – Scripts de utilidad para generar, incrustar y validar tokens, además de helpers para búsqueda de slides.
• templates/design-tokens-starter.json – Plantilla JSON inicial para definir tu propio set de tokens.

Esta estructura te permite decidir rápidamente qué partes adoptar: solo tokens, solo slides o el sistema completo.

Diseñar tu arquitectura de tokens

3. Entiende el modelo de tokens en tres capas

SKILL.md y references/token-architecture.md describen una estructura en tres pasos:

Primitive (raw values)
       ↓
Semantic (purpose aliases)
       ↓
Component (component-specific)

Usa los archivos de referencia para diseñar cada capa:

• references/primitive-tokens.md – Colores base, espaciados, radios, tipografía primitiva.
• references/semantic-tokens.md – Tokens orientados a propósito como --color-primary, --surface-elevated, --text-muted.
• references/component-tokens.md – Variables a nivel de componente como --button-bg, --card-border, --badge-pill-radius.

Esta separación facilita:

• Cambiar temas sin reescribir componentes.
• Mantener los detalles de implementación (variables CSS, config de Tailwind) alineados con el lenguaje de diseño.

4. Crea o adapta tu JSON de tokens

Usa templates/design-tokens-starter.json como base para tu propio archivo de tokens.

Flujo de trabajo típico:

1. Copia templates/design-tokens-starter.json en tu proyecto como tokens.json.
2. Rellena primero los valores primitive (colores, espaciamiento, tamaños de fuente).
3. Asigna primitives a roles semantic (primary, secondary, surface, border, etc.).
4. Mapea tokens semantic a tokens de componente para cada elemento clave de la UI.

Consulta:

• references/component-specs.md – Para pensar cómo los componentes consumen tokens.
• references/states-and-variants.md – Para estados hover, focus, disabled, error y variaciones.

Generación y validación de tokens

5. Genera variables CSS a partir de los tokens

Usa el script de generación de tokens descrito en SKILL.md:

node scripts/generate-tokens.cjs --config tokens.json -o tokens.css

• --config apunta a tu JSON de tokens (por ejemplo, tokens.json).
• -o define el archivo CSS de salida (por ejemplo, tokens.css).

El resultado es un archivo CSS que define tu set de tokens como --custom-properties, listo para importarse en tu frontend.

6. Valida el uso de tokens en tu código

Para asegurar que tu código solo usa tokens aprobados, ejecuta el validador de tokens:

node scripts/validate-tokens.cjs --dir src/

Esto revisa el directorio indicado (por ejemplo src/) en busca de patrones de uso de tokens y te ayuda a:

• Detectar valores hard-coded que deberían ser tokens.
• Identificar tokens obsoletos o no definidos.

Validadores adicionales en scripts/ incluyen:

• html-token-validator.py – Para escanear HTML en busca de patrones de uso de tokens.
• slide-token-validator.py – Para validar el uso de tokens en contextos relacionados con slides.

Úsalos para mantener tu UI y tus slides alineados con tu design system.

7. Incrusta tokens donde sea necesario

Si tu entorno requiere incrustar tokens en documentación o HTML, puedes usar:

• scripts/embed-tokens.cjs – Incrusta tokens en archivos de destino.

Revisa los comentarios inline en el script y en SKILL.md para ver pautas de uso específicas para tu entorno.

Tailwind y consideraciones de implementación

8. Planifica la integración con Tailwind

La skill incluye una referencia específica para Tailwind:

• references/tailwind-integration.md – Guía para mapear nombres de tokens y escalas a una configuración de tema de Tailwind.

Úsala para:

• Mapear tokens primitive/semantic a las escalas colors, spacing y fontSize de Tailwind.
• Mantener las utility classes de Tailwind alineadas con tu diseño de tokens (por ejemplo, una paleta primary derivada de primitives).

Aunque no vayas a usar Tailwind de inmediato, esta referencia es útil para pensar cómo tu sistema de tokens escalará hacia CSS utility-first.

Crear pitch decks sistematizados

Aunque la categoría principal es design systems, ckm:design-system también soporta diseño de presentaciones estructuradas.

9. Usa las tablas de datos de slides para layout y visuales

El directorio data/ contiene archivos CSV que codifican patrones de slides de buenas prácticas:

• data/slide-backgrounds.csv – Tipos recomendados de imagen de fondo, overlays y ubicación por tipo de slide (hero, visión, equipo, testimonio, CTA, problema, solución, etc.).
• data/slide-color-logic.csv – Cómo se asocian emociones (frustration, hope, fear, relief, trust, urgency, curiosity, etc.) con estilos de fondo, colores de texto y uso de acentos.
• data/slide-typography.csv – Guía tipográfica por tipo de slide (jerarquía, énfasis, etc.).
• data/slide-layout-logic.csv – Patrones de layout impulsados por objetivos narrativos y emociones (hook, problem, solution, proof, traction, CTA, timeline, features, etc.).
• data/slide-layouts.csv – Patrones de layout concretos con pistas de estructura CSS (por ejemplo, grids, layouts divididos, estructuras hero, sugerencias de animación).

Puedes cargar estas tablas en tu propio pipeline (scripts, hojas de cálculo o un generador de decks) para crear slides consistentes guiados por la narrativa y la emoción, en lugar de decisiones de diseño arbitrarias.

10. Estructura el copy de tus slides con fórmulas probadas

data/slide-copy.csv incluye fórmulas de copywriting adaptadas a diferentes tipos de slide, entre ellas:

• AIDA (Attention → Interest → Desire → Action)
• PAS (Problem → Agitate → Solution)
• 4Ps (Promise → Picture → Proof → Push)
• Before-After-Bridge
• QUEST
• Star-Story-Solution

Cada fila incluye:

• formula_name y keywords
• components estructurados
• use_case y example_template
• emotion_trigger y slide_type

Úsalos para:

• Pedir a un agente que redacte el copy de slides siguiendo una fórmula específica.
• Estandarizar el copy entre pitch decks y presentaciones comerciales.

11. Elige estrategias de slides para decks completos

data/slide-strategies.csv define patrones de decks completos, por ejemplo:

• YC Seed Deck
• Guy Kawasaki 10/20/30
• Series A Deck

Cada estrategia incluye:

• Número recomendado de slides
• Secuencia (title, problem, solution, traction, market, etc.)
• Objetivo, audiencia y tono
• Arcos narrativos y emocionales

Esto te permite:

• Generar un esquema completo de slides para una estrategia elegida.
• Mantener alineados el design system y la estructura narrativa.

12. Trabaja con los scripts de slides

El directorio scripts/ incluye utilidades relacionadas con flujos de trabajo de slides:

• scripts/generate-slide.py – Lógica central de generación de slides (puedes adaptarla a tu propio generador de decks o pipeline).
• scripts/search-slides.py y scripts/slide_search_core.py – Utilidades de búsqueda que te ayudan a encontrar patrones o estrategias de slides relevantes según keywords y contexto.
• scripts/fetch-background.py – Ayuda a obtener imágenes de fondo (por ejemplo, de Pexels/Unsplash) basadas en las directrices de data/slide-backgrounds.csv.

Estos scripts son bloques de construcción. Puedes ejecutarlos o adaptarlos según tu entorno y necesidades de automatización.

Trabajar con referencias y documentación

13. Usa las referencias como checklists de implementación

La carpeta references/ no es solo documentación; también funciona como checklist mientras construyes tu design system:

• references/token-architecture.md – Comprueba que tu estratificación primitive/semantic/component sea sólida.
• references/primitive-tokens.md – Asegúrate de tener un set completo de tokens base.
• references/semantic-tokens.md – Verifica que cada token semantic tenga un propósito claro.
• references/component-tokens.md – Mapea tokens a componentes reales.
• references/component-specs.md – Recoge estados, variantes, interacciones y consideraciones de accesibilidad.
• references/states-and-variants.md – Evita olvidarte de estados hover, focus, active, disabled, error y success.

Usa estos archivos durante revisiones de diseño y handoff para mantener alineados a diseñadores y desarrolladores.

Adaptar la skill a tu stack

14. Integra de forma gradual

No tienes que adoptar toda la skill de una vez. Enfoques incrementales habituales:

• Adopción solo de tokens – Empieza con templates/design-tokens-starter.json, generate-tokens.cjs y validate-tokens.cjs para poner en marcha un pipeline de tokens.
• Adopción solo de slides – Usa los CSV de data/ y scripts/generate-slide.py para estandarizar tus presentaciones manteniendo tu design system actual.
• Adopción completa – Combina tokens, componentes y estructuras de slides para construir un sistema de marca unificado entre la UI del producto y los pitch decks.

Céntrate primero en la parte que resuelve tu problema más urgente y después amplía.

FAQ

¿ckm:design-system es un UI kit o un motor de design tokens?

Es principalmente una skill de design system y arquitectura de tokens que además incluye un sistema de slides estructurado. No se entrega como un UI kit de Figma, pero te proporciona:

• Una arquitectura de tokens en tres capas
• Scripts para generar y validar tokens
• Referencias para specs y estados de componentes

Puedes reflejar fácilmente los mismos tokens y componentes en Figma o en cualquier otra herramienta de diseño.

¿Puedo usar ckm:design-system sin Tailwind ni React?

Sí. La integración con Tailwind se documenta en references/tailwind-integration.md, pero es opcional. Los tokens se generan como variables CSS estándar, por lo que puedes usarlos en cualquier stack:

• CSS plano o CSS Modules
• Styled-components u otras soluciones CSS-in-JS
• Design tokens para Web Components u otros frameworks

¿Cómo ayuda ckm:design-system con las presentaciones?

La skill trata los slide decks como un problema de design system:

• data/slide-layouts.csv y data/slide-layout-logic.csv definen patrones de layout y estructuras CSS.
• data/slide-backgrounds.csv y data/slide-color-logic.csv relacionan tipos de slide y emociones con elementos visuales.
• data/slide-copy.csv y data/slide-strategies.csv aportan fórmulas de copy y estructuras de decks.
• Scripts como generate-slide.py y search-slides.py ayudan a automatizar la generación y la búsqueda.

Esto te permite crear decks repetibles y coherentes con la marca en lugar de slides aislados.

¿Tengo que usar los datos CSV tal cual vienen?

No. Los CSV son defaults con opinión. Puedes:

• Usarlos tal cual para generar pitch decks rápidamente.
• Hacer fork y personalizarlos para que encajen con la voz y el estilo visual de tu marca.
• Sustituirlos por completo por tus propios datos manteniendo los mismos patrones de scripts.

¿Por dónde empiezo si solo me interesan los design tokens?

Si tu foco está exclusivamente en tokens e implementación de UI:

1. Lee SKILL.md, especialmente las secciones "When to Use" y "Token Architecture".

2. Abre references/token-architecture.md y las referencias de tokens primitive/semantic/component.

3. Copia templates/design-tokens-starter.json y crea tu tokens.json.

4. Ejecuta:

   node scripts/generate-tokens.cjs --config tokens.json -o tokens.css
   node scripts/validate-tokens.cjs --dir src/
   

Con esto tendrás un pipeline de tokens funcionando sin necesidad de tocar el sistema de slides.

¿ckm:design-system es adecuada para proyectos pequeños?

Puede serlo, pero su fortaleza se nota en proyectos donde:

• Varias personas contribuyen a la UI o a los decks
• La consistencia y la escalabilidad importan
• Esperas iterar sobre la marca o el producto con el tiempo

Para una landing page puntual o una sola presentación interna, el sistema completo puede ser más estructura de la que necesitas. Aun así, puedes aprovechar la arquitectura de tokens o las fórmulas de slides como guía ligera.

¿Cómo veo todo lo que incluye la skill?

En tu explorador de skills o de archivos, revisa el árbol completo de la skill design-system, en especial:

• SKILL.md
• data/
• references/
• scripts/
• templates/design-tokens-starter.json

Así verás todas las referencias anidadas y scripts de ayuda y podrás decidir qué piezas integrar en tu propio flujo de trabajo.