Consider this a bug report.
\nExcept this time, the bug had access to the roadmap.
\nI'm talking about that fascinating professional category capable of turning incompetence into confidence, bullshit into strategy, and bluffing into a career.
\nAnd the best part is that, for a while, it actually works.
\nYou can bluff.
\nYou can sell confidence instead of competence.
\nYou can fill meetings with words, turn processes into theater, and bury problems under explanations complicated enough to make it look like the blame always belongs somewhere else.
\nYou can even convince yourself that managing people means manipulating the perception of what's happening, instead of taking responsibility for what you do.
\nThe problem is that reality has this annoying habit of producing measurable results.
\nAnd when incompetence, arrogance, and a certain talent for snake-oil salesmanship start leaving enough wreckage behind, even the most patient companies eventually do the math.
\nMaybe after spending money.
\nMaybe after burning energy.
\nMaybe after wasting time and losing good people.
\nBut eventually, they do.
\nAnd that's when the castle of storytelling finally collides with that ancient, decidedly non-agile concept we call \"consequences\".
\nSome call it accountability.
\nSome call it corporate natural selection.
\nRomantically, I prefer to call it karma.
Because you can pretend to know how to do a job for a very long time.
\nThe difficult part is keeping the act going once the people around you start looking at results instead of slides.
\nAnd thankfully, there are still companies healthy enough to realize, even if a little late, that sometimes the best way to improve a product isn't to add a feature.
\nIt's to remove a bug.
\nTo all you Senior Email Forwarders out there, I wish you nothing but the best.
\n", "image": "https://dout.dev/assets/og/posts/2026-08-12-the-bullshit-doesnt-scale.png", "date_published": "2026-08-12T00:00:00.000Z", "tags": [ "culture", "opinion", "leadership", "engineering" ] }, { "id": "https://dout.dev/posts/2026-08-10-nodejs-concurrency-event-loop.html", "url": "https://dout.dev/posts/2026-08-10-nodejs-concurrency-event-loop.html", "title": "Node.js Concurrency Is Not a Mystery - You Just Never Learned the Event Loop", "summary": "Your server is slow because you are fighting a runtime you never learned", "content_html": "Every Node.js developer has a story about the endpoint that worked fine in development and collapsed in production. The CPU spiked. The event loop stalled. Health checks started failing. And someone on the team said the words that have launched a thousand misdiagnoses: \"Node is single-threaded, we need more servers.\"
\nNode.js is not single-threaded. Your JavaScript runs on one thread. The process uses several. Conflating the two is not a minor technicality - it is the root cause of most Node performance incidents I have seen in fifteen years of reviewing backend code.
\nThe OpenReplay Team wrote a precise, layered breakdown of how the event loop, libuv thread pool, and worker threads actually work. What follows builds on their technical blueprint and adds what every senior backend engineer should internalize: the mental model that makes the right concurrency tool obvious before you touch a config file.
\nHere is the sentence you need to memorize: Node.js executes your JavaScript on one thread. The runtime is not single-threaded. libuv maintains a pool of background threads, and the operating system handles network I/O on Node's behalf. Treat \"single-threaded\" as a statement about where your code runs, not about the process as a whole. Get this wrong and you will reach for cluster when you need a worker, or bump UV_THREADPOOL_SIZE when you need to refactor a blocking function.
The distinction that matters is between concurrency and parallelism:
\nThe practical consequence: concurrency solves waiting problems (I/O). Parallelism solves computing problems (CPU). Reaching for the wrong one is how slow endpoints happen.
\nEvery Node.js tutorial hand-waves the event loop as \"the thing that makes async work.\" That is like saying \"the engine makes the car go.\" The event loop runs in a fixed cycle of six phases. Each phase has its own queue of callbacks that it drains completely before moving to the next:
\n┌───────────────────────────┐\n│ 1. timers │ setTimeout(), setInterval()\n├───────────────────────────┤\n│ 2. pending callbacks │ Deferred system callbacks\n├───────────────────────────┤\n│ 3. idle, prepare │ Internal libuv bookkeeping\n├───────────────────────────┤\n│ 4. poll │ New I/O events; blocks here if idle\n├───────────────────────────┤\n│ 5. check │ setImmediate()\n├───────────────────────────┤\n│ 6. close callbacks │ socket.on('close', ...)\n└───────────────────────────┘Phase 3 (idle, prepare) is real. Many explainers omit it because you never schedule into it directly. It exists for libuv's internal housekeeping. I mention it because omitting it is how developers grow up thinking the event loop is five phases and then get confused when something runs between poll and check.
\nThis is where most interview candidates fail and most production incidents begin. Microtasks are not a phase of the event loop. They drain between phases, and they have a strict internal order:
\nprocess.nextTick() → drains first\nPromise.then() → drains second\nmacrotasks → timers, I/O, setImmediate - only after both microtask queues are emptyprocess.nextTick outranks Promise.then, which outranks setTimeout. This is not an implementation detail. It is a three-tier priority system baked into the runtime, and if you do not know it, you will write code whose execution order surprises you in production.
// Run on Node.js 24. Prove it to yourself.\nconst fs = require('node:fs');\n\nfs.readFile(__filename, () => {\n setTimeout(() => console.log('1: setTimeout(0)'), 0);\n setImmediate(() => console.log('2: setImmediate'));\n Promise.resolve().then(() => console.log('3: promise'));\n process.nextTick(() => console.log('4: nextTick'));\n});\n\n// Prints:\n// 4: nextTick\n// 3: promise\n// 2: setImmediate\n// 1: setTimeout(0)nextTick drains first. Then the promise microtask queue. Then - because we are inside an I/O callback (poll phase) - the loop hits the check phase next, so setImmediate fires before the loop wraps around to the timers phase. Schedule the same setTimeout(0) and setImmediate() at the top level instead of inside an I/O callback, and the order is non-deterministic. Do not rely on it. This is the kind of thing that works on your machine and fails in CI.
The rule: process.nextTick → Promise.then → macrotasks. Always. Every time. No exceptions.
The libuv thread pool is a fixed set of background threads - 4 by default, expandable to 1024 - that libuv uses to run operations with no non-blocking OS primitive. The pool is shared across all event loops in a process.
\nHere is the list of what runs on it, and this list is finite and specific:
\n| Uses the pool | \nDoes NOT use the pool | \n
|---|---|
fs APIs (async variants) | \nNetwork sockets (epoll/kqueue/IOCP) | \n
dns.lookup() (calls getaddrinfo) | \ndns.resolve*() (uses c-ares, bypasses pool) | \n
crypto.pbkdf2(), crypto.scrypt() | \nRegular TCP/HTTP requests | \n
crypto.randomBytes(), crypto.generateKeyPair() | \ndns.resolve() family | \n
zlib compression | \nEvent loop callbacks | \n
Network I/O does not touch the thread pool. It goes through the operating system's polling mechanism - epoll on Linux, kqueue on macOS, IOCP on Windows - and surfaces directly in the poll phase. The dns distinction trips people up constantly: dns.lookup() uses the pool, the dns.resolve*() family does not. If your mental model was \"DNS uses the pool,\" it is wrong. Half of DNS does. The other half doesn't.
# Set BEFORE Node starts. The pool preallocates on first use.\n# Mutating process.env.UV_THREADPOOL_SIZE after the pool is touched does nothing.\nUV_THREADPOOL_SIZE=8 node server.js\"Bump UV_THREADPOOL_SIZE to speed up my API.\" No. Raising UV_THREADPOOL_SIZE speeds up concurrent pool-backed I/O - more parallel fs reads, more parallel crypto operations. It will never, ever speed up CPU-bound JavaScript. The pool runs libuv's C-level operations, not your functions. If your endpoint is slow because fib(45) runs on the main thread, UV_THREADPOOL_SIZE=1024 does absolutely nothing. You need a worker thread.
A worker thread is not an OS thread with a JavaScript face. It is a separate V8 isolate with its own event loop and its own libuv loop. This is why workers cannot share ordinary JavaScript objects. It is not a limitation. It is the architecture. Everything you postMessage is deep-copied via the HTML structured clone algorithm:
// main.js\nconst { Worker } = require('node:worker_threads');\n\nconst worker = new Worker('./fib-worker.js', { workerData: { n: 42 } });\nworker.on('message', (result) => console.log('fib(42) =', result));\nworker.on('error', (err) => console.error(err));\n\n// fib-worker.js\nconst { parentPort, workerData } = require('node:worker_threads');\n\nfunction fib(n) {\n return n < 2 ? n : fib(n - 1) + fib(n - 2);\n}\n\nparentPort.postMessage(fib(workerData.n));Functions, class prototypes, and live references do not survive postMessage. The only escape from copying is SharedArrayBuffer - shared memory with all the synchronization responsibility that implies. This model trades shared-memory-by-default (and the locks, mutexes, and race conditions of C++/Java threading) for isolation-by-default. Safer, with copying as the cost. It is a deliberate design choice, not a missing feature.
The Node.js documentation is explicit about this, and everyone ignores it: spawning a Worker for every HTTP request is wasteful. The overhead of creating a V8 isolate, a libuv loop, and an event loop exceeds the benefit for anything but the heaviest computations. Use a pool. The community standard is piscina:
const Piscina = require('piscina');\nconst pool = new Piscina({ filename: path.resolve(__dirname, 'fib-task.js') });\n\napp.get('/report', async (req, res) => {\n const value = await pool.run({ n: 45 }); // Worker handles it; loop stays free\n res.json({ value });\n});One pool, reused across requests. Workers stay alive. Zero startup cost per task.
\nIf you wrap crypto.pbkdf2 in a worker thread, you have achieved nothing. That function already runs on the libuv thread pool. You have scheduled a thread (the worker) to schedule another thread (libuv). Congratulations, you added latency and memory for zero benefit. Workers earn their keep only for synchronous, CPU-bound JavaScript - heavy computation that would otherwise freeze the main thread.
Here is the failure mode that takes down production:
\n// server-blocking.js - THE WRONG WAY\nconst express = require('express');\nconst app = express();\n\nfunction fib(n) {\n return n < 2 ? n : fib(n - 1) + fib(n - 2);\n}\n\napp.get('/report', (req, res) => {\n res.json({ value: fib(45) }); // Blocks the event loop FOR EVERYONE\n});\n\napp.get('/health', (req, res) => res.send('ok'));\n\napp.listen(3000);\n// While fib(45) runs, /health returns NOTHING. Every request queues.The production signature of a blocked event loop is distinctive: many concurrent users stall at the same wall-clock instant. Not one user's bad network. Not a slow database query for one session. Everyone freezes simultaneously because the single JavaScript thread is busy computing. You can confirm it at runtime with monitorEventLoopDelay from node:perf_hooks - a high p99 means the loop is saturated.
The fix is a worker pool:
\n// server-pooled.js - THE RIGHT WAY\nconst Piscina = require('piscina');\nconst pool = new Piscina({ filename: path.resolve(__dirname, 'fib-task.js') });\n\napp.get('/report', async (req, res) => {\n const value = await pool.run({ n: 45 }); // Runs on a worker; loop stays free\n res.json({ value });\n});\n\napp.get('/health', (req, res) => res.send('ok')); // Always responds immediatelyCluster forks multiple processes, each with its own V8 isolate, its own event loop, its own memory, sharing a listening socket. Workers are multiple threads within one process. The distinction is not academic:
\n| \n | Worker Threads | \nCluster | \n
|---|---|---|
| Unit | \nThread within a process | \nSeparate OS process | \n
| Memory | \nCan share via SharedArrayBuffer | \nFully isolated, IPC only | \n
| Use case | \nCPU-bound JavaScript off the main thread | \nScale I/O-bound throughput across cores | \n
| Overhead | \nV8 isolate + structured clone | \nFull process + IPC serialization | \n
In practice, a high-throughput service often uses both: cluster (or container replicas) to span cores, and a worker pool inside each process to absorb occasional CPU spikes. The mental model is not \"cluster OR workers.\" It is \"cluster for I/O scaling, workers for CPU offloading, and yes you probably want both.\"
\nStop searching \"Node.js concurrency best practice.\" The answer depends on your bottleneck, and there are exactly four tools:
\nWHAT IS YOUR BOTTLENECK?\n─────────────────────────────────────────────────────────\nIs it I/O-bound (network, DB, files)?\n └── async/await. The event loop already handles this.\n Do not add workers. Do not add cluster.\n The platform solved this. Use it.\n\nIs it CPU-bound JavaScript (computation, parsing, crypto)?\n └── Worker threads, behind a pool.\n Do not bump UV_THREADPOOL_SIZE. It won't help.\n\nIs one core saturated under concurrent I/O traffic?\n └── Cluster across cores (or run multiple container replicas).\n This is about throughput, not computation.\n\nAre you spawning a worker per request?\n └── Stop. Use piscina. You are paying startup cost for nothing.\n─────────────────────────────────────────────────────────Four tools. Four bottlenecks. Four answers. Everything else is premature optimization or cargo-cult config tweaking.
\n| Tool | \nRuns JS in parallel? | \nBest for | \nMain cost | \n
|---|---|---|---|
async/await + event loop | \nNo | \nI/O-bound work | \nBlocks if you do CPU work on main thread | \n
| libuv thread pool | \nNo (runs C, not your JS) | \nfs, dns.lookup, crypto, zlib | \nFixed size; never accelerates your JS | \n
| Worker threads + pool | \nYes | \nCPU-bound JavaScript | \nStartup + structured-clone copying | \n
| Cluster / replica processes | \nYes | \nScaling I/O load across cores | \nProcess overhead; no shared state | \n
The most expensive mistake in Node.js performance tuning is optimizing the wrong bottleneck. You think your endpoint is slow because of I/O, so you add cluster. It was actually a synchronous JSON.parse on a 5 MB payload blocking the event loop. Cluster added four more processes all blocking on the same JSON.parse. You made it worse.
Before you touch UV_THREADPOOL_SIZE, before you add cluster, before you reach for workers, run monitorEventLoopDelay. If the p99 is high, the event loop is saturated. Then ask: is it saturated because of I/O (add cluster/replicas) or because of CPU (add workers)? The answer is in the data. The data is in node:perf_hooks. Use it.
const { monitorEventLoopDelay } = require('node:perf_hooks');\nconst histogram = monitorEventLoopDelay({ resolution: 20 });\nhistogram.enable();\n\n// Let it collect for a while under load, then:\nsetTimeout(() => {\n histogram.disable();\n console.log('Event loop delay (ms):');\n console.log(' min:', histogram.min / 1e6);\n console.log(' p50:', histogram.mean / 1e6);\n console.log(' p99:', histogram.percentile(99) / 1e6);\n console.log(' max:', histogram.max / 1e6);\n}, 30000);If p99 is above 10ms, your users feel it. Above 50ms, your health checks are at risk. Above 100ms, you are one traffic spike away from an incident. The numbers do not lie. Your intuition about where the bottleneck is probably does.
\nThe OpenReplay Team's article ends with a mental model worth tattooing on your debugging workflow: stop asking \"is Node single-threaded?\" and start asking \"what is my bottleneck?\" Waiting is the event loop's job. Computing in parallel is the worker pool's. Spreading load across cores is cluster's.
\nProfile the slow endpoint. Identify whether it is stuck waiting or stuck computing. The right tool follows directly. Everything else is guessing, and guessing in production is how 3 AM incidents happen.
\nNode.js gives you four concurrency primitives. They are well-documented, well-tested, and stable. The reason your server is slow is not that Node is inadequate. It is that you never sat down and learned what your runtime actually does.
\nNow you know. Go fix that endpoint.
\nThis article was written with AI support and reviewed by the author.
\n", "image": "https://dout.dev/assets/og/posts/2026-08-10-nodejs-concurrency-event-loop.png", "date_published": "2026-08-10T00:00:00.000Z", "tags": [ "nodejs", "backend", "performance", "architecture", "javascript" ] }, { "id": "https://dout.dev/posts/2026-08-09-html-is-automation-disguised-as-markup.html", "url": "https://dout.dev/posts/2026-08-09-html-is-automation-disguised-as-markup.html", "title": "HTML Is Automation Disguised as Markup (11 Features That Deleted My JavaScript)", "summary": "The markup you skip is the code you rewrite", "content_html": "Sandhya Mehtele wrote a piece that should resonate with every frontend developer who has ever treated HTML as the boring part of the job. Her thesis is simple: she ignored HTML for years, reached for JavaScript and libraries to solve every problem, then discovered that the platform had already solved most of them in markup.
\nI am going further. HTML is not just \"useful.\" HTML is a runtime. Every native element, every semantic tag, every built-in attribute is code the browser executes on your behalf - tested across billions of devices, maintained by browser vendors, and immune to framework churn. When you replace a native HTML feature with JavaScript, you are not adding functionality. You are paying to rewrite something the platform already shipped.
\nHere are the 11 features that prove it, with the architectural reasoning Sandhya's article implies but doesn't spell out.
\nThe difference between a <div> and a <nav> is not cosmetic. A <div> is a rectangle. A <nav> is a contract: it tells the browser, the screen reader, the search engine, and the next developer that this region contains navigation.
<!-- Div soup: the browser knows nothing, the screen reader knows nothing -->\n<div class=\"header\">\n <div class=\"logo\">...</div>\n <div class=\"nav\">\n <div class=\"nav-item\" onclick=\"navigate('/home')\">Home</div>\n </div>\n</div>\n<div class=\"main-content\">...</div>\n<div class=\"footer\">...</div>\n\n<!-- Semantic HTML: the structure is the documentation -->\n<header>\n <a href=\"/\" aria-label=\"Homepage\"><img src=\"logo.svg\" alt=\"Acme\"></a>\n <nav aria-label=\"Primary\">\n <ul>\n <li><a href=\"/home\">Home</a></li>\n </ul>\n </nav>\n</header>\n<main>...</main>\n<footer>...</footer>Semantic HTML eliminates the need for:
\nrole=\"navigation\" on your nav - <nav> implies itrole=\"main\" on your content wrapper - <main> implies itrole=\"banner\" on your header - <header> implies it (when not nested in <article> or <section>)role=\"contentinfo\" on your footer - <footer> implies itonclick handlers for links - <a href> handles navigation, focus, keyboard, and context menus nativelyEvery ARIA role you add to a <div> is an admission that you used the wrong element. The browser already shipped <nav>, <main>, <header>, <footer>, <article>, <section>, <aside>, <details>, <summary>, <figure>, <figcaption>, <time>, <address>, and more. Each one carries implicit ARIA semantics. Each one is understood by every screen reader released in the last decade. Each one costs zero JavaScript.
The rule: if your UI only works because of CSS hacks and ARIA duct tape, your HTML structure is broken. Fix the structure first. The styles will follow.
\nEvery frontend developer has written some version of this:
\n// The JavaScript you no longer need\nfunction validateEmail(email) {\n const re = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n return re.test(email);\n}\n\nfunction validateForm() {\n const email = document.getElementById('email').value;\n const password = document.getElementById('password').value;\n const errors = [];\n\n if (!email) errors.push('Email is required');\n else if (!validateEmail(email)) errors.push('Invalid email');\n\n if (!password) errors.push('Password is required');\n else if (password.length < 8) errors.push('Password must be at least 8 characters');\n\n if (errors.length) {\n errors.forEach(e => showError(e));\n return false;\n }\n return true;\n}Here is the HTML that replaces all of it:
\n<form>\n <label for=\"email\">Email</label>\n <input\n type=\"email\"\n id=\"email\"\n name=\"email\"\n required\n autocomplete=\"email\"\n >\n\n <label for=\"password\">Password</label>\n <input\n type=\"password\"\n id=\"password\"\n name=\"password\"\n required\n minlength=\"8\"\n autocomplete=\"current-password\"\n >\n\n <button type=\"submit\">Sign in</button>\n</form>What the browser gives you for free:
\ntype=\"email\": validates email format, triggers the @ key on mobile keyboardsrequired: blocks submission, shows a localized error messageminlength=\"8\": blocks submission if the password is too shortautocomplete: lets the browser prefill saved credentials, no JavaScript:invalid and :valid pseudo-classes: style validation states with zero JavaScriptinput:invalid {\n border-color: var(--color-error);\n}\n\ninput:valid {\n border-color: var(--color-success);\n}This is not \"nice to have.\" This is 200 lines of JavaScript deleted and replaced by four HTML attributes. The validation is more robust than your hand-rolled regex (the browser's email validator handles internationalized domain names, quoted local parts, and edge cases you forgot). It works offline. It is accessible by default. It ships in every browser.
\nThe only legitimate reason to write custom form validation in 2026 is when the constraint is genuinely custom - two fields must match, or a value depends on an API response. Even then, use setCustomValidity() on the native constraint validation API instead of building your own error system. Work with the platform. Don't pave over it.
pattern attribute: regex validation without JavaScript<!-- Username: 3-20 alphanumeric characters, must start with a letter -->\n<input\n type=\"text\"\n pattern=\"[A-Za-z][A-Za-z0-9]{2,19}\"\n title=\"Username must be 3-20 characters, starting with a letter\"\n required\n>\n\n<!-- Italian VAT number: 11 digits -->\n<input\n type=\"text\"\n pattern=\"[0-9]{11}\"\n title=\"Enter an 11-digit VAT number\"\n inputmode=\"numeric\"\n>\n\n<!-- Hex color -->\n<input\n type=\"text\"\n pattern=\"#[0-9A-Fa-f]{6}\"\n title=\"Enter a hex color like #FF6600\"\n>The pattern attribute runs a regex against the input value on form submission. If it fails, the form does not submit and the title text appears as the error message. No JavaScript. No library. No custom validation function. Just a regex and a human-readable description.
This also reduces bad data at the backend. If the pattern blocks \"not-a-color\" before it reaches your server, you have fewer validation edge cases to handle, fewer error responses to render, and a smaller attack surface. The frontend validation is not a replacement for backend validation - it is a free pre-filter that catches honest mistakes before they cost a round-trip.
download attribute: file downloads without a backend<!-- A PDF that downloads instead of opening in the browser -->\n<a href=\"/reports/q4-2026.pdf\" download>\n Download Q4 Report (PDF)\n</a>\n\n<!-- Download with a custom filename -->\n<a href=\"/generated/invoice-83721.pdf\" download=\"Acme-Invoice-83721.pdf\">\n Download Invoice\n</a>\n\n<!-- A CSV export generated client-side from a blob -->\n<a id=\"export-link\" download=\"data.csv\">Export Data</a>\n<script>\n const csv = 'Name,Email\\nAlice,alice@example.com\\n';\n const blob = new Blob([csv], { type: 'text/csv' });\n document.getElementById('export-link').href = URL.createObjectURL(blob);\n</script>Before the download attribute, triggering a file download required a Content-Disposition header on the server, or a server-side proxy, or a form POST with the right encoding. Now a single attribute on an <a> tag solves it. Combine it with URL.createObjectURL() for client-side generated files, and you have a fully client-side export system with zero backend involvement.
contenteditable: rich text editing without a library<div contenteditable=\"true\" role=\"textbox\" aria-multiline=\"true\">\n Start typing here. <strong>Bold</strong>, <em>italic</em>, whatever you want.\n</div>For internal tools - admin panels, CMS backends, dashboards - contenteditable replaces entire rich text libraries. The browser handles cursor position, text selection, undo/redo, spell check, and keyboard navigation. You get document.execCommand() for bold, italic, lists, links. Or better, use the modern Input Events API for structured editing.
// Listen for changes without polling\nconst editor = document.querySelector('[contenteditable]');\neditor.addEventListener('input', (e) => {\n console.log('Content changed:', e.target.innerHTML);\n});Is this a replacement for a full collaborative editor like ProseMirror or Slate? No. Those libraries exist for a reason - real-time collaboration, structured document models, version history. But for an admin panel where someone needs to edit a product description, contenteditable with ten lines of JavaScript handles the entire use case. No 200 KB editor bundle. No dependency tree. No framework-specific wrapper.
autofocus: one attribute, one click deleted<!-- The search field is ready before the user's finger touches the keyboard -->\n<input type=\"search\" name=\"q\" autofocus placeholder=\"Search articles...\">\n\n<!-- Login form: focus on the email field -->\n<input type=\"email\" name=\"email\" autofocus autocomplete=\"email\">Every login page, every search bar, every form where the first action is obvious - the user should not have to click the first field. autofocus places the cursor automatically. One attribute. Zero JavaScript. No document.getElementById('email').focus(). No useEffect(() => ref.current?.focus(), []). No timing bugs where the focus fires before the DOM is ready.
The browser handles edge cases: autofocus respects prefers-reduced-motion, it does not steal focus from a different tab, and it only fires once per page load. Your JavaScript implementation probably missed at least one of these.
hidden attribute: state management without CSS<!-- Hidden until JavaScript toggles it -->\n<div id=\"error-message\" hidden>\n Something went wrong. Please try again.\n</div>\n\n<script>\n // Show the error\n document.getElementById('error-message').hidden = false;\n\n // Hide it again\n document.getElementById('error-message').hidden = true;\n</script>Before hidden, toggling visibility required:
element.style.display = 'none' - overwrites any existing display value, breaks flex/grid items when restoredelement.classList.toggle('hidden') - requires a CSS rule .hidden { display: none !important }, adds a specificity landmine{error && <ErrorMessage />}, which unmounts the element entirely and resets its stateThe hidden attribute is none of these. It is a native HTML boolean attribute with a single, predictable behavior: the element is removed from the accessibility tree and hidden from view. You toggle element.hidden = true/false. No CSS conflict. No specificity war. No lost state. The platform does exactly what you mean.
/* Style hidden elements differently when they become visible */\n#error-message:not([hidden]) {\n display: flex;\n gap: 0.5rem;\n padding: 1rem;\n background: var(--color-error-bg);\n border-radius: var(--radius-md);\n}<!-- Determinate: value is known -->\n<label for=\"upload-progress\">Uploading files...</label>\n<progress id=\"upload-progress\" value=\"65\" max=\"100\">65%</progress>\n\n<!-- Indeterminate: value is unknown, bar animates automatically -->\n<progress id=\"loading\">Loading...</progress>\n\n<script>\n const bar = document.getElementById('upload-progress');\n let percent = 0;\n const interval = setInterval(() => {\n percent += 5;\n bar.value = percent;\n if (percent >= 100) clearInterval(interval);\n }, 200);\n</script>The <progress> element renders a native progress bar. Determinate mode (value + max) shows a filled bar. Indeterminate mode (no value) shows an animated striped bar - the browser handles the animation, no CSS @keyframes required.
Use cases: file uploads, background job status, multi-step form progress, data sync indicators. Every one of these was previously implemented with a <div> and a width percentage in JavaScript, or worse, an entire progress bar library. The platform ships one. Use it.
<meter>: visual indicators that feel professional<!-- Disk usage: 68% -->\n<label for=\"disk-usage\">Disk Usage</label>\n<meter id=\"disk-usage\" value=\"0.68\" min=\"0\" max=\"1\">68%</meter>\n\n<!-- Risk score with thresholds -->\n<meter value=\"75\" min=\"0\" max=\"100\" low=\"33\" high=\"66\" optimum=\"0\">\n Risk: 75/100\n</meter>\n\n<!-- CPU usage: gauge-style -->\n<label for=\"cpu\">CPU</label>\n<meter id=\"cpu\" value=\"0.42\" min=\"0\" max=\"1\" low=\"0.5\" high=\"0.8\" optimum=\"0.2\">42%</meter><meter> is the semantic sibling of <progress>, designed for scalar measurements within a known range - disk usage, risk scores, quotas, ratings. It has built-in threshold styling: values below low get one color, between low and high another, above high a third. The browser handles the color transitions. You get a professional-grade gauge with one HTML element.
This is the kind of element developers rebuild in JavaScript because they do not know it exists. Stop rebuilding platform features. Learn them instead.
\n<!-- Email: validates format, triggers email keyboard on mobile -->\n<input type=\"email\" name=\"email\" autocomplete=\"email\" required>\n\n<!-- URL: validates protocol, triggers URL keyboard on mobile -->\n<input type=\"url\" name=\"website\" autocomplete=\"url\" placeholder=\"https://example.com\">\n\n<!-- Tel: triggers phone keypad, no format validation -->\n<input type=\"tel\" name=\"phone\" autocomplete=\"tel\" inputmode=\"tel\">\n\n<!-- Number: numeric keyboard, built-in min/max/step -->\n<input type=\"number\" name=\"quantity\" min=\"1\" max=\"99\" step=\"1\" value=\"1\">\n\n<!-- Date: native date picker, localized format -->\n<input type=\"date\" name=\"birthday\" min=\"1920-01-01\" max=\"2026-12-31\">\n\n<!-- Search: clear button, search keyboard on mobile -->\n<input type=\"search\" name=\"q\" autocomplete=\"search\" aria-label=\"Search articles\">Every one of these input types:
\ntype=\"email\" rejects \"not-an-email\")type=\"number\" shows numeric keypad, type=\"tel\" shows phone keypad)type=\"date\" shows a date picker, type=\"search\" shows a clear button)If you are using <input type=\"text\"> with a custom JavaScript validator for email, URL, number, date, or search, you are rewriting platform code. Stop it. The browser already ships the validator, the keyboard, the picker, and the accessibility tree. Your job is to use them, not to replace them.
<mark> and <time>: semantic power moves<!-- Highlight search matches -->\n<p>\n Results for \"<mark>CSS Grid</mark>\": found in 3 articles.\n The <mark>CSS Grid</mark> specification defines a two-dimensional layout system...\n</p>\n\n<!-- Machine-readable time with human-readable display -->\n<p>\n Published on\n <time datetime=\"2026-08-09T10:00:00+02:00\">August 9, 2026</time>\n</p>\n\n<!-- Duration -->\n<p>\n Estimated reading time:\n <time datetime=\"PT7M\">7 minutes</time>\n</p><mark> semantically indicates highlighted text - typically for search results or passages of interest. Screen readers may announce it differently. Search engines can extract it as relevant context. It communicates intent in a way <span class=\"highlight\"> does not.
<time> makes dates and durations machine-readable via the datetime attribute while displaying human-friendly text. Browsers can offer \"Add to Calendar\" for events. Search engines extract structured data without JSON-LD. Assistive technology can convert relative times (\"3 days ago\") to absolute dates.
These are not flashy features. They are quiet, structural improvements that compound across a project: better SEO, better accessibility, better interoperability. The kind of thing JavaScript cannot fix retroactively because by the time the script runs, the parser has already decided what the document means.
\nSandhya closes with a line worth engraving: \"HTML5 is automation disguised as markup.\" She is right, and the implication is bigger than she states.
\nEvery native HTML feature you use is code you do not write, test, debug, bundle, update, document, or maintain. The browser vendor does all of that for you, for free, across every device their engine runs on. When you replace a native feature with a JavaScript implementation, you are not adding capability. You are moving code from the platform (where it is free, fast, and maintained by someone else) to your bundle (where it costs you everything).
\nThe 11 features above are the tip of the iceberg. There are more: <datalist> for autocomplete, <details>/<summary> for collapsible sections, <dialog> for modals, <output> for calculation results, <template> for reusable fragments, <slot> for content projection, <picture> for responsive images, <map> for image maps, <abbr> for abbreviations, <dfn> for definitions, <kbd> for keyboard input, <samp> for sample output, <del> and <ins> for document changes.
Every one replaces JavaScript you were about to write.
\nThe developers who ship fastest are not the ones who know the most frameworks. They are the ones who know what the platform already does, and only write code for what it does not.
\nStop treating HTML as a wrapper. It is a runtime. Learn it like one.
\nThis article was written with AI support and reviewed by the author.
\n", "image": "https://dout.dev/assets/og/posts/2026-08-09-html-is-automation-disguised-as-markup.png", "date_published": "2026-08-09T00:00:00.000Z", "tags": [ "html", "frontend", "web-standards", "a11y", "vanilla-js" ] }, { "id": "https://dout.dev/posts/2026-08-06-css-grid-vs-flexbox-2026.html", "url": "https://dout.dev/posts/2026-08-06-css-grid-vs-flexbox-2026.html", "title": "CSS Grid vs Flexbox in 2026 - Stop Guessing, Start Knowing", "summary": "The war that never should have happened", "content_html": "For nearly a decade, frontend engineers have treated CSS Grid and Flexbox as opposing factions. \"Should I build this layout with Grid or Flexbox?\" The question itself is broken. It is like asking whether you should build a house with a hammer or a saw. You need both. The difference between a senior and a junior CSS architect is knowing which tool activates before typing a single property.
\nRahul Kaklotar wrote the definitive technical breakdown of how these two engines work under the hood and when to reach for each. What follows builds on his blueprint and adds the layer most tutorials skip: the architectural reasoning that makes the choice obvious before you write any code.
\nCSS layout engines are not competing. They solve fundamentally different spatial problems.
\n┌────────────────────────────────────────────────────────┐\n│ Modern Layout Engine │\n└──────────────────────────┬─────────────────────────────┘\n │\n ┌────────────────────┴────────────────────┐\n ▼ ▼\n┌─────────────────────────┐ ┌─────────────────────────┐\n│ Flexbox (1D) │ │ CSS Grid (2D) │\n├─────────────────────────┤ ├─────────────────────────┤\n│ • Content-driven │ │ • Structure-driven │\n│ • Single-axis flow │ │ • Dual-axis alignment │\n│ • Dynamic space sharing │ │ • Rigorous track grid │\n│ • \"Content decides\" │ │ • \"Container decides\" │\n└─────────────────────────┘ └─────────────────────────┘Flexbox is content-first. You put items in a row. The items tell the container how much space they need. The container distributes the remainder. When it wraps, each row is an independent universe - items in row 2 have zero awareness of column edges in row 1.
\nCSS Grid is structure-first. You define the tracks. The tracks exist before the content arrives. Children are placed into coordinate intersections. An item in Row 2, Column 3 is bound to the exact track boundaries as the item in Row 1, Column 3. The grid enforces alignment. You cannot opt out.
\nThis is not a philosophical difference. It is a mechanical one. And it has concrete consequences for every layout decision you make.
\nThe number one Flexbox mistake is treating it as \"a row of things\" without understanding how the browser calculates widths. Here is the formula Rahul surfaced:
\nFLEX ITEM SIZING FORMULA\n────────────────────────────────────────────\nAvailable Free Space = Container Width − SUM(flex-basis)\n\nIf Free Space > 0:\n Final Width = flex-basis + (flex-grow / SUM(flex-grow)) × Free Space\n\nIf Free Space < 0:\n Final Width = flex-basis − (flex-shrink-scaled / SUM(flex-shrink-scaled)) × |Free Space|\n────────────────────────────────────────────When you write flex: 1 1 200px, you are configuring three engine parameters: how much the item wants (flex-basis), how much it takes from leftover space (flex-grow), and how much it gives up under pressure (flex-shrink).
flex-basis: 0 vs flex-basis: auto distinction everyone gets wrongThis is the single most misunderstood mechanic in Flexbox:
\n/* Equal widths regardless of content length */\n.equal-columns {\n flex: 1 1 0%;\n /* Basis is zero. ALL container width is free space.\n Every item gets exactly one share. Content doesn't matter. */\n}\n\n/* Proportional sizing based on content + remaining space */\n.natural-columns {\n flex: 1 1 auto;\n /* Basis is the item's intrinsic content width.\n Only leftover space is distributed by flex-grow.\n A longer word gets more base width. */\n}Use flex-basis: 0 when you want enforced visual equality. Use flex-basis: auto when you want natural reading flow that expands proportionally. Confuse the two and you will spend an hour wondering why your equal-width columns are not equal.
align-content upgradeModern browser engines now support align-content on single-line flex containers - a feature that historically required align-items hacks or margin: auto tricks:
.card-actions {\n display: flex;\n flex-direction: row;\n align-content: center; /* Works on single-line containers in 2026 */\n gap: 0.75rem;\n}This closes one of the last ergonomic gaps between Flexbox and Grid for vertical centering.
\n.site-header {\n display: flex;\n align-items: center;\n justify-content: space-between;\n gap: 1.5rem;\n padding: 1rem 2rem;\n}\n\n.nav-group {\n display: flex;\n align-items: center;\n gap: 1rem;\n}\n\n/* Push user profile to the far right without wrapper divs */\n.user-profile {\n margin-inline-start: auto;\n}This is Flexbox at its best: a single-axis flow where one item (margin-inline-start: auto) consumes all remaining space and pushes itself to the edge. No grid declaration. No column math. The browser calculates the space distribution in O(N) time.
Grid activates when the layout is a system, not a list. The key engineering difference is that Grid solves a constraint problem across two axes simultaneously.
\n.grid-container {\n display: grid;\n grid-template-columns: 250px 1fr 2fr;\n gap: 1.5rem;\n}After the fixed 250px track is allocated, the remaining space is split into 3 fractions. Track 2 gets 1. Track 3 gets 2. The container defines the structure. The content adapts.
\nThe sizing primitives give you surgical control:
\n.grid-advanced {\n grid-template-columns:\n minmax(200px, 400px) /* Clamped: never smaller than 200, never larger than 400 */\n fit-content(500px) /* Intrinsic size, capped at 500px */\n max-content /* Expand to fit the longest unbroken string */\n min-content; /* Contract to the widest single word */\n}auto-fill vs auto-fit: the responsive grid you don't need media queries for/* AUTO-FILL: Creates empty tracks if space permits */\n.grid-auto-fill {\n grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));\n}\n\n/* AUTO-FIT: Collapses empty tracks, items stretch to fill */\n.grid-auto-fit {\n grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));\n}At 1000px container width with 280px minimum items:
\nAUTO-FILL (2 items present):\n┌──────────┬──────────┬────────────┐\n│ Item 1 │ Item 2 │ (empty) │ ← Track created, stays empty\n└──────────┴──────────┴────────────┘\n\nAUTO-FIT (2 items present):\n┌────────────────────┬────────────────────┐\n│ Item 1 (stretched)│ Item 2 (stretched)│ ← Empty track collapsed\n└────────────────────┴────────────────────┘Use auto-fill when you want a fixed grid that leaves gaps for potential future items. Use auto-fit when you want the existing items to expand and fill the container. Choose wrong and you have either awkward empty columns or unexpectedly wide cards. Know the difference and your responsive grids become deterministic.
grid-template-areas: the visual layout mapThis is the feature that makes Grid a genuine engineering tool:
\n.app-shell {\n display: grid;\n grid-template-areas:\n \"header header\"\n \"sidebar main\"\n \"footer footer\";\n grid-template-columns: 260px 1fr;\n grid-template-rows: auto 1fr auto;\n min-height: 100vh;\n}\n\n.header { grid-area: header; }\n.sidebar { grid-area: sidebar; }\n.main { grid-area: main; }\n.footer { grid-area: footer; }The CSS is the wireframe. A new team member reads the grid-template-areas block and understands the entire page structure in five seconds. No framework, no component tree traversal, no layout documentation that has drifted from the code. The layout is the documentation.
Subgrid lets nested elements inherit and lock onto the parent's track lines:
\n.parent-grid {\n display: grid;\n grid-template-columns: repeat(3, 1fr);\n gap: 1.5rem;\n}\n\n/* Spans all 3 parent columns, but subgrid aligns internal content */\n.card-composite {\n grid-column: 1 / -1;\n display: grid;\n grid-template-columns: subgrid; /* Inherits parent tracks */\n}\n\n.card-composite .header { grid-column: 1 / 3; }\n.card-composite .aside { grid-column: 3 / 4; }Before subgrid, aligning nested card headers across different cards required JavaScript to measure heights and set min-height values. Now the browser does it natively. This is the kind of platform absorption that makes utility libraries obsolete - a problem that used to require a framework or a script is now a one-line CSS declaration.
Grid and Flexbox decide how things flow. Container queries decide when the flow changes. Together they make responsive design component-driven instead of viewport-driven:
\n.card-wrapper {\n container-type: inline-size;\n container-name: card;\n}\n\n/* Default: stack vertically (Flexbox) */\n.card-component {\n display: flex;\n flex-direction: column;\n gap: 1rem;\n}\n\n/* Wider container: switch to 2D layout (Grid) */\n@container card (min-width: 550px) {\n .card-component {\n display: grid;\n grid-template-columns: 200px 1fr;\n grid-template-rows: auto 1fr;\n }\n .card-media {\n grid-row: 1 / -1;\n }\n}The component queries its own parent, not the viewport. Place it in a narrow sidebar - it stacks. Place it in a full-width article - it goes side-by-side. Same component, same code, zero media queries. This is the correct abstraction for reusable UI: the component adapts to the space it is given, not the space of the entire browser window.
\nRahul's analysis of layout pass complexity is worth internalizing:
\n| Engine | \nComplexity | \nWhat it means | \n
|---|---|---|
| Flexbox | \nO(N) | \nLinear pass along one axis. Fast. Fixed flex-basis: 0 makes child calculations O(1). | \n
| Grid | \nO(N log N) | \nConstraint solver across two axes. Explicit templates (grid-template-areas) bypass auto-placement and reduce cost. | \n
This is not an argument against Grid. It is an argument against using Grid for single-axis layouts. When you write display: grid; grid-template-columns: repeat(4, auto) for a button row, you are paying O(N log N) for a problem Flexbox solves in O(N). The performance difference is invisible for a single component, but it compounds across a page with hundreds of layout containers.
The rule: Flexbox for lists. Grid for systems. Container queries for behavior.
\n/* WRONG: calc() hacks to fake 2D alignment */\n.bad-fake-grid {\n display: flex;\n flex-wrap: wrap;\n margin: -10px;\n}\n.bad-fake-grid > * {\n width: calc(33.333% - 20px);\n margin: 10px;\n}\n\n/* CORRECT: the browser already has this engine */\n.good-real-grid {\n display: grid;\n grid-template-columns: repeat(3, 1fr);\n gap: 20px;\n}If you are doing math in calc() to make flex items align in columns, you are using the wrong tool. CSS Grid was literally built for this.
/* WRONG: a 2D constraint solver for a 1D problem */\n.bad-button-group {\n display: grid;\n grid-template-columns: repeat(4, auto);\n gap: 1rem;\n}\n\n/* CORRECT: the 1D engine for a 1D problem */\n.good-button-group {\n display: flex;\n gap: 1rem;\n}Every unnecessary Grid declaration is O(N log N) work the browser does not need to do.
\nmin-width: 0 in flex containersFlex items default to min-width: auto, which means they refuse to shrink below their intrinsic content size:
/* Without this, long URLs or unbroken strings overflow the container */\n.flex-item-with-truncation {\n min-width: 0;\n overflow: hidden;\n text-overflow: ellipsis;\n white-space: nowrap;\n}This is the single most common Flexbox bug in production and the one that wastes the most debugging time because the visual result (overflow) looks like a Grid problem when it is actually a Flexbox default.
\nLAYOUT SELECTION - ASK IN ORDER\n─────────────────────────────────────────────\nQ1: Do you need strict 2D column/row alignment?\n ├── YES → CSS GRID. Stop asking.\n └── NO → Proceed to Q2.\n\nQ2: Is the layout driven by content length or dynamic wrapping?\n ├── YES → FLEXBOX. Stop asking.\n └── NO → Proceed to Q3.\n\nQ3: Are you positioning major page-level structural zones?\n ├── YES → CSS GRID (grid-template-areas).\n └── NO → FLEXBOX. It's a list. Treat it like one.\n─────────────────────────────────────────────Three questions. No guesswork. No \"I'll try Grid and see if it works.\" The choice falls out of the problem description.
\nBefore you open a pull request, run through these five checks:
\ngap, not margin. Gap is the layout engine's responsibility. Margin is the element's.minmax() with auto-fill/auto-fit, not brittle media query breakpoints.grid-template-rows: subgrid is the one-line answer.min-width: 0.Here is the thing Rahul's article implies but does not say outright: the CSS layout engine is now complete. Between Flexbox, Grid, container queries, subgrid, native masonry (grid-template-rows: masonry), and the align-content single-line upgrade, there is no layout problem that requires a third-party abstraction layer.
You do not need a layout framework. You do not need a grid system library. You do not need Bootstrap's grid, Tailwind's grid utilities, or any col-md-6-style abstraction. The browser ships two layout engines that together cover the entire problem space. Learn them. Use them directly. Delete the middleman.
The difference between \"CSS is hard\" and \"CSS is deterministic\" is not talent. It is understanding the mechanical difference between a 1D content-first distribution engine and a 2D structure-first constraint solver. Once you internalize that distinction, every layout decision becomes obvious.
\nThe war is over. Grid and Flexbox won. Now go build.
\nThis article was written with AI support and reviewed by the author.
\n", "image": "https://dout.dev/assets/og/posts/2026-08-06-css-grid-vs-flexbox-2026.png", "date_published": "2026-08-06T00:00:00.000Z", "tags": [ "css", "frontend", "layout", "web-standards", "performance" ] }, { "id": "https://dout.dev/posts/2026-08-03-bury-utility-css-frameworks.html", "url": "https://dout.dev/posts/2026-08-03-bury-utility-css-frameworks.html", "title": "It Is Time to Bury Utility CSS Frameworks (Yes, Even Tailwind)", "summary": "The platform moved. Tailwind didn't get the memo.", "content_html": "Italo Baeza Cabrera wrote a measured piece asking whether it is time to move on from Tailwind CSS. His conclusion was careful: Tailwind is overkill for presentational sites, still useful for high-interactivity apps when you build a proper three-layer design system on top of it. I think Italo was too generous.
\nThe question is not whether Tailwind is sometimes useful. The question is whether it is still the best tool for the job it claims to solve. And the answer, in 2026, is no. The platform absorbed every problem Tailwind was built to solve, and the framework's remaining value proposition is a build step you don't need, a class-name tax you shouldn't pay, and a specificity model that fights the cascade instead of working with it.
\nThis is not a \"Tailwind sucks\" post. Tailwind was brilliant in 2017. The problem is that 2017 was almost a decade ago, and CSS is not the same language anymore.
\nLet's be fair. When Tailwind appeared, it addressed four genuine pain points:
\n.card, .container, .panel, or .box. Utility classes sidestep naming entirely.#876876 means nothing. bg-red-500 means something. A constrained palette of values kept teams consistent.In 2017, every one of those was a real problem. In 2026, none of them are.
\nThe Tailwind solution to naming was to eliminate names: don't call it a card, call it rounded-lg bg-white p-4 shadow-md. This works until you have twenty cards on a page, each with the same fourteen-class string repeated identically. At that point, you have not eliminated the abstraction-you have just refused to give it a name, and now the abstraction lives as a string literal duplicated across your markup instead of as a single CSS class.
Native CSS gives you better options:
\n/* Option A: a semantic class backed by custom properties */\n.card {\n border-radius: var(--radius-lg);\n background: var(--color-white);\n padding: var(--spacing-4);\n box-shadow: var(--shadow-md);\n}\n\n/* Option B: an attribute selector backed by custom properties */\n[data-component=\"card\"] {\n border-radius: var(--radius-lg);\n background: var(--color-white);\n padding: var(--spacing-4);\n box-shadow: var(--shadow-md);\n}The attribute selector approach has a property that utility classes lack: the selector itself carries semantic meaning. class=\"rounded-lg bg-white p-4 shadow-md\" tells you what the element looks like. [data-component=\"card\"] tells you what the element is. When you read the HTML, you understand the document structure. When you read the CSS, you find the component definition in one place, not scattered across every instance in the markup.
:root {\n --color-primary: oklch(0.55 0.2 260);\n --color-primary-hover: oklch(0.55 0.2 260 / 0.8);\n --radius-sm: 0.25rem;\n --radius-md: 0.5rem;\n --radius-lg: 0.75rem;\n --shadow-sm: 0 1px 3px oklch(0 0 0 / 0.1);\n --shadow-md: 0 4px 6px oklch(0 0 0 / 0.1);\n --spacing-2: 0.5rem;\n --spacing-4: 1rem;\n}Every one of Tailwind's @theme tokens maps directly to a custom property. The difference is that custom properties work in every browser, require zero build steps, are debuggable in DevTools, and can be changed at runtime. Tailwind's @theme block compiles down to… custom properties. You are running a build step to generate something the browser already supports natively.
Italo mentions that \"pairing Tailwind CSS with a CSS processor is the only way to make the framework extend its legs.\" That is an admission of failure. If your utility framework requires a preprocessor to be useful, and the preprocessor features you need (nesting, mixins, color manipulation) are now native to CSS, then the utility framework is a middleman. Cut the middleman.
\nWhat Sass gave us → what CSS absorbed:
\n$variable → --custom-propertydarken($color, 10%) → color-mix(in srgb, var(--color), black 10%)@mixin → CSS Functions and Mixins Module (working draft, shipping behind flags)& syntax)@if / @else → CSS if() function (shipping in Chrome)The pipeline that was once Sass → PostCSS → Tailwind → Autoprefixer → CSS is now CSS. One step. Zero dependencies.
Every Tailwind class on an element is a string the browser must parse, intern, and match against the stylesheet. Twenty classes on an element means twenty lookups. Now multiply by a hundred elements on a page. Now multiply by every page on your site.
\n<!-- This element carries fourteen class lookups -->\n<div class=\"flex flex-col gap-4 p-6 bg-white rounded-lg shadow-md border border-gray-200 hover:shadow-lg transition-shadow duration-200\">Compare:
\n<!-- This element carries one attribute lookup -->\n<div data-component=\"card\">The CSS for the second approach:
\n[data-component=\"card\"] {\n display: flex;\n flex-direction: column;\n gap: var(--spacing-4);\n padding: var(--spacing-6);\n background: var(--color-white);\n border-radius: var(--radius-lg);\n box-shadow: var(--shadow-md);\n border: 1px solid var(--color-gray-200);\n transition: box-shadow 200ms ease;\n}\n\n[data-component=\"card\"]:hover {\n box-shadow: var(--shadow-lg);\n}Same visual result. One attribute selector instead of fourteen classes. The browser does one lookup, not fourteen. The HTML is readable. The CSS is maintainable. The abstraction has a name.
\nEvery time I suggest [data-component=\"card\"] over class=\"card\", someone objects that attribute selectors are \"slower\" than class selectors. Let me kill this myth: the performance difference between a class selector and an attribute selector is below the noise floor for any real application. Browsers optimize both to the same order of magnitude. The thing that actually slows down style resolution is the number of rules and the complexity of the cascade, not the selector type.
What attribute selectors give you that classes do not:
\n[aria-expanded=\"true\"], [aria-current=\"page\"], [data-loading]-these selectors tie visual state directly to semantic state. When your accessible markup is correct, your styles are automatically correct too. No class=\"is-active is-expanded\" sync bugs.0,1,0). They don't create specificity wars. Combined with @layer, you control the cascade explicitly.<nav data-component=\"breadcrumb\" aria-label=\"Breadcrumb\"> tells you everything. <nav class=\"flex gap-2 text-sm text-gray-500\"> tells you nothing about what it is, only how it looks right now.[data-component=\"card\"] will never conflict with a third-party library's .card class. The data- namespace is yours.@layer fixes what utility frameworks brokeTailwind's approach to specificity is brute force: generate every utility at the same specificity level (0,1,0 for classes) and let the cascade's source order resolve conflicts. When that fails-when a component style needs to override a utility-you have two options: !important (which Tailwind uses liberally) or the @layer directive (which Tailwind added in v3 to fix the mess !important created).
Native CSS gives you @layer without the framework:
@layer reset, tokens, utilities, components, overrides;\n\n/* reset layer: lowest priority */\n@layer reset {\n *, *::before, *::after { box-sizing: border-box; margin: 0; }\n}\n\n/* tokens layer: design decisions */\n@layer tokens {\n :root {\n --radius-md: 0.5rem;\n --color-primary: oklch(0.55 0.2 260);\n }\n}\n\n/* utilities layer: single-purpose, composable */\n@layer utilities {\n .sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0,0,0,0); }\n .truncate { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n}\n\n/* components layer: your design system */\n@layer components {\n [data-component=\"card\"] { /* ... */ }\n [data-component=\"btn\"] { /* ... */ }\n}\n\n/* overrides layer: one-off adjustments, always wins */\n@layer overrides {\n .home-page [data-component=\"card\"] { /* special case */ }\n}The cascade is explicit. You know exactly what overrides what. No !important, no framework-mandated specificity battles, no generated CSS that weighs 300 KB. The @layer order is declared once, and every rule in every file respects it. This is what Tailwind's @layer base, @layer components, @layer utilities was trying to be-except you control it, the browser enforces it, and no build step is required.
Tailwind requires a build step. Full stop. You need PostCSS, you need the Tailwind plugin, you need the content paths configured, you need the @tailwind directives processed. This adds:
bg-red-500) is not the CSS the browser applies. What the browser sees is a generated rule somewhere in a 200 KB stylesheet. DevTools can map it back, but you have added an indirection layer between author intent and browser reality.@layer directives, the @apply escape hatch, the theme() function, and the arbitrary value syntax (w-[327px]). Compare: to work with native CSS, they need to understand CSS.The build step made sense when it was doing real work: transpiling modern syntax, removing unused styles, optimizing for production. In 2026, every browser you care about supports modern syntax natively. Tree-shaking CSS matters less with HTTP/2 multiplexing and @layer-organized stylesheets that are small by design. The build step is now a ritual performed because the framework requires it, not because the output needs it.
@apply escape hatch admits the framework failedTailwind's @apply directive exists because even Tailwind's creators understand that repeating the same fourteen classes on every card instance is untenable:
.card {\n @apply rounded-lg bg-white p-4 shadow-md;\n}This is the framework admitting that classes are a better abstraction than utility strings for reusable components. But @apply combines the worst of both worlds: you still need the build step, you still pay the specificity tax, and now you have a non-standard syntax (@apply) that will never work in a browser.
The native equivalent is shorter, portable, and requires zero tooling:
\n.card {\n border-radius: var(--radius-lg);\n background: var(--color-white);\n padding: var(--spacing-4);\n box-shadow: var(--shadow-md);\n}Custom properties are the variables. The component class is the abstraction. The cascade handles the rest. What exactly did @apply add to this equation? A build step and a dependency.
Every major LLM writes standard CSS fluently. They do not need a cheat sheet for Tailwind class names because they were trained on the entire corpus of web development, which is overwhelmingly standard CSS. When an LLM generates class=\"flex items-center gap-2 px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition-colors\", it is hallucinating Tailwind syntax from memorized patterns-and it gets it wrong approximately as often as it gets it right because the training data is noisy.
When the same LLM generates:
\n.btn-primary {\n display: flex;\n align-items: center;\n gap: var(--spacing-2);\n padding: var(--spacing-2) var(--spacing-4);\n background: var(--color-primary);\n color: var(--color-white);\n border-radius: var(--radius-md);\n transition: background 200ms ease;\n}\n.btn-primary:hover { background: var(--color-primary-hover); }…the output is verifiable. Every property is a standard CSS feature. Every value is a standard CSS value. You can read it, test it, diff it, and debug it with the same tools you use for the rest of your codebase. The LLM is generating standard web platform code, not framework-specific incantations.
\nThis matters because AI-assisted development shifts the bottleneck from code generation speed to code verification speed. Standard CSS verifies faster than framework CSS because there are fewer layers to audit, fewer dependencies to trust, and fewer build artifacts to inspect.
\nIf you read this far thinking I am about to say \"never,\" here is the nuance.
\nA small set of genuinely single-purpose utility classes still earns its keep. sr-only, truncate, visually-hidden-these are one-property classes that express a single concept and never change. They are closer to \"design tokens in selector form\" than to \"a framework-level styling strategy.\"
The key distinction is who defines the utility and how many there are. A project-specific @layer utilities block with fifteen classes, curated by your team, matching your design system, is a reasonable abstraction. A third-party framework that generates ten thousand classes, most of which you will never use, is a dependency tax you should refuse to pay.
The line is: if your utility class is a thin wrapper around a custom property, it is a design token, and that is fine. truncate wraps text-overflow: ellipsis. sr-only wraps an accessible hiding pattern. These are not \"Tailwind lite.\" These are platform abstractions that happen to be expressed as classes.
Italo described his three-layer approach: utilities → elements → blocks, built on Tailwind's @theme. Here is the same system in native CSS, with zero dependencies:
/* --- Layer 1: Semantic tokens (the @theme replacement) --- */\n:root {\n --color-primary: oklch(0.55 0.2 260);\n --color-primary-hover: oklch(0.55 0.2 260 / 0.85);\n --color-muted: oklch(0.7 0.01 260);\n --color-bg: oklch(1 0 0);\n --radius-sm: 0.25rem;\n --radius-md: 0.5rem;\n --radius-lg: 0.75rem;\n --shadow-sm: 0 1px 3px oklch(0 0 0 / 0.1);\n --shadow-md: 0 4px 6px oklch(0 0 0 / 0.1);\n --shadow-neon: 0 0 12px oklch(0.7 0.2 260 / 0.5);\n --spacing-2: 0.5rem;\n --spacing-4: 1rem;\n --spacing-6: 1.5rem;\n}\n\n/* --- Layer 2: Elements (the .card, .btn replacement) --- */\n[data-element=\"card\"] {\n border-radius: var(--radius-lg);\n background: var(--color-bg);\n padding: var(--spacing-4);\n box-shadow: var(--shadow-sm);\n}\n\n[data-element=\"btn\"] {\n display: inline-flex;\n align-items: center;\n gap: var(--spacing-2);\n padding: var(--spacing-2) var(--spacing-4);\n border-radius: var(--radius-md);\n background: var(--color-primary);\n color: var(--color-white);\n border: none;\n cursor: pointer;\n transition: background 200ms ease;\n}\n\n[data-element=\"btn\"]:hover {\n background: var(--color-primary-hover);\n}\n\n/* --- Layer 3: Blocks (the .testimony, .pricing-table replacement) --- */\n[data-block=\"testimony\"] {\n display: grid;\n gap: var(--spacing-4);\n padding: var(--spacing-6);\n border-radius: var(--radius-lg);\n background: var(--color-bg);\n box-shadow: var(--shadow-md);\n}\n\n[data-block=\"testimony\"] > [data-element=\"card\"] {\n box-shadow: none;\n background: transparent;\n}This is Italo's exact architecture-semantic tokens feed elements, elements compose into blocks-expressed in 100% standard CSS. Change --color-primary in one place, every button, card, and block updates. No build step. No @apply. No framework churn. The platform does the work.
The neon shadow example from Italo's article? One line change:
\n--shadow-sm: 0 0 12px oklch(0.7 0.2 260 / 0.5);Done. Every element consuming var(--shadow-sm) updates. This is the power of the cascade, not the power of Tailwind.
Italo ends with a concern I want to amplify: Tailwind risks becoming what Bootstrap became-a visual signature that screams \"I was built with X.\" Every Tailwind site starts from the same palette, the same spacing scale, the same shadow tokens. Customizing the @theme helps, but customization requires time and expertise that the \"just use the defaults\" pitch actively discourages.
Agencies that sell visual differentiation should be terrified of this. If your landing page looks like every other Tailwind landing page, your client paid for a template with their logo on it. Native CSS, by contrast, has no default aesthetic. Every property starts empty. The design is yours to define, not yours to override.
\nThis is not an accident. It is a consequence of off-the-shelf design systems: they optimize for consistency within a project at the cost of differentiation between projects. And in a market where AI can generate a Tailwind landing page in thirty seconds, differentiation is the only thing left to sell.
\nTailwind CSS was the right answer to the wrong question. The question was: \"how do we make CSS productive given that CSS is missing core features?\" The answer in 2017 was a utility class framework. The answer in 2026 is: \"CSS is no longer missing those features.\"
\nUse custom properties for design tokens. Use @layer for cascade control. Use [data-component] selectors for reusable abstractions. Use native nesting for readability. Use :has() for parent-aware styling. Use color-mix() for derived colors. Use clamp() for fluid sizing.
Delete the build step. Delete the dependency. Delete the class-name tax.
\nThe platform caught up. Your stack should catch up too.
\n@layer):has() selectorcolor-mix() functionif() functionThis article was written with AI support and reviewed by the author.
\n", "image": "https://dout.dev/assets/og/posts/2026-08-03-bury-utility-css-frameworks.png", "date_published": "2026-08-03T00:00:00.000Z", "tags": [ "css", "tailwind", "frontend", "web-standards", "architecture" ] }, { "id": "https://dout.dev/posts/2026-07-30-vanilla-js-plus-llm-is-the-only-way.html", "url": "https://dout.dev/posts/2026-07-30-vanilla-js-plus-llm-is-the-only-way.html", "title": "Vanilla JS + LLM Is the Only Way Forward (The Frameworks Did Their Job - Now Let Them Rest)", "summary": "The industry ran a forty-four-meter circle and landed in your living room", "content_html": "David Poblador's What Happened to the Frontend is the best map of the last two decades I have seen. Read it if you haven't. The thesis at bedrock is worth quoting:
\n\n\n\"After two decades and forty-four meters of build tools and bundlers and hydration schemes, the industry sprinted in a giant circle and arrived, slightly out of breath, back at something that looks an awful lot like the file you uploaded over FTP.\"
\n
He is right. The frontier of 2026 is the thing we had in 2008: server-rendered HTML, minimal JavaScript, the platform doing the heavy lifting. But David stops at describing the pendulum swing. I want to name the mechanism that made it inevitable, because once you see it, the next step is obvious.
\nFrameworks were never the destination. They were the W3C's R&D department - a distributed, global, unpaid prototyping lab that explored every idea the platform needed, crashed on the ones that didn't work, and handed the survivors to the standards bodies. Now the standards bodies have finished their homework. And a second force - large language models that write JavaScript as fluently as they write English - just made the framework layer structurally unnecessary for a huge and growing class of work.
\nThis is not \"frameworks bad.\" This is \"frameworks completed their mission. Let them rest.\"
\nThe pattern is so consistent it is almost boring once you see it. Someone hits a wall with the platform. They build a library to work around it. The library becomes popular. The W3C (or TC39, or WHATWG) watches, learns, standardises. The library's reason for existing evaporates.
\nquerySelector, fetch, classList, Array.fromjQuery solved real pain: the DOM API was verbose, inconsistent across browsers, and missing common operations. Every $(\"#cart\").toggleClass(\"active\") was a prayer that you weren't on IE6.
What the W3C absorbed: document.querySelector and querySelectorAll (Selectors API, 2013), element.classList (2010, 2014 across browsers), fetch (2015, replacing XMLHttpRequest), Array.from, Object.assign, Array.prototype.includes. What remains of jQuery's reason to exist? Essentially nothing. Nobody starts a jQuery project today, and the sites still running it do so because they stopped evolving in 2014.
React's big idea - describe the UI as a function of state, let the runtime reconcile the difference - was genuinely new in 2013. The Virtual DOM was the implementation strategy, not the insight. The insight was declarative UI.
\nWhat the W3C and TC39 absorbed:
\ncustomElements.define(\"my-button\", MyButton) - no framework required.<template> and <slot> gave us native content projection without JSX.What remains of React's unique territory? Less every year. The JSX syntax will survive as a convenience, but the runtime - the reconciler, the fiber tree, the synthetic event system - is increasingly redundant against native APIs.
\nThe build step was never fun. It was a workaround for a platform that didn't have modules, didn't understand modern syntax, and punished you with HTTP/1.1 round-trips for every file.
\nWhat happened:
\nimport/export, 2018 in all major browsers) ended the module fragmentation war. CommonJS, AMD, UMD - all fossils.{\"imports\": {\"lit-html\": \"https://cdn.jsdelivr.net/npm/lit-html@3/\"}}. No webpack. No config.type=\"module\" scripts load deferred by default, scoped by module, cleanly separated. No IIFE wrapping, no global leaks.This one is almost embarrassing in retrospect. We reached for Sass, PostCSS, Styled Components, CSS Modules - all to compensate for features that CSS has now natively absorbed:
\n:has() (2022+) - a parent selector, which Sass never even attempted. \"Style the parent if it contains a child matching X\" - the web's most-requested feature, delivered by the platform, impossible in any preprocessor.@layer, 2022+) - specificity management without !important screaming or BEM naming gymnastics.color-mix(), light-dark(), and relative color syntax (2023–2025) closed the remaining gaps.Every JS framework built a state management story because the platform didn't have reactive primitives. Now TC39 is standardising Signals, structuredClone handles deep copies, and BroadcastChannel + SharedWorker covers cross-tab state sharing. The remaining use cases are genuinely application-specific, not infrastructure missing from the platform.
Guseyn, who built a complete SaaS product - instruxmusic.com - in vanilla JavaScript with Web Components, puts his finger on something I have felt for years but never articulated this cleanly:
\n\n\n\"I tend to believe if something requires from you more lines of code and more abstractions in an abstract framework to achieve than in native technology, then maybe this framework does not really make your life easier.\"
\n
He crystallises the framework mindset into five commandments, and reading them as a list makes the pattern embarrassing:
\n\n\n\n
\n- NO, YOU CANNOT MANIPULATE DOM DIRECTLY, ONLY WE CAN DO THAT INSIDE OF OUR FRAMEWORK.
- NO, YOU CANNOT JUST ATTACH EVENT LISTENER TO WINDOW OBJECT. YOU NEED TO WRAP IT.
- NO, YOU CANNOT JUST USE GLOBAL STATE. USE THIRD-PARTY LIBRARY WITH FANCY FUNCTIONAL DESIGN.
- NO, YOU CANNOT USE NATIVE WEB COMPONENTS. YOU MUST USE HOOKS AND OUR LIFECYCLE WE INVENTED.
- NO, YOU CANNOT USE IMPORT MAP. YOU MUST USE A BUILD TOOL AND PREPROCESSORS.
Each of these is a ban, not a simplification. They are walls built around a captive audience. The native web platform never banned any of those things - frameworks did, because controlling the escape hatches is how frameworks retain relevance.
\nAnd yet the industry swallowed it. We accepted that writing HTML meant picking from a shelf of twenty-odd templating languages (Jinja, Pug, Handlebars, Nunjucks, Mustache, EJS, Blade, Twig, ERB, Haml, Slim, Thymeleaf, Tera, Askama, Maud - and that is not exhaustive). We accepted that CSS needed a preprocessor (Sass, Less, Stylus, PostCSS, Myth - all solving problems the platform has since absorbed). We accepted that JavaScript was somehow not good enough and needed to be written in TypeScript, CoffeeScript, PureScript, ReasonML, Elm, ReScript, ClojureScript, or Dart. The tower of Babel was not a bug. It was a business model.
\nReact, in particular, is a masterwork of branding. The name evokes speed, dynamism, life - the opposite of what it actually does, which is interpose a ~45 KB reconciler between you and the platform. As Guseyn notes:
\n\n\n\"It's a strong name, isn't it? It gives speed and power. It gives something dynamic, positive and full of life.\"
\n
The irony is that the fastest thing you can do is nothing. No framework runtime. No reconciliation. No hydration. The browser already has a rendering engine. It is extremely good at its job. You do not need to simulate it in JavaScript.
\nLook at the list above. Every major innovation of the framework era - components, reactivity, modules, bundling, styling, state - has either shipped as a native web API or is actively progressing through standards. The ones that are still framework-only are either too niche to standardise (JSX's ergonomics, which you can replicate with tagged template literals) or too new to have reached consensus yet.
\nThe frameworks served a function analogous to the DARPA of the web platform: they took risks, iterated fast, burned down bad ideas, and handed the survivors to the standards bodies. That function is not infinite. At some point the prototyping phase ends and the standardisation phase produces a platform that makes the prototypes unnecessary.
\nThat point is now.
\nIf the platform had matured in isolation, we would still need something to wire components together, handle routing, manage data fetching - the application-level orchestration that no standards body will ever define because it is inherently non-standard. A decade ago that \"something\" was a framework. Today it is an LLM.
\nHere is the crucial insight that most framework advocates miss:
\nAn LLM generates JavaScript, not React. It generates HTML, not JSX. It generates CSS, not Sass. The more you lean on the platform, the better the LLM's output is - because the LLM was trained on the entire platform, not on any single framework's subset.
\nWhen I prompt an LLM with \"build me a product page with a cart button that updates a badge count,\" it returns:
\n<script type=\"module\">\n import { signal, effect } from \"./signals.js\";\n\n const count = signal(0);\n\n document.querySelector(\"#add-to-cart\")\n .addEventListener(\"click\", () => count.set(count.get() + 1));\n\n effect(() => {\n document.querySelector(\".cart-badge\").textContent = count.get();\n });\n</script>That's ~200 bytes of vanilla JS. It uses platform APIs (querySelector, addEventListener, textContent, type=\"module\"). It uses a lightweight signal library (which exists on a CDN, zero install). It has no build step, no JSX transform, no Virtual DOM, no hydration, no suspense boundaries, no server components, no \"use client\" directives. It works in every modern browser. It will work in every future browser. It was written by an AI in three seconds.
Now contrast what the same LLM generates when it's been trained on React tutorials:
\n\"use client\";\nimport { useState, useEffect } from \"react\";\nimport { useCart } from \"@/hooks/use-cart\";\nimport { Button } from \"@/components/ui/button\";\nimport { Badge } from \"@/components/ui/badge\";\n\nexport function AddToCart({ productId }) {\n const [count, setCount] = useState(0);\n const { addItem } = useCart();\n\n useEffect(() => {\n // 27 lines of hydration safety, SSR guards,\n // and a dependency array that will cause a lint warning\n }, [count, productId, addItem]);\n\n return (\n <div className=\"flex items-center gap-2\">\n <Button onClick={() => { setCount(c => c + 1); addItem(productId); }}>\n Add to Cart\n </Button>\n <Badge>{count}</Badge>\n </div>\n );\n}That's ~600 bytes of source code that ships ~30 KB of framework runtime (React + ReactDOM + the component library). It requires a build step, a bundler config, a tsconfig.json, a tailwind.config.js, a components.json, 250,000 files in node_modules, and a deployment platform that understands the meta-framework of the week. The AI wrote it in three seconds too. But the AI is reflecting the framework's assumptions, not the platform's capabilities.
The difference is not about developer skill. It is about which set of defaults you carry into the prompt.
\n\"The browser is already the framework\"This is the single line from Guseyn's essay that cuts the deepest:
\n\n\n\"The browser engine is a huge and complex piece of software that handles so much for you that the only thing you really need is just to write dynamic files with HTML, CSS and JavaScript and a browser engine glues everything for you.\"
\n
He built instruxmusic.com - a full SaaS for music schools with lesson scheduling, automated invoicing, video chat with file sharing, a brand page builder with custom domains, a booking system, dashboards, stats, messaging - using exactly this philosophy. Web Components. Import maps. Zero build step. Zero framework runtime. The whole application, backend and frontend, is vanilla JavaScript, HTML, and CSS.
\nAnd here is the number that should make every framework advocate pause:
\nFrontend only:\n-----------------------------------------------------------------\nLanguage files code\n-----------------------------------------------------------------\nHTML 54 17687 ← 50%+\nCSS 6 5437 ← 15%\nJavaScript 102 9252 ← 35%\n-----------------------------------------------------------------\nSUM: 162 32376\n-----------------------------------------------------------------Nine thousand lines of JavaScript - frameworks included - for a complete SaaS product, running in production, serving real customers.
\nHTML is over half the codebase. CSS is 15%. The JavaScript is a minority of the application. This is the exact inverse of the typical React app, where the JavaScript bundle dwarfs everything else because it carries the framework runtime, the component library, the state management library, the routing library, the data fetching library, and the thousand other things you \"need\" to build a modern web app.
\nGuseyn's approach is not an exception. It is a template. Custom elements, import maps, <template> for declarative rendering, native form handling with JSON, HTML caching for multi-page navigation that feels like SPA. Every technique uses the platform as designed, not as a target to be transpiled to.
And the best part? He writes:
\n\n\n\"You don't need AI to build with this approach. Or at very least you definitely don't have to spend so many tokens.\"
\n
Because when your codebase is 50% HTML and 15% CSS, the surface area the LLM needs to cover is small. The LLM writes the JavaScript glue - the event listeners, the API calls, the custom element lifecycle. The HTML and CSS are already declarative. They are the spec.
\nA 2026 frontend built for vanilla JS and LLM collaboration:
\nProject root:\n├── index.html ← server-rendered or static, no build\n├── styles.css ← native CSS, nesting, layers, container queries\n├── scripts/\n│ ├── main.js ← type=\"module\", imports from CDN\n│ ├── components/\n│ │ ├── cart.js ← custom elements + signals\n│ │ ├── product.js\n│ │ └── search.js\n│ └── utils/\n│ ├── signals.js ← ~50 lines, or import from CDN\n│ └── api.js ← fetch, no client state library\n├── assets/\n└── _headers ← cache policy, CSPZero package.json. Zero node_modules. Zero build steps. Zero tsconfig.json. Zero framework-specific CI config. Zero lockfiles. Zero migrations every two years. Zero of the 250,000 files that a blank create-next-app deposits on your filesystem.
Deployment: copy to a CDN. Or GitHub Pages. Or Netlify with --no-build. Or a single Nginx folder.
Performance: whatever the platform gives you, which is a lot - native ESM is deferred, CSS content-visibility: auto handles virtualisation, loading=\"lazy\" on images, fetchpriority=\"high\" on the hero, dns-prefetch and preconnect for third parties. No framework runtime at all. Every byte is yours.
You cannot optimise faster than zero.
\n\"You need TypeScript for any serious project.\"
\nTypeScript's value is real. But // @ts-check plus JSDoc annotations gives you type checking on vanilla JS without a build step. Or use tsc --noEmit as a lint pass - it checks types and emits nothing. The LLM will generate the JSDoc annotations. You get autocomplete, you get type errors at save time, you get zero compilation overhead. Is it as ergonomic as TSX with full type inference? No. Does it cover 90% of the value? Yes.
\"Web Components are ugly/hard/not ready.\"
\nThis was true in 2018. Custom Elements v1 is shipped in every browser. Declarative Shadow DOM is shipped. The HTML template element, slots, part and exportparts for styling - all shipped. The developer experience is not JSX-level ergonomic, but it is platform-level stable, which means any code you write today will work in 2035. The LLM handles the boilerplate. Lit and Shoelace prove that the ergonomics can be excellent.
\"You still need a framework for a large app.\"
\nDefine \"large.\" The largest frontend apps in the world - Google Docs, Figma, VS Code - are not built with React. They are built with platform APIs, custom rendering pipelines, and carefully owned abstractions, because the framework would get in the way at that scale. If your app is smaller than Figma, you almost certainly don't need a framework. If your app is Figma, a framework is the last thing you want.
\n\"You lose the ecosystem.\"
\nThe ecosystem of 2026 is mostly a liability. Every shadcn/ui component is copy-pasted into your repo anyway. Every Tailwind utility is a CSS rule you could write yourself. Every React hook is a function you could write in vanilla JS. The ecosystem is a crutch that became a cage. The LLM is your ecosystem now - it has memorised every good pattern from every library, and it generates them on demand without the import.
\n\"Vanilla JavaScript does not have a structure. It does not scale.\"
\nThis is the most persistent objection, and Guseyn dismantles it with a single number:
\n\n\n9,252 lines of JavaScript - frameworks included - for a complete SaaS product with billing, video chat, booking, dashboards, and a brand page builder.
\n
Let that sink in. A production SaaS, running today, serving real music schools, with less JS than a single node_modules dependency tree walk. And the codebase is 50%+ HTML, because the structure is not in the JavaScript - the structure is in the HTML. Custom elements give you a component model. Import maps give you module resolution. The browser gives you the runtime. The framework you were told you \"need\" for structure was actually the thing generating most of the code you are maintaining.
\n\n\"Sure, it is messy. You know why? Because for the last 20 years, instead of solving real issues and making good decisions on how to simplify code, we just invented so many abstractions, languages and tools just to avoid the problem instead of solving it.\"
\n
The structure argument is a self-fulfilling prophecy. Frameworks are necessary because frameworks are the only thing people learn. The platform is dismissed as unstructured because nobody teaches platform architecture anymore. But Guseyn's numbers prove it: the platform scales. It scales to a six-figure SaaS without a framework.
\nThis is not a hit piece on the people who built the frameworks. React literally changed how we think about UI. Vue's progressive design made frontend development accessible to millions. Svelte showed that compilation was a viable strategy. Astro proved that shipping less JavaScript was not a regression but an advance. Every framework team pushed the platform forward by building things the platform didn't have yet.
\nThe debt is paid. The platform now has the APIs that were missing. The LLM now writes the orchestration that the framework used to supply. The node_modules directory - that two-hundred-megabyte tax on starting a project - is structurally optional for the first time since 2012.
\nYou can keep using React. You can keep building Next.js apps. Nothing will stop you. The tools will continue to exist, maintained by talented people and an ecosystem that has learned to profit from complexity. But the justification for starting a new project on a framework is evaporating. The defaults have shifted. The platform is mature. The AI speaks platform JavaScript, not React JavaScript, unless you teach it otherwise.
\nThe frameworks did their job. They ran the experiments. They crashed the prototypes. They handed the survivors to the W3C. The standards bodies standardised. The browsers shipped. The LLMs memorised.
\nThe era of the framework was a necessary, productive, temporary phase of web platform evolution. It is over.
\nHere is a concrete workflow that works today, on this blog, without a framework:
\ndata/posts/.src/posts/.{% block %} syntax - no JSX, no components, just template inheritance.<script type=\"module\"> in the HTML file, importing from CDN sources where needed.The result is a site that loads faster than 99% of the framework-built web, contains zero unused JavaScript, requires zero dependency updates, and will render identically on the browser of 2035 because it uses nothing but platform APIs.
\nThis is not nostalgia. This is the frontier.
\nDavid Poblador ends his descent with this:
\n\n\n\"The frontier of 2026 looks an awful lot like the file you uploaded over FTP.\"
\n
I agree. And I add: the reason you can go back to that file - with better CSS, better JavaScript, better performance, and an AI that writes the boring parts - is that the frameworks finished the work they set out to do. They explored the design space, the platform absorbed the lessons, and the platform is now good enough.
\nThe frameworks were a scaffold around an unfinished building. The building is finished. Take down the scaffold.
\nVanilla JS plus an LLM is not a regression. It is the final form of an evolution that began when someone typed $(\"#cart\").load(\"/items\") and thought \"there has to be a better way.\" There is now. The better way is the thing you started with, grown up, with an AI at your side.
Ship HTML. Enhance with vanilla JS. Let the LLM write the glue. The platform handles the rest.
\nWelcome back.
\n", "image": "https://dout.dev/assets/og/posts/2026-07-30-vanilla-js-plus-llm-is-the-only-way.png", "date_published": "2026-07-30T00:00:00.000Z", "tags": [ "vanilla-js", "llm", "frontend", "architecture", "web-standards" ] }, { "id": "https://dout.dev/posts/2026-07-28-how-to-write-agent-skills-that-actually-trigger.html", "url": "https://dout.dev/posts/2026-07-28-how-to-write-agent-skills-that-actually-trigger.html", "title": "How to Write Agent Skills That Actually Trigger (The Art of Not Being Ignored)", "summary": "The mistake most people make", "content_html": "Most bad skills are not bad because the instructions are weak. They are bad because the skill never loads at the right time, or loads for the wrong task.
\nThat is the main point I took from Anthropic's PDF, The Complete Guide to Building Skills for Claude, and it is also the point the Medium summary by Ruqaiya Beguwala gets most right. The description field is not marketing copy. It is routing logic written in prose.
\nAnthropic's framing is Claude-specific, but the lesson generalizes cleanly to agent skills of any kind. A skill is not \"a prompt you saved somewhere.\" A skill is packaged operational knowledge with an activation rule.
\nAnthropic defines a skill as a folder with an exact SKILL.md file plus optional scripts/, references/, and assets/. The useful idea is the three-level loading model:
SKILL.md body is the working playbook.That is a better mental model than \"write one giant instruction file.\"
\nFor agent design, I would translate it like this:
\nIf you collapse all three into one document, the skill gets harder to trigger, harder to maintain, and more expensive to load.
\nOne of the better parts of the PDF is that Anthropic pushes two seemingly different ideas at once, and both are correct.
\nFirst, define 2-3 concrete use cases before you start. Second, iterate on one challenging task until the agent can do it reliably, then extract the pattern into a skill.
\nThat is the right order.
\nDo not start with \"project management assistant\" or \"software engineering copilot.\" Those are product categories, not skills. Start with something that has a visible outcome:
\nIf the outcome is narrow, you can tell when the skill works. If the scope is broad, everything looks vaguely plausible and you ship prompt soup.
\nThe most important field in the whole skill is still the description.
\nAnthropic's PDF is very explicit here: the description must say what the skill does and when to use it. It should include concrete trigger phrases users might actually say, stay under 1024 characters, and avoid XML angle brackets because the frontmatter lands in the system prompt.
\nThe document also adds practical constraints that the summary article only mentions lightly:
\nSKILL.md must be named exactly that, case-sensitive;README.md does not belong inside the skill folder;claude or anthropic are reserved;compatibility, metadata, and even allowed-tools exist in the reference appendix.That level of specificity matters because skills fail for boring reasons more often than clever ones.
\nA good description looks more like an API contract than a slogan:
\n---\nname: db-migration-review\ndescription: Reviews database migration plans, flags backward-compatibility and rollout risks, and proposes safe sequencing. Use when the user mentions schema changes, backfills, migrations, rollbacks, or zero-downtime deploys.\nmetadata:\n version: 1.0.0\n---This is specific about the outcome, the scope, and the trigger language. That is what gives the model a chance to route correctly.
\nAnthropic is also right about the body of the skill: vague verbs are useless.
\n\"Validate the data before proceeding\" is not an instruction. \"Run python scripts/validate.py --input {filename} and stop on missing required fields or invalid dates\" is an instruction.
The more critical the step, the less you should rely on ambiguous language. The PDF says this plainly in the troubleshooting section: for important checks, prefer a bundled validation script because code is deterministic and language interpretation is not.
\nThat is one of the most transferable ideas in the whole guide.
\nA good skill body usually needs four things:
\nA minimal structure is enough:
\n# Database Migration Review\n\n## Step 1: Read the migration plan\n\nInspect the schema change, expected rollout path, and rollback strategy.\n\n## Step 2: Run deterministic checks\n\nExecute scripts/check_migration.py --plan {filename}\n\n## Step 3: Produce the review\n\nReturn risks, missing safeguards, recommended sequence, and rollback notes.\n\n## Troubleshooting\n\nError: Migration plan missing rollback path\nSolution: Stop and ask the user for rollback semantics before continuingThis is dull on purpose. Dull is good. Skills are operating manuals, not thought leadership.
\nOne subtle PDF note is worth keeping: \"take your time\" style performance notes work better in the user prompt than in the skill file. That matches my experience with agent systems generally. Routing and workflow belong in the skill. Session-specific emphasis belongs in the prompt.
\nThe Anthropic PDF is strongest when it stops talking in abstractions and starts naming workflow patterns. It identifies five that show up repeatedly:
\nThat list is more useful than it sounds because each pattern implies a different structure.
\nA sequential onboarding skill wants strict step ordering and rollback rules. A multi-system handoff skill wants phase boundaries and shared state. An iterative report skill wants explicit quality thresholds and a stop condition. A context-aware storage skill needs a decision tree. A compliance skill needs governance before action.
\nIf you mix these patterns without choosing one, the skill becomes mushy. It has tools, but no shape.
\nThe testing section in the PDF is better than most AI workflow docs because it separates three different questions.
\nFirst: does the skill trigger when it should? Anthropic suggests 10-20 obvious and paraphrased prompts, plus unrelated prompts that must not trigger. The rough target is 90% on relevant queries and 0% on clearly unrelated ones.
\nSecond: does the skill actually do the job? Run the same request 3-5 times. Compare structure, tool calls, and failure handling. If results wander too much, the instructions are under-specified.
\nThird: is the skill better than not having the skill? Compare tool calls, token use, back-and-forth, and failed API calls. If the skill does not reduce friction or improve consistency, it is decorative.
\nThe PDF also gives one debugging trick that is almost embarrassingly useful: ask the model, \"When would you use the [skill name] skill?\" The answer reflects the description back at you. If the answer is vague, the routing is vague.
\nThis is also where the PDF goes beyond the Medium summary in practical detail. It recommends keeping SKILL.md under 5,000 words, moving deep material into references/, and being careful once you have 20-50 skills enabled at once. That is not a theoretical concern. Too many skills turn progressive disclosure back into context sludge.
The summary article focuses on the zip-and-upload flow, which is fine for Claude.ai. The PDF goes further and treats distribution as product work.
\nThe recommended path is: host the skill on GitHub, keep a human-oriented README at the repo level, document why the skill plus your MCP integration are better together, and provide a quick-start guide with examples and screenshots.
That is the right instinct even outside the Claude ecosystem. If people cannot tell what outcome the skill produces, they will not install it. If the setup guide only talks about folders and YAML, you are describing mechanics instead of value.
\nThe PDF also makes the API surface explicit. Skills can be managed through /v1/skills, attached through container.skills, and used through the Agent SDK, with the note that the Code Execution Tool beta is required. Even if you never touch Claude's API, the general lesson holds: skills are not just authoring artifacts, they are deployment artifacts.
The Anthropic guide is nominally about Claude skills, but most of its best advice is really about agent design in general.
\nI would keep five rules:
\nThe simplest way to say it is this:
\n\n\nA good agent skill is not a prompt dump. It is a narrow workflow with strong routing, explicit steps, and enough structure to fail predictably.
\n
That is the real takeaway from the PDF. The fancy part is not the packaging. The hard part is deciding what the agent should do, when it should do it, and what evidence counts as success.
\nWe 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.
\n