saltjsx/build-design-system

Construir un sistema de diseño

El vocabulario está en references/glossary.md, los valores predeterminados para prohibiciones y anchos en references/taste.md. La apariencia propia de la aplicación es la fuente. No inventes ningún valor de color, fuente, sombra, degradado o movimiento que no tenga ya, a menos que la persona haya elegido una fuente de diseño y confirmado una muestra.

Los scripts están en scripts/ de esta habilidad. Ejecútalos desde la raíz del repositorio con node y lee primero --help. scripts/capture.mjs toma las capturas de pantalla que respalda scripts/capture-guard.mjs, el cual bloquea cada escritura, y scripts/pixdiff.mjs las compara. Capture y pixdiff necesitan Playwright y un Chromium, que scripts/find-chromium.mjs encuentra o explica cómo instalar.

Pasos

1. Enmarcar. Lee AGENTS.md o CLAUDE.md, el manifiesto y el árbol de rutas. Escribe la queja con las palabras de la persona, el primer cambio visible que la responda y el flujo piloto (el que nombra la queja, si no, el flujo con más familias de componentes y un formulario con un estado de error). Agrega .design-system/ a .git/info/exclude para que nunca se confirme ninguna nota, captura o archivo temporal. Usa la rama que la persona nombró como rama de ejecución, o crea una y escribe la rama en la que empezaste en .design-system/start-branch, que land.mjs rechaza. Ofrece references/taste.md una vez con sus prohibiciones sin seleccionar y guarda la copia aceptada en .design-system/taste.md. No preguntes nada más. Toma el valor predeterminado, regístralo como default (unanswered) y continúa. Hecho cuando la queja, el piloto, la rama y el archivo de gusto aceptado están escritos.

2. Inventario y líneas base. Enumera cada superficie, sus estados y si escribe datos. Cuenta los valores sin procesar en ocurrencias (#fff, text-gray-500, p-[13px]) con scripts/check-system.mjs --no-allowlist --no-self-test --json, y agrupa los componentes en familias. Captura cada superficie en cada estado en el ancho más estrecho y más ancho compatible (390 y 1280 por defecto), una navegación nueva por ancho, antes de cualquier edición. Con la aplicación en ejecución (puerto 3000 aquí), enumera cada superficie como una fila surface<TAB>route<TAB>states en .design-system/surfaces.tsv y cada escritura que la aplicación envía como METHOD URL en .design-system/writes.txt, copiado de su registro de red, luego ejecuta node <ruta-de-esta-habilidad>/scripts/capture.mjs --base http://localhost:3000 --kind before --out .design-system/captures --surfaces .design-system/surfaces.tsv --writes .design-system/writes.txt. Se niega a comenzar sin --writes (o --no-backend para una aplicación que no envía escrituras), comprueba que cada escritura esté bloqueada antes de que el navegador se abra, guarda el árbol de accesibilidad de cada captura y sale con 1 en cualquier captura que falte. Elimina lo que nada usa, en su propio commit. Hecho cuando cada superficie tiene una línea base o una razón not captured indicada.

3. Tokens. Agrupa los valores sin procesar por rol, nómbralos por propósito y empareja cada superficie con su primer plano (references/tokens.md). Ejecuta token-mapping hasta que cada valor sin procesar se asigne a un rol, una fusión o una excepción listada. Las fusiones dentro de la tolerancia son decisiones. Más allá de la tolerancia, abre una puerta por cada grupo cuyo valor predeterminado sea la fusión. Realiza cada intercambio de valor idéntico en cada ruta. Hecho cuando token-mapping informa cero brechas fuera de la lista de excepciones y pixdiff.mjs con tolerancia 0 informa 0 % para cada superficie que un intercambio tocó.

4. Componentes. Construye la familia más utilizada de principio a fin primero (references/components.md). La primitiva de texto y la primitiva de texto pequeño se envían en la oleada 1 junto con Button. Documenta cada una con component-docs. Muestra la familia a la persona antes de la expansión, porque un error central encontrado después de que las pantallas consumen el sistema cuesta un barrido (un campo deshabilitado aún dibujado en rojo, un Combobox 2 px más alto que Input, acciones de panel que no se envuelven, una carga de archivos que falla en silencio). Hecho cuando cada componente canónico tiene una fila de registro y un documento, y sus estados deshabilitado, requerido, error y texto largo están capturados en el escaparate y mostrados a la persona.

5. Verificaciones. Copia scripts/check-system.mjs y scripts/oklch.mjs en scripts/ del repositorio, ejecuta --init, luego --init-allowlist una vez. Una regla cuenta solo una vez que se ve fallar: planta una violación en una carpeta escaneada, ejecuta --files <planta> --no-allowlist, observa la salida 1 nombrando la regla, luego elimina la planta. La lista blanca y el trinquete solo se reducen. Una prohibición se envía con su regla de verificación en el mismo cambio. Las reglas de copia se envían con sus exenciones, con ámbito de elemento, para el texto que debe permanecer textual (citas, términos, cadenas de versión) y para las cadenas de carga útil que una máquina o persona pega en otro lugar (un prompt, un ejemplo de API, un valor del portapapeles), porque reescribirlas cambia lo que alguien más recibe. Hecho cuando la verificación sale con 0 en un clon limpio, --self-test termina con "all as expected", y cada regla que la ejecución agregó fue vista fallando en su planta esta sesión.

6. Piloto. Mueve el flujo piloto con un codemod que lees fragmento por fragmento. Captura después con el comando de la línea base, los anchos, temas y datos, cambiando solo --kind after, luego pixdiff.mjs las dos carpetas. Una diferencia inexplicada es un defecto. Recorre el flujo con el teclado, fuerza sus estados de error y carga, luego ejecuta ui-review en las capturas posteriores. Hecho cuando cada diferencia en las capturas se remonta a una decisión o puerta. Un cambio renderizado sin captura se informa checks-only.

7. Preparación. Antes de que una migración se expanda, las cinco auditorías a continuación se mantienen o llevan una exención registrada.

8. Entrega. Vuelve a ejecutar los recuentos. Informa lo que cubre el sistema en números, primero los valores predeterminados sin respuesta, luego lo que se encontró y no se corrigió, clasificado. Ofrece la migración con su tamaño. No la inicies. Hecho cuando cada número en el informe nombra el comando que lo produjo.

Auditorías de preparación

Una brecha encontrada después de que las pantallas consumen el sistema cuesta un barrido. Una brecha encontrada antes cuesta una fila. Ejecútalas al final del paso 5 y nuevamente antes de la primera oleada. Escribe cada resultado en .design-system/readiness.md con una palabra de veredicto.

1. Paridad de ranuras y propiedades. Cada propiedad de cada primitiva heredada que tiene sitios de llamada tiene una propiedad correspondiente en la nueva primitiva o una fila de brecha.
2. Contratos de comportamiento. Una tabla de "qué se activa cuándo" por primitiva interactiva, cada fila una prueba (references/components.md).
3. Paridad de tono. Cada primitiva presionable y de fila cruzada con cada tono de estado más silenciado. Cada celda vacía es una fila de brecha o se indica como no compatible.
4. Cadenas fijas. Cada consulta de prueba heredada por nombre de rol o texto tiene un nombre predeterminado en la nueva primitiva y una anulación de etiqueta.
5. Pantallas más difíciles. Un sitio de llamada más difícil por familia se renderiza en el escaparate, con una captura de pantalla.

Una familia que no está lista no se migra. Sus pantallas permanecen en el sistema heredado.

Nunca

• Hacer push, publicar o desplegar, a menos que la persona lo solicite en esta sesión.
• Hacer commit en la rama en la que comenzó la ejecución. Primero crea la rama de ejecución.
• Hacer stash o cambiar de rama en un checkout sucio. Un checkout sucio obtiene la rama de ejecución en su propio árbol de trabajo (git worktree add).
• Eliminar nada que otro paquete o una API pública exporte. Detente y enuméralo como una puerta con sus importadores.
• Saltar un paso en silencio. Si la aplicación no se compila o no se ejecuta, el informe dice code-complete, not runtime-verified y nombra lo que no se ejercitó.
• Llamar a tu propio trabajo verified. En un host que no puede iniciar otros agentes, ejecuta los pasos en orden, verifica cada uno desde una lectura limpia del diff y las capturas, y marca esos veredictos self-verified.

Reglas

• Los olores de valores sin procesar son #fff, rgb(, text-gray-500, p-[13px] y style={{ padding: 12 }}. Cada uno se asigna a un token semántico o una excepción listada.
• Una primitiva faltante es una fila de brecha, nunca una solución alternativa dentro de una superficie.
• Las fusiones de color dentro de delta E OK 2 y las fusiones de espaciado dentro de 2 px son decisiones. El ancho de borde, el peso y la suavización no tienen tolerancia.
• Un cambio que solo agrega semántica (un nombre, un rol, aria-current) es una decisión. Uno que elimina o reestructura semántica es una puerta.
• Incorrecto: {saving ? "Saving..." : "Save"}. Correcto: la etiqueta inactiva permanece, un spinner se sienta dentro del mismo cuadro, aria-busy está establecido.
• Una corrección que se repite dos veces se convierte en una regla de verificación o un script, no en otra oración.
• Una línea base nunca se edita para que un diff pase. Una verificación que marca código correcto se corrige en la verificación, con un caso plantado que demuestre la corrección, nunca doblando el código.
• Un recuento que ningún script produjo, o una verificación que nunca se vio fallar, no se informa.

Hecho

La verificación sale con 0 en un clon limpio con cada regla vista fallando, cada ruta responde 200 en la compilación de producción (capture.mjs --status), el piloto coincide con su línea base excepto por los cambios intencionados listados, y cada recuento de entrega proviene de un script.

references/traps.md enumera las trampas de comportamiento por ID. references/tokens.md contiene capas, nombres, tolerancias y ajustes preestablecidos de movimiento.