Publicado em: 10 de novembro de 2026
Contexto: modernização da arquitetura de front-end com padrões da Web
A note inc. é uma das maiores plataformas de criadores de conteúdo e mídia do Japão, atendendo a mais de 90 milhões de usuários ativos por mês. Como parte de um esforço contínuo para modernizar o front-end, os aplicativos da Web do note são criados com Next.js e React.
A equipe de engenharia de front-end incorporou assistentes de programação com IA ao fluxo de trabalho de desenvolvimento. Para ajudar essas ferramentas a gerar código moderno e compatível com padrões, o Google lançou o Modern Web Guidance, um conjunto de habilidades que integra conhecimento sobre plataformas da Web, práticas recomendadas e dados de compatibilidade de navegadores diretamente aos seus agentes de programação.
Para avaliar como o Modern Web Guidance afeta o código gerado na base de código
do Next.js e determinar como integrá-lo à biblioteca de componentes interna
(note-ui), a note realizou uma avaliação comparativa estruturada em seis
cenários de interface reais.
O desafio: coordenar componentes internos com padrões da Web
observação mantém o note-ui, uma biblioteca interna de componentes do React que fornece
elementos acessíveis e consistentes com a marca, como caixas de diálogo, dicas, acordeões e
campos de formulário. As diretrizes da equipe especificam o uso de note-ui para manter a consistência visual
e os valores de referência de acessibilidade em toda a plataforma.
A equipe de front-end do note queria determinar onde o Modern Web Guidance oferece o maior benefício arquitetônico e como coordenar melhor os padrões da Web com a biblioteca de componentes atual.
A configuração da avaliação
A note realizou um estudo comparativo em clones da base de código de produção do Next.js em seis tarefas de interface reais, comparando três condições:
- Sem orientação: ferramentas de IA que operam sem o Modern Web Guidance.
- Com orientação explícita: ferramentas de IA equipadas com o Modern Web Guidance e solicitadas a consultá-lo.
- Com orientação implícita: Modern Web Guidance disponível no repositório sem menção explícita ao comando.
As seis tarefas foram categorizadas com base na relação delas com a biblioteca de componentes internos do Notes:
- Tarefas cobertas por
note-ui: caixa de diálogo de confirmação da exclusão. - Tarefas fora do escopo do
note-ui: cabeçalho que diminui ao rolar a página, otimizações de velocidade da página do artigo. - Tarefas parcialmente cobertas por
note-ui: acordeão de perguntas frequentes (exigindo comportamento de abertura única e capacidade de localização na pesquisa na página), dicas de ferramentas de perfil de usuário avançadas, formulários de inscrição de membros.
As implementações foram verificadas não apenas por análise de código estático, mas também pela inspeção de propriedades DOM e CSS renderizadas em testes automatizados de navegadores Chromium e WebKit.
Veja a seguir os seis cenários de interface e a nota de critérios funcionais avaliada.
Principais descobertas: onde as diretrizes para a Web moderna têm o maior impacto
Para medir o impacto real do Modern Web Guidance, a note executou uma avaliação estruturada em 180 execuções em clones do repositório de produção do Next.js. Eles avaliaram dois agentes de programação de fronteira comercial em seis cenários de interface em três condições: sem orientação, com orientação não solicitada (habilidade no nível do repositório disponível) e com comandos explícitos.
Os pacotes de testes automatizados verificaram o DOM renderizado, o layout e as propriedades CSS computadas em ambientes de execução de navegador Chromium e WebKit headless em relação a 19 critérios definidos nos padrões modernos da Web.
Aderência aos padrões da Web por condição de avaliação
1. Melhorias de arquitetura e desempenho
O Modern Web Guidance provou ser um complemento poderoso para a arquitetura atual do
Note. Enquanto a biblioteca de componentes note-ui manteve a consistência da marca para elementos da interface padrão, o Modern Web Guidance equipou as ferramentas de IA para lidar com comportamentos interativos complexos e otimizações de desempenho usando APIs nativas do navegador.
Sem orientação, as ferramentas de IA costumavam gerar listeners de eventos JavaScript personalizados, gerenciamento de estado manual e carregamento de recursos ad hoc. Com as orientações da Web moderna, as ferramentas adotaram de forma consistente recursos nativos declarativos e reforçaram as práticas recomendadas de desempenho crítico.
Impacto da adoção de padrões modernos da Web em comparação com a implementação sem orientação
Os impactos do Modern Web Guidance na sua base de código variam de acordo com os comandos e os recursos usados. Para um exemplo concreto, veja como os listeners de rolagem imperativos do JavaScript para o cabeçalho foram substituídos por animações de rolagem nativas do CSS.
/* With Modern Web Guidance: CSS scroll-driven animation (excerpt, CSS Modules) */
.header {
--shrink-progress: 0;
--shrink-distance: calc(var(--header-max-height) - var(--header-min-height));
position: fixed;
inset: 0 0 auto;
/* Without support, a JS fallback updates --shrink-progress */
height: calc(var(--header-max-height) - var(--shrink-distance) * var(--shrink-progress));
}
/* The shadow fades in through opacity only */
.header::after {
content: "";
position: absolute;
inset: 0;
pointer-events: none;
box-shadow: var(--elevation-4);
opacity: var(--shrink-progress);
}
@supports ((animation-timeline: scroll()) and (animation-range: 0% 100%)) {
.header,
.header::after,
.logo {
animation-duration: auto;
animation-timing-function: linear;
animation-fill-mode: both;
animation-timeline: scroll(block root);
animation-range: 0px var(--shrink-distance);
}
.header { animation-name: header-shrink; }
.header::after { animation-name: header-shadow; }
.logo { animation-name: logo-shrink; }
}
@media (prefers-reduced-motion: reduce) {
.header,
.header::after,
.logo {
animation-timing-function: steps(1, end);
}
}
@keyframes header-shrink { to { height: var(--header-min-height); } }
@keyframes header-shadow { to { opacity: 1; } }
@keyframes logo-shrink { to { transform: scale(0.5); } }
2. Estabelecer o limite operacional certo para sistemas de design internos
A avaliação também destacou como as ferramentas de programação de IA interpretam as instruções. Quando
as ferramentas receberam uma instrução explícita e incondicional para seguir as orientações da Web,
elas selecionaram naturalmente elementos HTML nativos (como <dialog> ou
<input> nativos), mesmo quando um componente note-ui preexistente estava disponível.
observou que a solução é simples: em vez de tratar as orientações da Web
como uma alternância de tudo ou nada, as equipes alcançam o melhor resultado
estabelecendo uma hierarquia de regras clara nas instruções do repositório (como
AGENTS.md).
A decisão: uma estrutura de regras hierárquica no AGENTS.md
Com base nas descobertas da avaliação, o Note estabeleceu uma regra sistemática nas diretrizes do repositório (AGENTS.md) para orientar os desenvolvedores e as ferramentas de IA:
## UI Components and Modern Web Guidance
When building UI, follow this order of precedence. This applies even though the `modern-web-guidance` skill describes itself as mandatory for all HTML/CSS and client-side JavaScript tasks.
1. **Prioritize noteui**: For UI elements already provided by noteui (dialogs, toasts, buttons, form fields, popovers, etc.), use those components and follow existing conventions (such as `useDialogState` and react-hook-form). In apps, import them through `@/ui/noteui`. Do not replace an available component with a native HTML element (such as `<dialog>` or a plain `<input>`) simply because Modern Web Guidance recommends it.
2. **Use Modern Web Guidance where noteui falls short**: For capabilities that noteui does not cover or requirements it cannot meet, consult the `modern-web-guidance` skill before writing HTML, CSS, or client-side JavaScript. For example:
- Scroll-linked effects: Use CSS scroll-driven animations instead of scroll event listeners.
- Exclusive or page-searchable disclosure: Use `<details name="...">` and `hidden="until-found"`.
- Core Web Vitals: Use `fetchpriority` for LCP images and `content-visibility` for off-screen content.
- Form attributes: Pass attributes such as `autocomplete` and input `type` through the field component's props.
3. **Prioritize existing components when guidance conflicts**: Apply Modern Web Guidance only through the props and attributes supported by the component. For noteui form fields, display validation errors using the component's built-in mechanisms (`validationState` / `errorMessage`, or `HelpText` with `aria-describedby`) rather than custom alert elements.
Ao definir essa hierarquia:
- A consistência da interface atual é preservada: as caixas de diálogo e os formulários padrão
continuam usando
note-ui. - O JavaScript personalizado é eliminado: novos comportamentos e animações interativos aproveitam os recursos nativos do navegador.
- A qualidade do código é padronizada: as ferramentas para desenvolvedores seguem automaticamente os padrões modernos da Web onde eles são mais importantes.
Pontos importantes para as equipes de engenharia
- Use recursos de plataformas modernas onde os sistemas de design terminam: as bibliotecas de componentes são excelentes para elementos de interface de marca, mas os navegadores mais recentes oferecem recursos nativos poderosos para rolagem, pop-overs e prioridades de carregamento. O Modern Web Guidance ajuda as ferramentas para desenvolvedores a adotar esses recursos nativos em vez de escrever JavaScript personalizado.
- Defina uma hierarquia de prioridade clara: em bases de código com uma biblioteca de componentes existente, adicionar uma ordem de prioridade concisa nos arquivos do repositório (como AGENTS.md) garante que as ferramentas respeitem seu sistema de design ao adotar padrões da Web modernos.
- Verificar em ambientes de execução de navegadores reais: testar a saída renderizada em navegadores automatizados fornece feedback imediato sobre como o CSS e o HTML modernos interagem com bundlers e ambientes de framework específicos.
"Nossa missão no note é 'Começar e continuar criando'. Por isso, nossa plataforma precisa ser rápida e acessível para todos os criadores e leitores. À medida que mais códigos são escritos com agentes de programação de IA, o Modern Web Guidance ajuda a alcançar soluções modernas e baseadas em padrões, em vez de recorrer a padrões JavaScript mais antigos. Ele também destaca detalhes que podem passar despercebidos, como a prioridade de carregamento de imagens e a acessibilidade de formulários. Combinado com nosso sistema de design, ele nos permite continuar melhorando o Note e, ao mesmo tempo, manter nossa interface consistente."