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ón | Haz esto |
|---|---|
No hay STATE.json y el descubrimiento no encuentra ningún sistema atómico existente | Inicia 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: 2 | Sistema 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 claro | Pregunta, 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/.
| # | Etapa | Produce |
|---|---|---|
| 0 | Descubrir | brief/DESIGN-BRIEF.md, STATE.json, esqueleto README.md, CHANGELOG.md, reference/index.html (00) |
| 1 | Fundamentos | tokens/tokens.css (+ json/md generados), foundations/FOUNDATIONS.md, reference/foundations.html (01) |
| 2 | Átomos | components/atoms/A-nn-*.md, reference/atoms.html (02), reference/icons.html (02A) |
| 3 | Moléculas | components/molecules/M-nn-*.md, reference/molecules.html (03) |
| 4 | Organismos | components/organisms/O-nn-*.md, reference/organisms.html (04) |
| 5 | Plantillas | components/templates/T-nn-*.md, reference/templates.html (05) |
| 6 | Páginas | reference/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 endata-*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
@tierentokens.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.htmldonde 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 desdereference/pages/reference/pages/(relativo a la raíz del sistema) y se referencia desdereference/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-currenten el espécimen activo y se genera coninit-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. noindexen cada página de referencia. La revisión no es contenido público.- Sistema tipográfico con fuentes web cargadas. La declaración
@font-faceva enreference/styles.css; las fuentes se sirven desdereference/fonts/. prefers-reduced-motion,prefers-contrast-more,forced-colors: activeson tratados en el CSS fundacional, no
...
[truncado para traducción]