Arquitectura CSS

FDS está construido sobre cascade layers (@layer) de CSS nativo. El orden de capas determina qué reglas ganan, y dentro de cada capa los archivos se cargan en una secuencia concreta desde main.css.

Orden de capas

main.css declara el orden global:

@layer theme, base, layouts, components, utilities, custom;

De menor a mayor especificidad efectiva: theme aporta tokens, base resetea y aplica defaults a elementos HTML, layouts resuelve estructura, components aporta clases reutilizables, utilities son las atómicas de Tailwind y custom es el escape hatch del proyecto.

Una utility de Tailwind (text-xl) siempre gana sobre un default de base porque está en una capa posterior. Por eso puedes sobrescribir tipografía base con clases sin pelear especificidad.

base/base.css

Resets globales y comportamiento de elementos HTML básicos. Vive en el layer base.

Contiene:

  • html: overflow-x: hidden y font-size: 100%.
  • body: aplica --font-body, --text-base, --ft-color-background, --ft-color-text, scroll-behavior: smooth y min-height: 100vh.
  • *, *::before, *::after: box-sizing: border-box, border-width: 0, border-color: var(--color-neutral-300). Esto sustituye al border-reset de Tailwind con un color por defecto neutro.
  • img, svg, video: display: block; max-width: 100%; height: auto.
  • figure > img: object-fit: cover ocupando el figure.
  • Utilidad .skip-link para accesibilidad (oculta hasta recibir :focus).
  • Resets de abbr[title], fieldset y legend.

No define tipografía: solo elementos de chasis y multimedia. Toda la tipografía base vive en el archivo siguiente.

base/typography.css

Aplica tipografía por defecto a h1–h6, a y, sobre todo, define .prose: el contenedor que da formato editorial a contenido HTML semántico (artículos, contenido de WordPress, Markdown renderizado).

Estructura del archivo:

  1. Override fuera de layer. La primera regla vive fuera de @layer base:

    a:where(:not(.wp-element-button)) {
  text-decoration: none;
}

    Esto sirve para ganar la cascada contra reglas no encapsuladas en layers (típicamente las que inyecta Gutenberg en WordPress). Las reglas sin layer ganan a las que sí lo tienen, así que para neutralizar el text-decoration: underline de Gutenberg hay que jugar también fuera de layer.

  2. Defaults dentro de @layer base para h1–h6 (escala fluida con font-display, font-bold, tracking-tight, text-balance) y a (no-underline).

  3. Bloque .prose con reglas anidadas para tipografía editorial: tamaños de heading dentro del contenedor, espaciado entre párrafos y headings, listas, tablas, blockquotes, primer/último hijo sin margen, etc.

    Aquí es donde están realmente definidos los estilos prose de FDS. La página Prose (Typography) documenta el uso; este archivo es la fuente.

components/typography.css

Diferente a base/typography.css. Vive en el layer components (carga después de base) y aporta clases de componente con intención visual, independientes del elemento HTML:

  • .display, .display-lg, .display-md, .display-sm, .display-single
  • .heading-lg, .heading, .heading-md, .heading-sm
  • .subheading-lg, .subheading, .subheading-sm
  • .text-large, .text-medium, .text-small

Documentadas en Tipografía. Estas clases ganan sobre los defaults de base/typography.css porque viven en una capa posterior — por eso puedes hacer <h2 class="display"> y la h2 adoptará los estilos del display sin necesidad de !important.

Cómo se cargan

Desde main.css:

@layer theme, base, layouts, components, utilities, custom;

@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);

@import './theme/flowtitude.css';

@import './base/base.css';
@import './base/typography.css';

@import './layouts/section.css';
@import './layouts/content-flex.css';

@import './components/components.css';
@import './components/typography.css';
@import './components/buttons.css';
@import './components/cards.css';
@import './components/custom.css';

Importar fds/main.css desde el entry del proyecto trae todo en el orden correcto. No hay que importar archivos sueltos salvo casos avanzados.

Cómo sobrescribir

Tres niveles, de menos a más invasivo:

  1. Cambiar tokens en @theme del proyecto: afecta a todos los componentes que los referencian. Es la opción correcta el 90 % de las veces.
  2. Aplicar utilities de Tailwind sobre el HTML: ganan a base/typography.css y components/typography.css por orden de capa.
  3. Sobrescribir reglas en el layer custom del proyecto: declarado al final del orden de capas, gana a todo lo demás. Reservado para casos donde tokens y utilities no llegan.
@layer custom {
  .prose h2 {
    /* override puntual sin tocar el sistema */
    @apply text-primary-700;
  }
}

No edites los archivos de FDS

Editar base/base.css o base/typography.css directamente rompe las actualizaciones del sistema. Usa @theme para tokens y el layer custom para overrides puntuales.

Referencias