We live in an era where technology permeates every aspect of our daily lives. However, not everyone can benefit equally from these advancements. This is where Accessibility by Design comes into play, a fundamental approach that must be incorporated from the early stages of digital product development. But why is it so important? And what are the advantages it offers in terms of inclusivity, responsiveness, usability, and marketing?
\nInclusivity is not just a buzzword; it is a fundamental principle of a fair and just society. About 20% of the world's population lives with some form of disability. Ignoring this significant portion of the population means excluding millions of people from accessing digital resources. Accessibility by Design ensures that our products are usable by everyone, regardless of their physical or cognitive abilities. This not only improves the quality of life for many people but also strengthens our social responsibility as a company.
\nAn accessible design makes digital products more responsive. This means that our software, website, or application can easily adapt to the diverse needs of users. Whether it's people with visual, auditory, motor, or cognitive disabilities, an accessibility-focused approach ensures that everyone can effectively interact with our product. This not only enhances the user experience but also ensures that there are no technological barriers to access.
\nOften, accessible design brings significant improvements in overall usability. Features such as clear and readable text, adequate color contrasts, intuitive navigation, and audio/video descriptions not only help users with disabilities but also enhance the experience for everyone. A product that is easy to use is a successful product, capable of meeting the needs of a wide range of users.
\nFrom a marketing perspective, Accessibility by Design offers extraordinary benefits. With 20% of the world's population consisting of people with disabilities, we are talking about a vast segment of potential users, stakeholders, operators, and customers. Ignoring this segment means missing out on a significant market opportunity. On the other hand, creating accessible products can set our company apart from the competition, positioning us as leaders in the industry and enhancing our reputation.
\nAdopting Accessibility by Design is not just good practice but a winning strategy that encompasses inclusivity, responsiveness, usability, and marketing. It is an investment that pays off handsomely, improving our corporate image, expanding our user base, and demonstrating our commitment to a more equitable and inclusive society.
\nLet's make accessibility a priority and work together to create a digital future that is truly for everyone.
\nAccessibility by Design is not just a trend but a necessity. We are ready to make a difference. Join us on this journey toward a more inclusive digital world.
\n", "image": "https://dout.dev/assets/og/posts/2026-07-25-accessibility-by-design.png", "date_published": "2026-07-25T00:00:00.000Z", "tags": [ "accessibility", "design", "responsive-design" ] }, { "id": "https://dout.dev/posts/2026-07-23-manual-a11y-audit.html", "url": "https://dout.dev/posts/2026-07-23-manual-a11y-audit.html", "title": "Manual A11y Audit: axe, Keyboard, Screen Reader in an Afternoon (You Have Time for This)", "summary": "The claim", "content_html": "An accessibility audit is not a three-week project. For a static blog of reasonable size, a complete manual audit - automated scan plus keyboard-only pass plus screen reader pass - fits in one afternoon. This post is the protocol I use.
\nThree passes. Each catches a different class of problem. None replaces the others.
\nAxe-core is the de facto standard for automated a11y checks. It catches mechanical violations - missing labels, contrast failures, heading order skips, ARIA misuse, missing alt text, keyboard traps in known patterns. What it does not catch is semantic correctness and interaction-level issues.
\nTime budget: 30 minutes for a small site.
\nThe easiest way to run axe is the browser extension. Install it, open DevTools, Scan. For deterministic reruns, the axe Chrome extension exports a JSON report; if you want CI integration, use the Playwright or Puppeteer bindings.
\nimport { test, expect } from '@playwright/test';\nimport { injectAxe, checkA11y } from '@axe-core/playwright';\n\ntest('home passes axe', async ({ page }) => {\n await page.goto('/');\n await injectAxe(page);\n const violations = await checkA11y(page, null, {\n detailedReport: true,\n axeOptions: { runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag22aa'] } },\n });\n expect(violations).toBeFalsy();\n});Common findings on a first-time audit:
\nalt=\"\", not no alt).aria-label on elements that already have visible accessible text.<button> inside an <a>).Fix these first. They are mechanical; they do not need judgment. Axe will flag them again if they come back.
\nUnplug your mouse. Literally, or at least commit to not using it.
\nTime budget: 45 minutes.
\nThe protocol:
\nWhat to look for:
\norder: -1 in Flexbox without a matching tabindex.<div onclick> is a keyboard dead zone. Fix by replacing with <button>.This pass catches almost everything axe missed. The findings are usually not \"my code is broken;\" they are \"my interaction model assumed a mouse.\"
\nTime budget: 90 minutes.
\nThis is the uncomfortable pass. You have to turn on a screen reader and use the site for real. On macOS, that is VoiceOver. On Windows, NVDA (free) or JAWS (commercial). On iOS, VoiceOver. On Android, TalkBack.
\nI use VoiceOver on macOS because it is built in and most of my readers on Apple devices use it. If the site works in VO, it usually works elsewhere, because the assistive APIs are fairly consistent.
\nBasic VoiceOver commands:
\nCmd+F5 - toggle VoiceOver.Ctrl+Option+arrow - move through content.Ctrl+Option+U - open the Rotor, which navigates by headings, landmarks, links, etc.Ctrl+Option+Space - activate the current element.The audit protocol:
\nCtrl+Option+U and navigate by landmarks. You should hear banner, main, contentinfo. No orphan landmarks. No missing landmarks.h1, descending properly. If you hear a skip (\"h2 ... h4\"), that is a violation.The findings from this pass are qualitatively different. They are about announcement correctness and context. Things you might catch:
\n<time> element was used.aria-label that reads awkwardly.aria-live.These are the findings that automated tools cannot produce. They are also the ones that most improve the experience for actual screen reader users.
\nI keep a simple markdown log per audit. Date, scope, findings, status.
\n# A11y audit - 2026-11-10\n\n## Scope\n\nHome, archive, a random post, search, about.\n\n## Findings\n\n- [x] Home: axe flagged color contrast on `.post-card__date` (3.9:1). Fixed.\n- [x] Post: Tab from outline link did not move focus into the section. Added `tabindex=\"-1\"` on headings. Fixed.\n- [ ] Search: VoiceOver does not announce result count change. `aria-live=\"polite\"` is set but on the wrong element. Open.\n- [x] Archive: focus ring invisible on pagination numbers in dark mode. Bumped outline-offset. Fixed.The log is a working document, not a report. I update it as I fix things. At the end of the audit, the open items are the follow-up tasks.
\nFor dout.dev, this full audit happens every quarter. Short passes (axe only) run on every CI build. The quarterly cadence catches what CI cannot: semantic issues, new content patterns, regressions that axe does not model.
\nAccessibility auditing on a static blog is bounded work with clear protocols. Axe + keyboard + screen reader, in an afternoon, quarterly. The findings get better over time as the codebase gets better; the first audit is always the longest.
\n\"Your repo has pnpm-workspace.yaml. Why? It is one site.\"
Fair question. A workspace implies multiple packages that share tooling. A single site does not have multiple packages. On the face of it, pnpm-workspace.yaml in a single-site repo is overkill. Sometimes it is. On dout.dev it is not, and this post is the reasoning.
Turning a repo into a pnpm workspace adds:
\npnpm-workspace.yaml, with the packages glob.workspace: protocol for internal package references, if you use it.node_modules is hoisted at the workspace root, with per-package exceptions.That is all. No different commands. No different build time. The incremental cost is almost zero if you stop there.
\nThree things, each of which I expected to eventually need on dout.dev.
\nExtract a package. If the template engine, the CMS, or the syntax highlighter becomes useful outside this repo, it moves into packages/pix-template-engine/ without restructuring anything. The workspace already knows how to build and test sub-packages.
Share dev tooling across packages. Biome config, Prettier config, TypeScript config, Playwright config - any of these can live at the root and be inherited by packages. A workspace makes this natural.
\nRun scripts across the graph. pnpm -r test, pnpm -r build, pnpm -r lint. If there are multiple packages, you get parallel execution and topological ordering for free.
None of these is free-as-in-beer to retrofit. Adding a workspace to an established single-package repo means moving files, updating imports, reshuffling package.json entries, and fixing a week of small breakages. Starting with a workspace costs nothing and avoids that migration.
On a throwaway project that will never be more than one package: skip it. On a learning project where the workspace concept itself is a distraction: skip it. The workspace is a bet on future-you wanting to extract something; if that bet is clearly wrong, do not place it.
\npackages:\n - '.'That is it. The root itself is the one package in the workspace. Adding more later is a one-line change.
\nCompare to the alternative where the repo grows a second package and you have to migrate on the spot. The migration is mechanical, not hard, but every \"mechanical\" task on a side project is a chance to stall. I prefer the inert one-line file.
\npnpm workspaces hoist shared dependencies to the root node_modules. That means:
node_modules/.bin at the root contains the CLIs from any package.The hoisting is usually invisible and always correct. The one case where it is not invisible is when a tool reads node_modules directly and makes assumptions - older tools occasionally get confused. I have not hit this on dout.dev, but it is the reason some projects still prefer yarn 1 or npm with explicit workspaces.
package.json?Currently there is only the root package.json. If I extracted the template engine into packages/pix-template-engine/, it would have its own package.json with name, version, exports, and dependencies declared there. The main repo would reference it as \"pix-template-engine\": \"workspace:*\".
The workspace:* protocol means \"use the current version in the workspace, whatever that is.\" It is the feature that makes local development across packages painless - you do not npm link, you do not publish to a test registry. You just work across the tree.
These terms get conflated. A monorepo is a repository that contains multiple projects. A workspace is a package-manager feature that supports monorepos. You can have a monorepo without workspaces (you can have a monorepo without any package manager conventions at all, like the Linux kernel). You cannot really have workspaces without a monorepo - it would be pointless.
\nFor dout.dev, I currently have a monorepo-of-one, with workspace tooling ready for the day it becomes a monorepo-of-several.
\nA pnpm workspace on a single-site repo is cheap insurance. It costs nothing today and avoids a migration tomorrow. On a throwaway project, skip it. On a project you expect to live for years, the one-line pnpm-workspace.yaml is worth adding upfront.
workspace: protocolCore Web Vitals are not a complete performance model. They are three numbers Google decided matter for user experience, and they correlate strongly with perceived quality. For a content site, the three are:
\nOn dout.dev the live numbers are well under target on desktop and comfortably under on mobile. This post is what made that achievable, with the specific choices that matter.
\nFor a blog, the LCP element is almost always the post cover image or the first heading. Two decisions dominate.
\nThe cover image is eager and high-priority.
\n<img\n src=\"/assets/images/cover.jpg\"\n alt=\"...\"\n width=\"1200\"\n height=\"630\"\n loading=\"eager\"\n fetchpriority=\"high\"\n decoding=\"async\"\n/>Default loading=\"lazy\" on the LCP image delays the one number that most affects the score. fetchpriority=\"high\" moves the image up in the network queue. Both are opt-in changes from the default behavior, and both are measurable.
The font that renders the LCP text is preloaded.
\n<link rel=\"preload\" as=\"font\" type=\"font/woff2\" href=\"/assets/fonts/Inter-Bold.woff2\" crossorigin />Without preload, the font is discovered when the CSS parses the @font-face rule, which is at least one round trip later. Preloading the weight used in the LCP heading saves a round trip and prevents the \"invisible text\" flash while the font arrives.
No render-blocking third-party resources above the fold. No Google Fonts link, no analytics script in the head, no \"quick chat widget\" that loads before the page. Every third-party script on dout.dev loads after the main content, or not at all on the critical path.
\nLayout shift is mostly a function of elements arriving after layout is computed. Four rules cover 95% of it.
\nEvery image has width and height. The post generator reads the image manifest and emits the attributes. The browser reserves the box at the correct aspect ratio before the pixels arrive.
Web fonts do not shift layout. font-display: swap uses a fallback while the web font loads, and the fallback is chosen to have similar metrics. The metric pair I use for Inter is Arial with size-adjust and ascent-override tuned:
@font-face {\n font-family: 'Inter Fallback';\n src: local('Arial');\n size-adjust: 107%;\n ascent-override: 90%;\n}\n\nbody {\n font-family: 'Inter', 'Inter Fallback', sans-serif;\n}When Inter loads, the text does not visibly shift because the fallback is already sized to match. This is a handful of CSS lines that prevent an entire class of \"text jumped when font arrived\" bugs.
\nEmbedded iframes have reserved space. The Giscus comments shell has a minimum height before the iframe loads. When the iframe arrives and reports its real height, the shell expands downward, which does not affect layout above it.
\nDynamically injected content pushes nothing. The one place that loads content dynamically on dout.dev is the comments. Because they are at the bottom of the page, they cannot shift layout above them.
\nINP replaced FID as the responsiveness metric because FID only measured the first interaction. INP measures every interaction and reports the 75th percentile.
\nThree decisions keep it low.
\nThe main thread is small. Total JavaScript on a post page is under 10KB gzipped. No framework runtime, no hydration, no dev-mode analytics agent. The JS that runs is the theme switcher, the scrollspy, the lazy-load observer, and the search initializer. Each is small and non-blocking.
\nEvent handlers are short.
\ndocument.addEventListener('click', (event) => {\n const toggle = event.target.closest('.theme-toggle');\n if (toggle) handleThemeToggle();\n});A delegated click handler is cheaper than 20 individual ones. The work inside each handler is under 5ms on a mid-tier phone.
\nNo synchronous layout thrashing. When the color-scheme changes, I write to document.documentElement.dataset.colorScheme, which sets an attribute. The browser recomputes styles once on the next animation frame. No forced layout, no offsetWidth reads in a loop.
Lab measurements (Lighthouse) are useful for finding regressions. Field measurements (real users) are the ones that actually count for SEO. For a small site without a backend, the options are:
\nThe library is under 3KB gzipped and the handler is short:
\nimport { onCLS, onLCP, onINP } from 'web-vitals';\n\nfunction send(metric) {\n navigator.sendBeacon('/metrics', JSON.stringify(metric));\n}\n\nonLCP(send);\nonCLS(send);\nonINP(send);Collecting field vitals for a small blog is optional. Collecting them is how you catch regressions that lab tests miss - device variability, network variability, the long tail of \"users on 3G in a basement.\"
\nCore Web Vitals on a static blog are a solved problem if you make the right small choices: eager LCP image, font preload, no third-party critical-path scripts, known image dimensions, font metric matching, a small main thread. Each is a specific, bounded decision. None requires a framework.
\nweb-vitals JavaScript library\"Focus trap\" has a bad reputation because most implementations get it wrong. A trap that is actually a prison - where the user cannot escape with Escape, cannot close with a click outside, and cannot tell that they are trapped - is a bug.
\nA focus trap done right is a kindness. It says: \"while this overlay is open, Tab cycles within it. When you close it, focus returns where it came from. Escape works. Outside click works.\"
\nOn dout.dev the mobile menu, the search dialog, and any future modal follow the same rules. This post is those rules, with code.
\nTwo criteria, both required.
\nIf either is false, do not add a trap. A tooltip trap is a bug.
\nRule 1: remember where focus was.
\nlet previouslyFocused = null;\n\nfunction openOverlay(overlay) {\n previouslyFocused = document.activeElement;\n // ...\n}\n\nfunction closeOverlay(overlay) {\n overlay.hidden = true;\n previouslyFocused?.focus();\n previouslyFocused = null;\n}When the overlay closes, focus returns to the element that opened it. Without this, focus goes to document.body, and the next Tab jumps to the top of the page. Disorienting.
Rule 2: move focus into the overlay on open.
\nfunction openOverlay(overlay) {\n previouslyFocused = document.activeElement;\n overlay.hidden = false;\n\n const firstFocusable = overlay.querySelector(\n 'a[href], button:not([disabled]), input, [tabindex]:not([tabindex=\"-1\"])'\n );\n firstFocusable?.focus();\n}The first interactive element inside the overlay receives focus. Screen readers announce it. Keyboard users are immediately in context.
\nRule 3: cycle Tab within the overlay.
\nfunction trapFocus(event, overlay) {\n if (event.key !== 'Tab') return;\n\n const focusables = overlay.querySelectorAll(\n 'a[href], button:not([disabled]), input, [tabindex]:not([tabindex=\"-1\"])'\n );\n if (focusables.length === 0) return;\n\n const first = focusables[0];\n const last = focusables[focusables.length - 1];\n\n if (event.shiftKey && document.activeElement === first) {\n event.preventDefault();\n last.focus();\n } else if (!event.shiftKey && document.activeElement === last) {\n event.preventDefault();\n first.focus();\n }\n}Tabbing past the last element wraps to the first. Shift+Tab past the first wraps to the last. Anywhere in between, default Tab behavior.
\nRule 4: Escape closes.
\nfunction handleKeydown(event, overlay) {\n if (event.key === 'Escape') {\n event.preventDefault();\n closeOverlay(overlay);\n return;\n }\n trapFocus(event, overlay);\n}Universal expectation. Not optional.
\nRule 5: outside click closes.
\noverlay.addEventListener('click', (event) => {\n if (event.target === overlay) {\n // Click on the backdrop, not a child\n closeOverlay(overlay);\n }\n});If the overlay is a full-screen layer with a visible backdrop, clicking the backdrop is a valid close affordance. Screen reader users have Escape; pointer users have click-outside.
\nclass Overlay {\n constructor(root, { onClose } = {}) {\n this.root = root;\n this.onClose = onClose;\n this.previouslyFocused = null;\n this.handleKeydown = this.handleKeydown.bind(this);\n this.handleClick = this.handleClick.bind(this);\n }\n\n open() {\n this.previouslyFocused = document.activeElement;\n this.root.hidden = false;\n const first = this.getFocusables()[0];\n first?.focus();\n document.addEventListener('keydown', this.handleKeydown);\n this.root.addEventListener('click', this.handleClick);\n }\n\n close() {\n this.root.hidden = true;\n document.removeEventListener('keydown', this.handleKeydown);\n this.root.removeEventListener('click', this.handleClick);\n this.previouslyFocused?.focus();\n this.previouslyFocused = null;\n this.onClose?.();\n }\n\n handleKeydown(event) {\n if (event.key === 'Escape') {\n event.preventDefault();\n this.close();\n return;\n }\n if (event.key !== 'Tab') return;\n\n const focusables = this.getFocusables();\n if (focusables.length === 0) return;\n\n const first = focusables[0];\n const last = focusables[focusables.length - 1];\n\n if (event.shiftKey && document.activeElement === first) {\n event.preventDefault();\n last.focus();\n } else if (!event.shiftKey && document.activeElement === last) {\n event.preventDefault();\n first.focus();\n }\n }\n\n handleClick(event) {\n if (event.target === this.root) this.close();\n }\n\n getFocusables() {\n return this.root.querySelectorAll('a[href], button:not([disabled]), input, [tabindex]:not([tabindex=\"-1\"])');\n }\n}60 lines, reusable, no framework. Every overlay on dout.dev uses it.
\nThe overlay element itself needs the right roles and attributes, not just the JS.
\n<div class=\"overlay\" role=\"dialog\" aria-modal=\"true\" aria-labelledby=\"overlay-title\" hidden>\n <h2 id=\"overlay-title\">Menu</h2>\n <!-- ... -->\n</div>role=\"dialog\" tells assistive tech this is a modal.aria-modal=\"true\" indicates that the rest of the page is inert while the dialog is open.aria-labelledby points to the visible title so screen readers announce it when focus moves in.hidden is the default state; JS toggles it.Without these, the JS trap works for keyboard users but screen readers do not understand that they are in a modal context. Both layers have to agree.
\nsetTimeout(focus, 0) is almost always a sign that the DOM is not ready. Fix the timing, not the symptom.body { overflow: hidden }. Sometimes useful, often jarring. On dout.dev the overlays are full-screen so scroll lock is redundant.inert attribute on the background content is still not uniformly supported. aria-modal=\"true\" is enough for current assistive tech.A focus trap is not the JavaScript pattern. It is the contract: remember where focus was, move focus to the overlay, cycle Tab within it, honor Escape, honor outside click. Sixty lines of code, five rules, one reusable class. Every modal on a well-built site follows the same shape.
\nMost sites ship a Content Security Policy that is effectively \"please stop yelling at me.\" A policy full of unsafe-inline, *, and wildcard sources is better than no policy, but not by much. A strict CSP is achievable on a modern static blog, it stops a large class of attacks dead, and it forces a few discipline improvements that pay off in other places.
On dout.dev the policy is strict enough to block an inline <script> I might write by accident. This post is the policy, the font story that enabled it, and the three gotchas I hit getting there.
Emitted via HTTP headers in production. Also mirrored as a <meta> tag for local preview (with one adjustment - upgrade-insecure-requests belongs in headers, not meta).
Content-Security-Policy:\n default-src 'self';\n base-uri 'self';\n form-action 'self';\n object-src 'none';\n img-src 'self' data: https:;\n font-src 'self';\n media-src 'self';\n manifest-src 'self';\n worker-src 'self';\n script-src 'self' 'unsafe-inline' https://giscus.app;\n style-src 'self' 'unsafe-inline';\n connect-src 'self' https://giscus.app;\n frame-src https://giscus.app https://codepen.io;\n upgrade-insecure-requestsTight, but pragmatic. Three concessions and the reasons for each.
\n'unsafe-inline' in script-src. Two inline scripts survive in the head: the theme pre-paint resolver and the file-preview banner. Neither accepts user input. Both could be moved to nonce-based CSP, but for a blog with a single deployment origin the cost of a nonce (rewriting the build to inject a fresh nonce per response) exceeds the benefit.
'unsafe-inline' in style-src. A few critical CSS declarations are inlined for performance (the file-preview banner, the theme bootstrap). Same reasoning. For a team product I would invest in a nonce; for a blog I did not.
https://giscus.app allowed on script-src, connect-src, frame-src. Giscus is a third-party comment system. It runs a script in the page, connects back to its own domain, and embeds an iframe. All three are required for the feature to work.
Everything else is 'self' or 'none'. No CDNs, no third-party analytics, no embed farms.
font-src 'self' possibleA common CSP mistake is leaving font-src wide-open because \"we use Google Fonts.\" The fix is to stop using Google Fonts as a third-party dependency and serve the fonts from your own origin.
The practical benefit is not just security. It is performance: one fewer DNS lookup, one fewer TLS handshake, one fewer cross-origin preconnect. For the LCP on a content-heavy page, that is measurable.
\nThe mechanics:
\nsrc/assets/fonts/.@font-face rules pointing at the local files.@font-face {\n font-family: 'Inter';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url('/assets/fonts/Inter-Regular.woff2') format('woff2');\n}\n\n@font-face {\n font-family: 'Inter';\n font-style: normal;\n font-weight: 700;\n font-display: swap;\n src: url('/assets/fonts/Inter-Bold.woff2') format('woff2');\n}<link rel=\"preload\" as=\"font\" type=\"font/woff2\" href=\"/assets/fonts/Inter-Regular.woff2\" crossorigin />font-display: swap tells the browser to use the fallback font until the custom one loads. It prevents the \"invisible text flash\" that font-display: block can cause.
The crossorigin on the preload is required even for same-origin fonts. Without it, the browser downloads the font twice - once for the preload, once for the actual request - because the cache key differs. One attribute, a real performance win.
The strict policy broke three things before it worked. Each is worth calling out.
\n<!-- Breaks under strict CSP -->\n<button onclick=\"doThing()\">Click</button>Every inline on* handler in the codebase got refactored into addEventListener calls in a shared script. Not hard, but easy to miss - and the browser console tells you exactly where the CSP violated, so it is a mechanical cleanup.
data: images are commonly blockedimg-src 'self' data: https:;The data: source is explicitly listed because inline SVGs and base64-encoded small images (favicons, icons) use data: URIs. Without that, the placeholders break.
https: is included because external cover images reference HTTPS URLs. Tight enough to keep out http: and file:; permissive enough to not break the CMS when a post links an external image.
worker-src 'self'Omitted from the policy, the service worker fails to register and there is nothing in the console that clearly says why. worker-src 'self' makes it work.
The policy will break something in the future. A new feature, a new library, a copy-pasted embed. The way to find out is to wire up a CSP report endpoint.
\nContent-Security-Policy:\n ...;\n report-to csp-endpoint;\n report-uri /csp-report;On a static site there is no endpoint to receive the reports. I use report-uri.com or a simple edge function to receive violations. The first time something breaks in production, the report arrives before the complaint does.
'self' on scripts, an injected <script src=\"evil.com/x.js\"> does not execute.frame-ancestors 'none' (not in the policy above, worth adding) plus the appropriate X-Frame-Options header stops the page from being embedded.form-action 'self' means a forged form cannot POST to an attacker's domain.A strict CSP on a modern static site is achievable and not exotic. The enabling moves are serving fonts from the same origin, removing inline event handlers, and being honest about the third-party embeds you need. Everything else is 'self' or 'none'.
font-display - MDNA theme switcher looks simple. Light mode, dark mode, auto. Maybe an accent color. In practice it has three common bugs I see in almost every implementation.
\nThe switcher on dout.dev addresses each explicitly. The code is under 50 lines.
\nThe switcher only works because the CSS is already token-driven. Every component reads semantic tokens; semantic tokens are defined on :root and overridden per theme.
:root {\n --color-bg: var(--surface-1);\n --color-fg: var(--text-primary);\n --color-accent: #ff6b3d;\n}\n\n[data-color-scheme='light'] {\n --color-bg: #fafafa;\n --color-fg: #1a1a1a;\n}\n\n[data-color-scheme='dark'] {\n --color-bg: #0b0b0f;\n --color-fg: #e7e7ef;\n}\n\n@media (prefers-color-scheme: dark) {\n :root:not([data-color-scheme]) {\n --color-bg: #0b0b0f;\n --color-fg: #e7e7ef;\n }\n}The rules:
\n:root defines the defaults (the \"auto\" case without system preference).[data-color-scheme='light'] and [data-color-scheme='dark'] override for explicit choices.@media (prefers-color-scheme: dark) block kicks in only when no explicit data-color-scheme is set - the :not([data-color-scheme]) selector - so user choice always wins over system preference.The browser must know the theme before it paints the first frame. That means the theme resolution happens in an inline script in the <head>, before any CSS that depends on it.
<script>\n (function () {\n try {\n var stored = localStorage.getItem('color-scheme');\n var stored_accent = localStorage.getItem('accent');\n if (stored === 'light' || stored === 'dark') {\n document.documentElement.dataset.colorScheme = stored;\n }\n if (stored_accent) {\n document.body.dataset.accent = stored_accent;\n }\n } catch (_) {\n /* localStorage unavailable */\n }\n })();\n</script>This script is blocking and synchronous and that is exactly what you want. It runs before the body parses, sets the attribute, and the initial CSS cascade applies the correct theme before paint.
\nIf the user has never made a choice, no attribute is set, and the prefers-color-scheme media query rules. That is the \"auto\" path.
The toggle is a button that cycles Auto → Dark → Light → Auto. The current state is mirrored to aria-pressed or announced via text for screen readers.
<button class=\"theme-toggle\" aria-label=\"Change theme\">\n <span class=\"theme-toggle__label\">Auto</span>\n</button>const toggle = document.querySelector('.theme-toggle');\nconst label = toggle.querySelector('.theme-toggle__label');\nconst order = [null, 'dark', 'light'];\n\nfunction setTheme(value) {\n if (value === null) {\n delete document.documentElement.dataset.colorScheme;\n localStorage.removeItem('color-scheme');\n label.textContent = 'Auto';\n } else {\n document.documentElement.dataset.colorScheme = value;\n localStorage.setItem('color-scheme', value);\n label.textContent = value === 'dark' ? 'Dark' : 'Light';\n }\n}\n\ntoggle.addEventListener('click', () => {\n const current = document.documentElement.dataset.colorScheme ?? null;\n const next = order[(order.indexOf(current) + 1) % order.length];\n setTheme(next);\n});\n\nconst currentOnLoad = document.documentElement.dataset.colorScheme ?? null;\nlabel.textContent = currentOnLoad === null ? 'Auto' : currentOnLoad === 'dark' ? 'Dark' : 'Light';The initial label.textContent assignment is subtle: on page load, the inline script has already applied the theme, so we read back from the DOM to render the correct label.
In \"auto\" mode, when the OS switches theme, the site should update live. The matchMedia API emits change events:
const media = matchMedia('(prefers-color-scheme: dark)');\nmedia.addEventListener('change', () => {\n // The CSS handles the color change automatically via the media query.\n // Nothing for us to do - the media query in CSS observes the same source.\n});Actually, nothing for us to do. The CSS already responds to the system change; this event is only useful if you want to mirror the state somewhere in the UI. If the toggle's label shows \"Auto,\" the visible state on screen updates naturally through CSS.
\nAccent is orthogonal to light/dark. A user can pick a dark theme with a green accent or a light theme with a violet accent. The primary accent is a separate attribute on body.
body[data-accent='violet'] {\n --color-accent: #8b5cf6;\n}\nbody[data-accent='green'] {\n --color-accent: #22c55e;\n}The picker is a radio group or a row of swatches. Selection writes to body[data-accent] and persists to localStorage.
The one detail that makes this land: the CSS --color-accent is referenced by derived tokens (like --color-accent-soft via color-mix()), so the whole accent-tinted surface updates in one paint.
Giscus is an iframe, so its theme does not inherit from the parent page CSS. The page has to postMessage the theme into the iframe whenever it changes.
\nfunction syncGiscusTheme(theme) {\n const frame = document.querySelector('iframe.giscus-frame');\n if (!frame) return;\n const giscusTheme = theme === 'dark' ? 'dark' : 'light';\n frame.contentWindow?.postMessage({ giscus: { setConfig: { theme: giscusTheme } } }, 'https://giscus.app');\n}A MutationObserver on document.documentElement watches for data-color-scheme changes and calls syncGiscusTheme. That keeps comments visually in sync with the rest of the page. Without this, switching from dark to light leaves the comments in a contrast mismatch.
The toggle is a real <button>, which means it is keyboard-focusable by default. Its focus ring uses :focus-visible, and clicking it does not steal focus.
For users with prefers-reduced-motion: reduce, the accent color transition is disabled. That is a two-line CSS rule:
body {\n transition:\n background-color 0.2s,\n color 0.2s;\n}\n\n@media (prefers-reduced-motion: reduce) {\n body {\n transition: none;\n }\n}A theme switcher that does not flash, respects the system, persists the user's choice, and syncs third-party iframes is about 50 lines of code and one well-structured CSS layer. The trick is the inline pre-paint script and the attribute-plus-media-query architecture. Neither requires a framework.
\nprefers-color-scheme - MDNmatchMedia - MDNcolor-mix() - MDNI've been writing CSS since before border-radius was a thing, back when we used -moz-border-radius and prayed everything to work well.
I've seen preprocessors rise (LESS, Sass, Stylus, the holy war... what a mess) and watched CSS itself absorb every feature they offered, one spec at a time.
\nAnd through all of it, one thing never changed: the absolute chaos of an unorganized ruleset.
\nWe all know about this: 400 lines of CSS where color: red is followed by position: absolute followed by three vendor-prefixed gradients followed by a font-size that overrides the one fifty lines up. It's not wrong, the cascade still resolves it, the browser still paints it, but it's unnecessary friction.
Every time you touch that file, you waste a few seconds scanning for what you need. Those seconds add up to hours. Those hours add up to bugs.
\nSo I developed a system. A hierarchy that mirrors the browser's own rendering pipeline: outside-in, layout-first, paint-last.
\nThe way I see it, every CSS ruleset tells a story, and the story has a logical narrative arc. The order isn't arbitrary - it's the same order the browser processes properties: computed values → layout → paint → compositing.
\nEvery time I break this order, I introduce a subtle cognitive tax on the next reader, myself included. Every time I follow it, the ruleset reads like a coherent paragraph instead of a shopping list.
\n1. Custom properties. These come first because they're the inputs. They're resolved by the cascade before any property does anything. You want them declared before they're consumed, and grouping them at the top makes the ruleset's \"API surface\" immediately visible.
\n2. Position. Next, because it takes the element out of flow before you even think about sizing or coloring it. Setting position: absolute after width is technically fine, but logically backwards - you're picking a layout strategy for the element before you decide its dimensions.
3. Display. Right after position, because it determines the formatting context. Flex, grid, block - the element needs to know how to be a box before you can meaningfully set gap, place-content, or align-items.
4. Opacity & visibility. These affect the box's presence without touching layout. They're the border between layout and paint.
\n5. Box-model. The geometry: inside-out - content size first, then padding, then border, then margin. box-sizing at the top of the section because it changes the math for everything below.
6. Colors & background. The paint layer. Text color, background, shadows, filters. These trigger repaints but not re-layouts (mostly).
\n7. Typography. After you've painted the background, you render the text on top. font, line-height, text-align, white-space, text-shadow.
8. Transforms & animations. The compositor stage. transform, transition, animation. These are the last thing that happens visually, but also the most performance-sensitive - having them in one block makes it easy to audit will-change usage.
9. Helpers. appearance, cursor, pointer-events - utility properties that don't fit anywhere else.
10. Pseudo-elements. &::before, &::after - they're part of the element's visual tree, nested inside.
11. Variants & pseudo-selectors. State changes: &.error, &[aria-hidden], &:hover. These override everything above, so they come last in the declaration block.
12. Media queries & children. Scoping. @media, & span, & > *. These are new contexts that restart the hierarchy - each is a fresh ruleset that follows the same order.
:root {\n --border-radius: 5px;\n}\n\n.element {\n /* css custom properties */\n --var--example: 1;\n\n /* position */\n position: absolute;\n inset: 0; /* top, right, bottom, left */\n z-index: 1;\n\n /* display */\n display: block;\n display: flex;\n place-content: center;\n place-items: center;\n justify-self: unset;\n gap: 1rem;\n\n opacity: 1;\n visibility: visible;\n\n /* box-model */\n box-sizing: border-box;\n width: 10rem;\n aspect-ratio: 16 / 9;\n padding: 1rem;\n border: 0.1rem solid black;\n border-radius: 0.4rem;\n margin: 1rem;\n outline: 0.3rem solid black;\n outline-offset: 0.3rem;\n\n /* colors & background */\n color: white;\n background-color: black;\n background-image: url();\n box-shadow: rgba(50, 50, 50, 1);\n filter: drop-shadow();\n\n /* text */\n font-family: 'Courier New', Courier, monospace;\n font-size: 1rem;\n font-weight: 700;\n line-height: normal;\n white-space: nowrap;\n text-align: center;\n text-shadow: none;\n\n /* transform & animations */\n transform: translate();\n transition: opacity 300ms ease-in, width 500ms linear;\n will-change: opacity, width;\n animation: test 300ms forwards alternate-reverse;\n\n /* helpers */\n appearance: none;\n cursor: pointer;\n pointer-event: none;\n\n /* pseudo elements */\n &::after {\n }\n\n /* variants & pseudo selectors */\n &.error {\n color: red;\n }\n\n &[aria-hidden=true] {\n display: none;\n }\n\n /* pseudo selectors */\n &:hover {\n }\n\n /* media queries */\n @media screen and (width >= 1024px) {\n /* repeat css hierarchy here */\n }\n\n /* ------------ children */\n span {\n /* repeat css hierarchy here */\n }\n\n input {\n /* repeat css hierarchy here */\n }\n\n > * {\n /* repeat css hierarchy here */\n }\n}Look at that ruleset. Now look at your last project's CSS. If the two don't look alike, you know what to do.
\nI'm not going to tell you this hierarchy is the One True Way™ - I've been in this game long enough to know that CSS is a language, not a religion, and anyone who tells you there's exactly one correct way to order properties is selling something (probably a linter rule they wrote). But I will tell you this: having any consistent order is infinitely better than having no order at all. The specific convention matters less than the fact that you have one and you follow it.
\nWhat I will claim is that this specific hierarchy has survived three major migrations, six codebases, twelve team members with varying skill levels, and zero arguments. Because it's not \"my opinion\" - it's the browser's rendering pipeline encoded as property order. You can't argue with the spec. Well, you can, but you'll lose.
\nThe beautiful thing is that once you internalize this order, you stop thinking about it. You just write properties in the order they naturally fall in your head, and they happen to match the hierarchy. It becomes as automatic as indenting nested blocks or putting spaces after commas. The ruleset writes itself, and the next person who opens that file doesn't curse your name. That's the real win.
\nAnd yeah, about the preprocessor thing: I started using this hierarchy back when I was writing Sass. When CSS custom properties landed in browsers, I realized --my-var slotted perfectly into the top section of the hierarchy - custom properties first, always. Nesting (& at the bottom for variants, pseudo-elements, children) was already how I organized Sass. The hierarchy didn't change when the tooling changed. The language caught up to the discipline.
That's when it clicked: the hierarchy wasn't a Sass convention. It was a CSS convention that happened to work in Sass. And once native CSS nesting landed in 2023, I deleted my last @use 'sass', not because I hate Sass (I don't), but because the hierarchy made it irrelevant. Discipline beats tooling every time. Always has.
So here's my challenge: pick any ruleset in your current project. Reorder it using this hierarchy. Don't change a single value, just move the lines around. Then read it again. I bet you find a bug, or a duplicate property you didn't notice, or an override that doesn't do what you thought. The hierarchy surfaces that stuff because related things are next to each other instead of scattered across 80 lines.
\nAnd when you find that bug, think about this: the hierarchy found it, not a linter. A linter can tell you \"duplicate property detected.\" The hierarchy tells you why it's a duplicate and which one wins.
\nTold you. CSS is a language, not a config file.
\n", "image": "https://dout.dev/assets/og/posts/2026-07-05-css-properties-hierarchy.png", "date_published": "2026-07-05T00:00:00.000Z", "tags": [ "html", "css" ] }, { "id": "https://dout.dev/posts/2026-07-04-pragmatic-service-worker.html", "url": "https://dout.dev/posts/2026-07-04-pragmatic-service-worker.html", "title": "A Pragmatic Service Worker: Cache Strategy, Offline, No Abuse (80 Lines, No Drama)", "summary": "The case against most service workers", "content_html": "Service workers are the feature most likely to end up on a \"cool feature I added and then forgot about\" list. The tradeoffs are real:
\nGiven all that, why ship one? For a blog: the offline page. For a PWA: the install experience and the background resilience. For dout.dev, both.
\nWhat I refuse to do is cache everything, intercept every request, and ship an SW that tries to be a runtime framework. The dout.dev SW is about 80 lines. This post is what is in it.
\nThree jobs, in order of importance.
\nEverything else - images, feeds, analytics beacons, third-party assets - is not intercepted.
\nAt install time, the SW precaches exactly the files needed to render the offline experience. That list is generated by the build and inlined into the SW file, so there is no manifest to drift.
\nconst PRECACHE = 'dout-precache-v1';\nconst RUNTIME = 'dout-runtime-v1';\n\nconst PRECACHE_URLS = ['/', '/offline.html', '/styles/index.css', '/scripts/main.js', '/assets/favicon.svg'];\n\nself.addEventListener('install', (event) => {\n event.waitUntil(caches.open(PRECACHE).then((cache) => cache.addAll(PRECACHE_URLS)));\n});The precache name includes a version (-v1). Bumping that version on a release invalidates the precache cleanly.
On activation, old caches get deleted. Without this, users accumulate dead caches forever.
\nself.addEventListener('activate', (event) => {\n const valid = new Set([PRECACHE, RUNTIME]);\n event.waitUntil(\n caches.keys().then((names) => Promise.all(names.filter((n) => !valid.has(n)).map((n) => caches.delete(n))))\n );\n self.clients.claim();\n});self.clients.claim() takes control of existing tabs on the first activation, so the new SW is in charge immediately instead of after a full reload. That is a judgment call - some projects prefer to wait for a reload to avoid mid-session inconsistencies. For a read-only blog, claiming is safe.
The fetch handler has three branches, and each is small.
\nFor navigation (a page load), try the network first. If the network wins, cache the response for later. If the network fails, serve the cached version, and if that is missing, the offline page.
\nself.addEventListener('fetch', (event) => {\n const req = event.request;\n if (req.mode === 'navigate') {\n event.respondWith(\n fetch(req)\n .then((res) => {\n const copy = res.clone();\n caches.open(RUNTIME).then((cache) => cache.put(req, copy));\n return res;\n })\n .catch(() => caches.match(req).then((cached) => cached || caches.match('/offline.html')))\n );\n return;\n }\n // ...\n});Network-first for HTML means readers always get the freshest post when they are online. The cache is a fallback, not a source of truth.
\nFor CSS, JS, and fonts on the same origin, cache-first with a background revalidate. This is the classic stale-while-revalidate pattern:
\nif (req.destination === 'style' || req.destination === 'script' || req.destination === 'font') {\n event.respondWith(\n caches.match(req).then((cached) => {\n const networkFetch = fetch(req).then((res) => {\n const copy = res.clone();\n caches.open(RUNTIME).then((cache) => cache.put(req, copy));\n return res;\n });\n return cached || networkFetch;\n })\n );\n return;\n}Returning cached content immediately keeps the page fast; the background fetch updates the cache for next time. The trade-off is that the first load after a deploy serves the old bundle, and the fresh one is picked up on the next navigation. For a blog, that is acceptable.
\nImages, feeds, third-party URLs, analytics beacons - pass through to the network without touching the cache. The SW explicitly does not intercept.
\n// fall through to the networkNot caching something is a decision too. It avoids the trap of caching things you never meant to cache and then not being able to invalidate them.
\noffline.html is a static page with the branding and a short message. It links to the home (which might be cached) and includes a small retry button that reloads the page.
The only trick: the offline page must not reference uncached resources. If the offline CSS is not in the precache, the page still renders but unstyled. The precache list above includes the main CSS, so this works.
\nThe SW updates itself when the browser fetches /sw.js and notices it differs byte-for-byte from the registered one. Because the precache list contains a version string, a deploy that bumps the precache version triggers an update.
For a blog, that is enough. I do not ship an explicit \"update available\" banner. The user gets the new SW on the next navigation after a deploy, and the cleanup handler deletes the old cache.
\nEach of these is a feature I could add later without restructuring the SW. Keeping the current one small is the point.
\nA service worker on a blog is worth the 80 lines if you ship the three jobs: offline fallback, shell precache, and a conservative runtime cache for repeat visits. Resist the urge to intercept every request. The bugs you avoid by caching less are worth more than the performance gains from caching more.
\nNative loading=\"lazy\" on <img> and <iframe> is a browser-managed hint. The browser decides when to load based on its own heuristics, and it usually does a good job. IntersectionObserver is a programmable primitive that tells your code exactly when an element enters a viewport band. Both are useful. They are not the same thing, and treating them as interchangeable is how you end up with images that load too late or scripts that fire too early.
This post is the mental model I use to pick between them.
\nFor most images on a blog, native lazy loading is correct and sufficient.
\n<img src=\"keyboard.jpg\" alt=\"A keyboard on a wooden desk\" width=\"1920\" height=\"1280\" loading=\"lazy\" decoding=\"async\" />What this gets you, for free:
\ndecoding=\"async\" hint tells the browser it can decode off the main thread.width and height reserve the aspect-ratio box so there is no layout shift when the image eventually arrives.The browser's heuristic is not perfect, but it is tuned for the 80% case of scrolling pages. If your images are content images on a standard reading flow, loading=\"lazy\" does the job.
Three situations where you should not use loading=\"lazy\", or where you have to combine it with IntersectionObserver.
The image that is going to be your Largest Contentful Paint should load eagerly. Setting loading=\"lazy\" on an LCP image delays the one number that most affects your page quality metric.
<img src=\"hero.jpg\" alt=\"Hero image\" width=\"1200\" height=\"800\" loading=\"eager\" fetchpriority=\"high\" />fetchpriority=\"high\" tells the browser this resource should be prioritized over others. Use it sparingly - if everything is \"high\", nothing is. One LCP candidate per page.
<source> inside <picture>loading=\"lazy\" on an <img> inside a <picture> applies to the image as a whole. But the <source> elements inside the picture have already been evaluated by the time the browser decides whether to defer the image. The browser will still download a WebP variant even if the fallback <img> is lazy.
For large below-the-fold <picture> blocks, the fix is to store the srcset in data-srcset and swap it with IntersectionObserver when the element is near the viewport.
<picture>\n <source\n type=\"image/webp\"\n data-srcset=\"/img/hero-320.webp 320w, /img/hero-640.webp 640w\"\n sizes=\"(max-width: 640px) 100vw, 640px\"\n />\n <img src=\"/img/hero.jpg\" alt=\"...\" width=\"1920\" height=\"1280\" loading=\"lazy\" />\n</picture>const io = new IntersectionObserver(\n (entries) => {\n for (const entry of entries) {\n if (!entry.isIntersecting) continue;\n const source = entry.target;\n source.srcset = source.dataset.srcset;\n source.removeAttribute('data-srcset');\n io.unobserve(source);\n }\n },\n { rootMargin: '200px' }\n);\n\ndocument.querySelectorAll('source[data-srcset]').forEach((s) => io.observe(s));This is the only reliable way I have found to avoid eager downloads of large WebP variants for below-the-fold pictures.
\nGiscus, CodePen embeds, video embeds: these are expensive third-party resources that you do not want to load on every page view. loading=\"lazy\" on the iframe helps, but you often want stricter control - load only when the user scrolls close, or only when a \"Show comments\" button is pressed.
<div class=\"comments-shell\" data-giscus-src=\"https://giscus.app/client.js\" data-giscus-attrs='{ \"data-repo\": \"...\" }'>\n <button type=\"button\" class=\"load-comments\">Load comments</button>\n</div>document.querySelector('.load-comments')?.addEventListener('click', (e) => {\n const shell = e.target.closest('.comments-shell');\n const attrs = JSON.parse(shell.dataset.giscusAttrs);\n const script = document.createElement('script');\n script.src = shell.dataset.giscusSrc;\n for (const [k, v] of Object.entries(attrs)) script.setAttribute(k, v);\n script.crossOrigin = 'anonymous';\n script.async = true;\n shell.appendChild(script);\n e.target.remove();\n});The cost of opting into \"click to load\" for comments is one button and a 20-line handler. The benefit is a significantly smaller critical path for readers who do not engage with comments.
\nOn dout.dev I ship the Giscus embed lazily via data-loading=\"lazy\" and do not hide it behind a button, because comments are part of the editorial experience. On a page with heavier embeds, the button pattern is the right default.
loading=\"eager\" + fetchpriority=\"high\".loading=\"lazy\".<source> inside a <picture> below the fold? → IntersectionObserver with data-srcset swap.Everything else is a variation.
\nI do not reinvent native lazy for plain images. I do not ship a \"lazyload.js\" dependency. I do not observe scroll events. IntersectionObserver is already in every target browser and has been for years.
\nNative lazy is a good default. Use it first. Reach for IntersectionObserver when the browser's heuristic is not under your control (nested picture sources, third-party iframes, expensive runtime costs). The two tools complement each other; they do not compete.
\nloading attribute - MDNfetchpriority - MDNA long post benefits from a sidebar outline that highlights the current section as the user scrolls. On a blog with 1500-word articles, it is the difference between a linear reading experience and a navigable document.
\nMost scrollspy implementations have three accessibility problems.
\ntabindex=\"0\" on every h2 is a trap, not a feature.aria-current that changes several times per second during scroll, which turns the outline into a screaming live region.This post is the design I landed on after tripping over all three.
\nThe outline is a normal <nav> with a list of anchor links to heading IDs. That is the document you would get from a static site with no JavaScript. Everything else is enhancement.
<aside class=\"post-outline\">\n <nav aria-label=\"Article outline\">\n <ol>\n <li>\n <a href=\"#the-feature-and-its-trap\">The feature and its trap</a>\n </li>\n <li>\n <a href=\"#the-dom-shape\">The DOM shape</a>\n </li>\n <li>\n <a href=\"#observing-headings-not-scroll\">Observing headings, not scroll</a>\n </li>\n </ol>\n </nav>\n</aside>Without JS: you get a jump-link navigation. With JS: the active link gets aria-current=\"location\" based on what is currently visible.
The post generator emits IDs on every heading (## The DOM shape → id=\"the-dom-shape\"). It also adds tabindex=\"-1\" to headings, so they can receive programmatic focus when a user activates an outline link. Without that, focus remains on the link that was activated, and the next tab stop is inside the link list instead of the section body.
<h2 id=\"the-dom-shape\" tabindex=\"-1\">The DOM shape</h2>tabindex=\"-1\" makes the heading programmatically focusable without adding it to the tab order. That is the shape you want for anchor targets. tabindex=\"0\" would make every heading a tab stop and is wrong.
Listening to scroll and computing which heading is \"current\" is a trap. It fires constantly, it does not know about the viewport's relevance cone, and it forces you to recompute heading positions on resize.
The right primitive is IntersectionObserver. Point it at the headings with a top-biased root margin, and let it tell you when headings enter or leave the relevance zone.
\nconst headings = document.querySelectorAll('article h2[id], article h3[id]');\nconst outline = document.querySelector('.post-outline');\n\nlet currentId = null;\n\nconst io = new IntersectionObserver(\n (entries) => {\n for (const entry of entries) {\n if (entry.isIntersecting) {\n currentId = entry.target.id;\n }\n }\n if (currentId) updateOutline(currentId);\n },\n {\n rootMargin: '-20% 0px -70% 0px',\n threshold: 0,\n }\n);\n\nfor (const h of headings) io.observe(h);The rootMargin shrinks the \"active\" band to the upper part of the viewport. A heading is \"current\" when it enters that band, which matches the reader's expectation.
The update function removes aria-current from all outline links and adds it only to the active one. That is a tiny DOM change, not a re-render.
function updateOutline(id) {\n const active = outline.querySelector('[aria-current]');\n if (active) active.removeAttribute('aria-current');\n\n const next = outline.querySelector(`a[href=\"#${CSS.escape(id)}\"]`);\n if (next) next.setAttribute('aria-current', 'location');\n}aria-current=\"location\" is the correct value for \"this link points at the user's current location in the document.\" aria-current=\"page\" is wrong here; that one is for pagination or site navigation.
IntersectionObserver is already asynchronous and batched. Callbacks fire at animation-frame cadence at most, and only when the observed elements actually cross a threshold. No requestAnimationFrame wrapper, no throttle, no debouncer. Writing one of those on top of IntersectionObserver is a code smell.
When the user clicks an outline link, the default behavior jumps to the anchor. On dout.dev the behavior is enhanced: smooth-scroll to the heading, then move focus to the heading so that subsequent tab keys land inside the section.
\noutline.addEventListener('click', (e) => {\n const link = e.target.closest('a[href^=\"#\"]');\n if (!link) return;\n e.preventDefault();\n\n const id = decodeURIComponent(link.hash.slice(1));\n const target = document.getElementById(id);\n if (!target) return;\n\n target.scrollIntoView({ behavior: 'smooth', block: 'start' });\n target.focus({ preventScroll: true });\n\n history.pushState(null, '', `#${id}`);\n});Two subtleties.
\npreventScroll: true on focus. Without it, focus() scrolls the heading to the top of the viewport, which fights the smooth-scroll animation.
history.pushState instead of assigning location.hash. Setting the hash re-triggers the native jump and cancels the smooth scroll. Pushing the URL manually gives the user a shareable link without breaking the animation.
Anyone with prefers-reduced-motion: reduce gets an instant scroll instead of smooth.
const reduceMotion = matchMedia('(prefers-reduced-motion: reduce)').matches;\ntarget.scrollIntoView({\n behavior: reduceMotion ? 'auto' : 'smooth',\n block: 'start',\n});The cost is one line. The benefit is that users with vestibular sensitivity do not get attacked by your animations.
\nA good scrollspy is three primitives the platform already gives you: IDs on headings, tabindex=\"-1\" on the targets, and IntersectionObserver for the activation logic. Anything more than that is a leak.
aria-current - W3C ARIAtabindex - HTML Living Standardprefers-reduced-motion - MDNSyntax highlighting on a blog is one of those problems with three plausible solutions, all of which bring a tax.
\nFor dout.dev I wanted something smaller than all three, with full control over the CSS tokens. The result is pix-highlighter, a custom element that takes the markdown fenced-code output, tokenizes on the client with a small lexer, and emits <span> tags keyed to design system tokens.
That choice has trade-offs. This post explains them honestly.
\nThe markdown renderer does not highlight. It emits structural markup:
\n<pre is=\"pix-highlighter\" lang=\"js\">\n <code>function hello() { return 42; }</code>\n</pre><pre is=\"pix-highlighter\" lang=\"js\"> is a customized built-in element. It upgrades <pre> with new behavior while keeping the semantic element intact. Screen readers and copy-paste behave correctly; the upgrade is purely visual.
The element is under 300 lines. It knows how to:
\nlang and pick the lexer.{ type, value } tuples.<span class=\"tok-<type>\"> wrapping the tokens.copy button that puts the raw source on the clipboard.class PixHighlighter extends HTMLPreElement {\n connectedCallback() {\n const code = this.querySelector('code');\n if (!code || this.dataset.highlighted) return;\n\n const lang = this.getAttribute('lang');\n const lexer = LEXERS[lang];\n if (!lexer) return;\n\n const tokens = lexer(code.textContent);\n code.innerHTML = tokens.map((t) => `<span class=\"tok-${t.type}\">${escapeHtml(t.value)}</span>`).join('');\n\n this.dataset.highlighted = 'true';\n this.appendCopyButton(code.textContent);\n }\n}\n\ncustomElements.define('pix-highlighter', PixHighlighter, { extends: 'pre' });The element only runs where <pre is=\"pix-highlighter\"> exists in the DOM. The bulk of the site - every page without a code block - pays nothing for it.
Each lexer is a single function that walks the string once and emits tokens. The language coverage is intentionally narrow: JS, TS, CSS, HTML, JSON, Bash, Python, Go, Rust, C, C++, PHP, C#, YAML, Markdown.
\nfunction lexJs(source) {\n const tokens = [];\n let i = 0;\n while (i < source.length) {\n const rest = source.slice(i);\n let m;\n if ((m = rest.match(/^\\/\\/[^\\n]*/))) {\n tokens.push({ type: 'comment', value: m[0] });\n } else if ((m = rest.match(/^\"(?:[^\"\\\\]|\\\\.)*\"/))) {\n tokens.push({ type: 'string', value: m[0] });\n } else if ((m = rest.match(/^\\b(function|return|const|let|var|if|else|for)\\b/))) {\n tokens.push({ type: 'keyword', value: m[0] });\n } else if ((m = rest.match(/^\\d+(?:\\.\\d+)?/))) {\n tokens.push({ type: 'number', value: m[0] });\n } else if ((m = rest.match(/^\\s+/))) {\n tokens.push({ type: 'ws', value: m[0] });\n } else {\n tokens.push({ type: 'text', value: source[i] });\n i += 1;\n continue;\n }\n i += m[0].length;\n }\n return tokens;\n}This is not correct in the \"TextMate-grade\" sense. It does not understand JSX, template literal interpolation, or JSDoc. It is correct enough for blog code samples, which are short, self-contained, and visually parseable.
\nIf I wanted the last 5% of fidelity, I would use Shiki. I did not.
\nBecause the element emits <span class=\"tok-string\"> and similar, the CSS lives in the design system. Colors reference semantic tokens, which means the highlighter follows the theme switcher automatically.
pre[is='pix-highlighter'] {\n background: var(--color-code-bg);\n color: var(--color-code-fg);\n padding: var(--space-4);\n border-radius: var(--radius-2);\n font: var(--font-mono);\n}\n\n.tok-comment {\n color: var(--color-code-comment);\n font-style: italic;\n}\n.tok-string {\n color: var(--color-code-string);\n}\n.tok-keyword {\n color: var(--color-code-keyword);\n font-weight: 600;\n}\n.tok-number {\n color: var(--color-code-number);\n}No separate \"light theme\" and \"dark theme\" stylesheets. One set of rules, driven by semantic tokens, which flip based on data-color-scheme.
The copy-to-clipboard button has a visible label and an accessible name. The <pre> has a semantic code region, the <code> inside keeps the text content intact, and the token spans are decorative - aria-hidden would be wrong because they do contain the text the screen reader should read; the tokens are styling, not semantics.
On a keyboard-only pass, the copy button receives focus with a visible ring, press fires the copy, and aria-live=\"polite\" on a sibling span announces \"Copied.\"
If the blog needed twenty languages with accurate semantic highlighting (JSX, template literals, complex macro systems), the cost of maintaining a handwritten lexer family would exceed the cost of adopting Shiki at build time. The trade-off is genuinely a spectrum.
\nThe cutoff I used: fewer than twenty languages, short code samples, theme integration matters, bundle size matters, fidelity at the 95% level is acceptable. Write your own. Otherwise, use Shiki.
\nCustom elements are underrated. A ~300-line pix-highlighter replaces a dependency I would have carried forever, integrates with the design system instead of a theme file, and only runs where it is needed. That pattern - small, scoped, declarative - fits the rest of dout.dev.
I will get the math out of the way first, because the cost is the part that surprises people.
\nread, write, edit, bash) plus three opt-in read-only ones (grep, find, ls). No plan mode, no sub-agents, no permission popups, no IDE lock-in.That is the actual economic story of this combination. It is not a benchmark artifact. It is the loop I work in every day. This post is the full setup, the daily workflow, the cost math, the things it does not do well, and why I now treat it as the default.
\nPi is the work of Mario Zechner, now maintained under the earendil-works GitHub organization. It is a terminal-native coding harness: you run it, it reads your repo, it proposes edits, it runs shell commands, and you review every change before it lands on disk. The repository sits at around 66.5K stars, and it has a very strong opinion about what a coding agent should be.
The opinion is minimalism without being stupid.
\nPi ships with exactly four core tools: read, write, edit, and bash. Three more, grep, find, and ls, are available as opt-in read-only tools. That is the entire built-in surface. Everything else is a TypeScript extension, a skill, a prompt template, or a theme. There is no plan mode because you can write a prompt template that asks the model to plan first. There is no sub-agent system because you can write a skill that delegates. There is no permission system because you are expected to read the diff before the model writes to disk.
That last point is the one most people miss. Pi does not remove safety. Pi removes friction. You still review every change. You still see the exact command before it runs. You still decide when the loop is done. What you give up is a layer of confirmation dialogs that, in my experience, do not actually catch the kind of mistakes that matter and mostly just slow down the parts of the work that are already correct.
\nAnd the entire thing is open source at its core. The repository at github.com/earendil-works/pi is MIT-licensed, and everything - the core loop, the tool harness, the MCP bridge, the provider abstraction - is readable, forkable, and hackable. You can strip it down, patch it, or build your own distribution. There is no proprietary layer, no closed-source enterprise edition, no telemetry-gated feature. The CLI, the TUI, the extension system, and the skill loader are all there in plain TypeScript.
\nThe consequence is that the extension API is unusually clean. Pi exposes a small, well-documented set of primitives - tools, MCP servers, skills, prompt templates, and themes - and you wire them together with a package.json and a single main file. The package manager (pi packages) discovers, installs, and updates extensions from pi.dev/packages, where anyone can publish.
I maintain a small extension myself: @pixu1980/pi-path-picker, a tool that autocompletes file paths inside the agent prompt. The source lives at github.com/pixu1980/pi-coding-agent-extensions, and the entire implementation - registering a custom tool, hooking into the prompt lifecycle, handling tab-completion in the TUI - fits in a handful of files. It is a good example of how little ceremony is involved: you write a TypeScript class, export it, publish it, and it works. No build step beyond TypeScript, no configuration wizard, no permission manifest.
The other thing Pi gets right is the provider model. It supports 20+ providers out of the box, including Anthropic, OpenAI, Google, xAI, Mistral, Groq, OpenRouter, and DeepSeek. DeepSeek is a first-class native provider because it speaks the OpenAI-compatible API, and you can switch models mid-session. The configuration lives in ~/.pi/agent/models.json and you can register as many models as you want.
I have seven models registered at any given time. I switch between them depending on the task. The default for almost everything I do is DeepSeek V4 Flash.
\nDeepSeek V4 launched in preview on April 24, 2026, in two variants. V4-Pro is the flagship: 1.6T total parameters, 49B active, around $1.74 per million input tokens and $3.48 per million output tokens. V4-Flash is the cost-optimized tier: 284B total, 13B active per token, 1M context window, 2,500 concurrent requests, and the pricing I quoted above.
\nThe interesting design choice is the MoE split. 284B sounds enormous, but only 13B parameters run on any given token, which is what gives Flash its cost and latency profile. The model is not a \"small model that tries to look big\" - it is a properly sparse MoE that pays a small compute bill per token while still benefiting from a much larger knowledge base when routing. DeepSeek also uses a sparse attention scheme (CSA / HCA) to keep the 1M-context long-tail cheap, which is exactly what an agent loop needs.
\nOn coding benchmarks, V4-Flash lands around 79% on SWE-bench Verified and 96% on HumanEval in third-party reporting, with a gap of about 1.6 percentage points to V4-Pro on SWE-bench Verified and around 1.9 points on LiveCodeBench. That is not the kind of gap I care about for the kind of work I do with it.
\nThe other important fact is that V4-Flash ships under an MIT license for the weights. The API name is deepseek-v4-flash, the older deepseek-chat and deepseek-reasoner aliases retire on July 24, 2026, and the integration with Pi is officially documented on the DeepSeek API docs, not just tolerated.
Here is the loop, condensed.
\npi runs in the terminal, reads the project context, and shows me the current state of the working tree.scripts/cms/_index.js. Do not touch the post template. Return the new file and the minimal diff to wire it up.\"pnpm test, runs pnpm lint, edits the right places, and reports back. Most of my sessions are 5 to 20 tool calls.The 1M context window matters more than I expected. Most of my projects are well under that, but the long-context behavior is what makes the agent loop feel cheap rather than expensive. When the model can hold the whole architecture in memory, it stops asking redundant questions, stops re-reading files, and stops producing context-degrading summaries of files it has already read.
\nLet me be specific, because vague cost claims are useless.
\nA typical milestone on dout.dev has been something like a CMS build step, a new template, or a content migration. The agent loop for one of those usually looks like:
\nAt the cache-miss rate, 500k input tokens cost $0.07. 20k output tokens cost $0.0056. Total: $0.0756 before cache.
\nAt the cache-hit rate for everything except the first turn, the same session lands closer to $0.02–$0.04. That is for a milestone that would have taken me hours and a significant amount of attention.
\nA heavy day, two milestones plus a refactor plus a documentation pass, has been landing somewhere in the $0.30–$0.90 range. I have had monthly totals that look like rounding errors. I am not being clever about it. I just do not have to think about the meter.
\nThere is also pi-deepseek-cache, a small extension that pins the system prompt and tool definitions to keep the prefix-cache hot, and the developer reports a 95%+ cache hit rate once the loop stabilizes. I have not measured my own hit rate that carefully, but I have watched my daily bill drop when I started using it, and the savings are real.
Let me be direct, because the marketing is designed to obscure this.
\nCursor is a VS Code fork with proprietary extensions glued to someone else's APIs. You do not own the loop, you do not own the integrations, and you pay a per-month subscription that rises without your consent. The model is venture-funded price suppression: lose money on every seat, make it up on the locked-in base when the music stops. The usual playbook.
\nClaude Code is a genuinely good tool harness owned by Anthropic, which means it exists to sell Anthropic models. You are not the customer of the tool - you are the inventory. The pricing is opaque, the model access is gated, and the open-source contributions are decorative. When Anthropic raises Opus pricing next quarter - and it will - your loop cost triples and you have no alternative provider to switch to within the same harness. That is not a product. That is addiction by design: low-dose introductory offer, price escalates after the habit forms.
\nChatGPT, GitHub Copilot, Codex - all proprietary. All trained on public data the companies would never let you train on. All designed to make you dependent on a closed API that can change terms, pricing, or access at any time with zero recourse. The open-weight models from DeepSeek, Mistral, and Llama are structurally more aligned with your interest as a developer: you can run them, fork them, audit them, and switch between them without asking for permission.
\nOpenCode and the emerging ecosystem of open-agent toolkits are moving in the right direction: tools that assume you want transparency, portability, and the freedom to change the model without changing the harness. That is the principle that matters. Not \"AI for everyone\" as a slogan, but \"AI you control\" as a property of the software.
\nPi is the only one of these that is open source at its core - MIT-licensed from day one, with a package registry where anyone can publish an extension without a review board or a commercial agreement. My @pixu1980/pi-path-picker is a small example, but the fact that I can write it, publish it, and use it without asking anyone is the entire difference between a platform and a prison.
The most surreal part of this setup is that the model itself can write extensions for the harness that runs it.
\nDeepSeek V4 Flash reads the Pi extension documentation - a few pages of TypeScript interfaces and a package.json schema - and generates working extensions on the first try. I have done it. You describe what you want in plain English, the model reads the API docs from the repository, and it produces a complete extension: tool registration, prompt hooks, TUI integration, the whole thing. One prompt.
That is the loop squared. You use an open-source agent to call an open-weight model, and the model extends the agent while you watch. The harness grows its own capabilities. There is no approval queue, no marketplace gatekeeper, no SDK version lock. You just describe, generate, publish, and use.
\nIt is incredible, it is satisfying, and it is the most empowering development workflow I have ever experienced. The ceiling is not set by a product manager's roadmap. The ceiling is set by what you can describe in a prompt.
\nNothing is free. Here is what I give up.
\nNone of these trade-offs are dealbreakers for me. They are constraints I work with.
\nFive years ago, the choice of a coding agent was a tooling preference. Today, it is a budget question, a workflow question, and a philosophical question.
\nPi is a small, transparent, customizable harness that does not try to be my IDE, my project manager, or my safety net. It gives me a loop and gets out of the way. DeepSeek V4 Flash is a fast, open, properly sparse model that charges cents for what used to cost dollars. Together, they make the kind of agent-driven, multi-file, context-heavy work I do every day economically trivial.
\nI am not saying Pi + V4-Flash is the right answer for every team. A regulated environment, a large enterprise, a security-sensitive codebase, or a team that needs deep IDE integration will make a different choice. But for an independent developer who ships a lot, who reads every diff, who does not need permission popups, and who used to flinch at the monthly AI bill, the answer is: this loop, this model, this cost.
\nThe model is becoming part of the abstraction layer. The agent harness is becoming part of the editor. The bill is becoming rounding error.
\nThat is the new default. I am not going back.
\nA static blog has no backend. That is the whole fucking point. So search has to satisfy three rules:
\nOn dout.dev this shipped as a single search.html page that loads prebuilt JSON indexes from /data/, runs a light ranking function in the browser, and paginates the results. Total client code is under 200 lines.
Every time the CMS runs, it emits four files under src/data/:
posts.json - one entry per published post: title, slug, date, description, tags, series, keywords extracted from the body;tags.json - one entry per tag: label, slug, count;months.json - one per month: YYYY-MM, count;series.json - one per series: label, slug, count.A post entry looks like this:
\n{\n \"slug\": \"2026-05-19-html-native-template-engine\",\n \"title\": \"An HTML-Native Template Engine Without eval()\",\n \"date\": \"2026-05-19\",\n \"description\": \"How the dout.dev template engine handles extends, blocks...\",\n \"tags\": [\"architecture\", \"vanilla-js\", \"frontend\"],\n \"series\": null,\n \"keywords\": [\"template\", \"engine\", \"extends\", \"blocks\", \"eval\", \"sandbox\"]\n}The keywords array is computed from the body during the build: frequent, informative tokens the reader would plausibly search for. The ranker uses them later for query-term boosting.
The search page reads everything from the URL. That makes results shareable, bookmarkable, and back-button friendly.
\n/search.html?q=template&type=post&type=tag&page=2q is the query term.type is repeatable and filters the result stream (post, tag, series, month).page is the pagination index, 1-based.Any change to the form updates the URL via history.pushState. No framework. No state library.
function updateUrl({ q, types, page }) {\n const params = new URLSearchParams();\n if (q) params.set('q', q);\n for (const t of types) params.append('type', t);\n if (page > 1) params.set('page', String(page));\n const next = `${location.pathname}?${params.toString()}`;\n history.pushState({}, '', next);\n}The ranker is deliberately simple. A weighted sum of term hits against different fields, a small boost for exact keyword match, a tiny recency tilt.
\nfunction scorePost(post, tokens) {\n const title = post.title.toLowerCase();\n const desc = post.description.toLowerCase();\n const tagString = post.tags.join(' ').toLowerCase();\n const kwSet = new Set(post.keywords);\n\n let score = 0;\n for (const t of tokens) {\n if (title.includes(t)) score += 5;\n if (desc.includes(t)) score += 2;\n if (tagString.includes(t)) score += 3;\n if (kwSet.has(t)) score += 4;\n }\n\n // Light recency nudge: newer posts win ties\n const days = (Date.now() - new Date(post.date).getTime()) / 86400000;\n score += Math.max(0, 1 - days / 3650);\n\n return score;\n}This is not Elasticsearch. It is a heuristic that works well when the corpus is a few dozen posts. I would not use it for ten thousand entries. For a blog, it is the right size of tool.
\nResults are paginated 10 at a time on the client. The pagination component matches the server-rendered archive pagination: rel=\"prev\" / rel=\"next\", aria-current=\"page\" on the active page, ellipses that are not clickable.
The results summary uses aria-live=\"polite\" so that screen readers hear the new result count when the query changes, without stealing focus.
<p class=\"results-summary\" aria-live=\"polite\" role=\"status\">7 results for \"template\". Page 1 of 1.</p>That single attribute is the whole accessibility story for live-updating results.
\nI punted. The corpus is small enough that users who mistype a word can correct it faster than the algorithm could guess. If the blog grows past a few hundred posts I would revisit - probably with a trigram index built at the same CMS step.
\nThe honest measurement is: on a corpus the size of dout.dev, exact-term search with field weighting is indistinguishable from fancier solutions in user satisfaction, and it costs a fraction of the bytes.
\nA static site can have a good search without a service. Build the indexes when you build the site. Load them on the search page only. Write a ranking function that matches your corpus. Drive it from the URL. That is the whole story, and the client code fits on a page.
\nFor the last twenty years, a large part of software development has been guided by a very simple reflex: when the platform feels too low-level, we install an abstraction.
\nAt first, this was not only reasonable, it was necessary. Platforms were incomplete, browser behavior was inconsistent, standard libraries were often limited, and teams needed shared mental models to ship products at a human pace. Frameworks and libraries gave us vocabulary, structure, conventions, and a way to avoid solving the same problems over and over again.
\nThe problem is that, over time, this useful reflex became almost automatic. Need UI composition? Install a framework. Need routing, state management, validation, forms, styling, animation, authentication glue, build orchestration, dependency injection, data fetching, queues, command handling, or configuration management? Install something.
\nEventually, the product starts becoming only one part of the system. The other part is a carefully negotiated dependency graph, where every new feature has to pass through somebody else's assumptions, release cycle, architecture, migration path, documentation quality, security posture, and long-term maintenance choices.
\nThis is not a frontend problem. It is not a JavaScript problem. It is not a React problem. It is not even a framework problem. It is a software problem.
\nEvery ecosystem has its own version of this story. JavaScript has frontend frameworks and npm. Python has web frameworks, ML stacks, data tools, and long chains of packages. Java has decades of enterprise abstractions. .NET has its own layered ecosystems. PHP, Ruby, Go, Rust, Swift, Kotlin, and C# all have communities that build towers of convenience on top of native language and runtime features.
\nAgain, this did not happen because developers were careless. It happened because abstractions are one of the main tools we have for dealing with complexity. Software is abstraction. The real question is not whether we should use abstractions, but where they should live, who should own them, how much of them should run in production, and whether borrowing them is still the best economic choice.
\nThat question is becoming more urgent because the ground is moving. The next major abstraction layer may not be another framework. The next major abstraction layer may be the model.
\nFrameworks exist because humans need constraints. We need names, conventions, file structures, lifecycle models, shared patterns, and a limited number of concepts to keep in our heads at the same time. A framework is not just code. It is a cognitive compression format.
\nIt tells us how to think about the system. Do not think about everything at once. Think in components, routes, controllers, models, hooks, stores, services, middleware, providers, modules, or pipelines. This is extremely useful when human developers are the only abstraction engine in the loop, because humans need stable shapes to coordinate work, communicate intent, and reduce ambiguity.
\nBut LLMs do not need abstractions in exactly the same way.
\nA model does not care whether a pattern is called a hook, a provider, a composable, a bean, a service, a trait, a reducer, a module, or a pipeline. Those names still matter to us, because they help teams communicate and maintain the system, but they are not the deepest source of quality for AI-assisted software.
\nWhat a model needs is context. It needs constraints. It needs examples, tests, schemas, documentation, review rules, runtime signals, tool access, and clear success criteria. In other words, the most important abstraction for an AI-assisted codebase is not always the framework used by the application. It is the operational environment around the codebase.
\nThat moves the center of gravity.
\nInstead of placing all best practices inside runtime abstractions, we can start placing more of them inside instructions, tests, static analysis, design tokens, architecture rules, accessibility checks, security policies, and project-specific agent skills. The abstraction is still there, but it is no longer necessarily something we ship to users or execute on every request.
\nThis is a very different kind of software architecture.
\nThe next abstraction layer will increasingly be made of things that surround the code rather than things that always run inside it. MCP servers, agent skills, local LLMs, cloud LLMs, project-specific prompts, typed schemas, linters, formatters, test suites, static analysis, design tokens, accessibility rules, security policies, architecture decision records, code review agents, and documentation indexed as working memory all point in the same direction.
\nThey create an environment where code can be generated, constrained, checked, refactored, and reviewed with more project awareness than before.
\nThis does not mean we stop using abstractions. That would make no sense. It means we can stop shipping so many borrowed abstractions to production when their main value is no longer runtime behavior, but repetition, convention, scaffolding, and guidance.
\nA model can generate repetitive implementation. A linter can enforce a project rule. A type system can constrain a data shape. A test can verify behavior. An agent can apply the same refactor across many files. A design system can become tokens, fixtures, examples, and visual checks. A security rule can become a gate. An accessibility expectation can become part of the definition of done.
\nAt that point, many dependencies start to look different. Some still provide deep value and should absolutely be used. Others begin to look less like leverage and more like inherited risk.
\nThe question changes from \"which library should we install?\" to \"should this be a dependency at all?\"
\nDependencies are not free. They increase bundle size, install time, build complexity, runtime surface, security exposure, version drift, documentation debt, maintenance overhead, and future migration cost.
\nThose are the obvious costs. The deeper cost is architectural.
\nEvery dependency imports somebody else's decisions into your product. It brings assumptions about how problems should be modeled, how APIs should behave, how edge cases should be handled, and how the future should evolve. It becomes part of your onboarding path, hiring profile, debugging surface, security model, review process, and long-term roadmap.
\nThe software industry loves reuse, and for good reason. Reuse can be powerful. But reuse is also coupling, and coupling has to be paid for.
\nThe npm ecosystem makes this easy to see because it is large, fast-moving, and deeply interconnected, but the same dynamic exists in every ecosystem. Sonatype reported more than 454,600 new malicious packages identified throughout 2025 across major open-source ecosystems, bringing the cumulative total of known and blocked malware above 1.233 million packages. Research on npm supply-chain weak links also shows how package metadata, install scripts, expired maintainer domains, inactive maintainers, and account takeover opportunities can expose thousands of downstream packages.
\nThis does not mean \"never use dependencies\". That would be a childish conclusion. It means dependencies must become deliberate architectural choices again. They should earn their place through real complexity, real specialization, real maintenance value, or real domain expertise.
\nThey should not be the default answer to every small discomfort.
\nFor a long time, dependency-heavy development made economic sense. Writing everything in-house was expensive. Maintaining internal abstractions was expensive. Generating boilerplate was boring. Refactoring repeated patterns was slow. Documenting everything was painful. Testing every variation took time.
\nSo we outsourced complexity to frameworks and libraries. We accepted the dependency tax because the alternative was often slower, more expensive, and more fragile.
\nAI changes that equation, not because it magically produces perfect software, but because it changes the cost of producing certain categories of code.
\nStack Overflow's 2025 Developer Survey reports that 84% of respondents are using or planning to use AI tools, and 51% of professional developers use them daily. GitHub reported that nearly 80% of new developers on GitHub used Copilot within their first week in 2025. Controlled research on GitHub Copilot found that developers completed a JavaScript task 55.8% faster when using the tool.
\nThe picture is not universally simple. Other studies are more nuanced, and they should be. AI coding tools are more useful in some contexts than others, and generated code still requires strong human review, especially in complex systems, proprietary codebases, security-sensitive areas, and large multi-file changes.
\nBut the important point is not that AI writes perfect code. It does not.
\nThe important point is that AI makes boilerplate, repetitive implementation, documentation, test scaffolding, migration work, refactoring, API adaptation, pattern replication, simple feature assembly, and codebase navigation cheaper than they used to be.
\nThose are exactly the categories of work that made teams install many libraries in the first place.
\nIf a model can generate a project-specific implementation that follows your coding rules, passes your tests, respects your security constraints, uses your design tokens, and avoids unnecessary runtime dependencies, then the economics of abstraction change.
\nAt that point, the question is no longer only \"which package solves this?\"
\nThe better question becomes \"why should this be a package?\"
\nOne of the common misunderstandings about AI-generated software is that it will make standards less important. I think the opposite is true.
\nAI will make standards more valuable because models work better when the target is stable, documented, widely used, and well represented. Language standards, platform APIs, protocol specifications, accessibility rules, security practices, and explicit architectural constraints are model-friendly.
\nA framework is a moving target controlled by a smaller community. A standard is a wider agreement.
\nOn the web platform, we can already see this shift. Modern CSS is absorbing capabilities that once required preprocessors, JavaScript helpers, or framework-level conventions. Typed attr() lets CSS read attributes as typed values. CSS if() brings conditional logic into values. CSS custom functions aim to make reusable CSS logic native to the language.
\nWhen the platform learns these primitives, teams can use them directly only if their abstraction layers do not get in the way. Otherwise, the browser may already support the capability, but the product still has to wait for a framework, a library, a wrapper, a plugin, or a design system abstraction to catch up, expose it, document it, and stop fighting it.
\nThat is one ecosystem, but the principle is broader. When platforms become more expressive, and AI becomes better at producing code against stable standards, the value of non-standard abstraction decreases.
\nThe winning move is not to reject every framework. The winning move is to move as much product logic as possible toward stable, inspectable, standard primitives.
\nUse the language. Use the runtime. Use the platform. Use the framework when it still buys something real.
\nMany teams use frameworks as delivery mechanisms for best practices. The framework tells them how to organize files, fetch data, render pages, place state, compose UI, and decide which patterns are acceptable.
\nIn an AI-assisted workflow, many of those rules can move into configuration, automation, and project context.
\nCoding standards can become lint rules. Architecture decisions can become generation constraints. Design guidelines can become tokens and visual tests. Accessibility expectations can become automated checks. Security policies can become static analysis and dependency gates. Performance budgets can become CI failures. Reusable patterns can become agent skills. Project knowledge can become context the model can actually use.
\nThis is a major change because best practices stop being trapped inside framework conventions and become executable governance.
\nA convention helps when developers remember it. A rule enforces it. A test verifies it. An agent applies it repeatedly. A model generates code from it.
\nThat is the future shape of software abstraction. Not \"everyone must memorize the framework\", but \"the system knows the rules and keeps applying them\".
\nThe industry has spent years treating frameworks as identity. We say \"I am a React developer\", \"I am a Laravel developer\", \"I am a Rails developer\", \"I am a Spring developer\", \"I am a Django developer\", \"I am a Next developer\".
\nThis made sense when frameworks were the main interface between developers and complexity. But in an AI-native development environment, that identity becomes too small.
\nThe valuable skill will not be loyalty to a framework. The valuable skill will be understanding systems: language, runtime, platform, accessibility, security, performance, data, product constraints, and the way AI-generated work must be instructed, constrained, verified, and reviewed.
\nThe senior developer of the next era is not the person who knows the most framework APIs by memory. It is the person who can design the rules of the system so that humans and models can safely produce good software together.
\nThat requires more engineering, not less.
\nThis future is not no-code. No-code pretends complexity can disappear, and complexity does not disappear. It moves.
\nWhat changes is the layer where engineering work happens. Less time wiring borrowed abstractions, more time defining contracts. Less time adapting to framework churn, more time designing durable systems. Less time installing packages for trivial problems, more time making sure the generated solution is correct, accessible, secure, observable, and maintainable.
\nAI does not remove the need for senior engineers. It increases the need for them.
\nBecause when code becomes cheaper to produce, judgment becomes more valuable.
\n\"Vanilla\" does not mean naive. It does not mean writing everything from scratch forever. It does not mean refusing tools, frameworks, libraries, or ecosystems.
\nIt means preferring the native language, native runtime, and platform standards unless a dependency clearly earns its place.
\nA more vanilla world is not a world without abstraction. It is a world where abstraction is generated, governed, inspected, and owned. A world where dependencies are exceptions, not defaults. A world where libraries are chosen because they provide deep, hard, specialized value, not because nobody wanted to write twenty lines of code.
\nIt is a world where frameworks are useful tools, not architectural religions. A world where the model becomes part of the abstraction layer, but the output remains understandable, standard, testable, and close to the platform.
\nThis will not happen all at once. There will still be frameworks, libraries, ecosystems, and very good reasons to depend on external code. But the default is going to change.
\nThe age of installing an abstraction for every small discomfort is ending.
\nThe next era belongs to teams that can combine human judgment, platform standards, automated governance, and AI-generated implementation. Not because frameworks suddenly became useless, but because many of the reasons we needed them are being absorbed by something else.
\nThe model is becoming part of the abstraction. The platform is getting stronger. The dependency graph is becoming a liability.
\nAnd software teams are about to rediscover a very old idea: the best code is not the code you borrowed. It is the code you understand, control, verify, and can afford to change.
\nMost teams treat accessibility as a checklist at the end of a sprint. That approach misses the real problem. Accessibility is the baseline behavior of the interface under real user constraints.
\nThose constraints are not abstract. They are concrete:
\nIf the UI ignores those settings, it is not accessible, even when every button has a good label.
\nThe popover on dout.dev exposes settings that the browser already knows about: motion, contrast, color scheme, font size. It does not invent new ones. The settings are mapped directly to CSS custom properties that flip at the root level.
\nAccessibility is not a feature you bolt on. It is the system's respect for user preferences. A popover that exposes those preferences is not a nice-to-have; it is the UI admitting that the browser cannot detect every user need, and giving the user control.
\nDesign for preferences first. Add ARIA second. That order matters.
\n", "image": "https://dout.dev/assets/og/posts/2026-06-09-why-display-preferences-popover-exists.png", "date_published": "2026-06-09T00:00:00.000Z", "tags": [ "accessibility", "frontend", "responsive-design" ] }, { "id": "https://dout.dev/posts/2026-06-06-how-pixhighlighter-is-built.html", "url": "https://dout.dev/posts/2026-06-06-how-pixhighlighter-is-built.html", "title": "How PixHighlighter Is Built (Or: I Wrote a Syntax Highlighter Because Prism Was Too Bloaty)", "summary": "The contract stays plain (because HTML should be readable)", "content_html": "PixHighlighter begins with the smallest useful shape:
<pre is=\"pix-highlighter\" data-lang=\"js\"><code>const answer = 42;</code></pre>That is still a real <pre> element with a real <code> child. The source is readable BEFORE JavaScript runs, copyable as text, and understandable to assistive technology. The component does not need a custom shadow tree to make code look like code.
The important decision is what it refuses to do by default: the primary path does NOT wrap every token in markup. The code block is not a pile of span wrappers. It is ONE text node that can be painted by the browser. This is the kind of detail that separates \"it works\" from \"it works well.\"
\nEach lexer under src/scripts/components/PixHighlighter/Lexers/ walks the source and emits ranges:
{ type: 'kw', start: 0, end: 5 }That object says \"the characters from 0 to 5 are a keyword.\" It does NOT say \"insert a span here.\" Parsing and rendering stay separate. The same token stream can power the modern renderer, the fallback renderer, tests, and any future diagnostics without changing the source model.
\nLanguage aliases are normalized before lookup. javascript becomes js, typescript becomes ts, shell and zsh become bash. Content authors get a forgiving interface; the renderer gets ONE clean language key. Consistency is a feature.
The best version of PixHighlighter uses the CSS Custom Highlight API. When CSS.highlights and Highlight exist, the component creates DOM Range objects for each token and stores them in named highlight registries:
const highlight = new Highlight(range);\nCSS.highlights.set('pix-kw', highlight);CSS then styles those names directly:
\n::highlight(pix-kw) {\n color: var(--pix-highlighter--kw);\n}That is the whole goddamn trick. The browser paints a range of text WITHOUT changing the text into markup. Selection stays clean. Copy stays clean. The DOM stays quiet. Themes remain normal CSS variables instead of a second token system hidden inside generated spans.
\nThe rule is simple: fallback spans only when the Highlight API is unavailable. In that case, the component maps the same token ranges to conservative markup:
\n<span data-token=\"kw\">const</span>The fallback is NOT a different highlighter. It is the same lexer output rendered into older browser primitives. The CSS already has matching rules for [data-token='kw'], [data-token='str'], and the rest of the token types, so the visual result remains close without forcing modern browsers to carry extra DOM.
Ten code blocks still get ONE style payload. The component can appear throughout an article without multiplying its CSS. No duplication. No waste.
\nEvery instance renders a compact toolbar with copy and theme controls. The picker appears per block, but the selected theme is page-wide state. That avoids a page where one snippet is using one palette and the next snippet is using another because of local component state. Code theme is a reading preference, so the page owns it.
\nThe copy button reads code.textContent. It does NOT inspect highlight ranges, fallback spans, toolbar state, or theme state. Highlighting is visual; the source text is the contract.
PixHighlighter is built for a static editorial site: short examples, no frontend framework, no runtime highlighter dependency, and a design system that already owns typography, color, and motion.
The architecture works because each layer has ONE job:
\nThat is the pattern I want here: ordinary HTML first, modern browser APIs where they remove markup, and a fallback that preserves the same source text instead of inventing a second content model.
\n", "image": "https://dout.dev/assets/og/posts/2026-06-06-how-pixhighlighter-is-built.png", "date_published": "2026-06-06T00:00:00.000Z", "tags": [ "vanilla-js", "frontend", "architecture" ] }, { "id": "https://dout.dev/posts/2026-06-02-wcag-22-aa-without-aria-spam.html", "url": "https://dout.dev/posts/2026-06-02-wcag-22-aa-without-aria-spam.html", "title": "WCAG 2.2 AA Without ARIA-Spam (Landmarks, Heading Order, Skip-Links - That's 80% of It)", "summary": "The unpopular opinion (brace yourself)", "content_html": "Most accessibility failures I see in production are not missing features. They are HTML that was never semantic, covered in ARIA attributes that were supposed to fix the damage. That approach is a tax forever. ARIA is a powerful tool and also a trap: the first rule of ARIA is to NOT use it if a native element would do the job.
\nFor dout.dev I made a rule for myself. Every page starts as semantic HTML. ARIA only shows up when there is no native alternative. That rule covered most of the WCAG 2.2 AA checklist before I wrote a single aria-* attribute.
HTML5 already gives you landmarks. A screen reader or a \"Rotor\" in VoiceOver reads them as navigation regions. You do NOT need to annotate them.
\n<body>\n <a class=\"skip-link\" href=\"#main\">Skip to content</a>\n <header>\n <nav aria-label=\"Primary\">\n <!-- navigation links -->\n </nav>\n </header>\n <main id=\"main\">\n <!-- content -->\n </main>\n <footer>\n <!-- footer content -->\n </footer>\n</body><header>, <main>, <footer> are already landmarks. The only role I add is on the <nav> when there are multiple nav elements, and even then I use aria-label=\"Primary\" to disambiguate.
A screen reader user navigates by headings. If your heading order goes h1 → h3 → h2, you are making blind people work harder for no reason. The rule is simple: never skip levels. h1 → h2 → h3, not h1 → h4.
\nEach page has exactly one <h1>. Sections within the page start at <h2>. Subsections at <h3>. If you need four levels of nesting in a blog post, your information architecture has bigger problems.
<a class=\"skip-link\" href=\"#main\">Skip to content</a>That is the single highest-impact accessibility fix for keyboard users. One link, visible on focus, that skips the navigation and lands the user in the main content. It takes five minutes to add and saves every keyboard user from tabbing through 47 navigation links.
\nWCAG 2.2 AA is not a checklist of ARIA attributes you need to add. It is a checklist of semantic HTML patterns you need to follow. Landmarks, heading order, skip-links - these three things cover more ground than any ARIA-based remediation.
\nWrite good HTML first. Add ARIA only when the native element genuinely does not cover the case. That is the entire accessibility strategy for dout.dev, and it works.
\n", "image": "https://dout.dev/assets/og/posts/2026-06-02-wcag-22-aa-without-aria-spam.png", "date_published": "2026-06-02T00:00:00.000Z", "tags": [ "accessibility", "html", "frontend" ] }, { "id": "https://dout.dev/posts/2026-05-30-modern-css-is-enough.html", "url": "https://dout.dev/posts/2026-05-30-modern-css-is-enough.html", "title": "Modern CSS Is Enough (Container Queries, Nesting, `:has()` - No Framework Required)", "summary": "The short version (for the impatient)", "content_html": "For about ten years, serious frontend work leaned on tooling that papered over missing CSS features: Sass for nesting, Styled Components for dynamic theming, BEM conventions for scoping, utility frameworks for constraint. Most of those reasons quietly disappeared in the last two browser cycles. Modern CSS has container queries, native nesting, :has(), cascade layers, logical properties, color-mix(), clamp(), and more. On dout.dev I ship ALL of these, and the CSS is shorter than it would have been five years ago.
This post is NOT \"CSS is cool now.\" It is a walk through specific modern features that let me delete a preprocessor and a handful of conventions. If you're still using Sass in 2026, we need to talk.
\nMedia queries size components against the viewport. That is the WRONG reference frame for components that can appear in a full-width article or a narrow sidebar. Container queries fix it.
\n.post-card {\n container-type: inline-size;\n container-name: card;\n}\n\n@container card (min-width: 400px) {\n .post-card__title { font-size: var(--text-xl); }\n}The component queries its own parent, not the viewport. That is the correct behavior for a reusable component. Media queries are for layout; container queries are for components.
\nNative nesting - header { h1 { ... } } works in every modern browser. No Sass compilation step. No & prefix needed for simple selectors.
:has() selector - the \"parent selector\" CSS always needed. post-card:has(> img) to style cards differently when they have cover images. No JavaScript, no extra class.
Cascade layers - @layer base, components, utilities lets you control specificity order explicitly instead of fighting it with !important.
color-mix() - color-mix(in srgb, var(--color-accent), white 20%) gives you tinted variants without maintaining color scales.
clamp() - font-size: clamp(1rem, 2.5vw, 1.5rem) gives you fluid typography without breakpoints.
darken() is color-mix().@scope reduce the need for naming conventions.box-sizing: border-box on everything and margin: 0 on body covers 90% of the cases.Modern CSS is not a toy. It is a production-ready styling system that has absorbed most of the reasons people reached for preprocessors and frameworks. If you are still reaching for Sass or a CSS framework out of habit, take a weekend to audit what you actually need. The answer might be \"less than you think.\"
\nYour bundle will thank you. Your users will thank you. Your future self maintaining this in 2030 will thank you.
\n", "image": "https://dout.dev/assets/og/posts/2026-05-30-modern-css-is-enough.png", "date_published": "2026-05-30T00:00:00.000Z", "tags": [ "css", "vanilla-js", "frontend" ] }, { "id": "https://dout.dev/posts/2026-05-26-vibe-coding-with-rigor.html", "url": "https://dout.dev/posts/2026-05-26-vibe-coding-with-rigor.html", "title": "Vibe Coding With Rigor (Or: How to Use AI Without Your Codebase Turning Into a Dumpster Fire)", "summary": "The term I am reclaiming (because \"vibe coding\" got a bad rap)", "content_html": "\"Vibe coding\" has become shorthand for \"let the AI write whatever it wants and see what happens.\" That is NOT what I did on dout.dev, and it is not what the term should mean if it is going to be useful. The version I work with looks more like this:
\n\n\nVibe coding is driving an AI copilot hard with clear intent, small units of work, and strict review, while keeping the architectural decisions in your own head.
\n
The vibe is the speed. The rigor is the review. This post is the workflow that made 19 milestones shippable without the repo turning into a science fair.
\nEvery session had one outcome. \"Wire up the RSS feed.\" \"Add the skip-link.\" \"Extract the pagination component.\" NOT \"improve the site.\" NOT \"make it more accessible.\" The outcome fit in one commit.
\nThat discipline mattered more than the prompt engineering. When a session has a scoped outcome, the copilot's proposals can be evaluated against a clear question: did this produce the outcome, and is the diff small? When a session is open-ended, every proposal feels plausible, and you accept changes you later regret.
\nContext: we are in a repo at <path>. The build system is <x>.\nTask: <one specific thing>. \nConstraints: <rules the output must follow>.\nAcceptance criteria: \n1. <checkable thing>\n2. <checkable thing>That's it. No system prompts. No \"act as a senior engineer\" preamble. The copilot does not need a persona; it needs context, a task, and constraints. The acceptance criteria are the most important part - they turn the output from \"looks right\" to \"provably right.\"
\nI read every diff. Every single one. If the copilot produced 200 lines and I needed 40, I kept the 40 and deleted the rest. If the copilot produced a pattern that was technically correct but did not match the rest of the codebase, I rewrote it.
\nThat is not a criticism of the copilot. It is the job. The copilot generates proposals; the engineer curates them. Anyone who skips the curation step is not engineering - they are editing.
\nArchitecture. Naming. Accessibility semantics. The CSP. URL design. Whether a given feature should exist at all.
\nThese stayed in my head. They are the difference between a codebase that is maintainable and a codebase that is \"working\" in the sense that a stopped clock is right twice a day.
\nVibe coding is not a license to abandon standards. It is a license to move faster while applying the same standards you would apply to a human pair programmer. Scope every session. Write acceptance criteria. Read every diff. Keep the architecture decisions in your own head.
\nDo that, and you can ship 19 milestones in weeks instead of months. Skip any of those, and you get a codebase that works today and is unfixable tomorrow.
\n", "image": "https://dout.dev/assets/og/posts/2026-05-26-vibe-coding-with-rigor.png", "date_published": "2026-05-26T00:00:00.000Z", "tags": [ "making-of", "ai", "workflow" ] } ] }