Communitygithub.com

mos-atomic-design-system

Construye o amplía un sistema de diseño atómico basado en la marca con tokens, especificaciones de componentes y un sitio de revisión en HTML. Útil para sistemas de diseño, kits de UI, bibliotecas de componentes, trabajo de marca a tokens y exportaciones de tokens desde Figma.

¿Qué es mos-atomic-design-system?

Este skill transforma una marca en un sistema de diseño completo y revisable, siguiendo una metodología por etapas (escalera) con aprobación humana entre cada una. Comienza con el descubrimiento de la marca y referencias de diseño, luego construye tokens, fundamentos, átomos, moléculas, organismos, plantillas y páginas, todo bajo una única carpeta `design-system/`. Cada etapa produce artefactos específicos (archivos de especificaciones, CSS de tokens, un sitio HTML de referencia estático) y se verifica automáticamente antes de solicitar aprobación. Funciona con MarketingOS (desde un cerebro activo) o con archivos de marca independientes, y puede extender sistemas existentes (v1 o legacy) sin migrarlos a menos que se solicite. El skill prioriza la coherencia de la marca, evita decisiones inventadas y permite reanudar el trabajo semanas después sin perder el contexto. Soporta exportación a tokens de Figma, integración con Taste Skill para dirección de arte, y un modo no interactivo para CI/evaluaciones.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/the-vibe-marketing-lab/mos-design-skills/tree/HEAD/mos-atomic-design-system

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

MarketingOS Sistema de Diseño Atómico

Convierte una marca en un sistema de diseño revisable: tokens por niveles, un archivo de especificaciones por componente y un sitio HTML de referencia estático, construido un escalón a la vez con aprobación humana entre cada uno, todo bajo una carpeta design-system/ que una persona o un agente puede navegar desde un único README.

Contexto y requisitos previos de MarketingOS

Resuelve el cerebro de negocio activo y el objetivo del sitio web desde la sesión actual y sus registros del proyecto. Lee el BRAIN.md del cerebro o las instrucciones del agente, CONTEXT.md, la marca, la voz, la audiencia, la oferta y las referencias de diseño guardadas antes de solicitar información. Mantén separado el contexto de cada negocio. Registra el cerebro fuente y el objetivo en el brief de diseño. Cuando se use sin MarketingOS, trabaja desde los archivos de marca suministrados e identifica las carencias genuinas.

Usa Bun para los scripts TypeScript empaquetados. Si falta, guía al usuario a las instrucciones oficiales de instalación en https://bun.com/docs/installation. Resuelve $SKILL al directorio real que contiene este SKILL.md cargado; los agentes instalan en diferentes lugares, así que no asumas una ruta de inicio particular.

Si el usuario ha seleccionado Taste Skill, lee primero sus instrucciones instaladas y usa su dirección de arte y hallazgos de referencia como entradas para este marco de trabajo. Preserva el contrato de marca de este marco de trabajo, su sistema de tokens y las decisiones de etapa. Taste Skill es una dependencia opcional separada, no incluida en este paquete; inspecciona sus instrucciones oficiales actuales en https://github.com/leonxlnx/taste-skill cuando se solicite su instalación.

Un solo prompt inicial puede impulsar el flujo de trabajo completo. Mantén las decisiones requeridas y las aprobaciones visuales de etapa en la misma conversación, reanudando después de cada respuesta sin requerir otro prompt de copiar-y-pegar. Detente en la etapa que el usuario solicitó; no trates una invocación como permiso para saltar aprobaciones.

La idea

Un sistema de diseño falla de dos maneras. O es inventado — el modelo elige una paleta bonita y el resultado es seguro, coherente y no la marca. O se construye todo de una vez, así que una decisión equivocada en la base se propaga silenciosamente a través de veinte páginas antes de que alguien la vea.

Este skill aborda ambas. Descubrimiento antes del diseño: encuentra lo que ya se ha decidido y sé explícito sobre las carencias. Una puerta entre escalones: retrabajar en Fundamentos es una edición de cinco líneas; ese mismo retrabajo en Páginas son veinte páginas.

Enrutador

Determina dónde está el usuario, luego actúa. No preguntes qué modo quieren.

SituaciónHaz esto
No hay STATE.json y el descubrimiento no encuentra ningún sistema atómico existenteInicia Etapa 0 (estructura v2)
El descubrimiento informa existingAtomicSystem pero no hay STATE.json (HTML construido manualmente, p. ej., public/atomic-framework/ de un proyecto existente, stage-*.html de un proyecto heredado)Sistema heredado. Extiéndelo en sus propios archivos y nomenclatura: añádelo a sus páginas existentes, mantén sus convenciones de marcado/clase/ID, registra el nuevo trabajo en un pequeño ATOMIC-NOTES.md junto a él. Sus convenciones se mantienen, pero no se baja el listón de calidad: :focus-visible visible, objetivos de 44px, contraste, y un Mapa de Inspiración con secciones de tomar y dejar completadas. Si vive en un repositorio hermano, es un segundo repositorio — pregunta antes de escribir allí (ver Seguridad) y dale al objetivo un breve DESIGN-SYSTEM.md que apunte a él. No andamies v2 a menos que el usuario pida migrar. Verifica con verify-stage.ts --legacy <dir>. Detalle: references/output-structure.md
design-system/STATE.json con schemaVersion: 2Sistema v2: informa el estado, ejecuta la siguiente etapa no aprobada
STATE.json sin schemaVersion: 2 (bajo docs/design-system/ o design-system/docs/)Sistema v1 construido por el skill antiguo. Extiéndelo en su estructura y convenciones v1 (init-system.ts --schema 1 si falta un archivo de andamiaje v1). No migres a menos que el usuario lo solicite
"migrar a v2" / "mover a la nueva estructura"Sigue el procedimiento de migración en references/output-structure.md, en una rama
"rehacer las moléculas" (o --stage <n> en la solicitud)Reconstruye esa etapa, marca las siguientes como obsoletas
"dónde estamos" (o --status)Imprime la escalera con estado por etapa y versión, luego detente
"exportar a figma" / "variables figma"Ejecuta export-figma.ts — ver references/figma-export.md. Nunca es parte de la escalera
El usuario renuncia explícitamente a las puertas ("no te detengas para aprobaciones"; --non-interactive en una evaluación o CI)Ejecuta la escalera sin detenerte y presenta todas las puertas juntas al final — ver "Aprobaciones renunciadas" más abajo
Repositorio objetivo poco claroPregunta, una vez. No adivines entre repositorios hermanos

Resuelve primero el repositorio objetivo. Todo lo demás es relativo a él.

--stage, --status y --non-interactive arriba son formas en que un usuario formula una solicitud a este skill — modos de comportamiento, no banderas de script.

Configuración

# Establece SKILL al directorio real que contiene el SKILL.md cargado
bun $SKILL/scripts/discover-brand.ts --target <repo> [--siblings <dir>]   # Etapa 0
bun $SKILL/scripts/init-system.ts    --target <repo>               # andamio v2; --schema 1 solo para un sistema v1 del skill antiguo
bun $SKILL/scripts/init-system.ts    --target <repo> --page <file> # pagina desde el shell, rail + aria-current completos
bun $SKILL/scripts/verify-stage.ts   --target <repo> --stage <n>   # lee schemaVersion; --legacy <dir> para sistemas construidos manualmente
bun $SKILL/scripts/build-index.ts    --target <repo>               # después de cada etapa aprobada
bun $SKILL/scripts/export-tokens.ts  --target <repo>               # tokens.css → tokens.json + TOKENS.md (build-index lo ejecuta)
bun $SKILL/scripts/export-figma.ts   --target <repo>               # opcional

discover-brand.ts busca en el objetivo y su directorio padre por defecto. Usa --siblings <dir> cuando el cerebro activo vive en otro lugar. Lee el cerebro resuelto explícitamente incluso cuando el descubrimiento no encuentra ningún hermano coincidente. Cada bandera de script está documentada en references/output-structure.md.

Salida (v2) — una raíz, un archivo de entrada, una especificación por componente:

design-system/
├── README.md          EMPIEZA AQUÍ — punto de entrada para personas y agentes
├── STATE.json         schemaVersion 2, etapas, aprobaciones, inventario, versión, temas
├── CHANGELOG.md       una entrada por etapa aprobada / publicación
├── brief/DESIGN-BRIEF.md
├── tokens/            tokens.css (canónico) · tokens.json · TOKENS.md (generado) · figma/ (opcional)
├── foundations/FOUNDATIONS.md
├── components/        INDEX.md (generado) · atoms/ molecules/ organisms/ templates/ <ID>-<slug>.md
├── rules/RULES.md
└── reference/         sitio HTML de revisión estático (noindex) · styles.css · pages/P-nn-<slug>.html

Por qué tiene esta forma, la especificación README, la tabla de ruta v1 → v2 y el procedimiento de migración: references/output-structure.md. Léelo al andar, escribir el README o migrar.

La escalera

Siete etapas de construcción. Fundamentos está antes de Átomos porque no puedes construir un átomo sin tokens; Reglas llega al final porque las protecciones se escriben a partir de lo que realmente se decidió. Las rutas son relativas a design-system/.

#EtapaProduce
0Descubrirbrief/DESIGN-BRIEF.md, STATE.json, esqueleto README.md, CHANGELOG.md, reference/index.html (00)
1Fundamentostokens/tokens.css (+ json/md generados), foundations/FOUNDATIONS.md, reference/foundations.html (01)
2Átomoscomponents/atoms/A-nn-*.md, reference/atoms.html (02), reference/icons.html (02A)
3Moléculascomponents/molecules/M-nn-*.md, reference/molecules.html (03)
4Organismoscomponents/organisms/O-nn-*.md, reference/organisms.html (04)
5Plantillascomponents/templates/T-nn-*.md, reference/templates.html (05)
6Páginasreference/pages.html (06), reference/pages/P-nn-*.html, reference/rules.html (07), rules/RULES.md, README.md final, versión 1.0.0

Artefactos completos por etapa y criterios de aceptación: references/stage-specs.md. Lee la sección de la etapa en la que estás, no el archivo completo.

Etapa 0 — Descubrir

Tres entradas, luego síntesis. Haz las dos primeras de forma concurrente; no dependen la una de la otra.

1. Inspiración de diseño. Reutiliza las referencias guardadas del cerebro activo o de la pasada de Taste Skill primero; solicita solo las URLs sin procesar que falten — de tres a seis, páginas específicas en lugar de páginas de inicio cuando sea posible. Captura cada una con la herramienta de navegador disponible, verificando las fuentes reales y el maquetado. Usa Interceptor solo si está instalado y es apropiado para la sesión. Extrae la paleta calculada, la pila tipográfica, el ritmo de espaciado y los radios — valores renderizados reales, no hexágonos de marketing.

2. Mobbin MCP (opcional). Para preguntas de patrón que las URLs no pueden responder: cómo esta categoría secuencia la incorporación, estructura los precios, maneja los estados vacíos. El MCP puede estar instalado pero no autenticado — si solo mcp__mobbin__authenticate / complete_authentication están expuestos, ejecuta el flujo OAuth y entrega al usuario la URL. Si se niegan, continúa y registra la carencia en el brief. Nunca insinúes que se realizó una investigación de patrón cuando no fue así.

3. Descubrimiento de marca. Ejecuta discover-brand.ts. Sonda las convenciones de ruta conocidas a través del objetivo y sus repositorios hermanos, fusiona documentos complementarios y particiona por familia de marca antes de clasificar — así que un documento pulido de otra marca nunca puede ganar. Lee tres cosas de él: qué documento, si el contrato visual es completo/parcial/solo-verbal, y si ya existe un sistema atómico (si es así, extiéndelo en lugar de empezar de nuevo).

Confirma la fuente de la marca con el usuario antes de compilar cualquier cosa. Es el único error que invalida cada etapa posterior.

Luego escribe DESIGN-BRIEF.md. Su Mapa de Inspiración necesita ambas mitades de cada fila — lo que tomamos y lo que deliberadamente dejamos. La columna de dejar es donde vive el juicio; una fila con solo "tomar" es una instrucción de collage. Su §3 contrato visual nombra cada tono y el paso en el que se encuentra cada hexágono dado, los temas, y la relación de escala tipográfica — las entradas que la Etapa 1 compila.

Detalle: references/brand-discovery.md y references/inspiration-research.md.

Etapas 1–6 — el bucle

Cada etapa ejecuta los mismos cinco pasos.

1. Construir. Sigue la especificación de la etapa. Compón solo piezas de nivel inferior aprobadas. Una etapa que necesita un token que Fundamentos no tiene significa que Fundamentos estaba incompleto — vuelve atrás y corrígelo en lugar de definir un valor local, o el sistema comenzará a contradecirse. Etapa 1: lee references/token-architecture.md primero. Etapas 2–4: lee references/component-anatomy.md primero, y escribe un archivo de especificación por componente desde assets/docs/COMPONENT-SPEC.md junto a su espécimen. La Etapa 1 también ejecuta export-tokens.ts para que tokens.json y TOKENS.md existan para la revisión. Comienza la página de cada etapa con init-system.ts --page <file> para que el rail se genere, no se copie manualmente.

2. Verificar. bun $SKILL/scripts/verify-stage.ts --target <repo> --stage <n>. Arregla lo que informe antes de mostrar cualquier cosa. Verifica la contigüidad de IDs, valores brutos fuera de tokens.css, marcadores de nivel y referencias de nivel, tratamientos de foco, noindex, cableado del rail, recetas de organismos y orden de estados.

3. Mostrar. Mira la página renderizada antes que el revisor, en este orden: la herramienta de navegador disponible de la sesión sobre HTTP local, con fuentes cargadas → otra herramienta de navegador visual disponible → solo comprobaciones DOM (tokens calculados, fuentes cargadas, sin desplazamiento lateral a 375px). Sin cabeza echa en falta fuentes web y problemas de renderizado, que son gran parte de lo que se juzga. Di qué nivel usaste y lo que no se verificó visualmente.

4. Puerta. Presenta el artefacto y pregunta usando la herramienta de preguntas disponible o un mensaje conciso:

  • Aprobar → avanza STATE.json, desbloquea la siguiente etapa
  • Revisar → toma las notas, reconstruye, verifica, muestra de nuevo
  • Aprobar con notas → avanza, registra las notas como decisiones abiertas

Solo avanza con un sí explícito. La puerta existe porque el revisor sabe cosas sobre esta marca que no están escritas en ningún lado — y porque es el acelerador que permite que una construcción grande se detenga después de Átomos y se reanude la próxima semana.

Aprobaciones renunciadas. Cuando el usuario dice explícitamente que no se detenga (o una evaluación o CI ejecuta no interactivo), ejecuta la escalera sin pausar: responde la entrevista de la Etapa 0 a partir de la solicitud y la evidencia, marca cada respuesta como provisional en las decisiones abiertas del brief, registra cada etapa como "aprobado sin revisión (renunciado por el usuario)" en STATE.json y CHANGELOG.md, y presenta todas las puertas juntas al final. Nunca renuncies por tu propio criterio — un usuario silencioso no ha renunciado a nada. Detalle: references/stage-specs.md.

5. Indexar. Al aprobar: marca las especificaciones de la etapa con status: approved, ejecuta build-index.ts (regenera tokens.json, TOKENS.md, components/INDEX.md y el índice del archivo README), agrega una entrada CHANGELOG.md que enumere solo lo que cambió, y aumenta STATE.json version — 0.1.0 para Fundamentos hasta 0.5.0 para Plantillas; aprobar Páginas publica 1.0.0. Enmendar una etapa aprobada es un parche (también lo es reaprobar cada etapa posterior obsoleta); reglas completas en references/output-structure.md. Los archivos generados llevan un encabezado de no-editar-a-mano; edita sus fuentes y vuelve a ejecutar.

Cuando presentes una etapa, mantenla breve: qué se construyó, el recuento por nivel, cualquier cosa que tuviste que decidir sin evidencia, y la única cosa que más vale la pena mirar. No un recorrido de cada espécimen.

Convenciones que se mantienen en todas partes

Detalle completo en references/html-conventions.md. Las que soportan carga:

  • IDs contiguos con ceros a la izquierda — A-01, M-17, O-04, T-05, P-02 — mostrados en la UI a través de .card-label, reflejados en data-* y coincidiendo con el nombre del archivo de especificación. Estables una vez aprobados; renumerar rompe cada referencia.
  • Cuatro niveles de tokens — marca → alias → mapeados → responsivos, cada uno abierto por un marcador @tier en tokens.css. Literales brutos solo en Marca y Responsivo. Color, ancho de borde y radio van Mapeados → Alias → Marca, nunca saltándose; --space-*, --duration-*, --ease-*, --shadow-* mapeados permanecen en su nivel — la abstracción es su propósito.
  • Una página HTML por nivel más una página de portada del sistema. Las páginas se nombran NN-slug.html donde NN coincide con el número de etapa de la escalera. La portada del sistema (index.html) es la página 00. Cada página se sirve desde reference/pages/reference/pages/ (relativo a la raíz del sistema) y se referencia desde reference/index.html.
  • Rail con enlaces de salto contextuales. Todas las páginas de nivel llevan un rail de navegación de una columna que enlaza a cada espécimen en la página; el rail muestra aria-current en el espécimen activo y se genera con init-system.ts --page, no se escriba a mano.
  • Cada espécimen de componente es una muestra de código renderizado con su etiqueta ID de nivel (<span class="card-label">A-01</span>) y un enlace a su archivo de especificación de componente.
  • noindex en cada página de referencia. La revisión no es contenido público.
  • Sistema tipográfico con fuentes web cargadas. La declaración @font-face va en reference/styles.css; las fuentes se sirven desde reference/fonts/.
  • prefers-reduced-motion, prefers-contrast-more, forced-colors: active son tratados en el CSS fundacional, no

...

[truncado para traducción]

Skills relacionados