Cómo note inc. aumentó el cumplimiento de los lineamientos de la Web moderna del 61% al 94% con Modern Web Guidance

Syna Kim
Syna Kim
Takehiko Itabashi
Takehiko Itabashi VP of Technology, note inc.

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:

  1. Sin orientación: Herramientas de IA que funcionan sin Modern Web Guidance
  2. Con orientación explícita: Herramientas de IA equipadas con Modern Web Guidance y con instrucciones para consultarla
  3. 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-ui cubre 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.

Diálogo de confirmación de eliminación
Se abre cuando se hace clic en Borrar; se cierra con Esc, un clic en el fondo o el botón Cancelar
Encabezado que se reduce al desplazarse
La altura inicial es de 120px; se reduce a 64px al desplazarse; permanece fijo en la parte superior
Información sobre la herramienta enriquecida para el usuario
Aparece cuando se coloca el cursor sobre el elemento y cuando se enfoca el teclado; desaparece cuando el puntero se aleja
Acordeón de preguntas frecuentes
Se expande cuando se hace clic en él; cuando se abre otro elemento, se contraen automáticamente los anteriores
Formulario de registro de miembros
Suprime los errores durante la escritura activa y muestra los errores de validación cuando se desenfoca el campo.
Renderización de la página del artículo
La imagen más grande en el viewport tiene prioridad alta y no se carga de forma diferida; las tarjetas fuera de la pantalla usan content-visibility: auto; y las imágenes fuera de la pantalla se cargan de forma diferida

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

Agente de programación Modelo de referencia Orientación no solicitada Orientación explícita Efectividad neta
Agente A
Modelo principal
60.8%
sin orientación
76.5%
+15.7 pt
94.0%
de rendimiento máximo
+33.2 p.p.
p < 0.001
Agente B
Modelo secundario
75.8%
sin orientación
86.2%
+10.3 p.p.
90.0%
precisión alta
+14.2 p.p.
p < 0.001
En cuanto a la metodología, el porcentaje representa la adhesión de la plataforma en 19 verificaciones automatizadas del navegador en Chromium y WebKit. Las pruebas verificaron que el código generado adoptó funciones web nativas en lugar de JavaScript personalizado heredado.

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

Función y API nativa Sin orientación Con Modern Web Guidance
Encabezado que se reduce al desplazarse
animation-timeline: scroll()
❌ Objeto de escucha de JS imperativo
Se ejecuta en el subproceso principal y causa problemas de desplazamiento
✅ Compositor fuera del subproceso principal
Animación de desplazamiento de CSS declarativa; cero código de objeto de escucha de JS
Cuadro de información interactivo
API de Popover
❌ Matemáticas de coordenadas de JS personalizadas
Cálculos manuales frágiles de viewport y cambio de tamaño
✅ Sobrecarga de paquetes de 0 KB
Ubicación nativa de la capa superior; cero cálculos matemáticos personalizados o wrappers de DOM
Acordeón de preguntas frecuentes con opción de búsqueda
<details name="faq">
❌ Estado de activación de React personalizado
Contenido oculto de la búsqueda de texto en la página (Ctrl + F), ARIA manual
✅ Búsqueda nativa en la página
El navegador se expande automáticamente con Ctrl + F; código de sincronización de estado cero
Imagen hero de LCP candidata
fetchpriority="high"
❌ Antipatrones en conflicto
Se combinó la prioridad alta con la carga diferida en las imágenes hero.
✅ Detección temprana del análisis de HTML
Se desvinculó de la carga diferida; +28% de adopción en las PR posteriores al MWG
Formulario de registro accesible
autocomplete y HTML semántico
❌ Faltan tokens de autocompletado
Se omitieron los anuncios de error accesibles
✅ Autocompletado del navegador sin inconvenientes
Entradas nativas y anuncios de ARIA; +69% de adopción del autocompletado
Nota sobre la metodología: Las filas 1 a 3 reflejan los resultados de la arquitectura verificados en 180 ejecuciones de pruebas de navegadores sin interfaz gráfica. Las filas 4 y 5 incluyen las ganancias de adopción de producción medidas en 431 PR posteriores a la introducció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".

— Takehiko Itabashi, vicepresidente de Tecnología, note inc.