Una responsabilidad por archivo
Cada módulo debe resolver un problema concreto. Si una clase pertenece a otro archivo, no debe añadirse donde resulte “más cómodo”.
Guidelines
Guidelines reúne las reglas de uso del framework para mantener claridad estructural, consistencia visual y escalabilidad real del sistema.
Qué resuelve esta guía
Un framework no se mantiene limpio solo por su código, sino por la manera en que se usa. Esta guía define principios y criterios para tomar decisiones consistentes al construir, extender o documentar el sistema.
Su objetivo es evitar duplicación, clases arbitrarias, mezcla de responsabilidades y CSS de proyecto dentro del núcleo del framework.
Principios del sistema
Mobile-first siempre
La base del sistema corresponde al estado móvil. Los breakpoints extienden el comportamiento, no lo corrigen desde desktop.
Tokens antes que valores arbitrarios
El sistema debe apoyarse en variables y escalas oficiales antes de introducir nuevos valores aislados.
Sistema antes que excepción
Si una necesidad se repite, debe convertirse en una solución sistemática, no en un parche local.
Claridad antes que acumulación
Es preferible tener menos clases bien justificadas que muchas utilidades con funciones superpuestas.
El proyecto no contamina el core
El CSS específico del sitio debe vivir fuera del núcleo o en overrides, no dentro del framework base.
Reglas prácticas de uso
- Usa section para ritmo macro entre bloques grandes.
- Usa stack para flujo vertical interno entre hijos.
- Usa spacing solo cuando necesitas un ajuste puntual.
- Usa grid cuando la estructura depende de columnas.
- Usa align cuando la composición depende de ejes flex.
- Usa width para ajustar anchos internos, no para reemplazar containers.
- Usa visibility solo cuando realmente necesitas mostrar u ocultar por breakpoint.
- Usa animations con moderación y siempre respetando accesibilidad.
Antes de crear una clase nueva
Preguntas clave
- ¿Esto ya se resuelve con una clase existente?
- ¿La necesidad es estructural o es específica del proyecto?
- ¿Esta solución se repetirá más de una vez?
- ¿Pertenece realmente a este archivo o a otro módulo?
- ¿Está alineada con la escala de tokens del sistema?
Criterio
Si la necesidad es repetible, pertenece al sistema y mantiene coherencia con la arquitectura existente, puede convertirse en helper o módulo nuevo.
Si solo resuelve una situación aislada del proyecto, debe quedarse fuera del core.
Qué evitar
Duplicar lógica
No repitas helpers que ya existen con otro nombre o en otro archivo.
Crear clases arbitrarias
No agregues clases fuera de escala o sin una lógica reutilizable clara.
Mezclar módulos
No metas spacing en stack, ni grid en align, ni text helpers en typography.
Resolver branding aquí
No lleves decisiones visuales específicas del sitio al core del framework.
Qué va en el framework y qué va en el proyecto
Sí va en el framework
- Utilidades reutilizables.
- Escalas del sistema.
- Helpers estructurales.
- Comportamientos base consistentes.
- Patrones generales y accesibles.
Debe quedarse en el proyecto
- Colores de marca específicos.
- Cards o componentes únicos de un sitio.
- Animaciones decorativas particulares.
- Hacks o correcciones locales.
- Layouts irrepetibles sin valor sistémico.
Flujo recomendado para construir
Container
Layout / Grid
Section / Stack
Typography / Text
Spacing / Align / Visibility
Este orden ayuda a construir primero la estructura, luego el ritmo, después la jerarquía visual y por último los ajustes finos.
Cómo mantener el sistema sano
- Revisa si una clase nueva ya existe antes de crearla.
- Documenta cualquier helper agregado al sistema.
- Evita agregar nombres ambiguos o demasiado específicos.
- Conserva la relación entre tokens, escalas y módulos.
- Si algo deja de ser útil o consistente, muévelo al proyecto o elimínalo.
Siguiente paso
Continúa con naming conventions para definir la lógica de nombres del sistema.