Qué aprendí construyendo un framework CSS desde cero

Crear HinataCSS me enseñó que escribir clases es la parte sencilla. El trabajo real consiste en diseñar un vocabulario coherente, controlar compatibilidad y evitar que cada componente resuelva el mismo problema de una forma diferente.

Tokens antes que componentes

Color, espacio, tipografía, radio y sombra forman la base. Los nombres representan intención, no un valor accidental.

:root {
  --color-surface: #ffffff;
  --color-text: #172033;
  --space-2: 0.5rem;
  --space-4: 1rem;
  --radius-control: 0.625rem;
  --shadow-raised: 0 8px 24px rgb(15 23 42 / 0.08);
}

Un botón puede cambiar de color sin cambiar su contrato. Esto permite temas y rediseños sin buscar cientos de valores hexadecimales.

Capas con responsabilidades

Organizo reset, elementos, utilidades y componentes. Mantengo baja especificidad para que personalizar no requiera !important.

@layer reset, base, components, utilities;

@layer components {
  .button {
    display: inline-flex;
    gap: var(--space-2);
    border-radius: var(--radius-control);
  }
}

Las utilidades resuelven composición; los componentes capturan patrones semánticos repetidos. Duplicar cada propiedad como utilidad aumenta superficie sin aportar necesariamente claridad.

Estados completos

hover no basta. Diseño foco visible, deshabilitado, carga, error, modo oscuro y movimiento reducido. Los componentes interactivos necesitan área táctil y contraste suficiente.

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    scroll-behavior: auto !important;
    animation-duration: 0.01ms !important;
  }
}

Distribución y compatibilidad

El paquete define entradas estables, prefijos cuando son necesarios y una estrategia de versionado. Una clase eliminada es una ruptura aunque el CSS siga compilando. Mantengo notas de migración y evito publicar comportamientos experimentales como API permanente.

Documentación y pruebas

Cada componente necesita ejemplos, opciones, límites y estados. Las pruebas visuales detectan cambios inesperados; una página de casos extremos revela títulos largos, densidad y combinaciones problemáticas.

Un framework propio ofrece control y aprendizaje, pero también crea una responsabilidad continua. Tiene sentido cuando existe una necesidad clara, un alcance controlado y tiempo para mantener documentación, accesibilidad y compatibilidad; no simplemente porque escribir CSS desde cero resulte atractivo.