I'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:
\nposition: absolute after width is technically fine, but logically backwards, you're picking a layout strategy for the element before you decide its dimensions.gap, place-content, or align-items.box-sizing at the top of the section because it changes the math for everything below.font, line-height, text-align, white-space, text-shadow.transform, transition, animation. These are the last thing that happens visually, but they're also the most performance-sensitive, so having them in one block makes it easy to audit will-change usage.appearance, cursor, pointer-events. Utility properties that don't fit anywhere else.&::before, &::after), they're part of the element's visual tree, nested in.&.error, &[aria-hidden], &:hover. These override everything above, so they come last in the declaration block.@media, & span, & > *. These are new contexts that restart the hierarchy. The comment says \"repeat css hierarchy here\" because each of these blocks is a fresh ruleset that follows the same order.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.
\nEvery time I follow it, the ruleset reads like a coherent paragraph instead of a shopping list.
\n: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 to you: 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.
\nThe 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.
I am not going to pretend the alternatives do not work. They do. They are just more expensive in ways that matter at the personal-tooling scale.
\nI am not saying these tools are bad. I am saying that for a developer who lives inside agent loops and who cares about the difference between a $0.30 day and a $5 day, the combination of Pi and DeepSeek V4 Flash is a structurally better default.
\nNothing is free. Here is what I give up.
\nNone of these trade-offs are dealbreakers for me. They are constraints I work with.
\nFive years ago, the choice of a coding agent was a tooling preference. Today, it is a budget question, a workflow question, and a philosophical question.
\nPi is a small, transparent, customizable harness that does not try to be my IDE, my project manager, or my safety net. It gives me a loop and gets out of the way. DeepSeek V4 Flash is a fast, open, properly sparse model that charges cents for what used to cost dollars. Together, they make the kind of agent-driven, multi-file, context-heavy work I do every day economically trivial.
\nI am not saying Pi + V4-Flash is the right answer for every team. A regulated environment, a large enterprise, a security-sensitive codebase, or a team that needs deep IDE integration will make a different choice. But for an independent developer who ships a lot, who reads every diff, who does not need permission popups, and who used to flinch at the monthly AI bill, the answer is: this loop, this model, this cost.
\nThe model is becoming part of the abstraction layer. The agent harness is becoming part of the editor. The bill is becoming rounding error.
\nThat is the new default. I am not going back.
\nA static blog has no backend. That is the whole fucking point. So search has to satisfy three rules:
\nOn dout.dev this shipped as a single search.html page that loads prebuilt JSON indexes from /data/, runs a light ranking function in the browser, and paginates the results. Total client code is under 200 lines.
Every time the CMS runs, it emits four files under src/data/:
posts.json - one entry per published post: title, slug, date, description, tags, series, keywords extracted from the body;tags.json - one entry per tag: label, slug, count;months.json - one per month: YYYY-MM, count;series.json - one per series: label, slug, count.A post entry looks like this:
\n{\n \"slug\": \"2026-05-19-html-native-template-engine\",\n \"title\": \"An HTML-Native Template Engine Without eval()\",\n \"date\": \"2026-05-19\",\n \"description\": \"How the dout.dev template engine handles extends, blocks...\",\n \"tags\": [\"architecture\", \"vanilla-js\", \"frontend\"],\n \"series\": null,\n \"keywords\": [\"template\", \"engine\", \"extends\", \"blocks\", \"eval\", \"sandbox\"]\n}The keywords array is computed from the body during the build: frequent, informative tokens the reader would plausibly search for. The ranker uses them later for query-term boosting.
The search page reads everything from the URL. That makes results shareable, bookmarkable, and back-button friendly.
\n/search.html?q=template&type=post&type=tag&page=2q is the query term.type is repeatable and filters the result stream (post, tag, series, month).page is the pagination index, 1-based.Any change to the form updates the URL via history.pushState. No framework. No state library.
function updateUrl({ q, types, page }) {\n const params = new URLSearchParams();\n if (q) params.set('q', q);\n for (const t of types) params.append('type', t);\n if (page > 1) params.set('page', String(page));\n const next = `${location.pathname}?${params.toString()}`;\n history.pushState({}, '', next);\n}The ranker is deliberately simple. A weighted sum of term hits against different fields, a small boost for exact keyword match, a tiny recency tilt.
\nfunction scorePost(post, tokens) {\n const title = post.title.toLowerCase();\n const desc = post.description.toLowerCase();\n const tagString = post.tags.join(' ').toLowerCase();\n const kwSet = new Set(post.keywords);\n\n let score = 0;\n for (const t of tokens) {\n if (title.includes(t)) score += 5;\n if (desc.includes(t)) score += 2;\n if (tagString.includes(t)) score += 3;\n if (kwSet.has(t)) score += 4;\n }\n\n // Light recency nudge: newer posts win ties\n const days = (Date.now() - new Date(post.date).getTime()) / 86400000;\n score += Math.max(0, 1 - days / 3650);\n\n return score;\n}This is not Elasticsearch. It is a heuristic that works well when the corpus is a few dozen posts. I would not use it for ten thousand entries. For a blog, it is the right size of tool.
\nResults are paginated 10 at a time on the client. The pagination component matches the server-rendered archive pagination: rel=\"prev\" / rel=\"next\", aria-current=\"page\" on the active page, ellipses that are not clickable.
The results summary uses aria-live=\"polite\" so that screen readers hear the new result count when the query changes, without stealing focus.
<p class=\"results-summary\" aria-live=\"polite\" role=\"status\">7 results for \"template\". Page 1 of 1.</p>That single attribute is the whole accessibility story for live-updating results.
\nI punted. The corpus is small enough that users who mistype a word can correct it faster than the algorithm could guess. If the blog grows past a few hundred posts I would revisit - probably with a trigram index built at the same CMS step.
\nThe honest measurement is: on a corpus the size of dout.dev, exact-term search with field weighting is indistinguishable from fancier solutions in user satisfaction, and it costs a fraction of the bytes.
\nA static site can have a good search without a service. Build the indexes when you build the site. Load them on the search page only. Write a ranking function that matches your corpus. Drive it from the URL. That is the whole story, and the client code fits on a page.
\nFor the last twenty years, a large part of software development has been guided by a very simple reflex: when the platform feels too low-level, we install an abstraction.
\nAt first, this was not only reasonable, it was necessary. Platforms were incomplete, browser behavior was inconsistent, standard libraries were often limited, and teams needed shared mental models to ship products at a human pace. Frameworks and libraries gave us vocabulary, structure, conventions, and a way to avoid solving the same problems over and over again.
\nThe problem is that, over time, this useful reflex became almost automatic. Need UI composition? Install a framework. Need routing, state management, validation, forms, styling, animation, authentication glue, build orchestration, dependency injection, data fetching, queues, command handling, or configuration management? Install something.
\nEventually, the product starts becoming only one part of the system. The other part is a carefully negotiated dependency graph, where every new feature has to pass through somebody else's assumptions, release cycle, architecture, migration path, documentation quality, security posture, and long-term maintenance choices.
\nThis is not a frontend problem. It is not a JavaScript problem. It is not a React problem. It is not even a framework problem. It is a software problem.
\nEvery ecosystem has its own version of this story. JavaScript has frontend frameworks and npm. Python has web frameworks, ML stacks, data tools, and long chains of packages. Java has decades of enterprise abstractions. .NET has its own layered ecosystems. PHP, Ruby, Go, Rust, Swift, Kotlin, and C# all have communities that build towers of convenience on top of native language and runtime features.
\nAgain, this did not happen because developers were careless. It happened because abstractions are one of the main tools we have for dealing with complexity. Software is abstraction. The real question is not whether we should use abstractions, but where they should live, who should own them, how much of them should run in production, and whether borrowing them is still the best economic choice.
\nThat question is becoming more urgent because the ground is moving. The next major abstraction layer may not be another framework. The next major abstraction layer may be the model.
\nFrameworks exist because humans need constraints. We need names, conventions, file structures, lifecycle models, shared patterns, and a limited number of concepts to keep in our heads at the same time. A framework is not just code. It is a cognitive compression format.
\nIt tells us how to think about the system. Do not think about everything at once. Think in components, routes, controllers, models, hooks, stores, services, middleware, providers, modules, or pipelines. This is extremely useful when human developers are the only abstraction engine in the loop, because humans need stable shapes to coordinate work, communicate intent, and reduce ambiguity.
\nBut LLMs do not need abstractions in exactly the same way.
\nA model does not care whether a pattern is called a hook, a provider, a composable, a bean, a service, a trait, a reducer, a module, or a pipeline. Those names still matter to us, because they help teams communicate and maintain the system, but they are not the deepest source of quality for AI-assisted software.
\nWhat a model needs is context. It needs constraints. It needs examples, tests, schemas, documentation, review rules, runtime signals, tool access, and clear success criteria. In other words, the most important abstraction for an AI-assisted codebase is not always the framework used by the application. It is the operational environment around the codebase.
\nThat moves the center of gravity.
\nInstead of placing all best practices inside runtime abstractions, we can start placing more of them inside instructions, tests, static analysis, design tokens, architecture rules, accessibility checks, security policies, and project-specific agent skills. The abstraction is still there, but it is no longer necessarily something we ship to users or execute on every request.
\nThis is a very different kind of software architecture.
\nThe next abstraction layer will increasingly be made of things that surround the code rather than things that always run inside it. MCP servers, agent skills, local LLMs, cloud LLMs, project-specific prompts, typed schemas, linters, formatters, test suites, static analysis, design tokens, accessibility rules, security policies, architecture decision records, code review agents, and documentation indexed as working memory all point in the same direction.
\nThey create an environment where code can be generated, constrained, checked, refactored, and reviewed with more project awareness than before.
\nThis does not mean we stop using abstractions. That would make no sense. It means we can stop shipping so many borrowed abstractions to production when their main value is no longer runtime behavior, but repetition, convention, scaffolding, and guidance.
\nA model can generate repetitive implementation. A linter can enforce a project rule. A type system can constrain a data shape. A test can verify behavior. An agent can apply the same refactor across many files. A design system can become tokens, fixtures, examples, and visual checks. A security rule can become a gate. An accessibility expectation can become part of the definition of done.
\nAt that point, many dependencies start to look different. Some still provide deep value and should absolutely be used. Others begin to look less like leverage and more like inherited risk.
\nThe question changes from \"which library should we install?\" to \"should this be a dependency at all?\"
\nDependencies are not free. They increase bundle size, install time, build complexity, runtime surface, security exposure, version drift, documentation debt, maintenance overhead, and future migration cost.
\nThose are the obvious costs. The deeper cost is architectural.
\nEvery dependency imports somebody else's decisions into your product. It brings assumptions about how problems should be modeled, how APIs should behave, how edge cases should be handled, and how the future should evolve. It becomes part of your onboarding path, hiring profile, debugging surface, security model, review process, and long-term roadmap.
\nThe software industry loves reuse, and for good reason. Reuse can be powerful. But reuse is also coupling, and coupling has to be paid for.
\nThe npm ecosystem makes this easy to see because it is large, fast-moving, and deeply interconnected, but the same dynamic exists in every ecosystem. Sonatype reported more than 454,600 new malicious packages identified throughout 2025 across major open-source ecosystems, bringing the cumulative total of known and blocked malware above 1.233 million packages. Research on npm supply-chain weak links also shows how package metadata, install scripts, expired maintainer domains, inactive maintainers, and account takeover opportunities can expose thousands of downstream packages.
\nThis does not mean \"never use dependencies\". That would be a childish conclusion. It means dependencies must become deliberate architectural choices again. They should earn their place through real complexity, real specialization, real maintenance value, or real domain expertise.
\nThey should not be the default answer to every small discomfort.
\nFor a long time, dependency-heavy development made economic sense. Writing everything in-house was expensive. Maintaining internal abstractions was expensive. Generating boilerplate was boring. Refactoring repeated patterns was slow. Documenting everything was painful. Testing every variation took time.
\nSo we outsourced complexity to frameworks and libraries. We accepted the dependency tax because the alternative was often slower, more expensive, and more fragile.
\nAI changes that equation, not because it magically produces perfect software, but because it changes the cost of producing certain categories of code.
\nStack Overflow's 2025 Developer Survey reports that 84% of respondents are using or planning to use AI tools, and 51% of professional developers use them daily. GitHub reported that nearly 80% of new developers on GitHub used Copilot within their first week in 2025. Controlled research on GitHub Copilot found that developers completed a JavaScript task 55.8% faster when using the tool.
\nThe picture is not universally simple. Other studies are more nuanced, and they should be. AI coding tools are more useful in some contexts than others, and generated code still requires strong human review, especially in complex systems, proprietary codebases, security-sensitive areas, and large multi-file changes.
\nBut the important point is not that AI writes perfect code. It does not.
\nThe important point is that AI makes boilerplate, repetitive implementation, documentation, test scaffolding, migration work, refactoring, API adaptation, pattern replication, simple feature assembly, and codebase navigation cheaper than they used to be.
\nThose are exactly the categories of work that made teams install many libraries in the first place.
\nIf a model can generate a project-specific implementation that follows your coding rules, passes your tests, respects your security constraints, uses your design tokens, and avoids unnecessary runtime dependencies, then the economics of abstraction change.
\nAt that point, the question is no longer only \"which package solves this?\"
\nThe better question becomes \"why should this be a package?\"
\nOne of the common misunderstandings about AI-generated software is that it will make standards less important. I think the opposite is true.
\nAI will make standards more valuable because models work better when the target is stable, documented, widely used, and well represented. Language standards, platform APIs, protocol specifications, accessibility rules, security practices, and explicit architectural constraints are model-friendly.
\nA framework is a moving target controlled by a smaller community. A standard is a wider agreement.
\nOn the web platform, we can already see this shift. Modern CSS is absorbing capabilities that once required preprocessors, JavaScript helpers, or framework-level conventions. Typed attr() lets CSS read attributes as typed values. CSS if() brings conditional logic into values. CSS custom functions aim to make reusable CSS logic native to the language.
\nWhen the platform learns these primitives, teams can use them directly only if their abstraction layers do not get in the way. Otherwise, the browser may already support the capability, but the product still has to wait for a framework, a library, a wrapper, a plugin, or a design system abstraction to catch up, expose it, document it, and stop fighting it.
\nThat is one ecosystem, but the principle is broader. When platforms become more expressive, and AI becomes better at producing code against stable standards, the value of non-standard abstraction decreases.
\nThe winning move is not to reject every framework. The winning move is to move as much product logic as possible toward stable, inspectable, standard primitives.
\nUse the language. Use the runtime. Use the platform. Use the framework when it still buys something real.
\nMany teams use frameworks as delivery mechanisms for best practices. The framework tells them how to organize files, fetch data, render pages, place state, compose UI, and decide which patterns are acceptable.
\nIn an AI-assisted workflow, many of those rules can move into configuration, automation, and project context.
\nCoding standards can become lint rules. Architecture decisions can become generation constraints. Design guidelines can become tokens and visual tests. Accessibility expectations can become automated checks. Security policies can become static analysis and dependency gates. Performance budgets can become CI failures. Reusable patterns can become agent skills. Project knowledge can become context the model can actually use.
\nThis is a major change because best practices stop being trapped inside framework conventions and become executable governance.
\nA convention helps when developers remember it. A rule enforces it. A test verifies it. An agent applies it repeatedly. A model generates code from it.
\nThat is the future shape of software abstraction. Not \"everyone must memorize the framework\", but \"the system knows the rules and keeps applying them\".
\nThe industry has spent years treating frameworks as identity. We say \"I am a React developer\", \"I am a Laravel developer\", \"I am a Rails developer\", \"I am a Spring developer\", \"I am a Django developer\", \"I am a Next developer\".
\nThis made sense when frameworks were the main interface between developers and complexity. But in an AI-native development environment, that identity becomes too small.
\nThe valuable skill will not be loyalty to a framework. The valuable skill will be understanding systems: language, runtime, platform, accessibility, security, performance, data, product constraints, and the way AI-generated work must be instructed, constrained, verified, and reviewed.
\nThe senior developer of the next era is not the person who knows the most framework APIs by memory. It is the person who can design the rules of the system so that humans and models can safely produce good software together.
\nThat requires more engineering, not less.
\nThis future is not no-code. No-code pretends complexity can disappear, and complexity does not disappear. It moves.
\nWhat changes is the layer where engineering work happens. Less time wiring borrowed abstractions, more time defining contracts. Less time adapting to framework churn, more time designing durable systems. Less time installing packages for trivial problems, more time making sure the generated solution is correct, accessible, secure, observable, and maintainable.
\nAI does not remove the need for senior engineers. It increases the need for them.
\nBecause when code becomes cheaper to produce, judgment becomes more valuable.
\n\"Vanilla\" does not mean naive. It does not mean writing everything from scratch forever. It does not mean refusing tools, frameworks, libraries, or ecosystems.
\nIt means preferring the native language, native runtime, and platform standards unless a dependency clearly earns its place.
\nA more vanilla world is not a world without abstraction. It is a world where abstraction is generated, governed, inspected, and owned. A world where dependencies are exceptions, not defaults. A world where libraries are chosen because they provide deep, hard, specialized value, not because nobody wanted to write twenty lines of code.
\nIt is a world where frameworks are useful tools, not architectural religions. A world where the model becomes part of the abstraction layer, but the output remains understandable, standard, testable, and close to the platform.
\nThis will not happen all at once. There will still be frameworks, libraries, ecosystems, and very good reasons to depend on external code. But the default is going to change.
\nThe age of installing an abstraction for every small discomfort is ending.
\nThe next era belongs to teams that can combine human judgment, platform standards, automated governance, and AI-generated implementation. Not because frameworks suddenly became useless, but because many of the reasons we needed them are being absorbed by something else.
\nThe model is becoming part of the abstraction. The platform is getting stronger. The dependency graph is becoming a liability.
\nAnd software teams are about to rediscover a very old idea: the best code is not the code you borrowed. It is the code you understand, control, verify, and can afford to change.
\nMost teams treat accessibility as a checklist at the end of a sprint. That approach misses the real problem. Accessibility is the baseline behavior of the interface under real user constraints.
\nThose constraints are not abstract. They are concrete:
\nIf the UI ignores those settings, it is not accessible, even when every button has a good label.
\nThe popover on dout.dev exposes settings that the browser already knows about: motion, contrast, color scheme, font size. It does not invent new ones. The settings are mapped directly to CSS custom properties that flip at the root level.
\nAccessibility is not a feature you bolt on. It is the system's respect for user preferences. A popover that exposes those preferences is not a nice-to-have; it is the UI admitting that the browser cannot detect every user need, and giving the user control.
\nDesign for preferences first. Add ARIA second. That order matters.
\n", "image": "https://dout.dev/assets/og/posts/2026-06-09-why-display-preferences-popover-exists.png", "date_published": "2026-06-09T00:00:00.000Z", "tags": [ "accessibility", "frontend", "responsive-design" ] }, { "id": "https://dout.dev/posts/2026-06-06-how-pixhighlighter-is-built.html", "url": "https://dout.dev/posts/2026-06-06-how-pixhighlighter-is-built.html", "title": "How PixHighlighter Is Built (Or: I Wrote a Syntax Highlighter Because Prism Was Too Bloaty)", "summary": "The contract stays plain (because HTML should be readable)", "content_html": "PixHighlighter begins with the smallest useful shape:
<pre is=\"pix-highlighter\" data-lang=\"js\"><code>const answer = 42;</code></pre>That is still a real <pre> element with a real <code> child. The source is readable BEFORE JavaScript runs, copyable as text, and understandable to assistive technology. The component does not need a custom shadow tree to make code look like code.
The important decision is what it refuses to do by default: the primary path does NOT wrap every token in markup. The code block is not a pile of span wrappers. It is ONE text node that can be painted by the browser. This is the kind of detail that separates \"it works\" from \"it works well.\"
\nEach lexer under src/scripts/components/PixHighlighter/Lexers/ walks the source and emits ranges:
{ type: 'kw', start: 0, end: 5 }That object says \"the characters from 0 to 5 are a keyword.\" It does NOT say \"insert a span here.\" Parsing and rendering stay separate. The same token stream can power the modern renderer, the fallback renderer, tests, and any future diagnostics without changing the source model.
\nLanguage aliases are normalized before lookup. javascript becomes js, typescript becomes ts, shell and zsh become bash. Content authors get a forgiving interface; the renderer gets ONE clean language key. Consistency is a feature.
The best version of PixHighlighter uses the CSS Custom Highlight API. When CSS.highlights and Highlight exist, the component creates DOM Range objects for each token and stores them in named highlight registries:
const highlight = new Highlight(range);\nCSS.highlights.set('pix-kw', highlight);CSS then styles those names directly:
\n::highlight(pix-kw) {\n color: var(--pix-highlighter--kw);\n}That is the whole goddamn trick. The browser paints a range of text WITHOUT changing the text into markup. Selection stays clean. Copy stays clean. The DOM stays quiet. Themes remain normal CSS variables instead of a second token system hidden inside generated spans.
\nThe rule is simple: fallback spans only when the Highlight API is unavailable. In that case, the component maps the same token ranges to conservative markup:
\n<span data-token=\"kw\">const</span>The fallback is NOT a different highlighter. It is the same lexer output rendered into older browser primitives. The CSS already has matching rules for [data-token='kw'], [data-token='str'], and the rest of the token types, so the visual result remains close without forcing modern browsers to carry extra DOM.
Ten code blocks still get ONE style payload. The component can appear throughout an article without multiplying its CSS. No duplication. No waste.
\nEvery instance renders a compact toolbar with copy and theme controls. The picker appears per block, but the selected theme is page-wide state. That avoids a page where one snippet is using one palette and the next snippet is using another because of local component state. Code theme is a reading preference, so the page owns it.
\nThe copy button reads code.textContent. It does NOT inspect highlight ranges, fallback spans, toolbar state, or theme state. Highlighting is visual; the source text is the contract.
PixHighlighter is built for a static editorial site: short examples, no frontend framework, no runtime highlighter dependency, and a design system that already owns typography, color, and motion.
The architecture works because each layer has ONE job:
\nThat is the pattern I want here: ordinary HTML first, modern browser APIs where they remove markup, and a fallback that preserves the same source text instead of inventing a second content model.
\n", "image": "https://dout.dev/assets/og/posts/2026-06-06-how-pixhighlighter-is-built.png", "date_published": "2026-06-06T00:00:00.000Z", "tags": [ "vanilla-js", "frontend", "architecture" ] }, { "id": "https://dout.dev/posts/2026-06-02-wcag-22-aa-without-aria-spam.html", "url": "https://dout.dev/posts/2026-06-02-wcag-22-aa-without-aria-spam.html", "title": "WCAG 2.2 AA Without ARIA-Spam (Landmarks, Heading Order, Skip-Links — That's 80% of It)", "summary": "The unpopular opinion (brace yourself)", "content_html": "Most accessibility failures I see in production are not missing features. They are HTML that was never semantic, covered in ARIA attributes that were supposed to fix the damage. That approach is a tax forever. ARIA is a powerful tool and also a trap: the first rule of ARIA is to NOT use it if a native element would do the job.
\nFor dout.dev I made a rule for myself. Every page starts as semantic HTML. ARIA only shows up when there is no native alternative. That rule covered most of the WCAG 2.2 AA checklist before I wrote a single aria-* attribute.
HTML5 already gives you landmarks. A screen reader or a \"Rotor\" in VoiceOver reads them as navigation regions. You do NOT need to annotate them.
\n<body>\n <a class=\"skip-link\" href=\"#main\">Skip to content</a>\n <header>\n <nav aria-label=\"Primary\">\n <!-- navigation links -->\n </nav>\n </header>\n <main id=\"main\">\n <!-- content -->\n </main>\n <footer>\n <!-- footer content -->\n </footer>\n</body><header>, <main>, <footer> are already landmarks. The only role I add is on the <nav> when there are multiple nav elements, and even then I use aria-label=\"Primary\" to disambiguate.
A screen reader user navigates by headings. If your heading order goes h1 → h3 → h2, you are making blind people work harder for no reason. The rule is simple: never skip levels. h1 → h2 → h3, not h1 → h4.
\nEach page has exactly one <h1>. Sections within the page start at <h2>. Subsections at <h3>. If you need four levels of nesting in a blog post, your information architecture has bigger problems.
<a class=\"skip-link\" href=\"#main\">Skip to content</a>That is the single highest-impact accessibility fix for keyboard users. One link, visible on focus, that skips the navigation and lands the user in the main content. It takes five minutes to add and saves every keyboard user from tabbing through 47 navigation links.
\nWCAG 2.2 AA is not a checklist of ARIA attributes you need to add. It is a checklist of semantic HTML patterns you need to follow. Landmarks, heading order, skip-links — these three things cover more ground than any ARIA-based remediation.
\nWrite good HTML first. Add ARIA only when the native element genuinely does not cover the case. That is the entire accessibility strategy for dout.dev, and it works.
\n", "image": "https://dout.dev/assets/og/posts/2026-06-02-wcag-22-aa-without-aria-spam.png", "date_published": "2026-06-02T00:00:00.000Z", "tags": [ "accessibility", "html", "frontend" ] }, { "id": "https://dout.dev/posts/2026-05-30-modern-css-is-enough.html", "url": "https://dout.dev/posts/2026-05-30-modern-css-is-enough.html", "title": "Modern CSS Is Enough (Container Queries, Nesting, `:has()` — No Framework Required)", "summary": "The short version (for the impatient)", "content_html": "For about ten years, serious frontend work leaned on tooling that papered over missing CSS features: Sass for nesting, Styled Components for dynamic theming, BEM conventions for scoping, utility frameworks for constraint. Most of those reasons quietly disappeared in the last two browser cycles. Modern CSS has container queries, native nesting, :has(), cascade layers, logical properties, color-mix(), clamp(), and more. On dout.dev I ship ALL of these, and the CSS is shorter than it would have been five years ago.
This post is NOT \"CSS is cool now.\" It is a walk through specific modern features that let me delete a preprocessor and a handful of conventions. If you're still using Sass in 2026, we need to talk.
\nMedia queries size components against the viewport. That is the WRONG reference frame for components that can appear in a full-width article or a narrow sidebar. Container queries fix it.
\n.post-card {\n container-type: inline-size;\n container-name: card;\n}\n\n@container card (min-width: 400px) {\n .post-card__title { font-size: var(--text-xl); }\n}The component queries its own parent, not the viewport. That is the correct behavior for a reusable component. Media queries are for layout; container queries are for components.
\nNative nesting — header { h1 { ... } } works in every modern browser. No Sass compilation step. No & prefix needed for simple selectors.
:has() selector — the \"parent selector\" CSS always needed. post-card:has(> img) to style cards differently when they have cover images. No JavaScript, no extra class.
Cascade layers — @layer base, components, utilities lets you control specificity order explicitly instead of fighting it with !important.
color-mix() — color-mix(in srgb, var(--color-accent), white 20%) gives you tinted variants without maintaining color scales.
clamp() — font-size: clamp(1rem, 2.5vw, 1.5rem) gives you fluid typography without breakpoints.
darken() is color-mix().@scope reduce the need for naming conventions.box-sizing: border-box on everything and margin: 0 on body covers 90% of the cases.Modern CSS is not a toy. It is a production-ready styling system that has absorbed most of the reasons people reached for preprocessors and frameworks. If you are still reaching for Sass or a CSS framework out of habit, take a weekend to audit what you actually need. The answer might be \"less than you think.\"
\nYour bundle will thank you. Your users will thank you. Your future self maintaining this in 2030 will thank you.
\n", "image": "https://dout.dev/assets/og/posts/2026-05-30-modern-css-is-enough.png", "date_published": "2026-05-30T00:00:00.000Z", "tags": [ "css", "vanilla-js", "frontend" ] }, { "id": "https://dout.dev/posts/2026-05-26-vibe-coding-with-rigor.html", "url": "https://dout.dev/posts/2026-05-26-vibe-coding-with-rigor.html", "title": "Vibe Coding With Rigor (Or: How to Use AI Without Your Codebase Turning Into a Dumpster Fire)", "summary": "The term I am reclaiming (because \"vibe coding\" got a bad rap)", "content_html": "\"Vibe coding\" has become shorthand for \"let the AI write whatever it wants and see what happens.\" That is NOT what I did on dout.dev, and it is not what the term should mean if it is going to be useful. The version I work with looks more like this:
\n\n\nVibe coding is driving an AI copilot hard with clear intent, small units of work, and strict review, while keeping the architectural decisions in your own head.
\n
The vibe is the speed. The rigor is the review. This post is the workflow that made 19 milestones shippable without the repo turning into a science fair.
\nEvery session had one outcome. \"Wire up the RSS feed.\" \"Add the skip-link.\" \"Extract the pagination component.\" NOT \"improve the site.\" NOT \"make it more accessible.\" The outcome fit in one commit.
\nThat discipline mattered more than the prompt engineering. When a session has a scoped outcome, the copilot's proposals can be evaluated against a clear question: did this produce the outcome, and is the diff small? When a session is open-ended, every proposal feels plausible, and you accept changes you later regret.
\nContext: we are in a repo at <path>. The build system is <x>.\nTask: <one specific thing>. \nConstraints: <rules the output must follow>.\nAcceptance criteria: \n1. <checkable thing>\n2. <checkable thing>That's it. No system prompts. No \"act as a senior engineer\" preamble. The copilot does not need a persona; it needs context, a task, and constraints. The acceptance criteria are the most important part — they turn the output from \"looks right\" to \"provably right.\"
\nI read every diff. Every single one. If the copilot produced 200 lines and I needed 40, I kept the 40 and deleted the rest. If the copilot produced a pattern that was technically correct but did not match the rest of the codebase, I rewrote it.
\nThat is not a criticism of the copilot. It is the job. The copilot generates proposals; the engineer curates them. Anyone who skips the curation step is not engineering — they are editing.
\nArchitecture. Naming. Accessibility semantics. The CSP. URL design. Whether a given feature should exist at all.
\nThese stayed in my head. They are the difference between a codebase that is maintainable and a codebase that is \"working\" in the sense that a stopped clock is right twice a day.
\nVibe coding is not a license to abandon standards. It is a license to move faster while applying the same standards you would apply to a human pair programmer. Scope every session. Write acceptance criteria. Read every diff. Keep the architecture decisions in your own head.
\nDo that, and you can ship 19 milestones in weeks instead of months. Skip any of those, and you get a codebase that works today and is unfixable tomorrow.
\n", "image": "https://dout.dev/assets/og/posts/2026-05-26-vibe-coding-with-rigor.png", "date_published": "2026-05-26T00:00:00.000Z", "tags": [ "making-of", "ai", "workflow" ] }, { "id": "https://dout.dev/posts/2026-05-23-ci-cd-around-github-pages.html", "url": "https://dout.dev/posts/2026-05-23-ci-cd-around-github-pages.html", "title": "CI/CD Around GitHub Pages (Or: How I Got Deploy Previews Without Paying Netlify)", "summary": "The gap GitHub Pages leaves open (it's not that bad)", "content_html": "GitHub Pages is excellent for serving a static site. It is also, by default, missing two features that Netlify and Vercel have made everyone expect: deploy previews on pull requests, and one-click rollback to a previous deploy.
\nNeither is actually missing. They are just not turned on. The pieces exist in GitHub Actions; you have to wire them up. On dout.dev, that wiring is about 40 lines of YAML and one simple naming convention.
\nProduction deploys run from main or from workflow_dispatch. The workflow has two jobs — build and deploy — and produces a site at https://dout.dev.
name: Deploy Pages\non:\n push:\n branches: [main]\n workflow_dispatch:\n\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: pnpm/action-setup@v4\n - run: pnpm install --frozen-lockfile\n - run: pnpm build\n - uses: actions/upload-pages-artifact@v3\n with: { path: dist }\n\n deploy:\n needs: build\n runs-on: ubuntu-latest\n environment:\n name: github-pages\n url: https://dout.dev\n steps:\n - uses: actions/deploy-pages@v4That is a complete Pages workflow. The concurrency group prevents two overlapping deploys from fighting. The environment: github-pages line is required for the Pages deployment to succeed and also records deploy history.
GitHub Pages has one \"live\" site per repository. You cannot deploy a PR to a live preview URL the way Netlify does.
\nWhat you CAN do: build the PR, upload the dist/ as an artifact, and comment on the PR with a link to download it. A reviewer can extract the zip locally and open it. For a single-author blog, that is often enough.
name: PR Build\non:\n pull_request:\n branches: [main]\n\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - run: pnpm install --frozen-lockfile\n - run: pnpm build\n - uses: actions/upload-artifact@v4\n with:\n name: dist-PR_NUMBER\n path: dist\n retention-days: 14The artifact is named with the PR number, so CI history stays navigable. Retention is two weeks — long enough to review, short enough to not accumulate forever.
\nThis is the feature I use more often than I expected.
\nWhen a bad deploy reaches production — wrong content, broken CSP, accidentally unpublished post — the recovery path is:
\nThat rebuilds the old commit and redeploys it. One minute from \"oh no\" to \"fixed.\"
\nThe prerequisites:
\nmain. No manual artifact uploads. Every deploy is reproducible from a specific SHA.The workflow at the top of this post satisfies both. That is why it rolls back cleanly.
\nA useful side effect of \"every deploy is a commit\" is that the Actions history is the deploy history. You can see which commit is live right now, which commits have been deployed before, and how long each deploy took.
\nThe Pages environment in the repo settings also tracks \"Active deployment\" and shows the deployed commit SHA at the top. If you have to answer \"what is live right now?\" for a coworker, that screen is the authoritative source.
\nGitHub Pages with GitHub Actions is a complete deploy pipeline, including previews and rollback, if you accept that previews come as artifacts rather than live URLs. For most personal projects that is the right trade-off — no third-party service, no extra auth, and the same UI you are already using for the repo.
\nIf your blog is not on GitHub Pages with a proper deploy pipeline in 2026, what are you even doing?
\n", "image": "https://dout.dev/assets/og/posts/2026-05-23-ci-cd-around-github-pages.png", "date_published": "2026-05-23T00:00:00.000Z", "tags": [ "making-of", "ci", "deployment", "github-pages" ] }, { "id": "https://dout.dev/posts/2026-05-19-quality-gate-lint-format-verify.html", "url": "https://dout.dev/posts/2026-05-19-quality-gate-lint-format-verify.html", "title": "Quality Gate: Linting, Formatting, and Verify (Or: How I Stopped Shipping Broken HTML)", "summary": "Why the gate exists (because you will ship shit if you don't)", "content_html": "A single-author blog does not need CI the way a team product does. But any site that accepts drive-by contributions, or any site that I want to be able to touch in six months without re-learning, benefits from a gate that answers one question at merge time:
\n\n\nDoes this change still produce a correct, accessible, valid site?
\n
The gate on dout.dev is a single command, pnpm quality:check, that runs the same checks locally and in GitHub Actions. If it is green, the site is publishable. If it is red, it tells me which layer broke. That's it. No excuses.
pnpm test\npnpm spellcheck\npnpm format:check\npnpm format:check:html\npnpm validate:allFive commands, each doing one thing. No overlap. No ambiguity.
\npnpm test — Node's built-in test runner on the CMS and template-engine code. Fast. No Jest, no Vitest, no configuration surface. Just tests.
pnpm spellcheck — cspell against the markdown and HTML files. Catches typos in posts and navigation labels BEFORE they reach the reader.
pnpm format:check — Biome in check mode over JavaScript. Enforces the single formatter.
pnpm format:check:html — Prettier in check mode over HTML templates. HTML formatting is one of those things everyone forgets to verify until a diff becomes impossible to review.
pnpm validate:all — a composite of HTML validation, structural validation, link checking, and accessibility validation. The one that catches the most real bugs.
HTML validation is underrated. Bad nesting, missing alt text, heading skips, unused IDs — all of these slip past manual review and all of them matter. The validator on dout.dev runs against every file under src/ and dist/ and reports problems with file and line.
import { HTMLHint } from 'htmlhint';\n\nfunction validateHtml(file) {\n const rules = {\n 'doctype-first': true,\n 'tag-pair': true,\n 'attr-lowercase': true,\n 'alt-require': true,\n 'id-unique': true,\n };\n const source = readFileSync(file, 'utf8');\n return HTMLHint.verify(source, rules);\n}HTMLHint is not the only option. For deep validation the W3C Nu Validator is authoritative. For this project HTMLHint is enough. \"Enough\" is a feature.
\nEvery internal link on the site gets resolved to an actual file at build time. A broken link in a post or in the navigation FAILS the build.
\nExternal links are checked only occasionally, not on every build, because network flakiness should not fail a PR. A scheduled task runs external-link validation once a week.
\nThe a11y check runs axe-core over every generated page, using Playwright as the headless browser. It catches a significant fraction of WCAG issues automatically — missing labels, insufficient contrast, heading order problems, keyboard trap candidates.
\nAxe does not catch everything. Nothing does. What it catches is the base rate of failures that keep creeping in through drive-by edits. That's good enough.
\nEarly in the project, I shipped a build with a broken CSP meta tag. The page rendered; the browser silently refused to load the JavaScript. The fix is a build-time check that verifies the generated CSP is well-formed and covers the scripts referenced in the HTML.
\nThis is the kind of check you write exactly once, after exactly one production incident. Learn from my pain.
\nAll of this is wired in .github/workflows/deploy-pages.yml as a single step:
- name: Build site\n run: pnpm build\n\n- name: Quality gate\n run: pnpm quality:checkLocally I run pnpm quality:check before any push. If I am about to merge something significant, I also run pnpm test:visual — the Playwright visual regression suite — which is slower and therefore not on the default path.
A quality gate is a contract with your future self. Write it once, keep it small, run it everywhere. The specific checks that matter depend on the project. For a static editorial site, HTML validity, link integrity, and axe-core accessibility cover most of what goes wrong.
\nShip shit, get paged. Gate your shit, sleep well.
\n", "image": "https://dout.dev/assets/og/posts/2026-05-19-quality-gate-lint-format-verify.png", "date_published": "2026-05-19T00:00:00.000Z", "tags": [ "making-of", "tooling", "linting", "ci" ] }, { "id": "https://dout.dev/posts/2026-05-16-seo-metadata-without-rituals.html", "url": "https://dout.dev/posts/2026-05-16-seo-metadata-without-rituals.html", "title": "SEO Metadata Without Rituals (Or: I Read 47 SEO Blog Posts So You Don't Have To)", "summary": "The short version (TL;DR for the impatient)", "content_html": "\"SEO\" is a category name. Inside it are a dozen unrelated concerns, some of which matter for most sites and many of which do not. This post is the handful of tags I ship on dout.dev because they demonstrably help crawlers and discovery, and the handful I do NOT ship because they are noise.
\nThe line I draw: a tag earns its place if a major crawler uses it or if it improves a demonstrable discovery behavior. If it is \"recommended\" but nobody can point to the behavior it improves, I leave it out.
\nEvery page on dout.dev has a canonical URL in the head. Every single one. No exceptions.
\n<link rel=\"canonical\" href=\"https://dout.dev/posts/some-post.html\" />The value is the absolute URL of the page as it lives on the site. Three rules. Follow them.
\nWhere canonical matters most is when the same content is reachable via multiple URLs. Pagination is the classic case: /tags/accessibility/2/ should still canonical to itself, not to /tags/accessibility/. On a clean static site with one URL per page, canonical is mostly boilerplate. It is still worth shipping, because the day a duplicate URL appears (through a short-link service, a Mastodon share, a paginated archive), the canonical is the difference between a clean index and content fragmentation.
JSON-LD is the format Google, Bing, and LinkedIn want for structured data. It is a <script type=\"application/ld+json\"> block in the head.
{\n \"@context\": \"https://schema.org\",\n \"@type\": \"BlogPosting\",\n \"headline\": \"...\",\n \"datePublished\": \"...\",\n \"author\": { \"@type\": \"Person\", \"name\": \"...\" },\n \"image\": \"...\",\n \"publisher\": { \"@type\": \"Organization\", \"name\": \"dout.dev\" }\n}That block earns its place because:
\nThe post generator emits this block from the normalized post record. One source, per-post substitution, no manual upkeep.
\nWebSite with SiteNavigationElement, BreadcrumbList on posts that have no breadcrumb UI, Article alongside BlogPosting, @type schemas for which no consumer has a documented behavior.
The heuristic: if I cannot point at a concrete consumer behavior, I do NOT ship the schema. \"Might help ranking someday\" is not a reason. Schema spam has a negative cost with some crawlers, which explicitly penalize sites that dump irrelevant structured data.
\nhreflang tells crawlers which language a page is in and what the equivalents are in other languages. dout.dev is English only. The roadmap removed the i18n milestone. So hreflang is a no-op for my case and I do not ship it.
Writing it out here for completeness: the moment a site has localized content, hreflang is non-optional, and omitting it is a real SEO hit.
\nThese are not strictly SEO, but they are discovery. Every post has the full set: og:site_name, og:type, og:title, og:description, og:url, og:image, og:locale, article:published_time, twitter:card.
The og:image:width and og:image:height are NOT optional in practice. Mastodon's preview system, in particular, falls back to a smaller thumbnail without them. Ask me how I know.
<meta name=\"robots\" content=\"index,follow\" />\n<meta name=\"referrer\" content=\"strict-origin-when-cross-origin\" />Drafts (published: false) never render, so there is no need for a noindex path for them. referrer is a privacy choice.
SEO on a blog is not magic. Three tags — canonical, structured data, Open Graph — cover most of the actual behavior. Hreflang only when you have multiple languages. Skip the dozens of \"recommended\" tags unless you can point at the consumer behavior they enable.
\nThe goal is a clean, honest document, not a Christmas tree of meta tags.
\n", "image": "https://dout.dev/assets/og/posts/2026-05-16-seo-metadata-without-rituals.png", "date_published": "2026-05-16T00:00:00.000Z", "tags": [ "making-of", "seo", "opengraph", "html" ] }, { "id": "https://dout.dev/posts/2026-05-12-og-images-at-build-time.html", "url": "https://dout.dev/posts/2026-05-12-og-images-at-build-time.html", "title": "OG Images at Build Time (Or: How I Stopped Worrying and Learned to Love Sharp)", "summary": "The problem and the usual solutions (none of which I wanted)", "content_html": "Every post needs a social preview image — the card that appears when someone shares the URL on Slack, Twitter, or LinkedIn. The options usually break down like this:
\nog.dev/render?title=... produces an image on demand. Works. Adds a third-party dependency, latency, and a potential point of failure.For dout.dev I went build-time, for one reason: I wanted the image to be a byproduct of the build, cacheable as a static file, with zero runtime dependency. The implementation is about 150 lines of Node. That's it.
\nThe trick is that OG images are rasterized SVGs. SVG is a markup language I can generate with the same template engine as the rest of the site. Sharp then converts the SVG to PNG at 1200×630, which is the OG card spec.
\n<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"1200\" height=\"630\" viewBox=\"0 0 1200 630\">\n <rect width=\"1200\" height=\"630\" fill=\"#0b0b0f\" />\n <text x=\"80\" y=\"180\" font-family=\"Inter, sans-serif\" font-size=\"24\" fill=\"#ff6b3d\"\n font-weight=\"600\" letter-spacing=\"0.08em\">DOUT.DEV</text>\n <text x=\"80\" y=\"320\" font-family=\"Inter, sans-serif\" font-size=\"64\" fill=\"#e7e7ef\"\n font-weight=\"700\" style=\"line-height: 1.1\">\n <tspan x=\"80\" dy=\"0\">OG Images at Build Time</tspan>\n <tspan x=\"80\" dy=\"80\">SVG + Sharp in 150 Lines</tspan>\n </text>\n <text x=\"80\" y=\"540\" font-family=\"Inter, sans-serif\" font-size=\"24\" fill=\"#a0a0b4\">\n by Some Nerd · Some Date\n </text>\n</svg>That template has variables where the title, date, and author go. The generator produces one per post. Simple. Elegant. No bullshit.
\nThe hardest single problem in OG image generation is fitting a variable-length title inside a fixed-width box without it running off the edge. You'd think this would be solved. You'd be wrong.
\nThe brute-force solution — \"measure the text, wrap manually\" — requires a font metrics library. The simpler solution — greedy wrapping with a conservative line-length budget — is what I use.
\nfunction wrapTitle(title, maxChars = 26) {\n const words = title.split(/\\s+/);\n const lines = [];\n let current = '';\n for (const word of words) {\n if ((current + ' ' + word).trim().length > maxChars) {\n lines.push(current);\n current = word;\n } else {\n current = (current + ' ' + word).trim();\n }\n }\n if (current) lines.push(current);\n return lines.slice(0, 3);\n}26 characters is an empirical value for Inter at 64px in a 1040px box with 80px margins. I tuned it once, compared against the longest real titles, and moved on. The generator truncates to three lines because four looks cramped.
\nSharp handles the SVG-to-PNG conversion. It is a one-liner with reasonable defaults.
\nimport sharp from 'sharp';\n\nasync function renderOg(svg, outputPath) {\n await sharp(Buffer.from(svg)).resize(1200, 630).png({ compressionLevel: 9 }).toFile(outputPath);\n}compressionLevel: 9 squeezes the PNG a bit at the cost of build time. On a small blog the total is under a second per image, so it is worth it.
import { readFileSync } from 'node:fs';\nimport sharp from 'sharp';\n\nconst template = readFileSync('src/og-template.svg', 'utf8');\n\nexport async function generateOgImage(post, outputPath) {\n const lines = wrapTitle(post.title);\n const titleSvg = lines.map((line, i) =>\n `<tspan x=\"80\" dy=\"${i === 0 ? 0 : 80}\">${escapeXml(line)}</tspan>`\n ).join('');\n\n const svg = template\n .replace('<title-placeholder>', titleSvg)\n .replace('<date-placeholder>', formatDate(post.date))\n .replace('<author-placeholder>', 'Some Nerd');\n\n await sharp(Buffer.from(svg)).png({ compressionLevel: 9 }).toFile(outputPath);\n}150 lines with the helpers included. No fonts-as-files wizardry. No headless browser. No Puppeteer. No \"let's spin up Chrome just to render an image.\" That would be insane.
\nSVG font-family=\"Inter\" only works if the system rendering the SVG has Inter installed, which is not the case on GitHub Actions runners. Because why would it be?
Two paths:
\nOn dout.dev I went with option 2: a GitHub Actions step installs Inter before the build runs. That keeps the SVG clean and the bundles lean.
\n- name: Install Inter font\n run: |\n wget -q https://fonts.google.com/download?family=Inter -O inter.zip\n unzip -q inter.zip -d /usr/share/fonts/inter\n fc-cache -fThe URL for Google Fonts bulk download is stable enough; if it breaks, I self-host the .ttf in the repo.
One PNG per post, under src/assets/og/posts/<slug>.png. The CMS also generates month OG images under src/assets/og/months/ and writes a manifest at src/assets/og/manifest.json so other build steps can reference them.
The post template references the image in the <head>:
<meta property=\"og:image\" content=\"https://dout.dev/assets/og/posts/some-post.png\" />\n<meta property=\"og:image:width\" content=\"1200\" />\n<meta property=\"og:image:height\" content=\"630\" />\n<meta name=\"twitter:card\" content=\"summary_large_image\" />og:image:width and og:image:height are not strictly required, but many crawlers check them and Mastodon's preview service will happily show a tiny image if dimensions are missing. Like a thumbnail from 2005.
You do NOT need a runtime OG service, a headless browser, or a third-party API. A templated SVG, a wrapping function, and Sharp cover the whole problem in 150 lines. It runs at build time, commits to dist/, and costs nothing after the first build.
No server. No API key. No \"we're sorry, the OG image service is down.\" Just files.
\n", "image": "https://dout.dev/assets/og/posts/2026-05-12-og-images-at-build-time.png", "date_published": "2026-05-12T00:00:00.000Z", "tags": [ "making-of", "opengraph", "seo", "static-site" ] }, { "id": "https://dout.dev/posts/2026-05-09-feeds-and-sitemaps-at-build-time.html", "url": "https://dout.dev/posts/2026-05-09-feeds-and-sitemaps-at-build-time.html", "title": "Feeds and Sitemaps at Build Time (RSS Is Dead, Long Live RSS. Also JSON Feed.)", "summary": "The distribution minimum (three files, that's it)", "content_html": "A blog that does not ship feeds and a sitemap is a blog that nobody can reliably subscribe to, and a blog that crawlers have to guess at. Both problems are fixed with three files:
\nfeed.rss for the greybeards who still use actual RSS readers (I love you people);feed.json for the modern readers who prefer JSON Feed (I also love you);sitemap.xml for crawlers (I tolerate you).On dout.dev all three are generated at build time from the same normalized dataset the page generator uses. No external tooling. No runtime hit. No excuses.
\nDespite being old enough to drink in most countries, RSS remains the format that every reader supports. If you ship exactly one feed, ship RSS. The schema is tiny and the templating is a for-loop.
\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<rss version=\"2.0\" xmlns:atom=\"http://www.w3.org/2005/Atom\">\n <channel>\n <title>dout.dev</title>\n <link>https://dout.dev</link>\n <description>Vanilla-first static blog on web standards and AI-assisted engineering.</description>\n <language>en-us</language>\n <lastBuildDate>Mon, 30 Jun 2026 08:00:00 GMT</lastBuildDate>\n <atom:link href=\"https://dout.dev/feed.rss\" rel=\"self\" type=\"application/rss+xml\" />\n <item>\n <title>How Feeds Work at Build Time</title>\n <link>https://dout.dev/posts/feeds.html</link>\n <guid isPermaLink=\"true\">https://dout.dev/posts/feeds.html</guid>\n <pubDate>Tue, 30 Jun 2026 08:00:00 GMT</pubDate>\n <description><![CDATA[The three distribution files every blog should ship...]]></description>\n </item>\n </channel>\n</rss>Two things are easy to get wrong here. Don't get them wrong.
\nThe lastBuildDate and pubDate must be RFC 822. Not ISO. Not \"a date.\" RFC 822 with a four-digit year is the correct shape. Readers will silently drop items that do not parse. I learned this the hard way so you don't have to.
The <atom:link rel=\"self\"> is not optional. It is the self-reference that tells aggregators where the feed lives. Some validators treat it as a warning; some treat it as a bug; some readers ignore it. Ship it anyway.
JSON Feed is worth shipping alongside RSS. The format is human-readable, trivial to parse, and the spec is under one screen. Readers like NetNewsWire and Readwise speak it natively.
\n{\n \"version\": \"https://jsonfeed.org/version/1.1\",\n \"title\": \"dout.dev\",\n \"home_page_url\": \"https://dout.dev\",\n \"feed_url\": \"https://dout.dev/feed.json\",\n \"items\": [\n {\n \"id\": \"https://dout.dev/posts/some-post.html\",\n \"url\": \"https://dout.dev/posts/some-post.html\",\n \"title\": \"Feeds at Build Time\",\n \"date_published\": \"2026-06-30T08:00:00Z\",\n \"tags\": [\"seo\", \"static-site\"]\n }\n ]\n}The cost of adding it is an extra file and twenty lines of generator code. The benefit is any reader that speaks JSON Feed gets richer metadata — tags, summaries, author — without the ceremony of extension namespaces in XML. Twenty lines. Do it.
\nThe sitemap is for crawlers. If you ship it, ship EVERYTHING. Partial sitemaps are worse than no sitemap because they implicitly tell the crawler \"these are the interesting pages,\" which de-weights everything not listed.
\nThe dout.dev sitemap includes posts, tag pages, month archives, series archives, the home page, the about page, and the search page. It does NOT include the 404, the offline page, or the playground.
\nThe changefreq and priority fields are advisory. Google has said publicly that it mostly ignores them. I still ship them because other crawlers read them and the cost is nothing. Zero-cost optional metadata is always a yes.
An underrated feature: each tag page and each month archive on dout.dev has its own RSS feed. A reader who cares about accessibility but not about css can subscribe to /tags/accessibility.xml and never see a post outside that tag.
The feeds are generated from the same dataset as the main feed, filtered to the tag or month. It is free to produce, because the normalized data already has the tag and month indexes. Free as in beer and free as in effort.
\n<link rel=\"alternate\" type=\"application/rss+xml\" title=\"dout.dev - accessibility\" href=\"/tags/accessibility.xml\" />That <link rel=\"alternate\"> is how readers auto-discover the feed. Every tag page ships it. Every month page ships it. No exceptions.
None of this happens at runtime. The feeds and sitemap are generated when the CMS builds, committed as artifacts in dist/, and served as plain static files by GitHub Pages. That means:
This is the elegance of static sites: everything is a file. Your feed is a file. Your sitemap is a file. Your images are files. Your pages are files. Files don't crash.
\nShipping RSS, JSON Feed, and a sitemap is an afternoon of generator code. The payoff is measurable: crawlers find your content, readers subscribe, and the blog stops being a black box to the rest of the web. If your blog doesn't have feeds in 2026, fix that before you write another post.
\n", "image": "https://dout.dev/assets/og/posts/2026-05-09-feeds-and-sitemaps-at-build-time.png", "date_published": "2026-05-09T00:00:00.000Z", "tags": [ "making-of", "feeds", "seo", "static-site" ] }, { "id": "https://dout.dev/posts/2026-05-05-build-assets-pipeline.html", "url": "https://dout.dev/posts/2026-05-05-build-assets-pipeline.html", "title": "Build Assets Pipeline (Or: How I Turned a Simple Blog Into an Image Processing Factory)", "summary": "The goal (four non-negotiable constraints)", "content_html": "Every image on this blog has to satisfy four constraints. Not \"nice to have.\" Non-negotiable. Like my morning coffee.
\nThe pipeline that delivers that is entirely build-time. There is NO image CDN, no runtime resize, no magic. This post walks through each layer.
\nThe markdown source looks like a normal image:
\nWhat makes it responsive is NOT a special syntax. It's the build pipeline that sees the local path and does work behind the scenes. Magic? No. Engineering.
\nOptionally the author can provide a title meta string to override the default behavior:
\nSegments separated by | let you specify custom srcset, sizes, loading, and priority. For most images I omit all of that and let the pipeline fill in the defaults. Because defaults should be smart.
Before the CMS runs, an image pipeline step generates responsive variants of every image under src/assets/images/:
image.jpg → image-320.jpg, image-640.jpg, image-960.jpg, image-1280.jpg, NEVER upscaled;image.webp) and matching WebP variants at each size.The output of that step is a manifest file (src/assets/images-manifest.json) with entries like:
{\n \"/assets/images/keyboard.jpg\": {\n \"width\": 1920,\n \"height\": 1280,\n \"variants\": [\n { \"src\": \"/assets/images/keyboard-320.jpg\", \"width\": 320 },\n { \"src\": \"/assets/images/keyboard-640.jpg\", \"width\": 640 }\n ]\n }\n}Sharp does the resizing. The manifest is the contract between the image step and the markdown renderer. Contracts are good. Trust me, I've been divorced.
\n<img> into <picture> (the fun part)When the renderer encounters an image with a local path, it looks up the manifest, computes srcset for WebP and raster sources, and emits a <picture> element:
<picture>\n <source type=\"image/webp\" data-srcset=\"/assets/images/keyboard-320.webp 320w, ...\" />\n <source type=\"image/jpeg\" data-srcset=\"/assets/images/keyboard-320.jpg 320w, ...\" />\n <img src=\"/assets/images/keyboard.jpg\" alt=\"A keyboard on a wooden desk\"\n width=\"1920\" height=\"1280\" loading=\"lazy\" decoding=\"async\" />\n <noscript>\n <img src=\"/assets/images/keyboard-640.jpg\" alt=\"A keyboard on a wooden desk\" />\n </noscript>\n</picture>Two details worth calling out because they matter:
\nWidth and height come from the manifest. The browser reserves the correct aspect-ratio box BEFORE the pixels arrive, so there is ZERO layout shift when the image loads. This is the single most impactful CLS fix on any image-heavy page. If you're not doing this, you're doing it wrong.
\ndata-srcset instead of srcset by default. The real srcset is swapped in by a tiny script when the image enters the viewport, which is how the \"lazy on-reveal\" policy is enforced. The <noscript> fallback covers users who disable JavaScript. Because not everyone lives in a perfect world.
data-srcset to srcset (12 lines, no framework)The runtime piece is small. Embarrassingly small:
\nconst io = new IntersectionObserver(\n (entries) => {\n for (const entry of entries) {\n if (!entry.isIntersecting) continue;\n const source = entry.target;\n if (source.dataset.srcset) {\n source.srcset = source.dataset.srcset;\n source.removeAttribute('data-srcset');\n }\n io.unobserve(source);\n }\n },\n { rootMargin: '200px' }\n);\n\ndocument.querySelectorAll('source[data-srcset]').forEach((s) => io.observe(s));That's the ENTIRE lazy-load layer. Everything else is declarative markup the browser understands natively. No library. No framework. No bullshit.
\nloading=\"lazy\" alone? (the nuance part)Native loading=\"lazy\" is a good default and I use it on <img> elements. But it does NOT cover <source> elements inside <picture>. The IntersectionObserver swap handles the source selection path, which is where the large WebP variants are chosen.
On a page with a dozen images below the fold, the difference is measurable in bytes saved on initial load. Measurable matters.
\nResponsive images do NOT need a service. A build step that generates variants, a manifest the renderer reads, and a markdown pass that emits <picture> are enough. The result is small pages, correct sizes, known dimensions, and lazy behavior that respects the user.
No CDN. No runtime. No excuses.
\n", "image": "https://dout.dev/assets/og/posts/2026-05-05-build-assets-pipeline.png", "date_published": "2026-05-05T00:00:00.000Z", "tags": [ "making-of", "build-assets", "performance", "images" ] }, { "id": "https://dout.dev/posts/2026-05-02-design-tokens-before-pages.html", "url": "https://dout.dev/posts/2026-05-02-design-tokens-before-pages.html", "title": "Design Tokens Before Pages (Yes, I Wrote the CSS Before the First Line of HTML)", "summary": "The mistake I kept making (repeat after me: tokens first)", "content_html": "Every time I started a personal site and went \"page first, design system later,\" I ended up with a pile of local exceptions. A margin-top: 24px here, a color: #f5a623 there, a breakpoint at 768px on one component and 720px on another. By the third page the design was already incoherent, and the only way to fix it was to go back and retrofit tokens onto a living codebase. That is the WORST moment to do it. Like painting the inside of your house after you've already moved in.
For dout.dev I flipped the order. Tokens first, components second, pages third. This post is what that looks like in practice. No Figma. No design system conference ticket. Just CSS and discipline.
\nDesign tokens are NOT a library. They are a flat set of named decisions, expressed as CSS custom properties, about spacing, type, color, elevation, motion, and layout. The rest of the CSS reads those decisions and NEVER hardcodes.
\nThe rule I hold to is simple: if a value appears in two components, it becomes a token. If it only appears once, I wait. YAGNI applies to design systems too.
\n:root {\n --space-1: 0.25rem;\n --space-2: 0.5rem;\n --space-3: 0.75rem;\n --space-4: 1rem;\n --space-5: 1.5rem;\n --space-6: 2rem;\n --space-8: 3rem;\n\n --text-sm: 0.875rem;\n --text-base: 1rem;\n --text-lg: 1.125rem;\n --text-xl: 1.25rem;\n\n --surface-1: #0b0b0f;\n --surface-2: #161621;\n --text-primary: #e7e7ef;\n --text-muted: #a0a0b4;\n\n --focus-ring: 2px solid #ff6b3d;\n}That is a single source of truth. It does not know about pages. It does not know about components. It knows about DECISIONS.
\nRaw tokens alone are not enough for a theme-able site. You need two layers. I use two layers. You should too.
\nPrimitive tokens — the raw decisions above. They never change at runtime. They're the concrete values.
\nSemantic tokens — aliases that map intent to primitives. These are the ones components actually read, and these are the ones that flip between themes.
\n: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}Components then write color: var(--color-fg), never color: #e7e7ef. Theme switching becomes a matter of changing a handful of semantic tokens at the root, not rewriting every goddamn rule. This is how adults do CSS.
Three rules keep the CSS from rotting. Written down. Checked in code review.
\nNo magic numbers in components. If a value is not a token, it is almost always a mistake. The exceptions are genuinely one-off values tied to a specific piece of geometry, and those get a comment explaining why.
\nNo color literals outside the token file. Not even in media queries, not even in box-shadow. If a color is referenced, it is via a variable. Period.
No breakpoint literals outside a shared map. Breakpoints are tokens too, expressed as container query breakpoints or named media queries, never inline numbers.
\n/* Good */\n.post-card {\n padding: var(--space-5);\n background: var(--color-bg-raised);\n color: var(--color-fg);\n}\n\n/* Bad */\n.post-card {\n padding: 24px;\n background: #161621;\n color: #e7e7ef;\n border-radius: 8px;\n}The \"bad\" version works. It will also be unfixable in a year. Trust me. I've been that guy.
\nWhen I added the light theme and the accent selector, the change was a few dozen lines. Every component picked it up for free, because no component hardcoded a single goddamn value. The dark mode toggle, the prefers-color-scheme hookup, and the accent switcher are all variations on the same idea: swap the semantic tokens at the root, let the cascade do the rest.
Without the two-layer setup, theming a site usually means touching every component. WITH it, theming is one file. One. That's the power of not being an idiot.
\nI did not build an elaborate token pipeline. No Style Dictionary, no JSON sources compiled into multiple formats, no cross-platform tokens. This is a single-target CSS project. A flat .css file that declares custom properties is enough, and any tooling beyond that would be overhead without a matching benefit.
If the project grew multiplatform — iOS, Android, email, a design tool plugin — I would pull in Style Dictionary. Until then, one file and discipline. Discipline over tools. Every time.
\nIf you are starting a personal site or a small design system, WRITE THE TOKEN LAYER BEFORE THE FIRST PAGE. It costs an afternoon. It buys you theming, consistency, and the ability to make design changes in ONE PLACE instead of twenty. Your future self will thank you. Your present self will be confused about why you didn't do this years ago.
\n", "image": "https://dout.dev/assets/og/posts/2026-05-02-design-tokens-before-pages.png", "date_published": "2026-05-02T00:00:00.000Z", "tags": [ "making-of", "design-systems", "css" ] } ] }