Publicado: 10 de noviembre de 2026
Contexto: Modernización de la arquitectura de frontend con estándares web
note inc. es una de las plataformas de creadores y medios más grandes de Japón, que ofrece servicios a más de 90 millones de usuarios activos por mes. Como parte de un esfuerzo continuo para modernizar su frontend, las aplicaciones web de note se compilan con Next.js y React.
El equipo de ingeniería de frontend incorporó asistentes de programación con IA en su flujo de trabajo de desarrollo. Para ayudar a estas herramientas a generar código moderno y que cumpla con los estándares, Google presentó Modern Web Guidance, un conjunto de habilidades que incorporan experiencia en plataformas web, prácticas recomendadas y datos de compatibilidad de navegadores directamente en tus agentes de programación.
Para evaluar cómo Modern Web Guidance afecta el código generado en su base de código de Next.js
y determinar cómo integrarlo con su biblioteca de componentes interna
(note-ui), note realizó una evaluación comparativa estructurada en seis
situaciones de IU reales.
El desafío: Coordinar los componentes internos con los estándares web
note mantiene note-ui, una biblioteca interna de componentes de React que proporciona
elementos accesibles y coherentes con la marca, como diálogos, cuadros de información, acordeones y
campos de formulario. Los lineamientos del equipo especifican el uso de note-ui para mantener la coherencia visual y los valores de referencia de accesibilidad en toda la plataforma.
El equipo de frontend de note quería determinar dónde ofrece Modern Web Guidance el mayor beneficio arquitectónico y cómo coordinar mejor los estándares web con su biblioteca de componentes existente.
La configuración de la evaluación
nota realizó un estudio comparativo sobre clones de su base de código de Next.js de producción en seis tareas de IU del mundo real, en el que se compararon tres condiciones:
- Sin orientación: Herramientas de IA que funcionan sin Modern Web Guidance
- Con orientación explícita: Herramientas de IA equipadas con Modern Web Guidance y con instrucciones para consultarla
- Con orientación implícita: Modern Web Guidance está disponible en el repositorio sin mención explícita de la instrucción.
Las seis tareas se categorizaron según su relación con la biblioteca de componentes internos de Notes:
- Tareas que abarca
note-ui: Cuadro de diálogo de confirmación del borrado. - Tareas fuera del alcance de
note-ui: Encabezado que se reduce al desplazarse, optimizaciones de la velocidad de la página de artículos. - Tareas que
note-uicubre parcialmente: Acordeón de preguntas frecuentes (que requiere un comportamiento de apertura única y visibilidad de búsqueda en la página), información sobre herramientas enriquecida del perfil de usuario y formularios de registro de miembros.
Las implementaciones se verificaron no solo a través del análisis de código estático, sino también inspeccionando las propiedades de DOM y CSS renderizadas en pruebas automatizadas de los navegadores Chromium y WebKit.
A continuación, se muestran las seis situaciones de la IU y la nota de criterios funcionales con la que se evalúan.
Hallazgos clave: Dónde la guía de la Web moderna tiene el mayor impacto
Para medir el impacto en el mundo real de Modern Web Guidance, note ejecutó una evaluación estructurada en 180 ejecuciones en clones de su repositorio de producción de Next.js. Evaluaron dos agentes de programación de frontera comerciales en seis situaciones de IU en tres condiciones: sin orientación, con orientación no solicitada (habilidad disponible a nivel del repositorio) y con instrucciones explícitas.
Los paquetes de pruebas automatizadas verificaron el DOM renderizado, el diseño y las propiedades de CSS calculadas en los entornos de ejecución de los navegadores Chromium y WebKit sin interfaz gráfica en función de 19 criterios definidos en los estándares web modernos.
Cumplimiento de los estándares web por condición de evaluación
1. Mejoras de arquitectura y rendimiento
Modern Web Guidance demostró ser un complemento potente para la arquitectura existente de
note. Si bien la biblioteca de componentes de note-ui mantuvo la coherencia de la marca
para los elementos de la IU estándar, Modern Web Guidance equipó las herramientas de IA para que controlaran
comportamientos interactivos complejos y optimizaciones de rendimiento con APIs nativas
del navegador.
Sin orientación, las herramientas de IA generaban con frecuencia objetos de escucha de eventos de JavaScript personalizados, administración manual de estados y carga de recursos ad hoc. Con Modern Web Guidance, las herramientas adoptaron de forma coherente funciones nativas declarativas y reforzaron las prácticas recomendadas de rendimiento fundamentales.
Impacto de adoptar estándares web modernos en comparación con una implementación sin orientación
Los impactos de Modern Web Guidance en tu base de código variarán según las instrucciones y las funciones que uses. Para ver un ejemplo concreto, aquí se muestra cómo se reemplazaron los objetos de escucha de desplazamiento imperativos de JavaScript para el encabezado por animaciones nativas basadas en el desplazamiento de 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. Establecer el límite operativo adecuado para los sistemas de diseño internos
La evaluación también destacó cómo las herramientas de programación de IA interpretan las instrucciones. Cuando
se les dio a las herramientas una instrucción explícita e incondicional para seguir la guía web,
seleccionaron de forma natural elementos HTML nativos (como <dialog> o
<input> nativos), incluso cuando había un componente note-ui preexistente disponible.
nota, se descubrió que la solución es sencilla: en lugar de tratar la orientación web
como un interruptor de todo o nada, los equipos logran el mejor resultado
estableciendo una jerarquía de reglas clara en las instrucciones del repositorio (como
AGENTS.md).
La decisión: Una estructura de reglas jerárquica en AGENTS.md
Según los resultados de la evaluación, Note estableció una regla sistemática en sus
lineamientos del repositorio (AGENTS.md) para guiar a los desarrolladores y las herramientas 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.
Si defines esta jerarquía, ocurrirá lo siguiente:
- Se conserva la coherencia de la IU existente: Los diálogos y formularios estándar siguen usando
note-ui. - Se elimina el JavaScript personalizado: Los nuevos comportamientos y animaciones interactivos aprovechan las capacidades nativas del navegador.
- La calidad del código está estandarizada: Las herramientas para desarrolladores siguen automáticamente los estándares web modernos donde más importan.
Conclusiones para los equipos de ingeniería
- Usa funciones de plataformas modernas donde terminan los sistemas de diseño: Las bibliotecas de componentes se destacan en los elementos de la IU de la marca, pero los navegadores actualizados proporcionan potentes capacidades nativas para el desplazamiento, los cuadros emergentes y las prioridades de carga. Modern Web Guidance ayuda a las herramientas para desarrolladores a adoptar estas capacidades nativas en lugar de escribir código de JavaScript personalizado.
- Define una jerarquía de prioridades clara: En las bases de código con una biblioteca de componentes existente, agregar un orden de prioridad conciso en los archivos del repositorio (como AGENTS.md) garantiza que las herramientas respeten tu sistema de diseño y, al mismo tiempo, adopten los estándares web modernos.
- Verifica en entornos de ejecución de navegadores reales: Probar el resultado renderizado en navegadores automatizados proporciona comentarios inmediatos sobre cómo interactúan el CSS y el HTML modernos con empaquetadores y entornos de framework específicos.
"Nuestra misión en note es 'Comienza y sigue creando', por lo que nuestra plataforma debe ser rápida y accesible para todos los creadores y lectores. A medida que se escribe más código con agentes de programación de IA, Modern Web Guidance los ayuda a buscar soluciones modernas basadas en estándares en lugar de recurrir a patrones de JavaScript más antiguos. También señala detalles que son fáciles de pasar por alto, como la prioridad de carga de imágenes y la accesibilidad de los formularios. En combinación con nuestro sistema de diseño, nos permite seguir mejorando las notas y, al mismo tiempo, mantener la coherencia de nuestra IU".