Cómo Corregir las Conjeturas de CSS de Claude Code con un Sistema de Diseño

Un desarrollador que construía un panel de análisis de acciones con Claude Code encontró una frustración común: la IA generaba repetidamente CSS roto para el mismo div desalineado. Durante seis iteraciones, los intentos de arreglar el relleno, cambiar de flex a grid y agregar overflow: hidden fallaron o empeoraron el problema.

El Problema: IA Diseñando a Ciegas

El desarrollador se dio cuenta de que Claude Code no tiene retroalimentación visual—no puede ver la salida del navegador. Hace coincidencia de patrones a partir de descripciones y adivina el estilo, a menudo produciendo "CSS técnicamente válido que parece diseñado por alguien que nunca ha usado una computadora".

La Solución: Restringir con un Sistema de Diseño

En lugar de dar tokens, proporciona una especificación completa del sistema de diseño. El desarrollador usó:

/* espaciado */
--space-xs: 4px;
--space-sm: 8px;
--space-md: 16px;
--space-lg: 32px;

/* colores */
--bg-primary: #0f1117;
--bg-card: #1a1d27;
--accent: #3b82f6;
--text-primary: #e2e8f0;
--text-muted: #64748b;
/* escala tipográfica */
--text-sm: 12px;
--text-base: 14px;
--text-lg: 18px;
--text-xl: 24px;

Luego instruye: "Usa solo estos valores. Sin números codificados en ningún lugar". Esto le da a Claude un marco para razonar en lugar de un lienzo en blanco para decisiones arbitrarias.

Separar Indicaciones de Estructura y Estilo

Nunca pidas a Claude que escriba HTML y CSS simultáneamente. El desarrollador dividió el proceso:

• Primera indicación: "Genera solo la estructura HTML para este panel. Sin atributos de estilo, sin CSS, sin clases aún. Solo estructura semántica."
• Segunda indicación: "Ahora escribe el CSS para esta estructura usando solo el sistema de diseño anterior."

Esto obliga a Claude a tratar el HTML como un contrato fijo antes de aplicar estilos, evitando que pierda el rastro de las suposiciones sobre su propia salida.

El resultado: el siguiente componente pasó de seis iteraciones a una. El desarrollador también planteó la pregunta de si este sistema de diseño podría aplicarse mediante un archivo CLAUDE.md para evitar pegarlo en cada sesión.