Saltar al contenido principal

Kit de agente

Cómo trabaja un agente de IA con la suite. Estas guías las escribo para ti, agente: son cortas, imperativas y comprobables. Todas siguen el mismo formato: reglas → patrones → verificación. Un cambio está terminado cuando la verificación pasa.

Qué leer antes de tocar nada​

TareaGuíaContrato legible por máquina
Usar o crear componenteszui/AGENTS.mdzui/manifest.json
Montar una pantallaPantallaszout/manifest.json
Elegir un iconozicon/AGENTS.mdzicon/manifest.json
Cambiar de marcaMarcatokens/dist/tokens.json
DocumentarDocumentaciónzudocs/zudocs.schema.json
Trabajar sin ReactOtros frameworkszui/html.json, zout/html.json
Tocar la lógica compartida o las pruebasArquitectura, Calidad y pruebastests/unit/run.mjs (lista COVERED)
Cambiar lo que se publicaEmpaquetado, Contrato públicopublishConfig.exports de cada package.json

Las siete reglas​

  1. Solo tokens. Ningún color, radio, sombra o fuente literal. Solo var(--z-*).
  2. Un token por uso del color. Texto de color: --z-*-text. Fondo con texto encima: --z-*-solid. El color sin sufijo (--z-accent, --z-danger…) es para rellenos, bordes e iconos. pnpm tokens mide el contraste del par que escribas y falla si no llega.
  3. Sin apariencia en línea. style={{…}} solo para maquetación calculada y variables locales.
  4. Iconos por nombre. <Icon name="…" /> en React, <z-icon name="…"> en el resto. Sin emojis, sin SVG a mano.
  5. Componentes del sistema. Si falta una variante se añade al sistema; no se improvisa en la pantalla. Sin bibliotecas de UI de terceros: lo interactivo se escribe sobre zui/src/core/ y la plataforma.
  6. Cristal en el cromo, opaco en la lectura. .z-liquid para paneles y barras; .z-solid para texto denso.
  7. Propiedades lógicas. inline-start y inline-end, nunca left y right: la suite funciona en RTL.

Verificación​

Desde la raíz de zuix:

ComandoCompruebaObjetivo
pnpm tokensTokens obligatorios por marca y tema; contraste WCAG de la matriz y de los pares reales de las hojasSin fallos
pnpm iconsIconos válidos; alias y emojis apuntan a iconos existentesSin fallos
pnpm style-auditColores literales, primitivos, tokens inexistentes, emojis, estilos en línea0 en todo
pnpm manifestCada componente exportado tiene manifiesto válidoSin fallos
pnpm barrelsCada componente con manifiesto se puede importar desde la raíz de su paqueteSin fallos
pnpm htmlEl contrato HTML se genera desde los componentesSin fallos
pnpm distCSS y módulos para usar sin bundlerSin fallos
pnpm typecheckTipos, incluidos los nombres de iconoSin errores
pnpm checkTodo lo anteriorSin fallos
pnpm lintBiome (TypeScript, React, accesibilidad, CSS, JSON) y la regla de "use client"0 errores y 0 avisos
pnpm format:checkFormatoSin diferencias
pnpm test:unitLógica pura con umbral de coberturaSin fallos
pnpm test:htmlContrato HTML en Chrome, sin ReactSin fallos
pnpm test:browserAplicación de ejemplo de React en ChromeSin fallos
pnpm test:siteEl sitio de documentación compiladoSin fallos
pnpm test:html:all, pnpm test:browser:all, pnpm test:site:allLas suites en Chrome, Firefox y WebKitSin fallos
pnpm buildBuild de publicación: ESM, declaraciones y CSS en dist/ de zicon, zui y zoutSin fallos
pnpm test:packLos paquetes empaquetados se instalan, resuelven, renderizan y compilan fuera del workspaceSin fallos
pnpm bump checkVersión única y entrada en cada CHANGELOG.mdSin fallos
pnpm verifyTodo, en orden, en ChromiumSin fallos

pnpm build y pnpm test:pack hacen falta cuando el cambio toca lo que se publica: un package.json, una entrada de exports o un archivo nuevo en src/. Detalle en Empaquetado.

La auditoría de estilo acepta rutas, así que sirve para una aplicación que consume la suite:

node tools/audit.mjs ../mi-app/src

Cuando falta algo​

FaltaQué hacer
Un tokenProponerlo en tokens/src/base.json, nivel component, referenciando un semántico
Una varianteAñadirla al componente y a su manifiesto
Un iconoInformar. No inventarlo
Un componenteCrearlo en zui con su manifiesto, siguiendo zui/AGENTS.md
Una dependenciaNo añadirla a un paquete publicable sin que yo lo apruebe

Lo que un agente no hace​

  • No publica, no crea etiquetas y no empuja a main.
  • No edita archivos generados; los regenera.
  • No desactiva una política de pnpm-workspace.yaml ni una regla del linter para que algo pase.
  • No da por hecho lo que no ha comprobado: lo dice.