Communitygithub.com

craft-sync

Úsalo cuando una tarea de diseño esté a punto de comenzar en un proyecto cuyo sistema de diseño ya vive en código (un paquete de UI, tokens de diseño, una librería de componentes) pero no está en la herramienta de diseño; cuando te pidan importar o traer el sistema de diseño, tokens o componentes a la herramienta; o para aplicar, enviar o sincronizar cambios desde la guía de la herramienta de vuelta al código.

¿Qué es craft-sync?

Esta skill (`craft-sync`) sincroniza un sistema de diseño existente en código con una herramienta de diseño (Paper, Figma, HTML, etc.), evitando que la guía se convierta en una fuente desactualizada. Permite **importar** tokens y componentes desde el código a la herramienta (bajo los mismos nombres), y **exportar** cambios realizados en la guía de vuelta al código como un diff revisado. Utiliza un archivo `design-sync.json` en la raíz del proyecto para recordar el último estado sincronizado y quién cambió qué. La skill prioriza el código como fuente de verdad hasta que el usuario decida lo contrario: las importaciones requieren un inventario y selección de componentes, mientras que las exportaciones proponen cambios, se detienen para aprobación, y solo aplican lo confirmado, ejecutando las verificaciones del proyecto. Es ideal para equipos que ya tienen un sistema en código (tokens CSS, componentes) y quieren reflejarlo fielmente en su herramienta de diseño sin duplicar esfuerzos.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/diego3g/craft/tree/HEAD/skills/craft-sync

Preguntar en tu IA favorita

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

Documentación

Sincronización del sistema de diseño

Resumen

Cuando un sistema de diseño ya existe en el código, la herramienta de diseño debe reflejarlo, no reinventarlo.

  • Importar trae los tokens del código y los componentes que la persona elija a la herramienta, bajo los mismos nombres.
  • Exportar lleva los cambios realizados en la guía de la herramienta de vuelta al código como un diff revisado.

Un pequeño archivo en la raíz del proyecto, design-sync.json, recuerda lo que se sincronizó por última vez. El código sigue siendo la fuente de verdad hasta que la persona indique lo contrario: los cambios se dibujan primero en la herramienta y aterrizan en el código mediante una exportación aprobada.

Cuándo usar

  • Una tarea de diseño está a punto de comenzar en un proyecto con un sistema de diseño en código y sin guía en la herramienta. craft-setup y craft delegan aquí.
  • "Importar / traer nuestro sistema de diseño (tokens, componentes) a Paper / Figma / la herramienta de diseño."
  • "Aplicar / enviar / sincronizar los cambios de la guía al código."

Cuándo NO usar

  • No hay sistema de diseño en código: craft-system (modo crear).
  • Una revisión, opciones o una edición pequeña en dicho proyecto: esas skills trabajan desde el código tal como está.
  • Un valor de token individual dictado por la persona ("haz el acento #3d7f69 en código"): edítalo directamente, actualiza design-sync.json para ese nombre, indica qué afecta.

Antes de empezar

  1. Lee DESIGN.md (Brand indica dónde vive el sistema) y design-sync.json si existen.
  2. Elige el adaptador de tu herramienta en references/adapters/ (paper.md, figma.md, html.md). Si ningún adaptador coincide con tu herramienta, realiza las mismas acciones en tu herramienta e indica cuáles mapeaste manualmente. Si no hay herramienta de diseño, construye en HTML (html.md). Si solo tienes una imagen, indica que los valores leídos son estimaciones.

design-sync.json

{
  "source": "packages/ui/tokens.css",
  "tool": "paper: archivo 'Fieldnote', página 'Guide'",
  "naming": "nombres de propiedades personalizadas CSS tal como están escritos en la fuente",
  "synced": "2026-11-15",
  "tokens": { "--color-accent": "#2e6b57", "--radius-md": "10px" },
  "components": { "Button": "dibujado", "Badge": "dibujado", "Input": "solo en código" }
}
  • tokens contiene los valores en los que ambos lados acordaron en la última sincronización, y solo esos.
  • Una importación de componente cambia solo su propia entrada en components.

Importar (código → herramienta de diseño)

  1. Detecta con las señales. Encuentra la fuente de verdad para los valores (la fuente de tokens, no un archivo generado) y la regla de nomenclatura que usará la herramienta. Dos paquetes de UI → enumera ambos y pregunta cuál es la fuente.

  2. Inventario, luego detente. Usa el formato de inventario:

    • tokens por rol, con conteos y rutas;
    • componentes (agrupados con conteos si hay más de unos 15);
    • documentos de pautas;
    • brechas;
    • conflictos: cualquier nombre que ya exista en la herramienta con un valor diferente, y cualquier tipo de token que la herramienta no pueda albergar.

    Pregunta qué componentes dibujar ahora, sugiriendo de 3 a 6 para las próximas pantallas, y cómo resolver cada conflicto. Nunca dibujes todo por defecto.

  3. Construye en la herramienta después de las respuestas:

    • registra los tokens bajo la regla de nomenclatura; nunca sobrescribas un valor de la herramienta que la persona no haya resuelto;
    • crea una página de guía de fundamentos, con los documentos de pautas como leyenda;
    • crea un índice de componentes: nombre, ruta de código, estado (dibujado / solo en código), con variantes completadas una vez dibujado;
    • dibuja los componentes seleccionados con su matriz de estados, usando valores del código. Un estado que el código no define se dibuja y etiqueta como "propuesto".
  4. Autoverificación. Renderiza la guía. Si el código puede renderizar el componente (Storybook, una página demo), compara al mismo tamaño. De lo contrario, indica que los valores se leyeron del código, sin renderizar.

  5. Registra:

    • escribe design-sync.json (todos los valores de tokens ahora son iguales en ambos lados, más los estados de componentes);
    • en DESIGN.md, Brand obtiene "Fuente del sistema de diseño: <ruta>; la guía de lo refleja", y el registro de Decisiones obtiene una línea de importación con fecha;
    • si no hay DESIGN.md, crea uno cuya primera línea sea <!-- sync record only: run craft-setup for the brief --> con solo Brand y el registro de Decisiones. craft trata un DESIGN.md sin sección de Producto como faltante.

Importar un componente individual (desde craft)

La persona ya aceptó reflejar el sistema, por lo que no hay parada de inventario:

  • dibuja ese componente;
  • establece su entrada en components como dibujado;
  • deja tokens intacto.

Si la herramienta aún no tiene guía, o la persona nunca aceptó una importación (o la rechazó), pregunta una vez: "Input existe solo en código. ¿Importarlo primero en la guía?"

Exportar (herramienta de diseño → código)

  1. Lee los valores de la guía (adaptador) y los valores del código, por nombre.

  2. Clasifica cada nombre con design-sync.json y el formato de diff:

    • igual ahora → sincronizado;
    • guía cambiada → proponer;
    • código cambiado → ofrecer actualizar la guía;
    • ambos cambiados → mostrar los tres valores y preguntar cuál gana.

    Sin design-sync.json, enumera cada diferencia y pregunta la dirección para cada una.

  3. Propón las ediciones a los archivos fuente (nunca un archivo generado): archivo y línea, qué afecta cada una y el contraste para colores. Los estados "Propuestos" y las fuentes sustituidas no son cambios para exportar. Detente.

  4. Aplica solo lo que fue aprobado, actualiza la guía para cualquier cosa decidida a favor del código, y ejecuta las verificaciones del proyecto (lint, typecheck, tests, tests visuales), o indica que no hay ninguna.

  5. Registra:

    • actualiza design-sync.json con los valores ahora iguales en ambos lados;
    • agrega una línea con fecha en DESIGN.md › registro de Decisiones;
    • agrega conflictos abiertos a Preguntas abiertas.

Reglas

ReglaPor qué
Mismos nombres en código y herramienta, mediante una regla de nomenclatura escritaUn nombre por decisión; sin mapeo que derive
design-sync.json registra solo valores acordadosSin el último valor acordado, "¿quién lo cambió?" es una suposición
Inventario y selección antes de dibujar; conflictos listados allíPaquetes grandes y tokens existentes en la herramienta necesitan la opinión de la persona
Valores del código, nunca de capturas de pantallaLas capturas redondean colores y tamaños
Estados faltantes dibujados como "propuesto"La guía no debe afirmar que el código hace lo que no hace
Exportar propone, luego se detiene; edita la fuente, no la salida generadaEl código se entrega a los usuarios; un archivo generado se sobrescribe en la siguiente compilación
Ambos cambiados → preguntarSobrescribir cualquiera de los lados pierde una decisión de alguien
El código es la fuente de verdad hasta que la persona indique lo contrarioCoincide con "el código vence a un resumen desactualizado"

Hecho cuando

  • Importación: inventario y conflictos resueltos; componentes seleccionados dibujados; guía renderizada (o "no renderizada" indicado); design-sync.json y DESIGN.md escritos.
  • Un componente: dibujado, con su estado actualizado.
  • Exportación: ediciones aprobadas aplicadas, verificaciones ejecutadas (o "ninguna" indicado), design-sync.json actualizado, conflictos decididos o abiertos.

Errores comunes

PensamientoRealidad
"El código tiene el sistema, así que la configuración solo necesita el resumen"Ofrece la importación, o la herramienta nunca tendrá guía y las pantallas se desvían del código.
"Construiré fundamentos y un índice, los componentes después"Muestra el inventario y pregunta qué componentes dibujar ahora.
"Renombraré --sand-200 a un nombre de rol mientras importo"Mantén el nombre del código; propón un rol como pregunta abierta.
"La herramienta ya tiene --color-accent, lo actualizaré"Eso es un conflicto para la parada de inventario, no una sobrescritura silenciosa.
"La guía y el código difieren, por lo que la guía está desactualizada"Revisa design-sync.json: puede ser el cambio no exportado de la persona.
"El diff es minúsculo, solo lo aplicaré"Propón, detente, luego aplica y ejecuta las verificaciones del proyecto.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Skills relacionados