DEV Community: FrozonFreak

Declare your color schemes before the first paint (Web HIG tip #17)

FrozonFreak — Fri, 13 Nov 2026 06:11:42 +0000

You open example.com on a phone that prefers dark mode. The page was authored as light, with no color-scheme in the head or the first CSS. In the Safari 27.3 beta, with Adaptive Dark Mode turned on, Safari can repaint that light page as dark: colors and light gradients change, some SVG images and simple logos recolor, and some masks or blend effects can be turned off. Scripts that read the page's colors still get the authored values. The page never told the browser which schemes it supports.

Web HIG tip #17 (Quick #64): Dark mode must re-verify contrast for every semantic token combination used. Declare supported color schemes in the document head or the initial CSS, before JavaScript. light dark is the usual declaration when both schemes are supported. light only is a narrow opt-out, not the default.

Why it matters

A missing declaration leaves the browser free to invent an appearance you did not author:

Safari Adaptive Dark Mode may transform a light page that does not declare schemes. Canvas stays as authored; CSS colors, gradients, and some images may not
Script and computed styles keep the authored values, so the repaint is invisible to ordinary CSS checks and many automated contrast tools
Text, focus, hover, SVG logos, transparent images, and canvas can look wrong while a lab check still reports the authored contrast
A declaration added by JavaScript later still takes effect, but the first render may already have used the browser's default light canvas and controls. That is the flash you're trying to avoid. WebKit advises against waiting to inject it with script

The full HIG covers this in §3.1, Supported color schemes: pages that support light and dark appearances MUST declare those schemes in the initial document, before any JavaScript runs. In practice, that means the browser knows the schemes before it first renders the page. Quick #64 is Quick-only guidance (no rule ID of its own). The same section states that Safari's contrast aim after a transformation is not a substitute for checking the authored interface in each supported scheme, including focus, hover, and non-text UI.

Before and after

This page has light and dark styles in /styles.css but never declares its schemes. The browser keeps its own canvas, form controls and scrollbars on light defaults, and Safari's Adaptive Dark Mode has to analyse the page instead of being told:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Orders — example.com</title>
  <link rel="stylesheet" href="/styles.css">
</head>
<body>
  <h1>Orders</h1>
</body>
</html>

Declare both schemes up front, in markup, in first-paint CSS, or both:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta name="color-scheme" content="light dark">
  <title>Orders — example.com</title>
  <style>
    :root { color-scheme: light dark; }
  </style>
  <link rel="stylesheet" href="/styles.css">
</head>
<body>
  <h1>Orders</h1>
</body>
</html>

light dark tells supporting browsers, including Safari Adaptive Dark Mode, that both appearances are intentional. Only declare dark when you ship an authored dark appearance (prefers-color-scheme, light-dark() or an explicit theme). Otherwise the browser's dark canvas, form controls and system colors can clash with colors you authored for light. Then re-check contrast in that appearance. This snippet does not ship a theme switcher, token files, or a full dark palette.

Do this instead

Put <meta name="color-scheme" content="light dark"> in the document head, and/or color-scheme: light dark on :root (WebKit also accepts body) in CSS that applies on first paint, such as a <style> in the head, so the browser has it before the first render and before any theme script runs. Only the root element's scheme sets the page canvas, so prefer :root
Use light dark when you support both. Use light only (and the matching meta value) only when a surface must stay light; it is a narrow opt-out, not the default
Do not rely on light only as an opt-out until you've confirmed it works in each browser in your matrix. Browsers have parsed only for years, and MDN notes Chrome's Auto Dark Theme respects it. But WebKit says Safari 27.3 beta 1's Adaptive Dark Mode did not support it, so it wasn't a working opt-out there
Re-check contrast for text, focus, hover, and non-text UI in every scheme you declare. Measure authored colors; a browser repaint that computed styles cannot see is not that measurement
When Safari is in your matrix, keep a visual record (screenshot or equivalent) of Adaptive Dark Mode cases. The HIG requires reviewers to capture these. Automated contrast on computed styles can stay green while the painted page fails
If the product adds a theme control later, keep the document-level declaration honest about the schemes you actually support

Quick check for your app

Open example.com and a second key page at a phone width. View source or the Accessibility/Elements panel and confirm a color-scheme meta tag or first-paint CSS declaration before any theme script. Toggle the OS appearance and, where you support Safari Adaptive Dark Mode, capture light pages with and without the declaration. Compare authored computed colors with what you see painted. Suitable automated checks can catch a missing declaration and authored contrast regressions; they do not prove how Adaptive Dark Mode paints. Pair them with a visual check on the browsers your audience uses.

The Web HIG is an open set of guidelines for how the web should behave, not a component library. Design systems define how it looks. The Web HIG defines how it behaves.

Your AI agent reused the wrong kind of screen. Name the experience purpose.

FrozonFreak — Fri, 13 Nov 2026 06:07:54 +0000

Say you ask your AI agent for a staff check-in screen at example.com. It returns a wide editorial layout, a large heading, and a single "Get started" button. You ask for a member briefing instead, and the next result is a dense table with bulk actions.

The agent reused a familiar pattern from a different kind of work.

Design Decision Method's agent procedure asks the agent to identify the experience purpose before it decides how a screen should look and behave. The live docs already use that idea in an illustration: a short request is not operational monitoring. The procedure is more specific. It names six purposes: operational work, reading and storytelling, exploration, evaluation and purchase, creation and editing, and participation and collaboration. Mixed-purpose products can use a different approach per flow.

What follows are four short, fictional illustrations on example.com. They are not case studies, and they do not report measured results.

Operational work

A staff tool for checking people into today's workshop. The job is to find a name, mark attendance, and undo a mistake.

The procedure's purpose reference treats operational work as a heuristic, not a mandatory template. It points to stable placement, visible state, fast entry, and reversible actions. A magazine-style page that hides the current list is the wrong import. So is a decorative metric row that does not help someone complete the check-in.

Reading and storytelling

A monthly member briefing: a short article with a clear reading order, headings, and a path into a longer report.

Here the priorities shift. The reference talks about reading order, pacing, and routes into deeper content. The procedure also says that reading or exploration need not end in a transaction or a single primary button. A checkout-shaped page, or a dashboard of tiles, imports another domain's conventions. The briefing can simply be readable on a phone.

Evaluation and purchase

A flow to buy a workshop ticket, with a date, a concession option, the total cost, and the cancellation terms.

For evaluation and purchase, the reference asks for suitability, variations, availability, total cost, terms, and an informed commitment — plus a way to correct the order. A dense admin table that buries the price is not that job. Neither is a long story page that never states what the buyer is committing to. Acceptance in this flow is about an informed choice, not about finishing a staff task.

AI as a capability, not a new purpose

example.com also has a small helper that drafts a workshop description. Because that AI feature already exists, the procedure says to apply AI checks only there: say what the helper can do and where it is limited, separate generating a draft from publishing it, and do not show fabricated confidence figures.

If the product had no AI feature, the rule is simpler: do not add AI controls. The purpose reference is just as plain: treat AI as a capability within a purpose, not a reason to replace every interface with chat. The ticket flow should stay a ticket flow.

Why this matters

Agents are good at completing a pattern they have seen. They are less good at noticing that the pattern belongs to another job. The procedure warns against importing one domain's conventions into another — an operations dashboard for a site that needed a readable page, for example.

Establish context is where purpose belongs, alongside audience, frequency, mistake cost, and device. Later, deliver and validate asks for acceptance criteria matched to that purpose: task execution in the check-in tool, comprehension in the briefing, informed purchase in the ticket flow.

The method does not claim this saves time. That has not been measured. It also does not guarantee a good result. What it gives you is a place to catch a borrowed layout before it hardens.

Try it

Design Decision Method is a lightweight design decision workflow for developers building interfaces with AI agents. It follows the open Agent Skills format and is MIT licensed. Install paths for Claude Code, Cursor, Gemini CLI, and Codex are in the README.

Six short notes before your AI agent builds a screen

FrozonFreak — Mon, 09 Nov 2026 16:30:22 +0000

You ask your AI agent for a small change: let someone snooze a reminder on example.com. Without a shared procedure, the reply can grow into controls nobody asked for.

Design Decision Method is six steps. For a small change, the notes can stay short. This walkthrough takes one fictional feature through all six as light notes — not a case study, not a measured result, and not a claim about every agent.

The product details below are invented for the illustration.

The brief

example.com already has reminders with a title, a due time, and a done action. You want snooze on the existing reminder detail view: one hour, tomorrow morning, or a time the person picks. No new navigation. No new object types.

1. Establish context

Audience: People who already use reminders on their phone.
Task / frequency: Snooze an upcoming reminder; occasional.
Cost of a mistake: Medium — a bad snooze can make someone miss a follow-up.
Device: Phone first.
Known: Title, due time, and done already exist. There is no calendar product.
Assumed (marked): Quiet hours were not requested, so none are designed.

Enough for establish context: who it is for, how often it happens, what a mistake costs, and what the product already has.

2. Choose the visual system

Keep the project's existing components and tokens. This change adds snooze actions; it does not introduce a new visual identity.

One line is enough when a system already exists. Choose the visual system starts there.

3. Object map — run the gate

The docs ask for a map when relationships would change the navigation, the routes, or the structure of the screen. Skip the map when the change does not depend on those relationships, such as a copy edit or a restyle that leaves the structure alone.

The agent procedure records the gate in one line:

Map: skipped — snooze adds actions on an existing reminder detail view. No new object types, no new routes, and navigation is unchanged.

When relationships would reshape the screen, map objects before layout. When they would not, do not invent a map for theatre.

4. Decision record

One consequential choice:

Decision: Three snooze presets (1 hour, tomorrow morning, pick a time). Presets first; custom time secondary.
Frequency / familiarity: Occasional; snooze is already familiar elsewhere.
Error cost: Medium if the new time is unclear.
Device: Phone.
Why: Presets cover common cases with less entry effort than opening a full picker every time.
Assumption: "Tomorrow morning" means 09:00 in the person's local timezone — marked, not smuggled in as an unmarked product rule.

A decision record is for choices that are costly to undo, not for every spacing tweak.

5. Structure each view

Purpose: Delay one reminder without opening a separate settings flow.
Information to decide: Reminder title, current due time, and the new time.
Actions: Snooze 1 hour; until tomorrow morning; pick a time; cancel.
States: Loading while saving; error if save fails (keep the reminder identity visible); success shows the new time on the detail view.
Device: Presets and cancel stay available on a narrow screen.

Structure each view before the chrome.

6. Deliver and validate

Delivered: Snooze actions on reminder detail (code), plus the notes above.
Acceptance / evidence:

Choosing "1 hour" updates the due time. Manual test on one phone-sized viewport.

Custom time rejects empty input and keeps the previous due time visible. Heuristic review of the flow only.

Contrast on the snooze actions. Automated check on the colours used — not a claim about the whole product.

People finish snooze without help. Proposed. Not tested. No user research. Not tested: screen reader pass, offline behaviour, other timezones beyond the marked assumption.

Deliver and validate labels what each result rests on and says what was not tested. Nothing above invents a measurement.

Keep it light

Six steps, still light: short context, a one-line visual keep, a skipped map with a reason, one decision, a compact view note, and an honest handoff. The method is a shared procedure, not mandatory for every small edit. It does not claim this saves time — that has not been measured. What it gives you is a trail of decisions the next prompt can reuse.

Try it

Did Place order work? Show the pending state (Web HIG tip #16)

FrozonFreak — Sun, 08 Nov 2026 09:50:26 +0000

Someone taps Place order on a slow connection. Nothing changes on screen. Did the tap register? Should they try again? A missing pending state leaves them guessing. If repeat requests reach an unprotected endpoint, that uncertainty can also become a duplicate order.

Web HIG tip #16 (Quick #45): Server mutations must show pending UI immediately — disable submit, show spinner.

Why it matters

A request in flight is invisible unless the interface makes it visible. Without that signal:

People can't tell a slow request from a tap that didn't register, so they tap again
Each extra tap can become another order, payment, invite or post
Keyboard users can face the same uncertainty; Enter can submit a form, depending on its controls and platform conventions
If the page looks frozen, some people reload or leave halfway through

The full HIG covers this in §4.2, Async Mutation & Server Action State Model: forms executing server mutations MUST supply immediate visual feedback without waiting for server response round-trips. Quick #47 adds that critical mutations should be idempotent. §4.5 says important mutations SHOULD use idempotency keys at the product/API layer. That protects the intended effect of an operation when requests repeat; it does not guarantee a single network request.

Before and after

This bare native POST form has no application-specific pending feedback. The browser may show navigation progress, but the button does not explain what is happening:

<form action="https://example.com/orders" method="post" id="checkout">
  <button type="submit">Place order</button>
</form>

Here is a client-side pending-state illustration, not a complete checkout. It keeps native POST navigation and assumes this is the form's only submission handler. It disables the single submit button and guards against later submit events while pending:

<form action="https://example.com/orders" method="post" id="checkout">
  <!-- Order fields and server-side security protections are omitted. -->
  <button type="submit">
    <span id="checkout-spinner" class="spinner" hidden aria-hidden="true"></span>
    <span id="checkout-label">Place order</span>
  </button>
  <p role="status" id="checkout-status"></p>
</form>

<style>
  .spinner:not([hidden]) {
    display: inline-block;
    width: 0.8em;
    height: 0.8em;
    border: 2px solid currentColor;
    border-inline-end-color: transparent;
    border-radius: 50%;
    animation: spin 1s linear infinite;
  }
  @keyframes spin { to { transform: rotate(360deg); } }
  @media (prefers-reduced-motion: reduce) {
    .spinner:not([hidden]) { animation: none; }
  }
</style>

<script>
  const form = document.getElementById('checkout');
  const button = form.querySelector('button[type="submit"]');
  const label = document.getElementById('checkout-label');
  const spinner = document.getElementById('checkout-spinner');
  const status = document.getElementById('checkout-status');
  let submitting = false;

  function resetPending() {
    submitting = false;
    button.disabled = false;
    label.textContent = 'Place order';
    spinner.hidden = true;
    status.textContent = '';
  }

  resetPending();
  form.addEventListener('submit', (event) => {
    if (event.defaultPrevented) return;
    if (submitting) {
      event.preventDefault();
      return;
    }
    submitting = true;
    button.disabled = true;
    label.textContent = 'Placing order…';
    spinner.hidden = false;
    status.textContent = 'Placing your order…';
    // Let this first submission continue as a native POST navigation.
  });

  window.addEventListener('pageshow', (event) => {
    if (event.persisted) resetPending();
  });
</script>

The handler updates the label, spinner and status text synchronously, before waiting for a response. A fast navigation may replace the page before that feedback is painted or announced. role="status" is a polite live region, not a promise that a screen reader will speak before navigation.

The guard covers only later submit events on this page while its flag is set. A direct form.submit() call bypasses that event. Other tabs, reloads and retries remain outside its scope. The pageshow handler resets the UI when this document returns from the back/forward cache; it does not establish whether an order succeeded.

This snippet does not handle a blocked or cancelled navigation, an in-page request failure, or a successful order response. A real flow needs outcome and recovery UI, preserved input, and server-side validation and security protections. Do not drop this handler into a framework-managed form without adapting it to that form's lifecycle.

A hidden input named idempotency_key would not solve duplication by itself. The server must implement deduplication, including concurrent requests, and bind a key to the same intended operation and authorised caller. Reuse that key for retries of that operation, not unrelated new orders; define payload checks and expiry. If a response is lost, do not assume the order failed. Check its outcome before starting another order. Those server and recovery pieces are outside this example.

Do this instead

Update pending feedback in the submission handler, without waiting for the network: disable the submit trigger, show an inline pending indicator, and keep a meaningful label such as "Saving…" or "Sending…"
Keep the label meaningful. A spinner alone tells people something is happening, not what
Show a clear result. For in-page requests, leave pending state when the outcome is known; on a recoverable failure, restore usable controls and preserve the input
For native navigation, provide a usable result or error page and a safe route back. A connection failure can leave the outcome unknown: offer a way to check it rather than blindly retrying
Don't rely on the disabled button alone. Important mutations need server-side repeat-request protection; a key only helps when the endpoint actually enforces it
If your framework exposes submission state, use its documented pending and recovery lifecycle, and test that feedback does not wait for the server response

Quick check for your app

Use a test environment, not a real payment or production invite. Slow down the response and check that the label and pending indicator update without waiting for it. Try repeated clicks and, where supported, Enter submission. Inspect the network, but also verify the server-side result: deliberately repeated requests for the same operation should not create duplicate orders. Test concurrent requests too.

Exercise validation failures, lost responses, recoverable errors, Back navigation and a retry of the same operation. Check keyboard use, reduced motion and screen-reader feedback; for native navigation, inspect the destination page as well as the pending state. Suitable automated browser and server tests can catch these problems. Pair them with manual checks on the browsers and assistive technology your audience uses. A green suite is evidence for what it actually exercised, not proof that every failure path works.

The Web HIG is an open set of guidelines for how the web should behave, not a component library. Design systems define how it looks. The Web HIG defines how it behaves.

Your AI agent added a feature. Why did it redesign the buttons?

FrozonFreak — Sun, 08 Nov 2026 09:50:00 +0000

You ask your AI agent to add an invoice filter to an existing product. The new screen comes back with pill-shaped buttons, a different type scale, and a new accent colour. The rest of the product still uses square buttons and the original tokens.

You wanted a filter. You got a second visual direction.

That is the problem this illustration starts with, not a claim about every agent. Design Decision Method's second step, choose the visual system, gives the agent a place to check what already exists before proposing something else.

Keep the system the project has

The live docs put the starting point plainly: keep a system the project already has. When it has none, select from the platform.

The agent procedure adds an important qualification: retain and extend a suitable existing system, brand, or platform direction, and verify its actual tokens, components, and supported versions. If the brief explicitly requests a different direction, assess that request first, including accessibility and platform constraints, migration scope, and consequential conflicts.

So this is not a rule against redesign. It is a rule against treating an ordinary feature request as permission to redesign.

A worked example: invoice filters on example.com

Imagine a small invoicing product at example.com. It already has an in-house component library, named colour roles, and a documented type scale. You ask for a filter that lets customers show unpaid invoices.

This is a fictional illustration, not a case study or a measured result. The product details and the following note are invented for the example.

Before building, the agent's note could read:

Existing direction: Keep the product's in-house system. This request adds filtering, not a new visual identity.

Reuse: Use the existing button and select components, the established text styles, and the project's colour roles. Check their definitions and supported states rather than recreating them from a screenshot.

Interaction need: Let someone choose an invoice status and clear the filter. If outside guidance helps with that interaction, adapt the behaviour into the existing components rather than importing another visual identity.

Gap: If a needed state is missing from the component library, flag it and propose an extension. Do not silently introduce a second button family.

Now the review has something concrete to compare against. Did the implementation use the existing components? Is a new style an intentional extension or an unexplained replacement? A polished screenshot alone cannot answer those questions.

An interaction pattern is not a brand

Choosing the visual system and borrowing an interaction pattern are separate decisions in DDM.

A filtering pattern might help organise choices. That does not mean the page needs the source system's colours, typography, or branding. The procedure says to borrow patterns when they solve the task, not to mix competing visual identities on one surface.

In the invoice example, an outside pattern would need a specific reason to be used. It is not a reason to replace the product's visual language. The question is what the interaction helps someone do, then how to express it within the system already chosen.

What if there is no system?

Then the platform matters. DDM's procedure gives selection rules rather than asking the agent to pick a favourite. For other web or cross-platform work with no system, it names Material 3 as the fallback, with implementation support checked.

That is a conditional fallback, not a ranking of design systems or an instruction to replace an existing one. The procedure also recognises documented bespoke or editorial direction. Use the applicable row, and check what the project's stack actually supports.

The accompanying reference asks the agent to inspect tokens, components, screenshots, and installed dependencies. Those are clues to investigate, not substitutes for understanding the project's visual decisions.

Try it

Choose the visual system is step 2 of DDM's six-step workflow. For your next feature request, ask the agent to identify the existing system, what it will reuse, and any gaps before it proposes new styling.

Design Decision Method is a lightweight design decision workflow for developers building interfaces with AI agents. It follows the open Agent Skills format and is MIT licensed. The README documents installation for Claude Code, Cursor, Gemini CLI, and Codex.

Your AI agent draws a pretty layout. Make it structure the view first.

FrozonFreak — Fri, 06 Nov 2026 05:10:02 +0000

You ask your AI agent for an order status page. It returns a polished card grid, a sparkline you never asked for, and a primary button that says "Explore insights." The status sits in the middle. There is no empty state. Error is a toast that vanishes. On a phone, cancel is gone.

The screen looks finished. The view was never defined.

Design Decision Method's fifth step is there to stop that. Step 5, structure each view, asks the agent to say what the view is for, what information people need to decide, which actions matter, and which states exist — before it invents a layout.

What step 5 asks for

For each important view, the method asks the agent to state:

its purpose
the information required to decide
the actions
the states that apply, including loading, empty, and error where they exist

It also asks the agent to keep essential information visible, and to adapt the layout to the device without dropping a capability the task needs.

That is the whole fifth step. A short definition of the view's job, then a layout that still does that job on a phone.

A worked example: order status on example.com

Say you run a small shop at example.com, and you ask your agent for the order status page. This is an illustration of how the procedure applies, not a case study or a measured result.

Without the method, the agent jumps to a familiar pattern: a dashboard-shaped page with charts, because status pages elsewhere often look like that. The order identity is secondary. Loading is a spinner with no context. Empty and error are afterthoughts.

With step 5 filled in first, the note might look like this:

Purpose: Show where one order is, what happens next, and what the customer can do about it.

Information required to decide: Order id, current status, last update, next step, items, and a path to support.

Actions: Track shipment (when a carrier link exists). Cancel while still allowed. Contact support. Back to orders.

States: Loading keeps the order context. Empty says this id has no order and offers a path back. Error keeps the order id visible and offers retry and support. The success path makes status and next step readable without a chart.

Device: Phone first. Cancel and support stay available; do not hide them behind a hover-only control.

Now the sparkline has nowhere to hide. "Explore insights" is out of scope. The layout still has to answer the purpose, surface the decision information, expose the actions, and cover the states.

Purpose before chrome

Agents are good at completing a visual pattern. They are less good at noticing that the pattern belongs to a different job. A monitoring dashboard and an order status page can both show numbers. Only one helps someone decide what to do about a single order.

Write the purpose first and the mismatch is obvious. Decorative metrics need a reason or they stay out. Essential information — status, next step, recovery — stays visible instead of being trimmed for whitespace.

Why this matters when you build with agents

A pretty first draft is easy to accept. The missing pieces are usually the ones that hurt later: empty, error, and the action that disappeared on a narrow viewport.

Structure each view puts those pieces in the first note. You can reject a layout that drops cancel on mobile, or never defines what happens when the order id is wrong.

The method does not claim this saves time. That has not been measured. What it does give you is a view definition you can check before the chrome hardens.

Keep it proportional

A one-line copy fix does not need a full view note. The method is a shared procedure, not mandatory for every small edit. When the change adds a screen, changes what people must see to decide, or could hide an action on a smaller device, spend the few lines.

Earlier steps give you context, a map when relationships matter, and a decision record for costly choices. Step 5 structures the views those decisions imply, instead of starting from a stock layout again.

Where this fits

Structure each view is step 5 of six: establish context, choose the visual system, map objects before layout, write a decision record, structure each view, then deliver and validate.

Try it

Docs: https://frozonfreak.github.io/DesignDecesionMethod/
Repo: https://github.com/frozonfreak/DesignDecesionMethod
Design record template: https://github.com/frozonfreak/DesignDecesionMethod/blob/main/assets/design-record-template.md

Don't lazy-load the image people see first (Web HIG tip #15)

FrozonFreak — Fri, 06 Nov 2026 05:09:51 +0000

Open your home page or a product page on a phone, on a slow connection. The headline and buttons show up, but the big hero image stays blank for a beat longer than everything else. Look at its markup and you'll often find loading="lazy", added to every <img> on the site by a template, a plugin, or a well-meant "lazy-load all images" change.

Web HIG tip #15 (Quick #84): Lazy-load below-the-fold media; never lazy-load the LCP candidate.

Why it matters

Lazy loading is a trade: the browser waits to fetch an image until it's close to the viewport. That's a win for images further down the page, and a loss for the one people see first:

Images far below the fold that nobody scrolls to never download, which saves data and leaves bandwidth for what's on screen
A lazy image's fetch can't start until the browser has laid out the page and worked out where the image sits, so a lazy hero image starts downloading later than it would have otherwise
The LCP candidate is usually the biggest image or text block in the first view. When it arrives late, the page looks unfinished, and Largest Contentful Paint gets worse
If the image URL only exists in JavaScript, for example a data-src that a script swaps in, the browser can't find it in the HTML at all until that script runs

The full HIG covers the image side of this in §2.1, Document Fundamentals, under responsive images: lazy-load non-critical images where appropriate, and avoid lazy-loading the LCP candidate and other immediately needed content. The LCP candidate SHOULD be discoverable early and MAY use fetchpriority="high" when appropriate. Quick #84 is Quick-only guidance, with no rule ID of its own. It pairs with Quick #83, which asks every image to declare its dimensions or aspect ratio, and with Quick #82's LCP target of 2.5 s or less.

The rule of thumb

Ask: will this image be on screen before anyone scrolls? If yes, don't lazy-load it.

This page looks fine on a fast laptop, but the hero waits for layout and for a script before it even starts downloading:

<!-- Hero: the LCP candidate, hidden from the browser until JS runs -->
<img class="lazy" data-src="https://example.com/img/hero.jpg" alt="">

<!-- Further down the page -->
<img src="https://example.com/img/team.jpg" alt="The team at the spring meetup">

Load the hero early and lazy-load what's further down:

<!-- Hero: a real src in the HTML, high priority, not lazy -->
<img src="https://example.com/img/hero.jpg"
     width="1200" height="600"
     fetchpriority="high"
     alt="A reader using the app on a phone">

<!-- Further down the page -->
<img src="https://example.com/img/team.jpg"
     width="800" height="533"
     loading="lazy"
     alt="The team at the spring meetup">

The page looks the same. The difference is when each image starts downloading.

Do this instead

Leave loading off the LCP image (the default is eager), give it a real src or srcset in the HTML, and consider fetchpriority="high". Browsers that don't support fetchpriority ignore it
Add loading="lazy" to images and iframes that sit well below the first view: long article bodies, comment sections, footers, embedded maps and video players
For a <video> further down the page, use preload="none" (or "metadata") and a poster image. loading="lazy" on <video> is newly specified but only some browsers support it so far, so treat it as a bonus, not the fix
In a carousel or gallery, load the first slide eagerly and lazy-load the rest
Give lazy images width and height (or a CSS aspect-ratio) so the page doesn't jump when they arrive
If the hero is a CSS background-image, the browser only finds it after the CSS has loaded. Use an <img> instead, or add <link rel="preload" as="image"> for it
The LCP element can be different on a phone and on a desktop. Check both layouts before you decide which images stay eager

Quick check for your app

Open your main pages (say, example.com and example.com/products) at a phone width and at a desktop width. In the browser's developer tools, find the LCP element in a performance recording, then check its markup: no loading="lazy", and a URL that's in the HTML rather than added by a script. Scroll down and watch the network panel: images further down should only start loading as you get near them. A tool can flag a lazy-loaded LCP image in a single lab run, but only checking the real LCP element on your own pages, at the widths people use, shows which image needs to load first.

The Web HIG is an open set of guidelines for how the web should behave, not a component library. Design systems define how it looks. The Web HIG defines how it behaves.

Your AI agent invents product rules. Make it establish context first.

FrozonFreak — Thu, 05 Nov 2026 05:44:41 +0000

You ask your AI agent for an account settings screen. It returns a grid of cards, a dark-mode toggle you never mentioned, and a "delete account" control sitting next to a harmless preference. You push back. The next prompt invents a different layout, and a social-login switch the product does not have.

The agent filled gaps. It treated guesses as product rules.

Design Decision Method's first step is there to stop that. Step 1, establish context, asks the agent to read the brief and the product you already have before it decides anything about layout.

What step 1 asks for

The method asks the agent to name:

the audience
how often the task happens
what a mistake costs
the device

It also asks the agent to keep what it knows separate from what it assumes, and not to invent rules or capabilities the product lacks.

That is the whole first step. No wireframe yet. No colour palette. A short read of the brief and the existing product, then an honest list of facts and assumptions.

A worked example: account settings on example.com

Say you run a small product at example.com, and you ask your agent for the account settings screen. This is an illustration of how the procedure applies, not a case study or a measured result.

Without the method, the agent invents. It adds toggles, cards, and a delete path because those are familiar from other products.

With step 1 filled in first, the note might look like this:

Audience: Account holders who manage their own profile. Mostly people who signed up themselves.

Task and frequency: Change email or password occasionally. Review notification preferences rarely. Delete the account almost never.

Cost of a mistake: Medium for email or password (lockout or missed mail). High for delete or billing changes.

Device: Phone first; desktop second.

Known: The product has email, password, and three notification toggles. There is no social login. There is no team account.

Assumptions (marked): Offline use was not requested, so none is designed. Billing settings live elsewhere; this screen does not invent them.

Now the agent has somewhere to stop inventing. A dark-mode switch that was never in the product stays out. A delete control does not sit next to a low-cost preference just because other apps do that. Optional additions get labelled instead of smuggled in as facts.

Known versus assumed

The useful part is the split. "Known" comes from the brief, the code, or a screen you already have. "Assumed" is everything else, and it stays marked.

If the agent cannot ask about a gap that would change the design, list the assumption in the deliverable instead of quietly filling it. You can confirm, correct, or reject the guess before layout hardens around it.

Why this matters when you build with agents

Agents are good at completing patterns. They are less good at noticing that your product never offered the pattern. The screen looks finished, and the invented parts are hard to spot until you click them.

Establish context makes the first deliverable a short statement of who the screen is for, how often people use it, what a mistake costs, and which device they are on. Later steps build on that statement. Without it, they decorate a guess.

The method does not claim this saves time. That has not been measured. What it does give you is a place to catch invented rules before they become UI.

Keep it proportional

A small copy change does not need a long context note. The method is a shared procedure, not mandatory for every small edit. When the change could invent a capability, bury a costly action, or import another domain's conventions, spend the few lines.

The design record template has a short Context section for this: audience and roles, primary tasks and frequency, cost of error, device, known facts, and assumptions. Use as much of it as the change needs.

Where this fits

Establish context is step 1 of six: establish context, choose the visual system, map objects before layout, write a decision record, structure each view, then deliver and validate.

Try it

Docs: https://frozonfreak.github.io/DesignDecesionMethod/
Repo: https://github.com/frozonfreak/DesignDecesionMethod
Design record template: https://github.com/frozonfreak/DesignDecesionMethod/blob/main/assets/design-record-template.md

"Done" isn't a test result. How your AI agent should hand off UI work

FrozonFreak — Wed, 04 Nov 2026 05:16:10 +0000

Your AI agent finishes a change and reports back: "Done. The form is accessible, responsive and works on mobile."

Did anyone check? Often the agent wrote the code, looked at it, and described what it hoped was true as if it had been tested.

Design Decision Method's last step is there to stop that. Step 6, deliver and validate, asks the agent to hand over the work, the decisions behind it, and a short validation status that says what each result rests on.

What step 6 asks for

The method asks the agent to deliver three things:

the requested artifact (spec, mockup, prototype, or code)
the consequential decisions and assumptions
a short validation status

Before validating, the agent defines a few observable acceptance criteria matched to the purpose of the experience. Then it labels each result by its evidence level and says what it did not test.

Five evidence labels

Each label says what a result can support and what it can't:

Level	Can support	Cannot support
Proposed	A target to aim for	Any claim about the result
Heuristic review	Likely problems, effort comparisons	Task-completion rates
Automated check	Specific rule failures	Overall accessibility or usability
Manual test	Behaviour of a flow, keyboard and focus	Population-level outcomes
User research	Real task outcomes for the sampled users	Claims beyond the sample

Two rules come with it. Never fabricate a measurement. If something wasn't tested, the record says "not tested". And a mockup can show routes and states, but it cannot establish task-completion rates.

A worked example: a handoff note

Say you ask your agent to rebuild the sign-up form on example.com. It's one page with name, email and password, and a clear way to fix errors.

Without the method, the handoff is the sentence at the top of this post. With it, the agent's note might read:

Delivered: Sign-up form (code). One page, three fields.

Decisions: Errors show next to the field and in a summary at the top. Entered values are kept after an error. The placeholder for email is name@example.com.

Assumptions: No social sign-in was requested, so none was added.

Acceptance criteria and status:

Valid entries survive a validation error. Manual test: submitted with a bad password, and name and email were still filled in.

Each error is announced next to its field. Heuristic review of the markup only. Not tested with a screen reader.

Text and background contrast. Automated check: the contrast check found no failures on the colours used. This does not show the whole form is accessible.

People complete sign-up without help. Proposed. Not tested. No user research was done.

Not tested: screen reader pass, mobile keyboard behaviour, the server's error responses.

Every line says what it rests on. You can see that mobile keyboard behaviour is the next check, and that nobody has tried the form with real users.

Why this matters when you build with agents

An agent that sounds confident is easy to trust. The evidence labels give you a quick way to read the handoff. "Proposed" means it hasn't been checked. "Automated check" means one rule ran. "Manual test" means somebody actually walked through the flow.

The list of untested items also gives you the next prompt: ask for exactly those checks.

The method doesn't claim this saves time. That hasn't been measured. What it does give you is a handoff note that says where its checks stop.

Keep it proportional

Pick a few criteria that fit the design. The method warns against a fixed score or a universal time or click limit. A copy fix might need one line of status. A new checkout flow needs more. The design record template has a short "Validation status" section for this: the evidence levels reached, what was tested and what wasn't, and open questions.

Where this fits

Deliver and validate is step 6 of six: establish context, choose the visual system, map objects before layout, write a decision record, structure each view, then deliver and validate.

Try it

Docs: https://frozonfreak.github.io/DesignDecesionMethod/
Repo: https://github.com/frozonfreak/DesignDecesionMethod
Evidence levels and record format: https://github.com/frozonfreak/DesignDecesionMethod/blob/main/references/acceptance-and-validation.md
Design record template: https://github.com/frozonfreak/DesignDecesionMethod/blob/main/assets/design-record-template.md

Your AI agent forgets why. Give it a decision record

FrozonFreak — Wed, 04 Nov 2026 05:10:36 +0000

You spend a session getting an order form right. One page, not three steps. A review summary before submit. Delivery date where people actually look for it. Then a new prompt regenerates the form, and the agent goes back to a three-step wizard, because nothing told it why you chose otherwise.

The agent kept the code. It did not keep the reasons.

Design Decision Method handles this with step 4 of its workflow: the decision record.

What a decision record captures

For a choice that would be costly to undo, the method asks you (or your agent) to record:

task frequency
user familiarity
the cost of a mistake
the device
the pattern chosen, and why

It also asks you to judge effort in a specific way: compare the effort to read, remember, enter, navigate, and recover, rather than counting clicks or visible elements. A three-step flow has fewer fields per screen. That does not make it less effort if people have to go back to check what they entered on step one.

Two more rules keep the record honest:

Cite a source only when it resolves an actual design problem. No decorative references.
Mark departures. When the design departs from a cited source's rule, add one adaptation line: source rule / what this design does instead / why the frequency, familiarity, or error cost requires it. Never present an adaptation as upstream guidance.

A worked example

Say you run a small print shop at example.com, and you ask your agent to build the order form. This is an illustration of how the procedure applies, not a case study or a measured result.

The decision row looks like this:

Decision	Frequency	Familiarity	Error cost	Device	Pattern chosen	Reason
Order form layout	Occasional, once per order	Mostly first-time customers	Medium: a wrong size or quantity means a reprint	Phone first	One page, grouped sections, review summary before submit	Customers need to see size, quantity, and price together to catch mistakes. Splitting them across steps adds recall effort at the point of decision.

If a source you cite recommends a different pattern for this form, that is where an adaptation line goes, in the same three-part form.

The record also carries a short validation status, because step 6 of the method asks for an honest evidence label on each result: proposed, heuristic review, automated check, manual test, or user research. For this form it might read:

Valid entries survive a validation error: not tested (manual test planned).
Size, quantity, and price visible together before submit: heuristic review.

Untested stays untested. The record says so instead of implying the form works.

What the next prompt does with it

Next week you ask the agent to add a "rush delivery" option. The following prompt starts from that record. The agent can see the form is one page for a reason, and that the reason is error cost, not taste. It adds the option inside the existing structure instead of reinventing the flow.

A person still checks the result. The method does not measure how many prompts that removes, and whether it saves time has not been measured.

Keep it small

The decision record is proportional. A small change gets a few lines. The repo's design record template is a scaffold, not mandatory overhead. Save the record with the work (as docs/design/<slug>.md) when your project keeps design records, or deliver a compact record inline with the change when it does not.

You do not need a record for every edit either. The method is a shared procedure, not mandatory for every small edit. Record the choices you would be annoyed to re-argue.

Where this fits

The decision record is step 4 of six: establish context, choose the visual system, map objects before layout, write a decision record, structure each view, then deliver and validate.

Try it

Docs: https://frozonfreak.github.io/DesignDecesionMethod/
Repo: https://github.com/frozonfreak/DesignDecesionMethod
Design record template: https://github.com/frozonfreak/DesignDecesionMethod/blob/main/assets/design-record-template.md

Tell the browser what each field is for (Web HIG tip #14)

FrozonFreak — Sun, 01 Nov 2026 08:48:20 +0000

Open your checkout or sign-up form on a phone and tap the email field. If the keyboard has no @ key, or the browser offers nothing to fill in, the form isn't telling the browser what it's asking for. Now try the phone number, the postcode, and the password. Every field that makes someone type by hand is one more chance for a typo or for them to give up.

Web HIG tip #14 (Quick #52): Use native input types and autocomplete attributes appropriate to the field purpose.

Why it matters

The browser already knows a lot about the person using it. It just needs to know which field is which:

type="email", type="tel", and type="url" bring up a keyboard suited to the field on most phones, so nobody has to hunt for @, digits, or a slash
autocomplete tokens let the browser offer the saved name, email, address, or card, so one tap can replace a whole block of typing
Password managers use autocomplete="current-password" and "new-password" as the clearest signal of whether to fill a saved password or offer a new one
People with motor or cognitive disabilities, and anyone on a small screen, gain the most from typing less

The full HIG covers this in §2.11, Forms Contract. Three rows of its table apply here. Autocomplete: use appropriate autocomplete tokens for common fields (name, email, address, cc-*). Password managers: do not block autofill, and use standard input types with autocomplete="current-password" / "new-password". Input types: use semantic types (email, tel, url, number) for mobile keyboard optimization. Quick #52 is Quick-only guidance, with no separate rule ID, and it pairs with Quick #50: every field still needs a visible label.

Author's note, not part of the HIG: WCAG 2.2 SC 1.3.5 Identify Input Purpose (Level AA) asks that fields collecting information about the user expose their purpose in code, for the purposes listed in WCAG section 7. The matching autocomplete tokens are the usual way to do that. one-time-code isn't on that list.

The rule of thumb

Ask: if the browser only had this markup, would it know what each field is for?

This form looks fine, but the browser sees three anonymous text boxes:

<label for="f1">Email</label>
<input id="f1" name="f1" type="text" autocomplete="off">

<label for="f2">Phone</label>
<input id="f2" name="f2" type="text">

<label for="f3">Password</label>
<input id="f3" name="f3" type="password" autocomplete="off">

Name the purpose and the browser does the rest:

<label for="email">Email</label>
<input id="email" name="email" type="email" autocomplete="email"
       placeholder="name@example.com">

<label for="phone">Phone</label>
<input id="phone" name="phone" type="tel" autocomplete="tel">

<label for="password">Password</label>
<input id="password" name="password" type="password"
       autocomplete="new-password">

The labels and layout don't change. The keyboard does, and so does what the browser offers to fill.

Do this instead

Pick the type from what the field holds: email, tel, url, search, password. Use type="number" only for real quantities you might step up or down. For digit strings that aren't numbers, such as card numbers, security codes and one-time codes, use type="text" with inputmode="numeric" and the matching autocomplete token (cc-number, cc-csc, one-time-code). Add pattern only when you also show a clear error message. Use inputmode="numeric" for a postcode only if every postcode you accept is digits-only
Add an autocomplete token to every field about the user: name, email, tel, address-line1, postal-code, country, cc-number, cc-exp, cc-csc, username. Sign-in codes get one-time-code
Use current-password on sign-in and new-password on sign-up and password change, so password managers fill or generate correctly
Don't set autocomplete="off" to stop autofill on these fields. Browsers often ignore it on sign-in fields anyway. Keep off for values that are never reused or where a saved suggestion would be wrong, such as a CAPTCHA answer, an in-app search or combobox that shows its own suggestions, or a one-off confirmation code. For a one-time sign-in code, use one-time-code so the phone can fill it from the SMS. On a form where an admin sets someone else's password, use new-password, not off
If a form asks for two addresses, prefix the tokens: shipping address-line1 and billing address-line1, shipping postal-code and billing postal-code. (street-address is for a single multi-line <textarea>.) For more than one shipping address, put a section- token first, e.g. section-gift shipping postal-code

Quick check for your app

Open your sign-up, sign-in, and checkout forms (say, example.com/checkout) on a real phone. Tap each field: the keyboard should match it, with @ for email and a keypad for phone and codes. Then let the browser fill the form from a saved profile and check that every value lands in the right box. Sign up with a password manager, sign out, and sign back in: it should offer to save, then fill. A tool can list the autocomplete attributes, but only filling the form shows whether the right values land in the right fields.

The Web HIG is an open set of guidelines for how the web should behave, not a component library. Design systems define how it looks. The Web HIG defines how it behaves.

Keep focus inside the dialog (Web HIG tip #13)

FrozonFreak — Fri, 30 Oct 2026 11:22:59 +0000

Open a modal on your site, the cookie settings, a confirm step, or a sign-in box, and press Tab a few times. If the focus ring disappears behind the dark overlay and lands on a link in the page underneath, a keyboard user is now working in a part of the page they can't see.

Web HIG tip #13 (Quick #73 / HIG-A11Y-008): Modals must trap focus inside and restore focus to the trigger on close.

Why it matters

A modal says "deal with this first". Focus has to agree with what the screen shows:

If Tab leaves the dialog, keyboard and switch users end up on controls hidden behind the overlay, and pressing Enter acts on something they can't see
Screen reader users who move past the dialog's content read the page behind it as if the dialog weren't there
If focus isn't moved in when the dialog opens, the user has to hunt for it, or doesn't know it opened at all
If focus isn't put back on close, it usually drops to the top of the page, and the user has to find their place again

The full HIG covers this in §5.3, Keyboard Focus & Interaction. HIG-A11Y-008 (Modal focus containment, severity error) asks for three things: focus moves into the dialog when it opens, Tab and Shift+Tab cycle within it while it's active, and focus returns to the control that opened it when it closes. The spec is explicit that aria-modal="true" tells assistive technology the dialog is modal but does not itself create a focus trap. The keyboard pattern table adds that Escape closes a dialog. On the WCAG side, this supports 2.4.3 Focus Order (Level A). A trap with no way out would fail 2.1.2 No Keyboard Trap (Level A), so the Escape key and a visible close button are part of the rule, not extras.

The rule of thumb

Ask: while the dialog is open, can Tab ever reach something behind it? And when it closes, am I back where I started?

The native <dialog> element, opened with showModal(), does most of the work:

<button type="button" id="open-settings">Cookie settings</button>

<dialog id="settings" aria-labelledby="settings-title">
  <h2 id="settings-title">Cookie settings</h2>
  <form method="dialog">
    …
    <button value="cancel">Cancel</button>
    <button value="save">Save</button>
  </form>
</dialog>

const dialog = document.getElementById('settings');
const trigger = document.getElementById('open-settings');

trigger.addEventListener('click', () => dialog.showModal());

showModal() makes the rest of the page inert, so Tab can't reach it, moves focus into the dialog, and closes it on Escape. Modern browsers also return focus to the element that was focused before the dialog opened. Test that in the browsers you support rather than assuming it. Tab can still move into the browser's own controls, such as the address bar. That's expected: the rule is about the page behind the dialog.

Do this instead

Prefer <dialog> with showModal() over a custom <div role="dialog">. If you have to keep a custom modal, set inert on the page content behind it, move focus in yourself, and handle Escape
Don't rely on aria-modal="true" alone. It changes what assistive technology is told, not where Tab goes
Pick the starting point on purpose: the first field in a form, the title for a long read, the safest button for a destructive confirm
On close, return focus to the trigger. If the trigger no longer exists, for example the row was deleted, move focus to the next logical place, such as the list or the following row
Give every dialog a visible close or cancel button as well as Escape
Use show() or a popover for non-modal UI. A dialog that doesn't block the page shouldn't trap focus either

Quick check for your app

Open a dialog on example.com using only the keyboard. Check that focus lands inside it. Press Tab and Shift+Tab ten times each: focus should stay in the dialog and never land on the page behind the overlay. Press Escape: the dialog should close and focus should be back on the button you opened it with. Repeat with a screen reader and with your confirm, sign-in, and cookie dialogs. A tool can tell you a dialog has aria-modal, but only tabbing through shows whether focus actually stays put.

The Web HIG is an open set of guidelines for how the web should behave, not a component library. Design systems define how it looks. The Web HIG defines how it behaves.