Hoe note inc. de naleving van de richtlijnen voor het moderne web verhoogde van 61% naar 94% met Modern Web Guidance

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

Gepubliceerd: 10 november 2026

Achtergrond: De frontend-architectuur moderniseren met webstandaarden

note inc. is een van de grootste creator- en mediaplatforms van Japan, met meer dan 90 miljoen maandelijks actieve gebruikers. Als onderdeel van een doorlopende inspanning om de frontend te moderniseren, zijn de web-apps van note gebouwd met Next.js en React.

Het frontend-engineeringteam heeft AI-programmeerassistenten opgenomen in hun ontwikkelingsworkflow. Om deze tools te helpen moderne, aan de normen voldoende code te genereren, heeft Google de Modern Web Guidance geïntroduceerd, een reeks vaardigheden die expertise over webplatforms, best practices en gegevens over browsercompatibiliteit rechtstreeks in je programmeeragents inbedden.

Om te evalueren hoe Modern Web Guidance de gegenereerde code in hun Next.js-codebase beïnvloedt en te bepalen hoe ze deze kunnen integreren met hun interne componentenbibliotheek (note-ui), heeft note een gestructureerde vergelijkende evaluatie uitgevoerd voor 6 praktijkscenario's voor UI.

De uitdaging: interne componenten coördineren met webstandaarden

note maintains note-ui, an internal React component library providing brand-consistent, accessible elements such as dialogs, tooltips, accordions, and form fields. Teamrichtlijnen schrijven het gebruik van note-ui voor om visuele consistentie en toegankelijkheidsbaselines op het platform te behouden.

Het frontendteam van note wilde bepalen waar Modern Web Guidance het grootste architectonische voordeel oplevert en hoe ze webstandaarden het beste kunnen afstemmen op hun bestaande componentenbibliotheek.

De evaluatie-instellingen

note heeft een vergelijkend onderzoek uitgevoerd naar klonen van hun productie Next.js-codebase voor 6 echte UI-taken, waarbij 3 voorwaarden werden vergeleken:

  1. Zonder begeleiding: AI-tools die werken zonder Modern Web Guidance.
  2. Met expliciete begeleiding: AI-tools die zijn uitgerust met Modern Web Guidance en die worden gevraagd deze te raadplegen.
  3. Met impliciete begeleiding: Modern Web Guidance is beschikbaar in de repository zonder expliciete vermelding van de prompt.

De 6 taken zijn gecategoriseerd op basis van hun relatie met de interne componentenbibliotheek van NotebookLM:

  • Taken die worden gedekt door note-ui: Bevestigingsvenster verwijderen.
  • Taken die buiten het bereik van note-ui vallen: Koptekst die kleiner wordt bij scrollen, optimalisatie van de paginasnelheid van artikelpagina's.
  • Taken die gedeeltelijk worden gedekt door note-ui: Veelgestelde vragen (vereist dat er maar één tegelijk kan worden geopend en dat ze vindbaar zijn via zoeken op de pagina), tooltips voor uitgebreide gebruikersprofielen, aanmeldingsformulieren voor leden.

Implementaties zijn niet alleen geverifieerd via statische codeanalyse, maar ook door gerenderde DOM- en CSS-eigenschappen te inspecteren in geautomatiseerde Chromium- en WebKit-browsertests.

Hieronder staan de 6 UI-scenario's en de functionele criteria die worden geëvalueerd.

Dialoogvenster voor verwijderingsbevestiging
Wordt geopend als je op Verwijderen klikt. Wordt gesloten met Esc, een klik op de achtergrond of de knop Annuleren.
Kop die kleiner wordt bij scrollen
De oorspronkelijke hoogte is 120px. De kop wordt kleiner tot 64px bij scrollen en blijft bovenaan staan.
Uitgebreide gebruikerstooltip
Verschijnt bij cursorplaatsing en toetsenbordfocus, verdwijnt als de cursor wordt weggehaald
Veelgestelde vragen
Wordt uitgevouwen als erop wordt geklikt. Als je een ander item opent, worden eerdere items automatisch samengevouwen.
Aanmeldingsformulier voor leden
Onderdrukt fouten tijdens actief typen; toont validatiefouten bij veldvervaging
Weergave van artikelpagina
De grootste afbeelding in de viewport heeft een hoge prioriteit en wordt niet lazy-loaded. Kaarten buiten het scherm gebruiken content-visibility: auto; en afbeeldingen buiten het scherm worden lazy-loaded.

Belangrijkste bevindingen: waar Modern Web Guidance de grootste impact heeft

Om de impact van Modern Web Guidance in de praktijk te meten, voerde note een gestructureerde evaluatie uit van 180 uitvoeringen op klonen van hun Next.js-productierepository. Ze evalueerden 2 commerciële frontier-coderingsagents in 6 UI-scenario's onder 3 omstandigheden: zonder begeleiding, met ongevraagde begeleiding (vaardigheid op repositoryniveau beschikbaar) en met expliciete prompts.

Geautomatiseerde testpakketten hebben de gerenderde DOM, de indeling en de berekende CSS-eigenschappen geverifieerd in headless Chromium- en WebKit-browserruntimes op basis van 19 criteria die zijn gedefinieerd in moderne webstandaarden.

Naleving van webstandaarden per evaluatievoorwaarde

Programmeer-agent Basislijn Ongevraagde begeleiding Expliciete richtlijnen Netto toename
Agent A
Primair model
60,8%
geen richtlijnen
76,5%
+15,7pt
94,0%
piekprestaties
+33,2 pt
p < 0,001
Agent B
Secundair model
75,8%
geen richtlijnen
86,2%
+10,3pt
90,0%
hoge nauwkeurigheid
+14,2 pt
p < 0,001
Wat betreft de methodologie: het percentage vertegenwoordigt de naleving van het platform voor 19 geautomatiseerde browsercontroles in Chromium en WebKit. Tests hebben geverifieerd dat de gegenereerde code native webfuncties gebruikt in plaats van verouderde aangepaste JavaScript.

1. Architectuur- en prestatieverbeteringen

Modern Web Guidance bleek een krachtige aanvulling op de bestaande architectuur van note. De componentenbibliotheek van note-ui zorgde voor merkconsistentie voor standaard UI-elementen, maar Modern Web Guidance rustte AI-tools uit om complex interactief gedrag en prestatieoptimalisaties te verwerken met systeemeigen browser-API's.

Zonder begeleiding genereerden AI-tools vaak aangepaste JavaScript-gebeurtenislisteners, handmatig statusbeheer en ad-hoc laden van componenten. Met Modern Web Guidance hebben tools consequent declaratieve native functies overgenomen en essentiële best practices voor prestaties versterkt.

Impact van de overstap naar moderne webstandaarden versus niet-begeleide implementatie

Functie en systeemeigen API Zonder begeleiding Met Modern Web Guidance
Kop die kleiner wordt bij scrollen
animation-timeline: scroll()
❌ Imperatieve JS-listener
Wordt uitgevoerd op de primaire thread, waardoor scrollen schokkerig wordt
✅ Samensteller buiten de hoofdthread
Declaratieve CSS-scrollanimatie; geen JS-listenercode
Interactieve tooltip
Popover API
❌ Aangepaste JS-coördinatenberekeningen
Kwetsbare handmatige viewport- en formaatberekeningen
✅ 0 KB bundeloverhead
Plaatsing in de native bovenste laag, geen aangepaste wiskunde of DOM-wrappers
Doorzoekbare accordeon met veelgestelde vragen
<details name="faq">
❌ Aangepaste React-schakelstatus
Content verborgen voor in-page tekstzoekopdrachten (Ctrl+F), handmatige ARIA
✅ Systeemeigen in-page zoeken
Browser wordt automatisch uitgevouwen bij Ctrl+F; synchronisatiecode voor nulstatus
Kandidaat voor LCP-hero-afbeelding
fetchpriority="high"
❌ Conflicterende antipatronen
Hoge prioriteit gekoppeld aan lazy loading voor hero-afbeeldingen
✅ Vroege HTML-parse-ontdekking
Losgekoppeld van lazy loading; +28% adoptie in PR's na MWG
Toegankelijk aanmeldingsformulier
autocomplete en semantische HTML
❌ Ontbrekende tokens voor automatisch invullen
Toegankelijke foutmeldingen weggelaten
✅ Probleemloos automatisch invullen in de browser
Systeemeigen invoer en ARIA-aankondigingen; +69% gebruik van automatisch invullen
Opmerking over de methodologie: De rijen 1-3 weerspiegelen architecturale resultaten die zijn geverifieerd in 180 headless browsertestuitvoeringen. Rij 4-5 bevatten de toename in productadoptie, gemeten over 431 PR's na de introductie.

De impact van Modern Web Guidance op je codebase varieert afhankelijk van de prompts en de gebruikte functies. Hier is een concreet voorbeeld van hoe de imperatieve JavaScript-scroll-listeners voor de kop zijn vervangen door 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. De juiste operationele grens bepalen voor interne ontwerpsystemen

De evaluatie benadrukte ook hoe AI-coderingstools instructies interpreteren. Als tools een expliciete, onvoorwaardelijke instructie kregen om webrichtlijnen te volgen, selecteerden ze vanzelf native HTML-elementen (zoals native <dialog> of <input>), zelfs als er een bestaande note-ui-component beschikbaar was.

vond dat de oplossing eenvoudig is: in plaats van webbegeleiding te behandelen als een alles-of-niets-schakelaar, bereiken teams het beste resultaat door een duidelijke regelhiërarchie vast te stellen in repository-instructies (zoals AGENTS.md).

De beslissing: een hiërarchische regelstructuur in AGENTS.md

Op basis van de evaluatiebevindingen heeft note een systematische regel opgesteld in de richtlijnen voor de repository (AGENTS.md) om ontwikkelaars en AI-tools te begeleiden:

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

Door deze hiërarchie te definiëren:

  • De consistentie van de bestaande UI blijft behouden: Standaarddialoogvensters en -formulieren blijven note-ui gebruiken.
  • Aangepaste JavaScript is geëlimineerd: Nieuwe interactieve gedragingen en animaties maken gebruik van systeemeigen browsermogelijkheden.
  • De codekwaliteit is gestandaardiseerd: Tools voor ontwikkelaars volgen automatisch moderne webstandaarden waar die het belangrijkst zijn.

Belangrijke punten voor technische teams

  • Gebruik moderne platformfuncties waar ontwerpsystemen eindigen: Componentbibliotheken zijn uitstekend voor UI-elementen van merken, maar moderne browsers bieden krachtige native mogelijkheden voor scrollen, pop-overs en laadprioriteiten. Modern Web Guidance helpt tools voor ontwikkelaars om deze systeemeigen mogelijkheden te gebruiken in plaats van aangepaste JavaScript te schrijven.
  • Definieer een duidelijke prioriteitshiërarchie: In codebases met een bestaande componentenbibliotheek zorgt de toevoeging van een beknopte prioriteitsvolgorde in repositorybestanden (zoals AGENTS.md) ervoor dat tools je ontwerpsysteem respecteren terwijl ze moderne webstandaarden overnemen.
  • Verifiëren in echte browserruntimes: Als je de gerenderde uitvoer test in geautomatiseerde browsers, krijg je onmiddellijk feedback over hoe moderne CSS en HTML werken met specifieke bundlers en frameworkomgevingen.

"Onze missie bij note is 'Start, and Keep on Creating' (Begin en blijf creëren). Daarom moet ons platform snel en toegankelijk blijven voor elke creator en lezer. Omdat steeds meer van onze code wordt geschreven met AI-programmeeragents, helpt Modern Web Guidance ze om moderne, op standaarden gebaseerde oplossingen te gebruiken in plaats van terug te vallen op oudere JavaScript-patronen. De tool wijst ook op details die je makkelijk over het hoofd ziet, zoals de prioriteit voor het laden van afbeeldingen en de toegankelijkheid van formulieren. In combinatie met ons ontwerpsysteem kunnen we Notities blijven verbeteren terwijl onze UI consistent blijft.'

— Takehiko Itabashi, VP of Technology, note inc.