Constructor de Sistemas de Diseño

¿Qué hace Constructor de Sistemas de Diseño?

Esto no es una lista genérica de mejores prácticas. Cada regla a continuación existe porque omitirla produjo un bug real — la mayoría de ellos silenciosos (sin error, sin fallo de compilación, simplemente incorrecto en el navegador). references/bug-catalog.md contiene el incidente específico detrás de cada una. Léelo una vez antes de comenzar un sistema lo suficientemente grande como para importar.

El hilo conductor: una regla que vive solo en un comentario o un documento eventualmente será violada por accidente, y la violación no generará un error. Cada fase a continuación termina preguntando "¿cómo se hace cumplir esto automáticamente?" — si la respuesta es "alguien lo recuerda", la fase no está completa.

Dos puntos de entrada:

• Construir nuevo → Fases 1–7 en orden.
• Auditar o evolucionar un sistema existente → Fase 8, que redirige a las fases 1–7 según sea necesario.

Fase 1 — Descubrir

Pregunta antes de construir; adivinar aquí produce un sistema que nadie quería, y cuando eso se hace visible, es costoso deshacerlo.

• Material de referencia como ejemplos literales, no adjetivos. "Moderno y limpio" no especifica nada; tres capturas de pantalla sí lo hacen.
• ¿El color tiene significado, o es solo estético? Si una paleta tiene valores categóricos (elemento, estado, línea de marca), decide de antemano si cada uno es también un comportamiento (movimiento, forma, peso) o puramente visual. Readaptar un significado a un color elegido por su apariencia es mucho más difícil que decidir esto primero.
• ¿Sobre qué se apoya el contenido? No asumas que el fondo de una página y el fondo de un panel son "suficientemente similares". Mide las combinaciones candidatas antes de comprometerte — ver Fase 2.3.
• Alcance: construcción nueva, refinar un sistema existente, o comparar con uno anterior/hermano. Dirige a la Fase 8 si no es una construcción nueva limpia.
• Distribución: un proyecto, o reutilizado en muchos? Esta única respuesta decide si la Fase 6 (empaquetado) aplica. Equivocarse significa que o sobreingenieras algo de un solo uso o subingenieras algo que está a punto de derivar a través de tres repositorios.

Fase 2 — Crear tokens

En orden de prioridad — equivocarse aquí significa que todo lo construido encima hereda una base incorrecta.

2.1 — Los colores se crean una vez, como tripletes de canal crudos, nunca como un hexágono simple.

--fire-rgb: 170 0 0;                          /* el único valor creado */
--fire: rgb(var(--fire-rgb));                 /* derivado */
--fire-soft: rgb(var(--fire-rgb) / 0.18);     /* derivado */

Esto no es estilístico. Los modificadores de opacidad de Tailwind (y la mayoría de los sistemas de utilidades) (bg-fire/40) no pueden componer un canal alfa sobre un valor hexágono opaco var(--x) — la clase se resuelve silenciosamente a nada, sin error, sin advertencia. Este error exacto es lo que inició el pase de endurecimiento del que proviene este patrón. Un número creado por color también significa que solo hay un lugar para cambiarlo.

2.2 — Cada color que pueda renderizarse como texto obtiene una variante -text, y los glifos la usan, nunca la base. Verifica el contraste calculando la luminancia relativa WCAG (fórmula en assets/check-tokens.template.mjs), no a ojo. Un tono que supera 4.5:1 contra una superficie puede fallar contra otra — que es exactamente por qué 2.3 importa.

2.3 — Si hay más de un nivel de superficie (página / panel / hundido), defínelo como una escala de elevación real y mide la separación entre niveles antes de comprometerte. "Un poco más claro" no es una decisión, es una suposición. Un sistema real revirtió un modelo de elevación completo (tinta-como-página → vacío-como-página) después de publicarlo, puramente porque alguien finalmente calculó el contraste compuesto real: 1.04:1 en un sentido, 1.19:1 en el otro. Haz esa aritmética antes de construir sobre la elección, no después de que un interesado diga "las tarjetas se ven planas".

Una vez que hay una escala, cada token seguro para texto necesita que se verifique el contraste contra cada nivel en el que pueda aparecer, no solo contra aquel para el que fue diseñado.

2.4 — Movimiento: una curva de easing, un conjunto pequeño y fijo de duraciones. Si alguna animación JS (framer-motion, GSAP, un requestAnimationFrame manual) va a consumir estos, exporta la curva y las duraciones como constantes JS junto con las CSS — una variable CSS es invisible para JavaScript, y un bezier o duración escritos a mano se desvían inmediata e invisiblemente. Mantén las versiones CSS y JS verificadas entre sí (Fase 4).

2.5 — Los límites numéricos en cualquier cosa similar a brillo/gradiente deben ser números reales, verificados contra el valor realmente enviado — incluyendo los stops del gradiente, no solo colores planos de un solo alfa. "Brillo sutil" sin un techo impuesto es cómo el brillo ambiental de página completa regresa, un componente a la vez, cada uno individualmente de aspecto razonable.

2.6 — Cada token obtiene un comentario de una línea que dice cuándo usarlo, no solo cómo se renderiza.

Fase 3 — Construir primitivas

• Los componentes referencian tokens exclusivamente. Sin hexágonos, sin valores arbitrarios, sin literales tipo white/10 — estos son exactamente lo que la guardia de la Fase 4 verifica, así que escribirlos ahora solo significa fallar la verificación más tarde.
• Cualquier uso de modificador de opacidad (bg-x/10) debe apuntar a un token que sea realmente composable alfa según 2.1 — verificable, así que verifícalo, no lo evalúes a ojo.
• No codifiques una variante en las clases base de un componente si una prop está destinada a sobrescribirla. className="shadow-lg" incluido en cada tarjeta, con una prop que se supone debe intercambiar shadow-root-earth, produce dos utilidades de box-shadow con la misma especificidad — el ganador se decide por el orden de origen en la hoja de estilo generada, silenciosamente. Haz que la variante sea una tabla de búsqueda indexada por la prop (Record<Variant, string>), nunca una clase base más una sobrescritura esperada.
• Una prop de estilo no es un sustituto de un elemento interactivo real. Una tarjeta que parece clickeable (cursor-pointer, elevación al hover) a través de una prop interactive, pero es un <div>, le da a un usuario de mouse una capacidad que un usuario de teclado nunca obtiene — sin anillo de enfoque, sin rol, sin activación. Si algo está destinado a ser clickeado, renderiza un <a> o <button> (un gemelo CardLink/CardButton), no un interruptor de estilo en la versión pasiva.
• Para componentes interactivos genuinamente complejos (modal, pestañas, toast), apóyate en la plataforma. El <dialog> nativo proporciona un foco atrapado y Escape para cerrar de forma gratuita; las versiones hechas a mano siempre fallan en uno de esos. El tabindex rotatorio para pestañas es el error más común en implementaciones de pestañas hechas a mano (cada pestaña inactiva sigue siendo un punto de tabulación) — verifícalo explícitamente (los tabindex se mueven [0,-1,-1,-1] → [-1,0,-1,-1] en la navegación con teclas de flecha), no asumas.
• Si el sistema necesita activos de icono/marca personalizados, fija las reglas de dibujo de antemano (cuadrícula, grosor de trazo, estilo de extremo) y hazlas cumplir de la misma manera que las reglas de color — esto también es trabajo de la Fase 4.

Fase 4 — Protegerlo

Escribe un script de verificación pequeño, idealmente sin dependencias. Este es el artefacto de mayor apalancamiento en todo el proceso — cada error en references/bug-catalog.md era una regla que existía solo en prosa hasta que alguien la codificó aquí.

Cobertura mínima (adapta assets/check-tokens.template.mjs):

• Cada token que un componente o ajuste preestablecido referencia realmente existe.
• Sin hexágono escrito a mano ni color de opacidad literal en el código fuente del componente.
• Contraste WCAG para cada token seguro para texto contra cada nivel de superficie en el que pueda aparecer (2.3).
• Límites numéricos documentados aplicados como números en el valor realmente enviado — incluyendo el stop más brillante de un gradiente, no solo colores simples (2.5).
• Las constantes de movimiento JS coinciden con sus contrapartes de token CSS (2.4).
• Reglas estructurales que son fáciles de violar por accidente — p. ej., "sin brillo de fondo de página completa": verifica que una utilidad de brillo nunca se aplique a un elemento a nivel de página, no solo que el alfa del token esté limitado.
• Limita cualquier regla que pueda coincidir con prosa ordinaria (p. ej., una regla sobre "una segunda curva de easing") a contextos de código reales — atributos de clase, valores CSS — no texto arbitrario. Un linter que marca tu propia documentación termina siendo deshabilitado, lo que derrota el propósito.

La verificación debe eventualmente ejecutarse contra los proyectos consumidores, no solo contra el repositorio del sistema. Esta es la lección más grande disponible aquí: en un sistema real, cada violación de regla que realmente ocurrió — once tamaños de tipo por debajo de 24px, tres diferentes tamaños de <h2> en un sitio, cinco valores de espaciado entre letras en competencia, una segunda curva de easing, duraciones inventadas — ocurrió en un proyecto consumidor del sistema, y la verificación interna nunca miró allí. Durante mucho tiempo, estaba protegiendo código que nunca había roto una regla. Distribuye el verificador para que se pueda ejecutar contra código fuente arbitrario (npx tu-verificacion ./src), y dale una escotilla de escape con alcance para excepciones genuinas (una convención de comentario tu-verificacion-permitir: <regla> — <razón>) en lugar de hacer que la gente deshabilite toda la verificación.

Prueba negativamente cada verificación antes de confiar en ella. Rompe deliberadamente cada regla en una copia de prueba y confirma que el script realmente falla en ella. Una verificación que nunca se ha observado fallar no está verificada — no sabes si funciona o está silenciosamente inerte.

Fase 5 — Documentar

Tres archivos, divididos por audiencia — resiste la tentación de agregar un cuarto. Un cuarto documento (un "diseño.md" agregado, una segunda guía de estilo como documento) es un segundo lugar para que los mismos valores se desvíen; tres que cada uno posee una pregunta distinta (por qué / qué-hacer / qué-se-decidió) es suficiente.

• philosophy.md — el por qué, la identidad, el significado detrás de las elecciones. Se lee una vez, rara vez se relee.
• foundations.md — las reglas operativas. Lo que alguien verifica antes de construir algo nuevo. Debe mapearse aproximadamente 1:1 con lo que la guardia de la Fase 4 hace cumplir — si una regla está en uno y no en el otro, elige cuál falta y arréglalo.
• decisions.md — un registro continuo, entrada más nueva primero, de juicios específicos y por qué. Nunca elimines una entrada reemplazada. Márcala como reemplazada y explica qué cambió y por qué. Revertir una decisión real (un modelo de elevación, una jerarquía de acento) sin un rastro en papel obliga a la siguiente persona — a menudo tú futuro — a derivar el razonamiento desde cero, o peor, a romper silenciosamente lo que la decisión original arregló.
• Una muestra en vivo que renderiza los tokens y componentes reales — no una descripción de ellos. Si no puede literalmente importar el paquete (un documento HTML estático de un solo archivo, por ejemplo), está llevando una segunda copia en línea de cada valor, y esa copia se desviará: la muestra de un sistema real se quedó silenciosamente dos versiones atrás de sus propios tokens antes de que alguien la reconstruyera como algo que importa el paquete real. La solución más rápida, si una muestra estática es inevitable por un tiempo, es que la Fase 4 proteja la copia en línea contra la fuente real — pero planea retirarla tan pronto como el sistema sea lo suficientemente estable como para tener un consumidor real.
• Si la muestra se puede desplegar, desplégala en una URL real y mírala en un viewport real y estrecho. Un error de diseño que solo aparece cuando una sección específica es más estrecha que su contenido (un elemento decorativo que se desborda intencionalmente ensanchando todo el documento, por ejemplo) es invisible para toda verificación estática — no una violación de token, no un fallo de contraste, no un error de lint. Solo existe en un navegador real con un ancho real. Uno de esos errores se envió y sobrevivió tres versiones porque el único lugar donde se veía el sistema era un archivo local.
• Escribe una política de versionado y el orden para leer los documentos, una vez que haya más de un documento. Cuesta un párrafo, le ahorra a alguien tener que derivarlo.

Fase 6 — Empaquetar y distribuir

Solo si la Fase 1 dijo "reutilizado entre proyectos".

• Distribúyelo como un paquete instalable (package.json con un mapa exports). Nunca "copia estos archivos en tu proyecto" — copiar no tiene un camino para que una corrección descendente fluya de vuelta al origen, lo que hace que la fuente de verdad del sistema se convierta silenciosamente en la más rota de dos copias. Esta fue la causa raíz del primer error en toda esta línea.
• Si distribuyes un preset de Tailwind: el arreglo content de un preset NO se fusiona por Tailwind. El propio arreglo content de un consumidor reemplaza directamente al del preset. Este es el segundo error más costoso en el catálogo, y la solución "obvia" — declarar los globs en el preset y asumir que se combinan — no funciona; la compilación regresa byte-identica, que es la señal. El preset debe exportar sus globs, y cada pieza de incorporación (README, un comando de andamiaje si existe) debe mostrar a los consumidores extendiéndolos explícitamente: content: [...preset.content, ...tusGlobs]. Verifica esto con la propia API de resolución de configuración del bundler, no asumas — un artefacto de compilación sin cambios después de una "corrección" es una señal de error, no una coincidencia.
• Versiona con etiquetas, no solo con ramas. Un pin de rama se mueve silenciosamente bajo un consumidor en el momento en que la rama del repositorio fuente avanza — que es exactamente cómo un consumidor puede terminar enviando una versión no probada sin que nadie lo decida. Si un consumidor necesita moverse a una nueva etiqueta, recuerda que los lockfiles pueden fijar el commit resuelto exacto independientemente de lo que diga la etiqueta en package.json — fuerza la re-resolución y verifica que node_modules realmente informe la nueva versión antes de confiar en una recompilación.
• Si el paquete ofrece un comando de andamiaje/init para nuevos consumidores, haz que emita la configuración content correcta, extendida, desde el día uno — no confíes en la disciplina de lectura de README de cada consumidor para una metedura de pata lo suficientemente grave como para tener su propia entrada en el registro de decisiones.

Fase 7 — Verificar

Se aplica continuamente, no solo una vez al final.

• Prueba contra una instalación o clon nuevo, no el directorio de trabajo. Un directorio de trabajo oculta exportaciones faltantes, correcciones sin confirmar y cachés obsoletos que un consumidor real encontrará el primer día.
• Un artefacto de compilación sin cambios después de una "corrección" es una señal de que la corrección no funcionó, no una coincidencia. Compara el resultado real antes de creer que algo cambió.
• La verificación de tipos no es verificación. El error más grave en este catálogo — una fuente renderizándose en un tipo de letra completamente incorrecto — pasó todas las verificaciones estáticas disponibles y solo se detectó al renderizar el componente en un consumidor real y mirarlo. Renderiza todo al menos una vez en algo real antes de darlo por terminado.
• Desconfía de las APIs de plataforma de apariencia conveniente para afirmaciones de verificación. document.fonts.check() parece la herramienta exactamente correcta para "¿esta fuente contiene realmente este glifo?" y miente (informa que una fuente está cargada incluso si solo lo está la variable estática, mientras que el consumidor solicitó un eje variable que la fuente no expone). Confírmalo renderizando realmente texto en un elemento del DOM y midiendo, no confíes en una promesa resuelta de la API de Font.

Fase 8 — Auditar un sistema existente

Este es el punto de entrada cuando no estás empezando desde cero. El proceso es el mismo trabajo que las Fases 1–7, pero en orden inverso y comenzando desde el resultado real:

1. Renderiza cada componente documentado en un navegador real (Fase 7 inversa). Un componente que no se ha renderizado nunca en un navegador real no está verificado. Toma capturas de pantalla.
2. Ejecuta la verificación de la Fase 4 contra todo el código fuente del sistema, incluyendo los proyectos consumidores (lo más probable es que esta verificación no exista, o nunca se haya ejecutado contra consumidores, o haya estado fallando silenciosamente durante meses).
3. Catáloga cada violación encontrada — no solo lo que está mal, sino qué error en references/bug-catalog.md describe el mismo patrón.
4. Para cada violación, decide: ¿es una anomalía histórica (el sistema siempre fue así y sobrevivió) o un riesgo activo? Si sobrevivió, probablemente sea porque se usa en contextos que no lo ejercitan — pero un nuevo consumidor podría ejercitarlo. Documéntalo de todas formas.
5. Mapea cada documento existente a los roles de la Fase 5: ¿cuál es el "por qué", cuál es el "qué hacer"? Si no hay un philosophy.md, la ausencia misma dice algo — documéntalo.
6. Mide la deriva de tokens (Fases 2 inversa). Toma el token más usado en producción, encuentra su valor real renderizado (inspección del navegador, no el código fuente), y compara con el token creado. Si no coinciden, rastrea dónde se desviaron — un fix en un proyecto consumidor que nunca regresó.
7. Busca artefactos de copia — una muestra estática, un README con ejemplos hexagonales, un segundo "tema" en el código que duplica valores — y decídete a migrar cada uno a referencias de tokens (Fase 6 inversa).
8. Verifica el comportamiento de la plataforma que puede estar silenciosamente roto (Fases 2.4, 3, 7): las animaciones JS todavía usan las curvas de easing escritas a mano de hace dos versiones; <dialog> se implementó como un div personalizado con un manejo de Escape roto; el tabindex de las pestañas nunca rota y nadie lo notó.
9. Escribe el primer informe de auditoría. Tres secciones: Lo que realmente se usa, Lo que está realmente verificado, Lo que necesita ser protegido o retirado.
10. Si el sistema va a sobrevivir, planea la Fase 6 — incluso si nunca se reutiliza entre proyectos, el acto de empaquetar (subir a un registro, instalar desde él) fuerza a que cualquier corrección fluya de vuelta al paquete, matando la deriva de copias que probablemente ya está ocurriendo.