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-setupycraftdelegan 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.jsonpara ese nombre, indica qué afecta.
Antes de empezar
- Lee
DESIGN.md(Brand indica dónde vive el sistema) ydesign-sync.jsonsi existen. - 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" }
}
tokenscontiene 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)
-
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.
-
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.
-
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".
-
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.
-
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.crafttrata unDESIGN.mdsin sección de Producto como faltante.
- escribe
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
componentscomodibujado; - deja
tokensintacto.
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)
-
Lee los valores de la guía (adaptador) y los valores del código, por nombre.
-
Clasifica cada nombre con
design-sync.jsony 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. -
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.
-
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.
-
Registra:
- actualiza
design-sync.jsoncon 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.
- actualiza
Reglas
| Regla | Por qué |
|---|---|
| Mismos nombres en código y herramienta, mediante una regla de nomenclatura escrita | Un nombre por decisión; sin mapeo que derive |
design-sync.json registra solo valores acordados | Sin 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 pantalla | Las 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 generada | El código se entrega a los usuarios; un archivo generado se sobrescribe en la siguiente compilación |
| Ambos cambiados → preguntar | Sobrescribir cualquiera de los lados pierde una decisión de alguien |
| El código es la fuente de verdad hasta que la persona indique lo contrario | Coincide 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.jsonyDESIGN.mdescritos. - Un componente: dibujado, con su estado actualizado.
- Exportación: ediciones aprobadas aplicadas, verificaciones ejecutadas (o "ninguna" indicado),
design-sync.jsonactualizado, conflictos decididos o abiertos.
Errores comunes
| Pensamiento | Realidad |
|---|---|
| "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. |