`, ``, `` for tabular data, headings in order. - **ARIA only when HTML can't do it.** ARIA changes what's announced, not how anything behaves. `role="button"` on a `

` makes a screen reader say "button", but the div still ignores Enter and Space and can't receive focus: a broken button that claims to work. That's why the W3C's [first rule of ARIA](https://www.w3.org/TR/using-aria/) is to use a native element whenever one exists. - **Custom widgets** (tabs, comboboxes, dialogs) follow the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) patterns, including their keyboard behavior. ## Keyboard and Focus Everything usable with a mouse is usable with a keyboard alone. - **Logical tab order,** following the visual order. No positive `tabindex`. - **Visible focus, always.** Never remove outlines without a replacement. `:focus-visible` shows focus for keyboard users without flashing it on every mouse click. - **Dialogs trap focus** while open and return it to the trigger when closed. `Escape` closes them. - **A skip link** to the main content on pages with long navigation. ## Color and Contrast - **Text:** at least 4.5:1 against its background, 3:1 for large text (18pt, or 14pt bold). - **UI components and graphics:** at least 3:1 for borders of inputs, focus indicators, icons and chart marks that carry meaning. - **Never color alone.** Errors get an icon and text, links get an underline or another cue, charts get labels or patterns. - **Check every theme.** A palette that passes in dark mode can fail in light mode. See [Design Tokens & Theming](/docs/frontend/design-tokens). ## Motion Respect [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion). Animations that move, zoom or parallax get a reduced or static alternative. Nothing flashes more than three times a second. ## Forms Forms are where most accessibility failures cost someone a task: unlabeled inputs, errors only shown in red, a form cleared on failure. [Forms & Validation](/docs/frontend/forms) covers labels, attached error messages and `autocomplete` in full. ## Images and Media - **Meaningful images** get `alt` text that says what the image communicates, not what it looks like. - **Decorative images** get `alt=""`, so screen readers skip them. - **Video** has captions; audio has transcripts. ## Testing Automated tools are necessary and nowhere near sufficient. They can tell that an image has `alt` text, not whether it describes the image; that a button has a name, not whether the name makes sense. [axe-core](https://github.com/dequelabs/axe-core), the engine behind most of them, reports finding about 57% of WCAG issues on average, so a clean report means the easy half is done. The rest takes a person: 1. **Automated checks in CI** with axe on key pages, failing the build on new violations. 2. **A keyboard pass** on every new flow: unplug the mouse and finish the task. 3. **A screen reader pass** on new components: VoiceOver on macOS and iOS, NVDA on Windows. 4. **Zoom to 200%** and check at 320px width: content reflows, nothing overlaps or gets cut off. ## It's the Law, Too In the US, the Department of Justice's position is that the ADA applies to the websites of businesses open to the public ([ADA.gov guidance](https://www.ada.gov/resources/web-guidance/)). In the EU, the [European Accessibility Act](https://commission.europa.eu/strategy-and-policy/policies/justice-and-fundamental-rights/disability/union-equality-strategy-rights-persons-disabilities-2021-2030/european-accessibility-act_en) has applied since 28 June 2025 and covers e-commerce and other consumer services. Building to WCAG 2.2 AA puts you on the right side of both. ## References **Specifications** - [W3C: Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/), success criteria, contrast ratios and conformance levels - [W3C: What's New in WCAG 2.2](https://www.w3.org/WAI/standards-guidelines/wcag/new-in-22/), the nine criteria added in 2.2 - [W3C: Using ARIA](https://www.w3.org/TR/using-aria/), the rules of ARIA use, starting with native HTML first **Reference** - [W3C: ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/), keyboard and ARIA patterns for custom widgets - [MDN: prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion), detecting the reduced-motion preference - [Deque: axe-core](https://github.com/dequelabs/axe-core), the automated testing engine and what share of issues it catches **In practice** - [WHO: Disability and health](https://www.who.int/news-room/fact-sheets/detail/disability-and-health), 1.3 billion people, about 1 in 6, with significant disability - [ADA.gov: Guidance on Web Accessibility and the ADA](https://www.ada.gov/resources/web-guidance/), how the ADA applies to websites - [European Commission: European Accessibility Act](https://commission.europa.eu/strategy-and-policy/policies/justice-and-fundamental-rights/disability/union-equality-strategy-rights-persons-disabilities-2021-2030/european-accessibility-act_en), scope of the EU requirements 52:T1a6e,Speed is a feature people notice only when it's missing, and it shows up directly in revenue: in a [Deloitte study](https://web.dev/case-studies/milliseconds-make-millions) of mobile sites, a tenth of a second faster across the journey lifted retail conversions by 8.4%. It's also one of the few features that degrades on its own. Every dependency, image and script is added for a good reason, and each makes the page a little slower; nobody decides to make the site slow. So performance is held with budgets that fail the build, not fixed in a big project every couple of years. ## Targets: Core Web Vitals I use the [Core Web Vitals](https://web.dev/articles/vitals) as targets because they measure what users feel (does the main content show up, does the page respond, does it stop jumping around) rather than what's convenient, like total bytes. Each is judged at the **75th percentile** of real page loads, separately for mobile and desktop: the median hides the slower devices where people give up, and the 99th is dominated by outliers you can't fix. | Metric | Measures | Good | | --- | --- | --- | | Largest Contentful Paint (LCP) | Loading: when the main content appears | 2.5 s or less | | Interaction to Next Paint (INP) | Responsiveness: how fast the page reacts to input | 200 ms or less | | Cumulative Layout Shift (CLS) | Visual stability: how much content jumps around | 0.1 or less | [INP replaced First Input Delay](https://web.dev/blog/inp-cwv-launch) as a Core Web Vital in March 2024. It measures every interaction, not just the first, which makes heavy JavaScript much harder to hide. ## Measure Real Users - **Field data decides.** Real-user monitoring (RUM) and the [Chrome UX Report](https://developer.chrome.com/docs/crux) show what people actually experience, on their devices and networks. - **Lab data explains.** Lighthouse and DevTools traces find why a number is bad and check a fix; they don't declare victory. A fast laptop on office Wi-Fi is not your median user. - **Watch the 75th percentile, not the average.** An average blends a fast majority with a slow minority into a number that describes nobody. ## Budgets in CI A budget turns "keep it fast" into a check that fails: - **JavaScript size** per route, compressed. The first budget to set, because it's the most common regression. - **Lab metrics** on key pages with [Lighthouse CI](https://github.com/GoogleChrome/lighthouse-ci), asserting LCP, CLS and total blocking time stay under thresholds. - **A new dependency** has to fit the budget, or something else gets removed. See [Dependencies & Upgrades](/docs/engineering/dependencies). Set budgets from where you are today, then tighten them. A budget nobody can meet gets ignored. ## Ship Less JavaScript JavaScript is the most expensive byte on the page: downloaded, parsed, compiled and executed on a slow phone's main thread, which is exactly what INP measures. - **Render on the server or at build time,** and send HTML. Static and server rendering get content on screen without waiting for a bundle. - **Hydrate only what's interactive.** A page of text doesn't need a client-side app. - **Split by route,** and load heavy components (editors, charts, maps) when they're needed. - **Question every dependency's size** before adding it. A date library for one format is rarely worth it. ## Images - **Modern formats** (AVIF, WebP) with explicit `width` and `height` so the browser reserves space and CLS stays at zero. - **Responsive sizes** with `srcset` and `sizes`, so phones don't download desktop images. - **[Lazy-load](https://web.dev/articles/browser-level-image-lazy-loading) below the fold,** and never the LCP image. The LCP image gets [`fetchpriority="high"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/fetchpriority) instead ([Optimize LCP](https://web.dev/articles/optimize-lcp)). ## Fonts - **Self-host** and subset to the characters you use. - **`font-display: swap` or `optional`,** so text renders immediately in a fallback instead of staying invisible. - **Preload only the one or two fonts** above the fold. Preloading everything competes with the content that matters ([font best practices](https://web.dev/articles/font-best-practices)). - **Match fallback metrics** to the web font, so the swap doesn't shift the layout. ## Caching Static assets get content-hashed filenames and `Cache-Control: public, max-age=31536000, immutable`, so repeat visits load them from the browser cache. HTML and API responses revalidate. See [Caching & Conditional Requests](/docs/requests/caching). ## Third-Party Scripts Every tag, widget and pixel runs on your users' devices and counts against your Core Web Vitals. Each needs an owner and a reason, loads after the content, and goes when nobody can say what it's for. ## This Site [syntaqx.com](https://github.com/syntaqx/syntaqx.com) is a Next.js site on Vercel, with pages rendered on the server or at build time. Fonts are self-hosted through `next/font`, images go through `next/image`, and [Vercel Speed Insights](https://vercel.com/docs/speed-insights) collects field data from real visitors at the 75th percentile (on the free plan, a Real Experience Score plus FCP and LCP; per-metric INP and CLS need the paid tier), alongside [Vercel Web Analytics](https://vercel.com/docs/analytics) for traffic. ## References **Reference** - [web.dev: Web Vitals](https://web.dev/articles/vitals), the Core Web Vitals and their thresholds - [web.dev: Interaction to Next Paint](https://web.dev/articles/inp), how INP is measured and its thresholds - [web.dev: INP is officially a Core Web Vital](https://web.dev/blog/inp-cwv-launch), INP replacing FID in March 2024 - [Chrome for Developers: Chrome UX Report](https://developer.chrome.com/docs/crux), field data from real Chrome users - [web.dev: Optimize Largest Contentful Paint](https://web.dev/articles/optimize-lcp), prioritizing and never lazy-loading the LCP image - [web.dev: Best practices for fonts](https://web.dev/articles/font-best-practices), preload and `font-display` - [MDN: fetchpriority](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/fetchpriority), hinting the priority of a resource **In practice** - [web.dev: Milliseconds make millions](https://web.dev/case-studies/milliseconds-make-millions), Deloitte's study of 0.1 s speed improvements and conversions - [Google: Lighthouse CI](https://github.com/GoogleChrome/lighthouse-ci), asserting performance budgets in CI - [Vercel: Speed Insights](https://vercel.com/docs/speed-insights), real-user performance data at the 75th percentile - [Next.js: Font optimization](https://nextjs.org/docs/app/getting-started/fonts), self-hosted fonts with no layout shift 53:T1330,A design token is a named design decision: `--border` instead of `#1c2423`. Components use the name, never the value. That one rule makes theming, rebranding and contrast fixes a change in one file instead of a hunt through a thousand. And the hunt is worse than it sounds: a hard-coded color looks fine the day it's written, in the one theme it was checked in, then surfaces months later as a white line in dark mode that nobody can trace to a decision, because there never was one. ## Tokens, Not Literals - **Color, type, spacing, radius, shadows and motion** are all tokens. A hex code, a pixel font size or a raw duration in a component is a bug. - **CSS [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)** are the delivery mechanism: they cascade, can be redefined per theme or component, and work in every framework. - **Utility frameworks map to tokens,** not to their default palette. If the framework offers `gray-800`, components should be using `border` instead. ## Semantic Over Raw Name tokens for what they're for, not what they look like. | Raw (palette) | Semantic (role) | | --- | --- | | `--teal-400` | `--accent` | | `--gray-950` | `--background` | | `--gray-100` | `--foreground` | | `--gray-800` | `--border` | - **Components only use semantic tokens.** `border: 1px solid var(--border)` keeps working in every theme; `var(--gray-800)` is correct in exactly one. - **A palette layer is optional.** Semantic tokens can point at palette tokens, which helps when a brand has many shades, but components never skip the semantic layer. - **Name the relationship, not the instance.** `--border` and `--border-strong` scale; `--table-header-line` multiplies until nobody knows which to use. ## Themes Are Token Redefinitions A theme is a set of values for the same names. Light and dark mode never fork component styles: ```css :root { --background: #0a0c0c; --foreground: #e6ece9; --border: #1c2423; color-scheme: dark; } @media (prefers-color-scheme: light) { :root:not(.dark) { --background: #eef2f1; --foreground: #0c1211; --border: #d2dad8; color-scheme: light; } } /* An explicit choice from the theme toggle beats the OS preference. */ .light { /* the light values again */ } .dark { /* the dark values again */ } ``` - **Respect the OS first** with [`prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme), in CSS, so the first paint is right before any JavaScript runs. A theme chosen in JavaScript flashes the wrong colors on every load: a white screen in a dark room. - **Let people override it,** with a class or data attribute on the root that beats the media query, remembered across visits. - **Set `color-scheme`** so form controls, scrollbars and system colors match the theme. ## Check Contrast in Every Theme Contrast is a property of a pair of tokens in a theme, not of a component. Check every foreground and background pairing in every theme against the [WCAG ratios](/docs/frontend/accessibility); a palette that passes in dark mode can fail in light mode. ## Interchange Format Once tokens exist in a design tool and in code, they drift unless one is generated from the other, so shared tokens live in one source and are generated into each platform. The W3C Design Tokens Community Group's [Design Tokens Format Module](https://www.designtokens.org/TR/2025.10/format/) is the common JSON format for that, stable as of its 2025.10 version, and supported by tools like Style Dictionary. ## This Site [syntaqx.com](https://github.com/syntaqx/syntaqx.com) defines its tokens in `app/globals.css`: dark values on `:root`, light values under `prefers-color-scheme: light`, and `.dark` and `.light` classes from the theme toggle that override the OS preference. Tailwind's theme maps its color utilities to the same variables, so `border-border` and `var(--border)` are one decision. It also shows why the semantic layer matters. Table header rules used `--foreground`, the text color, so they rendered far heavier than the row rules in both themes. The fix was one line: `--border-hover`, the token for a border one step stronger than `--border`, which is right in both themes without any theme-specific code. ## References **Specifications** - [Design Tokens Community Group: Design Tokens Format Module 2025.10](https://www.designtokens.org/TR/2025.10/format/), the interchange format for tokens - [W3C: Design Tokens Community Group](https://www.w3.org/community/design-tokens/), the group behind the format **Reference** - [MDN: Using CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties), cascading variables as the delivery mechanism - [MDN: prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme), respecting the OS theme preference 54:T2860,Forms are where users give you something: their money, their data, their time. A field that rejects valid input, an error that doesn't say what's wrong, a submit that wipes what someone typed: each turns a user who wanted to finish into one who gives up. Most of what follows is about not punishing people for the gap between what they entered and what the system expected. ## Native HTML First Every piece of a form the browser handles is one you don't build, test or get wrong. - **A visible `` for every input,** connected with `for`/`id`. Clicking it focuses the field, screen readers announce it, and it's still there after the user starts typing, which a placeholder isn't. - **The right `type`.** `email`, `tel`, `url` and `number` change the mobile keyboard, so someone typing a phone number gets a keypad. A usability win for one attribute. - **`autocomplete` with real tokens.** `given-name`, `email`, `street-address`, `postal-code`, `cc-number`, `one-time-code` and the rest are defined by the [HTML standard](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html) and let the browser fill a whole checkout in one tap. Getting them wrong, or turning them `off`, makes people retype what their browser already knows (and on login fields most browsers ignore `off` anyway, so password managers keep working, per [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete)). - **Constraint attributes** (`required`, `minlength`, `pattern`, `min`, `max`) give you [constraint validation](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Constraint_validation) and the `:invalid` state for free, with the rules in the markup where the next engineer will find them. ## When to Validate Validating on every keystroke tells people they're wrong while they're still typing: "Invalid email" after the first letter of every address anyone has ever entered. It's noise at best and alarming at worst, and it trains people to ignore the messages that matter. I validate when the person has finished: on submit, and optionally when they leave a field they've already corrected once. The [GOV.UK Design System](https://design-system.service.gov.uk/patterns/validation/), built on years of research with people who aren't comfortable online, goes further and validates only on submit. The exception is feedback that guides rather than judges: a character count nearing its limit, or password strength while someone chooses one. ## The Server Is the Source of Truth Client-side validation is a courtesy: fast feedback for the obvious cases, but anyone can bypass it, and the client can't know whether the email is already registered or the coupon expired a minute ago. The server validates everything, every time, so the form handles server errors as a first-class path. The API returns field-level failures as a `422` with an `errors` object keyed by field ([Error Responses](/docs/requests/error-responses)): ```json { "message": "The given data was invalid.", "errors": { "email": ["An account with this email already exists."], "address.postal_code": ["The postal code doesn't match the city."] } } ``` The form maps each key onto its field and shows the message there, exactly as for a client-side error; the user shouldn't be able to tell which side caught the problem. A `400` or `5xx` isn't about any field, so it becomes a form-level message. This is why the API's error shape matters to the frontend: one consistent `errors` object means one piece of form code handles every endpoint. ## Error Messages That Fix the Problem An error message has one job: get the person to a valid submission. "Invalid input" fails it; "Enter a date in the format 31/12/2026" does it. - **Say what's wrong and how to fix it,** in the person's terms, not the system's. "The card number is too short: it should be 16 digits", not "Validation failed: pan.length". - **Don't blame.** "Enter your postcode" beats "You didn't enter a postcode". - **Be specific to the field and the rule** that failed. One generic message per field hides which of three rules was broken. WCAG makes the first two requirements: errors must be identified and described in text ([3.3.1](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html)), and where a correction is known it should be suggested ([3.3.3](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html)). ## Accessible Errors A red border tells sighted users something is wrong, and nobody else anything. These are the form-specific parts of [Accessibility](/docs/frontend/accessibility). - **Text, not just color.** Every error has a message, ideally with an icon too. - **Attach the message to its field** with `aria-describedby`, so a screen reader announces it when the field gets focus, and mark the field with `aria-invalid="true"` ([MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid)). - **After a failed submit, move focus.** On a long form, focus an error summary at the top that links to each field; on a short one, focus the first invalid field. Either way, a keyboard or screen reader user lands on the problem instead of a submit button that silently did nothing. GOV.UK's [error summary](https://design-system.service.gov.uk/components/error-summary/) is a well-tested version, and it prefixes the page title with "Error:" so the problem is announced immediately. ## Never Lose Work The most expensive form bug is the one that clears the form: ten minutes on an application, one field fails, and it's back to blank. - **Keep every value on failure,** client-side and server-side. - **Don't make people re-enter what they already gave you** in the same flow ([WCAG 3.3.7, Redundant Entry](https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry.html)). Carry the shipping address into billing with a checkbox, not a retype. - **Save drafts of long forms** locally or on the server as people go, so a crash, an expired session or a closed tab doesn't erase their work. - **Split long forms into steps** with one topic each, and let people go back without losing later answers. Steps reduce what anyone has to hold in their head and localize errors to one page. ## Double Submits People double-click, and networks drop the response after the server did the work, so users click again. If submitting creates something (an order, a payment), two clicks can create two of it. Disabling the button in flight handles the double click, but not the retry after a lost response, which is the case that actually charges cards twice. Generate an [idempotency key](/docs/payments/idempotency) when the form is first shown and send it with every attempt: the button state is a courtesy; the key is the guarantee. ## Password Managers and Paste Blocking paste on password fields, or breaking autofill with unusual markup, pushes people toward short passwords they can type from memory, the opposite of what the restriction intends. NIST's [digital identity guidelines](https://pages.nist.gov/800-63-4/sp800-63b.html) say verifiers SHALL allow password managers and autofill and SHOULD permit paste, and WCAG 2.2's [Accessible Authentication](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html) criterion treats paste and password managers as the way to avoid making people memorize or transcribe anything. Use `autocomplete="current-password"` on sign-in and `new-password` on sign-up and password changes, so managers know whether to fill or generate; `one-time-code` lets the platform offer the code from an SMS without switching apps. ## This Site The site has no account forms, but the API reference's "Try it" console follows the same rules for its request form: every parameter has a visible label, the request body is checked as JSON before sending with a message that says what's wrong ("Body isn't valid JSON: …"), and a failed request leaves everything the user entered in place so they can fix it and send again. ## References **Specifications** - [WHATWG: HTML, Autofill](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html), the autocomplete tokens and how browsers use them - [W3C: Understanding WCAG 2.2, Error Identification](https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html), errors described in text - [W3C: Understanding WCAG 2.2, Error Suggestion](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html), suggesting how to fix an error - [W3C: Understanding WCAG 2.2, Redundant Entry](https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry.html), not asking for the same information twice - [W3C: Understanding WCAG 2.2, Accessible Authentication (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html), paste and password managers in sign-in - [NIST SP 800-63B: Authentication and Authenticator Management](https://pages.nist.gov/800-63-4/sp800-63b.html), allowing password managers, autofill and paste **Reference** - [MDN: autocomplete](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete), token list and browser behavior on login fields - [MDN: Constraint validation](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Constraint_validation), built-in validation attributes and states - [MDN: aria-invalid](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid), marking a field as invalid - [MDN: aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby), connecting an error message to its field - [W3C WAI: Forms tutorial, user notifications](https://www.w3.org/WAI/tutorials/forms/notifications/), accessible success and error notifications **In practice** - [GOV.UK Design System: Validation](https://design-system.service.gov.uk/patterns/validation/), validating on submit and keeping what users entered - [GOV.UK Design System: Error summary](https://design-system.service.gov.uk/components/error-summary/), the summary, focus management and the "Error:" title prefix - [web.dev: Sign-in form best practices](https://web.dev/articles/sign-in-form-best-practices), autocomplete and password manager friendly markup 55:T2555,Designs usually show the happy path: the dashboard full of data, the request that came back in 80 milliseconds. Production shows everything else. The list is empty on a new account, the API is slow on a bad connection, one widget's request fails while the rest succeed. If nobody designed those states, the code decides, and its default is a blank area, a spinner that never stops, or `undefined` in the middle of the page. The fix is cheap up front: every view that loads data gets its states designed alongside the happy path, not discovered in a bug report. ## Five States, Not One | State | What the user should see | | --- | --- | | Loading | That something is happening, without the layout jumping when it finishes | | Empty | Why there's nothing, and the next step to get something | | Error | What went wrong, what to do now, and a way to retry | | Partial | The parts that worked, with the failed part marked, not the whole view thrown away | | Success | The content, and confirmation when the user just did something | As a checklist in design review, this catches most problems before code exists. As a state machine in the component (one `status`, not a cluster of `isLoading`, `hasError` and `data` booleans that can contradict each other), it makes impossible combinations like loading-and-error unrepresentable. ## Loading Without Layout Shift How long the wait is decides what to show. Below about a second people barely notice, and a spinner that flashes for 200 ms is worse than nothing. NN/g's research puts the thresholds at 0.1 s (feels instant), 1 s (noticeable, but flow is kept) and 10 s (attention is lost), and past 10 s people need a real progress indicator with some sense of how long ([response time limits](https://www.nngroup.com/articles/response-times-3-important-limits/)). For page and section loads, I prefer **skeletons** over spinners: placeholder shapes in the layout's real dimensions. They show what's coming and reserve the space, so the page doesn't jump when content arrives. That jump is [Cumulative Layout Shift](https://web.dev/articles/cls), a Core Web Vital ([Web Performance](/docs/frontend/web-performance)), and it's how people end up clicking the wrong thing. NN/g recommends skeletons for full-page loads under about 10 seconds and spinners for a single module ([skeleton screens](https://www.nngroup.com/articles/skeleton-screens/)). Two rules that prevent common bugs: don't show "No results" while the request is still in flight (a flash of the empty state reads as a real answer), and give every loading state a timeout that turns into an error state, so a hung request can't leave a spinner forever. ## Error Messages People Can Act On "Something went wrong" is the most common error message and the least useful: it doesn't say whether to retry, wait, fix something or give up. A good message answers what happened, in plain terms, and what to do now. - **Specific beats generic.** "We couldn't save your changes because the connection dropped. They're still here; try again" tells the person their work is safe and what to do. "Error 500" tells them nothing. - **No blame, no codes in the headline.** NN/g's [error message guidelines](https://www.nngroup.com/articles/error-message-guidelines/) recommend plain language, avoiding words like "invalid" and "illegal", and keeping technical codes out of the main message. - **Severity matches impact.** A failed background refresh is a small inline notice, not a modal that blocks the whole page. - **Keep what the user did.** A failed save keeps the form filled in ([Forms & Validation](/docs/frontend/forms)). ### Give Support Something to Search For The API returns a `Request-Id` header on every response, including errors ([Error Responses](/docs/requests/error-responses)). When an error is worth contacting support about, show it in small text with a copy button. One line of UI turns "it didn't work yesterday" into a log search that takes seconds ([Observability](/docs/operations/observability)). ## Retry and Offline Most frontend errors are transient: a dropped connection, a timeout, a `503` during a deploy. Every error state for a read gets a retry button, and many reads can retry once automatically first. The rules are the same as anywhere ([Retries & Timeouts](/docs/architecture/retries-and-timeouts)): reads are safe to repeat, writes only with an [idempotency key](/docs/payments/idempotency), and automatic retries back off. When the device is offline, say so once, globally, instead of letting every widget fail separately. The browser's [`online` and `offline` events](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine) are a hint, not proof (a device can be "online" with no route to your server), so treat a failed request as the real signal and the event as a cue to retry when connectivity returns. ## Empty States Teach the Next Step An empty state is the first thing every new user sees, some of the most-viewed design in the product, and "No projects" wastes it. NN/g recommends that empty states communicate status, help people learn the feature, and give a direct path to act ([empty state design](https://www.nngroup.com/articles/empty-state-interface-design/)): "You haven't created a project yet. Projects group your API keys and webhooks. **Create a project**." Distinguish the kinds of empty, because they need different words: nothing exists yet (onboarding), a search or filter matched nothing (offer to clear it), and everything is done (an inbox at zero is a success, not a void). ## Optimistic UI and Rolling Back For quick, likely-to-succeed actions (starring, toggling, reordering), updating the UI before the server confirms makes the product feel instant. The cost is handling failure: roll the change back visibly and say why, rather than showing something the server never accepted. React's [`useOptimistic`](https://react.dev/reference/react/useOptimistic) models exactly this: the optimistic state lasts while the action is pending and reverts to the real state when it settles. Don't be optimistic about things that are expensive to be wrong about. A payment, a deletion or anything irreversible waits for the server. ## Never a Blank Page A rendering error in one component shouldn't take down the whole page. In React that's an error boundary: a component that catches errors thrown while rendering its children and shows a fallback. Error boundaries are still class components (libraries such as `react-error-boundary` wrap one), and they don't catch errors in event handlers or ordinary async code, which need their own handling ([React docs](https://react.dev/reference/react/Component)). Place them around each independent widget, so one failing chart doesn't blank the dashboard, and at the route level as a backstop. Next.js builds this in with an `error` file per route segment and a `global-error` file for the root layout ([Next.js error handling](https://nextjs.org/docs/app/getting-started/error-handling)). Every boundary reports to monitoring: a fallback the user sees and the team never hears about is a bug that lives forever. Announce dynamic changes for screen reader users too. A status message that appears without moving focus, like "Saved" or "3 results", needs a live region ([WCAG 4.1.3, Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html)). ## This Site - **Empty search:** the docs index search shows "Nothing matches" with the query and a "Show everything" button, rather than an empty list with no explanation. - **API console errors:** the reference console's "Try it" shows a request that never got a response as a network error with its timing, keeps the request as entered, and for any response that does arrive, error or not, lists its `request-id` among the headers, so a failure has something to search for. - **Loading:** route changes show a thin progress bar at the top of the viewport instead of blanking the page. - **Last resort:** a `global-error` page with a "Try again" button catches errors in the root layout, so even a crash there isn't a blank screen. ## References **Specifications** - [W3C: Understanding WCAG 2.2, Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html), announcing changes without moving focus **Reference** - [React: Component, catching rendering errors with an error boundary](https://react.dev/reference/react/Component), what error boundaries catch and don't - [React: useOptimistic](https://react.dev/reference/react/useOptimistic), optimistic state that reverts when an action settles - [Next.js: Error Handling](https://nextjs.org/docs/app/getting-started/error-handling), route-segment error files and global errors - [MDN: Navigator.onLine](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine), online and offline signals and their limits - [web.dev: Cumulative Layout Shift](https://web.dev/articles/cls), measuring layout shift **In practice** - [NN/g: Response Time Limits](https://www.nngroup.com/articles/response-times-3-important-limits/), when people need feedback while waiting - [NN/g: Skeleton Screens 101](https://www.nngroup.com/articles/skeleton-screens/), skeletons vs spinners vs progress bars - [NN/g: Error-Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/), wording, placement and recovery - [NN/g: Designing Empty States in Complex Applications](https://www.nngroup.com/articles/empty-state-interface-design/), status, learnability and next steps 56:T2a87,Internationalization (i18n) is engineering work: building the product so it *can* work in any language and region. Localization (l10n) is the content work that follows: translating, and adapting formats for a specific locale. The distinction matters because i18n has to happen in the code, and the cost of skipping it lands all at once, when the first translation exposes every hard-coded string, concatenated sentence and layout that assumed English word lengths. Even an English-only product benefits. Dates, numbers and currencies already vary between US and UK readers, names already come in shapes your validation didn't expect, and a later translation becomes a content project instead of a rewrite. ## Externalize Every String User-facing text lives in message catalogs keyed by ID, never inline in components. Grep the UI code for English sentences: every hit is a string a translator will never see. Keys describe meaning, not wording (`checkout.submit_button`, not `place_order`), so when the copy changes from "Place order" to "Pay now", the key stays valid and the translation system flags the string as changed instead of losing it. ## Plurals and Grammar: ICU MessageFormat English has two plural forms, so code naturally grows `count === 1 ? "file" : "files"`, which is wrong for most of the world. [CLDR's plural rules](https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html) give Arabic six categories (zero, one, two, few, many, other), Polish and Russian four (one, few, many, other), and Japanese one. No ternary survives that. [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/) moves the grammar into the message, where each translator writes the forms their language needs: ```text {count, plural, =0 {No files} one {# file} other {# files} } ``` The same syntax handles grammatical gender and other variants with `select`. The code passes values (`count`, `gender`); the message decides the words. In JavaScript, [`Intl.PluralRules`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) exposes the same CLDR categories when you need them directly. ## Never Concatenate Sentences `"Welcome back, " + name + "!"` assumes the name goes at the end, the punctuation is the same, and "welcome back" doesn't change form with the person. Word order differs across languages, so a sentence assembled from translated fragments is often ungrammatical, and translators can't fix what they can't see whole. Use one message with placeholders, `"Welcome back, {name}!"`, so the translator controls the sentence. Embedded links or emphasis stay inside the message as named tags rather than splitting the sentence around them. ## Formatting: Use Intl, Not Strings Dates, numbers, currencies, lists and relative times all have locale rules that string templates get wrong. `1,234.5` is `1.234,5` in Germany and `1 234,5` in France; a US date `3/4/2026` is March 4th in New York and April 3rd in London. The browser and Node ship the [`Intl`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) APIs, built on CLDR data: ```ts new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR" }).format(1234.5); // "1.234,50 €" new Intl.DateTimeFormat("en-GB", { dateStyle: "long" }).format(date); ``` Formatting happens at the edge, for display only. Data stays canonical, the way the API sends it: amounts as integer minor units with a currency code ([Money & Amounts](/docs/payments/money)), instants as UTC timestamps ([Time & Date Formats](/docs/fundamentals/time)). Convert when rendering, never before storing, or you'll be parsing "1.234,50" back into a number someday. ## Choosing the Locale The browser sends its preferences in [`Accept-Language`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept-Language), a weighted list of [BCP 47](https://datatracker.ietf.org/doc/html/rfc5646) language tags. It's a good default for a first visit, and better than guessing from IP location, which says where someone is, not what they read: a German speaker traveling in Japan doesn't want Japanese. An explicit choice always wins. Show a language switcher, persist the choice (in the account, or a cookie for anonymous visitors), and never override it with the header again; browser defaults are often whatever the device shipped with. Put the locale in the URL (`/de/pricing`) for public pages, so each language version is shareable and indexable. ## Right-to-Left Layouts Arabic, Hebrew and Persian read right to left, and a mirrored layout isn't a translation detail: navigation, icons with direction, progress bars and padding all flip. [CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values) make this nearly free from the start: `margin-inline-start` instead of `margin-left`, `text-align: start` instead of `left`, and with `dir="rtl"` on the document the layout flips itself. Retrofitting a codebase full of `left` and `right` is a long search-and-replace with visual review at every step. Don't mirror blindly, though: logos, media controls and numbers keep their direction. ## Text Expansion Translated text is usually longer than English, and short strings grow most. The W3C's [summary of IBM's guidelines](https://www.w3.org/International/articles/article-text-size) puts strings of up to 10 English characters at 200 to 300% of their original length, and strings over 70 characters at about 130%. A button labeled "Save" has to fit "Speichern"; a tab bar sized to English labels overflows in German. Design for it: let containers grow, avoid fixed widths on anything holding text, allow wrapping, and truncate only with the full text available on hover or focus. ## Unicode Traps - **Length isn't characters.** JavaScript's `string.length` counts UTF-16 code units, so "👍" has length 2 and a family emoji can be 11. Character limits, truncation and cursor movement should count graphemes (what a person sees as one character) with [`Intl.Segmenter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter), which follows [Unicode's segmentation rules](https://unicode.org/reports/tr29/). - **Equal-looking strings may differ.** "é" can be one code point or "e" plus a combining accent. Normalize with [`String.prototype.normalize`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize) (NFC is the usual choice, per [Unicode normalization forms](https://unicode.org/reports/tr15/)) before comparing, deduplicating or using text as a key. - **Names don't follow your rules.** One field, not first and last; no minimum length; no rejecting apostrophes, hyphens, spaces or non-Latin scripts. The W3C's [personal names guidance](https://www.w3.org/International/questions/qa-personal-names) shows how many assumptions a "first name" field bakes in. ## Pseudo-Localization in CI Most i18n bugs can be found before anyone translates anything. [Pseudo-localization](https://learn.microsoft.com/en-us/globalization/methodology/pseudolocalization) generates a fake locale from English: accented characters ("Ŝåṽé"), about 40% padding to simulate expansion, and brackets around each string. Unaccented text was never externalized; a missing closing bracket means truncation; a bracket pair mid-sentence reveals concatenation. The `en-XA` (accents) and `en-XB` (bidirectional) pseudo-locales exist for exactly this. Run the UI in one in CI with screenshot or end-to-end tests, and these bugs fail the build instead of a release. ## What Not to Translate Translate what people read. Identifiers stay stable: API field names, enum values, log messages, error codes and URLs, so code, support and search keep working across languages. An [error response](/docs/requests/error-responses) has a stable shape and a human message; the message is localizable, the shape isn't. Brand and product names usually stay as they are, by a decision written down. ## This Site The site is English-only and sets `lang="en"` on the document, which tells screen readers and translation tools what they're reading. Its converter tools show the length trap in miniature: their character counts use `string.length`, so an emoji counts as two. That's right for a byte-oriented encoder, where code units matter, and would be a bug behind a "maximum 280 characters" limit shown to users. ## References **Specifications** - [Unicode CLDR: Language Plural Rules](https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html), plural categories per language - [ICU: Formatting Messages](https://unicode-org.github.io/icu/userguide/format_parse/messages/), MessageFormat syntax for plurals and selects - [RFC 5646: Tags for Identifying Languages](https://datatracker.ietf.org/doc/html/rfc5646), BCP 47 language tags - [Unicode UAX #29: Text Segmentation](https://unicode.org/reports/tr29/), grapheme clusters - [Unicode UAX #15: Normalization Forms](https://unicode.org/reports/tr15/), NFC and NFD **Reference** - [MDN: Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl), locale-aware formatting in JavaScript - [MDN: Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), numbers and currencies by locale - [MDN: Intl.PluralRules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules), CLDR plural categories in code - [MDN: Intl.Segmenter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter), counting and splitting graphemes - [MDN: String.prototype.normalize](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize), Unicode normalization - [MDN: CSS logical properties and values](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values), direction-independent layout - [MDN: Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept-Language), the browser's language preferences **In practice** - [W3C: Text size in translation](https://www.w3.org/International/articles/article-text-size), expansion rates by string length - [W3C: Setting language preferences in a browser](https://www.w3.org/International/questions/qa-lang-priorities), how users set the preferences behind Accept-Language - [W3C: Personal names around the world](https://www.w3.org/International/questions/qa-personal-names), assumptions name fields shouldn't make - [Microsoft: Pseudolocalization](https://learn.microsoft.com/en-us/globalization/methodology/pseudolocalization), pseudo-translation techniques and the en-XA and en-XB locales 57:T1cfb,Security starts before the code: a threat model is a design review with an attacker in the room. Its value is timing. The flaws it finds cost a sentence to fix on a whiteboard and a migration to fix in production: a webhook receiver designed without signature verification is a one-line change in the design doc, and the same receiver shipped, integrated by partners and moving money is a breaking change and possibly an incident. It doesn't need a specialist or a week, just an hour with the people building the thing while the design is still cheap to change. ## When to Do One Not every change needs one; modeling a copy change teaches the team that threat modeling is ceremony. Do one when a change: - **Adds a way in:** a new service, a public endpoint, a webhook receiver, a queue consumer. Every entry point is something an attacker will try. - **Creates or moves a trust boundary:** data crosses from a less trusted zone into a more trusted one. That's where assumptions break. - **Touches authentication, authorization, money or personal data,** where a mistake is expensive by definition. - **Adds a third party:** a vendor API, an SDK, an AI model, an MCP server. You're extending trust to code you don't control. It lives in the [design doc](/docs/engineering/design-docs) as its own section and gets reviewed with the rest, so it happens before the code exists instead of after. ## Four Questions The process fits in four questions, Adam Shostack's framing, small enough that teams actually do it: 1. **What are we working on?** Draw it. 2. **What can go wrong?** Walk it, systematically. 3. **What are we going to do about it?** Mitigate, accept, or transfer each threat. 4. **Did we do a good job?** Check that the mitigations shipped, and revisit when the design changes. Most failed threat models skip the first or the fourth. Without a drawing, people argue about a system they each imagine differently. Without a check, the model is a document nobody acts on. ## Draw the System A data flow diagram, with four kinds of things: | Element | Example | | ------- | ------- | | External entity | A browser, a partner's server, a payment processor | | Process | The API, a worker, an AI agent | | Data store | Postgres, Redis, an S3 bucket, a log index | | Data flow | An HTTPS request, a queue message, a webhook | Then draw the **trust boundaries**, a dashed line wherever trust changes: the internet and your edge, your API and a vendor's, one tenant's data and another's, user-supplied text and the model that reads it. The boundaries are the point. Attacks happen where data crosses from something you don't control into something you do, so every flow crossing a dashed line gets examined, and flows inside one zone mostly don't. ## What Can Go Wrong: STRIDE Brainstorming finds the threats people already worry about and misses the rest. STRIDE makes it a checklist: for every element and every flow across a boundary, ask six questions, one per security property. | Threat | Violates | Ask | Typical mitigation | | ------ | -------- | --- | ------------------ | | **S**poofing | Authentication | Can someone pretend to be a user, a service or a webhook sender? | [Authentication](/docs/api-design/authentication), signed [webhooks](/docs/payments/webhooks) | | **T**ampering | Integrity | Can data be changed in transit or at rest? | TLS, signatures, append-only records | | **R**epudiation | Non-repudiation | Can someone deny an action we can't prove they took? | Audit logs with [request IDs](/docs/operations/observability) | | **I**nformation disclosure | Confidentiality | Can data reach someone who shouldn't see it? | Authorization, [redaction](/docs/payments/sensitive-data), encryption | | **D**enial of service | Availability | Can someone exhaust a resource? | [Rate limits](/docs/requests/rate-limiting), size limits, timeouts | | **E**levation of privilege | Authorization | Can someone do more than they're allowed? | Object-level checks, least privilege, [tenant isolation](/docs/architecture/multi-tenancy) | Not every letter applies to every element: a data store can't spoof anyone, but it can be tampered with, leaked or filled up. Skipping letters that don't apply is fine; skipping uncomfortable ones is how breaches happen. ### A Worked Example A webhook receiver that takes payment events from a processor: - **Spoofing:** anyone can `POST` to a public URL. Without signature verification, a forged `payment.succeeded` ships goods for free. Mitigation: verify the HMAC on the raw body. - **Tampering and replay:** a captured valid request, replayed a week later, double-credits an account. Mitigation: reject old timestamps and dedupe by event ID. - **Denial of service:** a flood of junk requests ties up workers that verify signatures. Mitigation: cheap rejections first, rate limits, a queue in front of processing. - **Information disclosure:** error responses that echo the payload leak card data into the sender's logs. Mitigation: return a bare status. Four rows, an hour of discussion, each far cheaper now than after launch. ## Rate and Decide Score each threat by **likelihood times impact**, each from 1 (low) to 3 (high). Anything at 6 or above gets a mitigation before launch. A 3 or 4 gets a ticket. Below that, write down that you accept it and why. The scale is deliberately coarse. The score only sorts the list so effort goes to the top; a finer scale invites arguing over 6.5 versus 7 instead of fixing it. ## The Output Is Work A threat model that ends as a document has failed. It ends as work: - Each mitigation becomes a tracked ticket, linked from the design doc, with an owner. - Accepted risks are listed with the reason and a date to revisit, so "we accepted this" is a decision someone can find and question, not an accident. - The launch checklist confirms the "before launch" mitigations actually shipped. ## Template ```markdown ## Threat Model **System:** one sentence. **Diagram:** link or embed. **Trust boundaries:** list each, and what crosses it. | # | Element / flow | STRIDE | Threat | L | I | Score | Decision | Ticket | | - | -------------- | ------ | ------ | - | - | ----- | -------- | ------ | | 1 | Webhook receiver | S | Forged events | 3 | 3 | 9 | Verify signatures | #123 | **Accepted risks:** threat, reason, revisit date. **Reviewed by:** names, date. ``` ## Keep It Alive Revisit the model when the design changes, after a security incident (see [Incident Response](/docs/operations/incident-response)), and whenever an [AI system](/docs/security/ai-security) gains a new tool or data source. A stale model is worse than none, because people trust it: the risk was handled for a design that no longer exists. ## References **Reference** - [OWASP: Threat Modeling Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Threat_Modeling_Cheat_Sheet.html), data flow diagrams, STRIDE and the process end to end - [Microsoft: Threat Modeling Tool threats](https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats), the STRIDE categories and the properties they violate **In practice** - [Adam Shostack: Four Question Framework](https://github.com/adamshostack/4QuestionFrame), the four questions this process is built on - [Threat Modeling Manifesto](https://www.threatmodelingmanifesto.org/), values and principles for keeping threat modeling practical 58:T50f8,[API Authentication](/docs/api-design/authentication) covers machines: keys and tokens a program sends with every call. People are harder. They pick weak passwords, reuse them across sites, lose phones, fall for convincing login pages, and stay signed in on laptops they leave in taxis. Authentication for people is two problems: proving who someone is once, and then remembering it safely for every request after. Most account takeovers aren't a broken algorithm; they're a reused password, a phished code, a recovery flow that asks for a pet's name, or a session nobody could revoke. [Authorization](/docs/security/authorization) only means something once this part holds. ## Buy Before You Build I don't write a login system from scratch for a product whose business is something else. A managed identity provider (Auth0, Okta, Cognito, Clerk, WorkOS, or a mature open-source server like Keycloak) has already built passkeys, MFA, breached-password checks, bot defenses, enterprise SSO and the hundred edge cases in between, and it gets audited for them. Signing in through it over OpenID Connect is covered in [SSO & Identity Federation](/docs/security/sso-and-federation), and which one to pick, hosted, self-hosted or a library like Better Auth, in [Choosing an Identity Provider](/docs/security/identity-providers). Buying moves the work; it doesn't remove it. You still own the session your application creates after the provider says yes, what counts as a sensitive action, the recovery policy, the audit trail, and what happens when the provider is down. The rest of this chapter applies either way: it's what to configure if you buy, and what to build if you can't. ## Passwords, If You Must NIST's current guidance, [SP 800-63B-4](https://pages.nist.gov/800-63-4/sp800-63b.html) (final in July 2025), overturns most of the password rules people still enforce: - **Length, not composition.** At least 15 characters when the password is the only factor, at least 8 when it's one of two. Accept at least 64, and allow spaces and any printable character. No rules demanding a digit and a symbol: they produce `Password1!`, not strength. - **No forced rotation.** Don't make people change passwords on a schedule; require a change only on evidence of compromise. Scheduled rotation trains people into predictable increments. - **Screen against a blocklist.** Check every new password against known-breached and common values. [Have I Been Pwned's Pwned Passwords](https://haveibeenpwned.com/API/v3#PwnedPasswords) does it without the password leaving your system: you send the first five characters of its SHA-1 hash and compare the returned suffixes locally. - **No hints, no security questions.** NIST forbids both. A hint helps the attacker as much as the user, and "mother's maiden name" is public record. - **Limit failed attempts.** No more than 100 consecutive failures per account before the authenticator is disabled, and in practice far fewer, with throttling (below) doing most of the work. **Store them so a database leak isn't a password leak.** Use a slow, memory-hard hash with a unique salt per password. [OWASP's current minimums](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html): Argon2id with 19 MiB of memory, 2 iterations and 1 degree of parallelism; scrypt where Argon2id isn't available; bcrypt only for legacy systems, with a cost of at least 10 and a hard limit of 72 bytes of input; PBKDF2 with 600,000 iterations of HMAC-SHA-256 where FIPS validation is required. A pepper, a secret mixed into every hash and kept outside the database in a vault or HSM ([HSMs & Key Management](/docs/industries/payments/key-management)), means a stolen database alone can't be cracked. Store the algorithm and parameters with each hash, and rehash on the next successful login when they change. Never anything reversible: if you can email someone their password, you're storing it wrong. ## Passkeys First Passwords can be phished because the user types a secret into whatever page asks for it. Passkeys can't, and that's why I make them the default for new sign-ins. A passkey is a [WebAuthn](https://www.w3.org/TR/webauthn-3/) credential: a key pair whose private half never leaves the authenticator, created for one relying party. The browser and authenticator only use it on origins belonging to that relying party's ID (your registrable domain), so a pixel-perfect copy of your login page on another domain gets nothing. The server stores a public key, so a database leak exposes nothing reusable either. - **Synced or device-bound.** [Synced passkeys](https://fidoalliance.org/passkeys/) are backed up across a user's devices by their platform (iCloud Keychain, Google Password Manager, a password manager), which solves "I lost my phone" for most people. Device-bound passkeys never leave one authenticator, such as a hardware security key, which suits administrators and regulated access. Revision 4 of NIST's guidance makes room for synced passkeys. - **The ceremony.** Registration: the server sends a random challenge and the user's ID, the authenticator creates a key pair after a local check (fingerprint, face, PIN), and the server stores the public key and credential ID. Sign-in: the server sends a fresh challenge, the authenticator signs it, the server verifies the signature and that the origin and relying party ID match. The challenge is single-use; reusing one is replay. - **Attestation is usually unnecessary.** Attestation proves which make and model of authenticator created the key. Consumer apps rarely need it, and requesting it adds privacy prompts and failure modes; ask for it only when policy requires specific hardware. - **Plan for both.** Offer passkeys at sign-up and after a password sign-in, and keep a fallback for devices that can't use them, without letting the fallback become the weak door. ## Multi-Factor Authentication Where people still use passwords, a second factor stops most takeovers, but factors aren't equal. [CISA](https://www.cisa.gov/sites/default/files/publications/fact-sheet-implementing-phishing-resistant-mfa-508c.pdf) ranks them: | Factor | Phished? | Notes | | ------ | -------- | ----- | | Passkey or security key (FIDO/WebAuthn) | No | The gold standard; required for administrators | | Authenticator app code (TOTP) | Yes, by a relay page | Good baseline; codes are short-lived | | Push with number matching | Yes, but resists push bombing | Plain approve/deny push is weaker: users approve prompts to stop them | | SMS or voice code | Yes, plus SIM swap and SS7 | Last resort; NIST calls telephone delivery "restricted" | Enrolling or removing a factor is itself a sensitive action: it needs a fresh, strong sign-in and a notification to the account's existing channels. ## Recovery Is the Real Login An account is only as strong as its weakest way in, and that's usually "forgot password." Attackers skip the passkey and go straight for recovery. - **Recovery codes at enrollment.** Single-use codes shown once when MFA is set up, stored hashed like passwords. - **No knowledge questions,** for the same reasons as hints. - **Email links that are single-use, short-lived and bound to the request,** and that sign the user in to a limited state where the next step is setting a new credential, not browsing the account. - **Notify every existing channel** when a password, email, phone or factor changes, with a way to say "this wasn't me." - **Slow down risky recovery.** When recovery removes the last strong factor, hold the change for a waiting period with notifications, so the real owner can stop it. Support staff who can reset accounts are a recovery path too, and social engineers know it: give them the same verification steps, and log every reset. ## Sessions: The Default After sign-in, the application has to recognize the same person on every request. For a first-party web application, the default I reach for is a server-side session: - **An opaque, random ID** with at least 64 bits of entropy from a cryptographically secure generator ([OWASP Session Management](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)), mapped to a row in a session store with who signed in, how (password, passkey, SSO), when, and from what device. - **In a cookie set like this:** `Set-Cookie: __Host-session=…; Secure; HttpOnly; SameSite=Lax; Path=/`. `HttpOnly` keeps it away from JavaScript, so a cross-site scripting bug can't read it. `Secure` keeps it off plain HTTP. The [`__Host-` prefix](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies) makes the browser refuse it unless it's `Secure`, has `Path=/` and no `Domain`, so a subdomain can't set or overwrite it. Set `SameSite` explicitly rather than trusting browser defaults; `Strict` where users never arrive by cross-site links. - **A new ID at every privilege change.** Issue a fresh session ID at sign-in, at step-up, and when roles change, and invalidate the old one. Keeping the pre-login ID is session fixation. - **Two timeouts, enforced on the server.** An idle timeout and an absolute one. OWASP suggests idle timeouts of 2 to 5 minutes for high-value applications and 15 to 30 for low-risk ones, and an absolute limit of 4 to 8 hours for an all-day tool; NIST's AAL2 asks for reauthentication at least every 24 hours and after no more than an hour of inactivity. Pick numbers per product and write them down. - **Logout deletes the session on the server.** Clearing the cookie alone doesn't help if someone already copied it. Give users a list of their active sessions with device and location, and a button to end each one, and end all of them on a password change. ## Why Not JWTs as the Session The common alternative is a signed JWT in the browser: the server verifies the signature and reads the claims, with no lookup. It's attractive for being stateless, and it's the wrong default for a browser session, for concrete reasons. - **You can't take it back.** A JWT is valid until it expires, whatever happens in between: the user logs out, changes a password after a phishing scare, has a laptop stolen, or is fired. With a 24-hour token, that's up to 24 hours of access nobody can cut off. - **The workarounds rebuild the session.** Short expiry plus a refresh token moves revocation to the refresh step, which needs server state. A denylist of revoked token IDs is a lookup on every request, which is the session store again, now with extra steps. Either can be right, but neither is stateless anymore. - **Claims go stale.** A token minted when someone was an admin still says admin after you remove the role, until it expires. Sessions read current roles from the store; tokens freeze them. - **Where do you keep it?** In `localStorage`, any script on the page can read and exfiltrate it, so one XSS bug becomes account takeover. In an `HttpOnly` cookie it's safe from scripts, but now it's a cookie with all of a cookie's CSRF concerns, and you've given up the main reason to use a token. - **Size.** It travels on every request and grows with every claim. Browsers cap a cookie at about 4 KB, and teams hit that once claims accumulate. - **Validation is easy to get wrong.** [RFC 8725](https://datatracker.ietf.org/doc/html/rfc8725) exists because libraries accepted `alg: none`, and because an attacker could switch `RS256` to `HS256` and get the RSA public key used as an HMAC secret. Pin one algorithm per key, check issuer and audience, and use explicit types. Every service that verifies tokens has to get all of it right. - **No view of who's signed in.** Without a store there's no list of active sessions to show the user or a security team, and no "sign out everywhere." Sessions have honest costs too: a store lookup on every request (fast in Redis, but a dependency), shared storage so any instance can serve any request, and awkwardness when many services and domains each need to know who the user is. Those costs are what the patterns below address. ## Combining Them The patterns teams actually run keep the revocable session where the user is and use tokens where they're good. ![A server-side session at the edge with short-lived tokens inside: the browser holds only an opaque HttpOnly cookie; a backend-for-frontend or gateway holds the session store and mints a signed JWT lasting minutes for each internal call; orders, payments and accounts services verify the signature with no lookup; logging out or revoking deletes the session, so no further tokens are minted.](/diagrams/session-hybrid.svg "Revoke in one place, verify everywhere else. The browser never holds a token; the session at the edge can be ended at once, and the tokens inside expire in minutes.") - **Session at the edge, short-lived tokens inside.** The browser holds an opaque `HttpOnly` cookie. A gateway, or a backend-for-frontend (BFF) that's part of the web app, holds the session and mints a signed access token lasting a few minutes for calls to internal services, which verify it without a lookup. Logout deletes the session, so no new tokens are minted, and outstanding ones die within minutes. [RFC 10017, OAuth 2.0 for Browser-Based Applications](https://www.rfc-editor.org/rfc/rfc10017), now strongly recommends this BFF architecture for business and sensitive applications, precisely because tokens never reach the browser. It fits most products with more than one backend service. - **The refresh token is the session.** A short-lived access token plus a long-lived refresh token, with the refresh token stored server-side or in an `HttpOnly` cookie scoped to the refresh endpoint's path. Revocation happens at refresh. [RFC 9700](https://datatracker.ietf.org/doc/html/rfc9700) requires refresh tokens for public clients to be sender-constrained or rotated: every refresh issues a new one, and if an old one is ever presented again, the server knows one copy was stolen and revokes the active token. It fits mobile apps and API clients, where there's no browser cookie to lean on. - **Check for revocation without a full lookup.** [Token introspection (RFC 7662)](https://datatracker.ietf.org/doc/html/rfc7662) lets a service ask the authorization server whether a token is still active; cache the answer briefly, knowing that a cached "yes" can outlive a revocation. A cheaper variant puts a session version in the token and compares it to a per-user counter in a fast cache: bump the counter on logout or password change, and every older token fails on its next use. It fits when minutes of exposure after revocation is too long. - **Keep JWTs for what they do well:** access tokens between services and for APIs, in the interoperable [RFC 9068](https://datatracker.ietf.org/doc/html/rfc9068) profile; one-time links like email verification; and ID tokens in federation. Not the browser's session. ## CSRF A cookie-based session brings cross-site request forgery: another site makes the browser send a request, and the cookie goes along. `SameSite=Lax` or `Strict` blocks most of it, since the cookie isn't sent on cross-site requests except top-level navigations. For state-changing requests, also verify the `Origin` header or require a CSRF token, and never change state on `GET`. [Security Headers & CSP](/docs/security/security-headers) covers the rest of the browser's defenses. ## Credential Stuffing and Enumeration Most password attacks aren't guesses; they're username and password pairs leaked from other sites, tried at scale. - **Throttle per account and per source.** Count failures against the account, not just the IP, or an attacker spreads attempts across thousands of addresses; and limit by IP, network and device to slow broad sweeps ([Rate Limiting](/docs/requests/rate-limiting)). Hard lockouts let anyone lock a victim out, so prefer escalating delays and step-up challenges, and keep password reset available. - **Breached-password checks** at sign-in as well as at creation, forcing a reset when a match turns up. - **MFA,** which [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html) calls by far the best defense against password attacks. Bot detection and CAPTCHAs add friction for attackers, as defense in depth, not prevention. - **Don't confirm which accounts exist.** One message for every failure ("Invalid email or password"), one for every reset request ("If that address has an account, we've sent a link"), the same status codes, and the same timing: hash the submitted password even when the user doesn't exist, so a fast response doesn't give it away. ## Step-Up for Sensitive Actions A session that's hours old shouldn't be enough to change the account's email, add a payout bank account, create an API key or delete data. Require a fresh, strong authentication for those, and record which method was used and when. In OAuth terms, [RFC 9470](https://datatracker.ietf.org/doc/html/rfc9470) standardizes it: the resource answers `insufficient_user_authentication` with the required `acr_values` and `max_age`, and the client sends the user back through sign-in to meet them. Payments has a regulated version of the same idea in [Strong Customer Authentication](/docs/industries/payments/strong-customer-authentication). ## Audit Every Auth Event Sign-ins, failures, factor changes, recoveries, new devices, session revocations and step-ups each become a structured event with the user, method, device, IP, outcome and request ID ([Observability](/docs/operations/observability)). They answer "was this account taken over, and when?", feed detection for impossible travel and stuffing waves, and give users a security page that shows what happened on their account. ## This Site syntaqx.com has no user accounts at all, so none of this runs here: no passwords to store, no sessions to steal and no recovery flow to attack. That's a deliberate departure, recorded in [ADR 0001](https://github.com/syntaqx/syntaqx.com/blob/main/docs/adr/0001-no-authentication-or-user-identity.md), and the cheapest authentication system is the one you don't need. ## References **Specifications** - [NIST SP 800-63B-4: Authentication and Authenticator Management](https://pages.nist.gov/800-63-4/sp800-63b.html), password length and blocklists, no composition rules or periodic changes, no hints or KBA, the 100-attempt limit, restricted telephone delivery, and AAL2 reauthentication - [W3C: Web Authentication Level 3](https://www.w3.org/TR/webauthn-3/), passkey ceremonies and credentials scoped to the relying party - [RFC 10017: OAuth 2.0 for Browser-Based Applications](https://www.rfc-editor.org/rfc/rfc10017), the backend-for-frontend pattern and its cookie requirements - [RFC 9700: OAuth 2.0 Security Best Current Practice](https://datatracker.ietf.org/doc/html/rfc9700), refresh token rotation and reuse detection - [RFC 8725: JSON Web Token Best Current Practices](https://datatracker.ietf.org/doc/html/rfc8725), `alg: none`, algorithm confusion, issuer and audience checks, explicit typing - [RFC 7662: OAuth 2.0 Token Introspection](https://datatracker.ietf.org/doc/html/rfc7662), asking whether a token is still active, and the cost of caching the answer - [RFC 9068: JWT Profile for OAuth 2.0 Access Tokens](https://datatracker.ietf.org/doc/html/rfc9068), where JWTs belong - [RFC 9470: OAuth 2.0 Step Up Authentication Challenge Protocol](https://datatracker.ietf.org/doc/html/rfc9470), `insufficient_user_authentication`, `acr_values` and `max_age` **Reference** - [OWASP: Password Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html), Argon2id, scrypt, bcrypt and PBKDF2 parameters, and peppers - [OWASP: Session Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html), session ID entropy, renewal on privilege change, idle and absolute timeouts - [OWASP: Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html), generic errors, consistent timing, throttling versus lockout - [MDN: Using HTTP cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies), `HttpOnly`, `Secure`, `SameSite`, the `__Host-` prefix and per-cookie size limits - [CISA: Implementing Phishing-Resistant MFA](https://www.cisa.gov/sites/default/files/publications/fact-sheet-implementing-phishing-resistant-mfa-508c.pdf), MFA forms ranked strongest to weakest - [FIDO Alliance: Passkeys](https://fidoalliance.org/passkeys/), synced and device-bound passkeys **In practice** - [Have I Been Pwned: Pwned Passwords API](https://haveibeenpwned.com/API/v3#PwnedPasswords), breached-password screening with k-anonymity