Adaptación de componentes semánticos

Usa consultas de estilo (@container style()) para activar variaciones contextuales sin codificar de forma fija lo que produce o reacciona a cada contexto. Esto reduce el acoplamiento del sistema de diseño y mejora la extensibilidad y la encapsulación de componentes.

Por ejemplo, una regla section.featured { --surface: featured } puede marcar un contexto, y una página de destino también puede usarlo de forma predeterminada a través de main { --surface: featured }. Luego, los componentes se habilitan para reaccionar a --surface: featured: una tarjeta revela una insignia promocional, un botón se establece de forma predeterminada en su variante rellena, etcétera.

Las consultas de estilo permiten que ambos lados permanezcan desacoplados: las superficies destacadas nunca nombran los elementos que se adaptan a ellas, y los componentes nunca inspeccionan lo que produjo el contexto. Cualquiera de los lados se puede extender de forma independiente (nuevos componentes, nuevas plataformas destacadas) sin tocar el otro. Los selectores descendientes (p.ej., .featured .button) fuerzan lo contrario: el selector debe codificar ambos lados de la relación y debe cambiar cada vez que lo haga cualquiera de los lados.

Cuándo usar esta guía

En esta guía, se abordan los cambios de comportamiento: un componente que decide qué renderizar, cómo organizarse o qué variante presentar en respuesta a su contexto, como ocultar o mostrar una insignia, cambiar la dirección del diseño o intercambiar una variante de botón.

Si, en cambio, necesitas cambios a nivel de token (modos de densidad, temas o otros tokens de orden superior que cambian de manera uniforme valores como el padding y el color en muchos componentes), consulta Reactividad de los tokens de diseño.

Elige la herramienta adecuada

Usa una consulta de estilo cuando ambos lados de una relación contextual puedan cambiar de forma independiente: es posible que nuevos elementos comiencen a producir el contexto o que nuevos componentes comiencen a reaccionar a él. La indirección se amortiza en extensibilidad y encapsulamiento, y las consultas de estilo cruzan los límites del DOM paralelo que los selectores descendientes no pueden. Cuando no se necesite esa flexibilidad, prefiere la herramienta más simple:

• Selectores descendientes (.toolbar .button): una relación fija y única que no se puede reutilizar ni extender. Se aplica el principio YAGNI: no agregues direccionamiento indirecto que no vayas a usar.
• Consultas de tamaño (@container (min-width: …)): Cambios de diseño y densidad impulsados por el espacio disponible, no por el estado semántico.
• Consultas de estilo (@container style(…)): estado semántico, es decir, lo que un componente debe renderizar, organizar o presentar en un contexto determinado.

Directivas de implementación

1. Define un indicador de contexto semántico con una propiedad personalizada de CSS en un contenedor.
2. NO establezcas container-type para las consultas de estilo, ya que consultan las propiedades personalizadas heredadas en el ancestro más cercano y no requieren un contexto de contención explícito.
3. OBLIGATORIO: Usa @container style(--property: value) para aplicar estilos condicionales a los elementos descendientes. Las consultas de estilo no pueden coincidir con el elemento en el que se establece la propiedad, solo con sus descendientes.
4. SÍ prefiere las consultas de estilo sobre los selectores descendientes cuando la relación debe permanecer extensible o cruzar los límites del componente o del DOM de sombra (consulta Cómo elegir la herramienta adecuada más arriba), pero conserva los selectores descendientes para las relaciones fijas y únicas en las que la indirección no aporta nada.

Ejemplo de implementación

/* 1. Set the context on a layout container */
.featured {
  --surface: featured; /* Semantic context flag for children */
}

/* 2. Component reacts to inherited flag */
.button {
  /* Default: Outlined informational style */
  background: transparent;
  border: 1px solid currentColor;
}

.badge {
  /* Default: Hidden — only revealed in featured surfaces */
  display: none;
}

@container style(--surface: featured) {
  .button {
    /* Automatic switch to Filled promotional style */
    background: var(--brand-accent);
    color: white;
    border: none;
  }

  .badge {
    /* Reveal decorative elements only in featured context */
    display: block;
  }
}

Estrategias de resguardo

Hasta que las consultas de estilo de contenedor estén ampliamente disponibles, agrégalas como una mejora progresiva: envía un valor predeterminado basado en selectores que funcione en todas partes y deja que la consulta de estilo lo anule cuando sea compatible. Usa :where() en el selector de contexto para que la consulta de estilo (misma especificidad, más adelante en el orden de origen) gane automáticamente.

/* Default styles — work everywhere */
.button {
  background: transparent;
  border: 1px solid currentColor;
}

.badge {
  display: none;
}

/* Selector-based contextual styles — broad browser support */
:where(.featured) .button {
  background: var(--brand-accent);
  color: white;
  border: none;
}

:where(.featured) .badge {
  display: block;
}

/* Progressive enhancement: style queries override when supported */
@container style(--surface: featured) {
  .button {
    background: var(--brand-accent);
    color: white;
    border: none;
  }

  .badge {
    display: block;
  }
}

El resguardo del selector vincula el diseño contextual a un nombre de clase, lo que acopla el componente a su ubicación en el DOM. Una vez que las consultas de estilo sean ampliamente compatibles, se podrá quitar la regla :where().