Adaptação de componentes semânticos

Use consultas de estilo (@container style()) para acionar variações contextuais sem codificar o que produz ou reage a cada contexto. Isso reduz o acoplamento do sistema de design e melhora a extensibilidade e o encapsulamento de componentes.

Por exemplo, uma regra section.featured { --surface: featured } pode marcar um contexto, e uma página de destino também pode usar esse contexto como padrão por meio de main { --surface: featured }. Os componentes então reagem ao --surface: featured: um card revela um selo promocional, um botão assume o padrão da variante preenchida e assim por diante.

As consultas de estilo permitem que ambos os lados permaneçam desacoplados: as superfícies em destaque nunca nomeiam os elementos que se adaptam a elas, e os componentes nunca inspecionam o que produziu o contexto. Cada lado pode ser estendido de forma independente, com novos componentes e novas plataformas em destaque, sem afetar o outro. Os seletores descendentes (por exemplo, .featured .button) forçam o oposto: o seletor precisa codificar os dois lados da relação e mudar sempre que um dos lados mudar.

Quando usar este guia

Este guia aborda mudanças comportamentais: um componente que decide o que renderizar, como se organizar ou qual variante apresentar em resposta ao contexto, ocultando ou mostrando um selo, mudando a direção do layout ou trocando uma variante de botão.

Se você precisar de mudanças no nível do token (modos de densidade, temas ou outros tokens de ordem superior que mudam uniformemente valores como padding e cor em muitos componentes), consulte Reatividade do token de design.

Como escolher a ferramenta certa

Use uma consulta de estilo quando os dois lados de uma relação contextual puderem mudar de forma independente. Novos elementos podem começar a produzir o contexto ou novos componentes podem começar a reagir a ele. A indireção se paga em extensibilidade e encapsulamento, e as consultas de estilo cruzam os limites do shadow DOM que os seletores descendentes não conseguem. Quando essa flexibilidade não for necessária, prefira a ferramenta mais simples:

• Seletores descendentes (.toolbar .button): uma relação fixa e única que não é reutilizável nem extensível. O princípio YAGNI se aplica: não adicione indireções que você não vai usar.
• Consultas de tamanho (@container (min-width: …)): mudanças de layout e densidade impulsionadas pelo espaço disponível, não pelo estado semântico.
• Consultas de estilo (@container style(…)): estado semântico, ou seja, o que um componente precisa renderizar, organizar ou apresentar em um determinado contexto.

Diretivas de implementação

1. Defina uma flag de contexto semântico usando uma propriedade personalizada de CSS em um contêiner.
2. NÃO defina container-type para consultas de estilo. Elas consultam propriedades personalizadas herdadas no ancestral mais próximo e não exigem um contexto de contenção explícito.
3. OBRIGATÓRIO: use @container style(--property: value) para aplicar estilos condicionais a elementos descendentes. As consultas de estilo não podem corresponder ao elemento em que a propriedade está definida, apenas aos descendentes dele.
4. RECOMENDAMOS priorizar as consultas de estilo em relação aos seletores descendentes quando a relação precisa permanecer extensível ou cruzar os limites do componente/DOM de sombra (consulte Como escolher a ferramenta certa acima). No entanto, mantenha os seletores descendentes para relações fixas e únicas em que a indireção não traz benefícios.

Exemplo de implementação

/* 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;
  }
}

Estratégias de fallback

Até que as consultas de estilo de contêiner estejam amplamente disponíveis, use-as como um aprimoramento progressivo: envie um padrão baseado em seletor que funcione em todos os lugares e permita que a consulta de estilo o substitua quando houver suporte. Use :where() no seletor de contexto para que a consulta de estilo (mesma especificidade, mais adiante na ordem de origem) vença automaticamente.

/* 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;
  }
}

O substituto do seletor vincula o estilo contextual a um nome de classe, que associa o componente ao posicionamento do DOM. Quando as consultas de estilo forem amplamente aceitas, a regra :where() poderá ser removida.