How note inc. boosted modern web guideline adherence from 61% to 94% using Modern Web Guidance

Syna Kim

Takehiko Itabashi VP of Technology, note inc.

Published: November 10, 2026

Background: Modernizing frontend architecture with web standards

note inc. is one of Japan's largest creator and media platforms, serving over 90 million monthly active users. As part of an ongoing effort to modernize its frontend, note's web applications are built with Next.js and React.

The frontend engineering team has incorporated AI coding assistants into their development workflow. To help these tools generate modern, standard-compliant code, note introduced Google's Modern Web Guidance, a set of skills that embed web platform expertise, best practices, and browser compatibility data directly into your coding agents.

To evaluate how Modern Web Guidance affects generated code in their Next.js codebase and determine how to integrate it with their in-house component library (note-ui), note conducted a structured comparative evaluation across six real-world UI scenarios.

The challenge: Coordinating in-house components with web standards

note maintains note-ui, an internal React component library providing brand-consistent, accessible elements such as dialogs, tooltips, accordions, and form fields. Team guidelines specify using note-ui to maintain visual consistency and accessibility baselines across the platform.

note's frontend team wanted to determine where Modern Web Guidance delivers the greatest architectural benefit, and how to best coordinate web standards with their existing component library.

The evaluation setup

note conducted a comparative study on clones of their production Next.js codebase across six real-world UI tasks, comparing three conditions:

1. Without guidance: AI tools operating without Modern Web Guidance.
2. With explicit guidance: AI tools equipped with Modern Web Guidance and prompted to consult it.
3. With implicit guidance: Modern Web Guidance available in the repository without explicit prompt mention.

The six tasks were categorized based on their relationship with note's internal component library:

• Tasks covered by note-ui: Delete confirmation dialog.
• Tasks outside note-ui's scope: Scroll-shrinking header, article page speed optimizations.
• Tasks partially covered by note-ui: FAQ accordion (requiring single-open behavior and in-page search findability), rich user profile tooltips, member sign-up forms.

Implementations were verified not only through static code analysis, but also by inspecting rendered DOM and CSS properties in automated Chromium and WebKit browser tests.

The following are the six UI scenarios and the functional criteria note evaluated against.

Key findings: Where Modern Web Guidance delivers the highest impact

To measure the real-world impact of Modern Web Guidance, note executed a structured evaluation across 180 runs on clones of their production Next.js repository. They evaluated two commercial frontier coding agents across six UI scenarios under three conditions: without guidance, with unprompted guidance (repository-level skill available), and with explicit prompting.

Automated test suites verified rendered DOM, layout, and computed CSS properties in headless Chromium and WebKit browser runtimes against 19 criteria defined in modern web standards.

Web standards adherence by evaluation condition

1. Architectural and performance improvements

Modern Web Guidance proved to be a powerful complement to note's existing architecture. While the note-ui component library maintained brand consistency for standard UI elements, Modern Web Guidance equipped AI tools to handle complex interactive behaviors and performance optimizations using native browser APIs.

Without guidance, AI tools frequently generated custom JavaScript event listeners, manual state management, and ad hoc asset loading. With Modern Web Guidance, tools consistently adopted declarative native features and reinforced critical performance best practices.

Impact of adopting modern web standards versus unguided implementation

The impacts of Modern Web Guidance on your codebase will vary based on prompts and the features used. For a concrete example, here's how the imperative JavaScript scroll listeners for the header were replaced with native CSS Scroll-Driven Animations.

/* 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. Establishing the right operational boundary for in-house design systems

The evaluation also highlighted how AI coding tools interpret instructions. When tools were given an explicit, unconditional instruction to follow web guidance, they naturally selected native HTML elements (such as native <dialog> or <input>), even when a pre-existing note-ui component was available.

note found that the solution is straightforward: rather than treating web guidance as an all-or-nothing toggle, teams achieve the best outcome by establishing a clear rule hierarchy in repository instructions (such as AGENTS.md).

The decision: A hierarchical rule structure in AGENTS.md

Based on the evaluation findings, note established a systematic rule in their repository guidelines (AGENTS.md) to guide developers and AI tools:

## 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.

By defining this hierarchy:

• Existing UI consistency is preserved: Standard dialogs and forms continue using note-ui.
• Custom JavaScript is eliminated: New interactive behaviors and animations leverage native browser capabilities.
• Code quality is standardized: Development tools automatically follow modern web standards where they matter most.

Takeaways for engineering teams

• Use modern platform features where design systems end: Component libraries excel at brand UI elements, but modern browsers provide powerful native capabilities for scrolling, popovers, and loading priorities. Modern Web Guidance helps development tools adopt these native capabilities instead of writing custom JavaScript.
• Define a clear priority hierarchy: In codebases with an existing component library, adding a concise priority order in repository files (like AGENTS.md) ensures tools respect your design system while adopting modern web standards.
• Verify in real browser runtimes: Testing rendered output in automated browsers provides immediate feedback on how modern CSS and HTML interact with specific bundlers and framework environments.