![Syna Kim](https://web.dev/images/authors/synakim.jpg) Syna Kim [LinkedIn](https://www.linkedin.com/in/synakim) ![Takehiko Itabashi](https://web.dev/images/authors/takehikoitabashi.jpg) Takehiko Itabashi VP of Technology, note inc. [LinkedIn](https://www.linkedin.com/in/takehiko-itabashi)

<br />


Published: November 10, 2026

<br />

## Background: Modernizing frontend architecture with web standards

[note](https://note.com) 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](https://developer.chrome.com/docs/modern-web-guidance.md.txt),
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.

|---|---|
| **Delete confirmation dialog** Opens on **Delete** click; closes with <kbd>Esc</kbd>, backdrop click, or Cancel button | **Scroll-shrinking header** Initial height is `120px`; shrinks to `64px` on scroll; remains fixed at top |
| **Rich user tooltip** Appears on hover and keyboard focus; dismisses when pointer leaves | **FAQ accordion** Expands on click; opening another item automatically collapses previous ones |
| **Member sign-up form** Suppresses errors during active typing; displays validation errors on field blur | **Article page rendering** Largest in-viewport image has high priority and is not lazy-loaded; offscreen cards use `content-visibility: auto;` and offscreen images are lazy-loaded |

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

| Coding Agent | Baseline | Unprompted Guidance | Explicit Guidance | Net Lift |
|---|---|---|---|---|
| **Agent A** Primary Model | 60.8% no guidance | 76.5% +15.7pt | 94.0% peak performance | +33.2pt p \< 0.001 |
| **Agent B** Secondary Model | 75.8% no guidance | 86.2% +10.3pt | 90.0% high accuracy | +14.2pt p \< 0.001 |
[Regarding methodology: the percentage represents platform adherence across 19 automated browser checks in Chromium and WebKit. Tests verified that generated code adopted native web features instead of legacy custom JavaScript.]

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

| **Feature and native API** | **Without guidance** | **With Modern Web Guidance** |
|---|---|---|
| **Scroll-shrinking header** `animation-timeline: scroll()` | **❌ Imperative JS listener** Runs on main thread; causes scroll jank | **✅ Off-main-thread compositor** Declarative CSS scroll animation; zero JS listener code |
| **Interactive tooltip** Popover API | **❌ Custom JS coordinate math** Brittle manual viewport and resize calculations | **✅ 0 KB bundle overhead** Native top-layer placement; zero custom math or DOM wrappers |
| **Searchable FAQ accordion** `<details name="faq">` | **❌ Custom React toggle state** Content hidden from in-page text search (<kbd>Ctrl+F</kbd>), manual ARIA | **✅ Native find-in-page search** Browser auto-expands on <kbd>Ctrl+F</kbd>; zero state sync code |
| **Candidate LCP hero image** `fetchpriority="high"` | **❌ Conflicting anti-patterns** Coupled high priority with lazy-loading on hero images | **✅ Early HTML parse discovery** Decoupled from lazy-loading; +28% adoption in post-MWG PRs |
| **Accessible sign-up form** `autocomplete` and semantic HTML | **❌ Missing autofill tokens** Omitted accessible error announcements | **✅ Frictionless browser autofill** Native inputs and ARIA announcements; +69% autofill adoption |
[Methodology note: Rows 1--3 reflect architectural outcomes verified across 180 headless browser test runs. Rows 4--5 include production adoption gains measured across 431 post-introduction PRs.]

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.

```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. 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:

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

>
> "Our mission at note is 'Start, and Keep on Creating,' so our platform has to stay fast and accessible for every creator and reader. As more of our code is written with AI coding agents, Modern Web Guidance helps them reach for modern, standards-based solutions instead of falling back on older JavaScript patterns. It also points out details that are easy to miss, such as image loading priority and form accessibility. Combined with our design system, it lets us keep improving note while keeping our UI consistent."
--- Takehiko Itabashi, VP of Technology, note inc.