All about Ken Hawkins

Blog art that belongs

2026-03-03T00:00:00.000Z

For a while I was using Loras for post art. Fine results, but the workflow sat completely outside of my writing flow and I'd never be able to fully adapt that to my style and iterate ... and, well, learn more about using image generators.

When FLUX.2-dev came out I wanted to try it — and connect it to the blog workflow directly rather than bolt on another external script. So I built a small browser tool that lives in the site itself. Paste your Together AI key, type a subject, hit Generate — three images run in parallel in about 20-30 seconds. Click one, crop, save straight to src/site/images/blog/. The tool spits out a frontmatter snippet ready to paste. All without leaving the browser.

For a post about search without external services: "paths worn into grass by footsteps, no paved road, just natural routes."

For a post about vector embeddings: "glowing points scattered in a dark field, some clustered, some drifting apart."

A consistent style prefix keeps images looking like a set across posts rather than a random pile. The rest is just picking a prompt that fits the feel of the post.

Three images run about $0.03 via Together AI. The tool is a single self-contained page if you want to adapt it.

Semantic search on a static site, no API keys required

2026-03-02T00:00:00.000Z

Last week I replaced Lunr.js with Pagefind for keyword search on this site. Pagefind works well ... type "eleventy image plugin" and get back pages containing those words. But search for "image formatting" and you'll miss the post you want.

AI would find it better.

I wanted to see how close I could get to natural-language search experience on a static site without any cloud infrastructure. No API keys, no SaaS, no server. Could the same embedding model run at build time and in the browser, and would the results actually be useful?

The answer is mostly: yes. Although the visitor's browser has to download ~30 MB on first use, the query runs entirely on device, and results are quite good.

Try the semantic search

As I don't get much traffic, this is a bit silly. But it's the perfect thing for my website playground. Vector search on a personal blog is a toy. Vector search on a documentation site with hundreds of pages and users who don't know the right terminology is a different story.

tl;dr#

Build-time script generates vector embeddings for all posts using MiniLM-L6-v2 via Transformers.js

Splits each post into overlapping chunks and embeds them separately — relevant content deep in a post is no longer invisible

Produces a vectors.json file shipped as a static asset

Browser loads the same model on first query (~30 MB with WASM runtime, cached afterward)

Cosine similarity ranks posts by meaning, not keywords

Try it on the search page

How vector search works#

Traditional search (Lunr, Pagefind, Elasticsearch) builds an inverted index: for each word, store which documents contain it. Query terms get looked up in the index and documents are ranked by term frequency, document length, and similar signals. This works well when the user's words match the author's words.

With vector search, a small neural network (all-MiniLM-L6-v2) reads a piece of text and produces a fixed-length array of numbers — a 384-dimension vector — that captures the text's meaning. Two texts about similar topics produce vectors that point in similar directions, even if they share no words.

At query time, the same model converts the question into a vector. The ranking itself is just cosine similarity. All the intelligence is handed off to the model that produces the vectors.

Want a visual explanation of the difference between keyword and vector search? This video covers it well:

The build-time half#

A Node.js script runs after Eleventy in the build pipeline. It reads every HTML file in the build/ directory, extracts text from <main data-pagefind-body> (the same element Pagefind uses to decide what's content), and generates embeddings.

MiniLM-L6-v2 has a 512-token (~2048 character) input limit — anything longer gets silently truncated. So if the relevant content is 2000 characters into a post, a single whole-page embedding won't see it. The script splits each post's body into overlapping ~1000-character chunks (stride 800, snapping to sentence boundaries), then embeds each one separately. The first chunk gets the title, description, and body text; later chunks get the title and body text only.

const chunks = chunkText(content.bodyText);  // ~1000 chars each, 200-char overlap
for (const chunk of chunks) {
  const text = title + ' ' + chunk.text;     // chunk 0 also gets description
  const output = await extractor(text, { pooling: 'mean', normalize: true });
}

The output is a JSON file with one entry per chunk:

{
  "model": "Xenova/all-MiniLM-L6-v2",
  "dimension": 384,
  "version": 2,
  "chunks": [
    {
      "url": "/posts/example/",
      "title": "...",
      "snippet": "First 200 chars of this chunk...",
      "teaser": "...",
      "date": "2026-02-28",
      "embedding": [0.023, -0.041, ...]
    }
  ]
}

Each chunk carries a snippet — the first 200 characters of that chunk's text — which the browser can show in results instead of the generic meta description. Only the first chunk per page carries teaser and date to avoid bloating the file.

Embeddings are rounded to 4 decimal places, well within MiniLM's noise floor. For 89 pages producing 645 chunks, the file is 2 MB raw, ~600 KB gzipped. The embedding step takes longer than the single-embedding approach but is still reasonable for a production build.

Embeddings run after Eleventy (which runs Pagefind in its eleventy.after hook), so the full HTML output is available.

The build-time @huggingface/transformers dependency is heavy — roughly 476 MB in node_modules, mostly ONNX Runtime native binaries for running the model in Node.js. It ships prebuilt binaries for every platform (macOS, Linux, Windows, multiple architectures), and there's no way to install only the one you need. None of this ships to the browser — it only runs during the build to generate the vectors.

This is the same kind of tradeoff as Pagefind shipping a Rust binary for its indexing step: the build-time tooling is large because something has to actually run the neural network over your content. The output is small and fast to query, but producing it requires real compute.

A Python script with just onnxruntime and tokenizers (no PyTorch) would cut the footprint to ~75-100 MB — ChromaDB uses this approach in production. You could also compile a Rust binary with fastembed-rs, though it's a library, not a CLI, so you'd need to write a wrapper. Either way, it means adding a non-Node dependency to the build. For now, one fat npm install is simpler.

The embedding script is not included in yarn dev — it's too slow for iterative development, same as my Pagefind indexing step. Run yarn build once to generate vectors, then yarn dev as usual.

The browser half#

The semantic search UI loads nothing on initial visit. On first query submit, three things happen:

Fetch /semantic-search/vectors.json
Import Transformers.js from jsDelivr
Initialize the MiniLM pipeline (~23 MB model + ~4 MB WASM runtime, with progress bar)

The model and runtime download once and cache normally. Subsequent queries within the same session are near-instant — embed the query (~100 ms), compute 645 dot products across all chunks, deduplicate to the best-matching chunk per page, sort and display. The scoring loop plus Map dedup takes under 10 ms.

// Lazy-load on first query, not on page load
const { pipeline } = await import('https://cdn.jsdelivr.net/npm/@huggingface/transformers@3');

extractor = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', {
  dtype: 'q8',
  progress_callback: (progress) => {
    if (progress.status === 'progress') {
      progressBar.value = Math.round(progress.progress);
    }
  },
});

Transformers.js handles model caching via the browser's Cache API, keyed by model ID. The ~23 MB download happens once; subsequent visits load from cache.

Results are filtered by a similarity threshold (score > 0.25) and limited to five. Below that threshold, results tend to be noise. The response templates are simple conditionals — no LLM generates the answer text:

Zero results: "I couldn't find anything closely related. Try rephrasing, or use keyword search."
One high-confidence result: "I found one post that closely matches:"
Multiple results: "Here are N posts that might be relevant:"

Every response includes a fallback link to Pagefind keyword search.

What the model sees#

MiniLM-L6-v2 is a sentence transformer — a BERT variant fine-tuned for producing sentence embeddings. It was trained on over a billion sentence pairs and distilled from a larger model. The "L6" means six transformer layers (BERT-base has twelve), and the output is 384 dimensions (half of BERT's 768). Smaller and faster, at the cost of some nuance.

It doesn't understand content the way a large language model would. It maps text into a geometric space where similar meanings cluster together. "Why meetings kill productivity" and "short disruptions cost lots of time" land near each other because the model learned from millions of examples that those phrases appear in similar contexts.

The input you feed it matters more than I expected. Just the title loses too much nuance. The entire article dilutes the signal with boilerplate. The model's hard limit is 512 tokens (~2048 characters) — anything longer gets silently truncated. So instead of embedding each page as a single vector, the build script splits the body into overlapping ~1000-character chunks and embeds each one with the title prepended. At query time, the browser scores every chunk and keeps the best match per page. This means relevant content buried 3000 characters into a post still surfaces, and the best-matching chunk's snippet can be shown in results instead of the generic meta description.

Pagefind and semantic search compared#

	Pagefind (keyword)	Semantic search
Query type	Exact and fuzzy keyword matching	Natural language, meaning-based
Initial download	~10 KB JS + ~75 KB WASM	~600 KB vectors + ~30 MB model + runtime (cached)
Per-query cost	~10-30 KB index fragments	~100 ms compute, no network
Best for	Known terms, specific phrases	Exploratory questions, topic discovery
Excerpts	Yes, highlighted in context	Yes (best-matching chunk snippet)
Build dependency	Rust binary (via npm)	~476 MB ONNX runtime (via npm)

Pagefind is better when you know the words. Semantic search is better when you know the idea but not the vocabulary. Both live on the same search page — keyword search is the default, and semantic search is an opt-in that loads on demand.

Tradeoffs#

The 30 MB elephant. The first query downloads the quantized model (~23 MB) plus the ONNX Runtime WASM engine (~4 MB), tokenizer, and Transformers.js library — about 30 MB total. The full-precision model is 90 MB; 8-bit quantization (dtype: 'q8') gets it to 23 MB with no noticeable quality loss for sentence embeddings. Everything caches, so repeat visitors pay nothing, but the first query on a new device is a real wait. The progress bar helps set expectations. I looked at lighter alternatives (see the Model2Vec note in "What I'd change") but nothing I tested matched the result quality of running a real transformer — the 30 MB is the cost of results that actually work.

Chunking bloats vectors.json. Splitting posts into overlapping chunks means ~7x more embeddings than one-per-page. The vectors file grows from 727 KB to 2 MB raw (~600 KB gzipped). Build time increases proportionally. The payoff: results now show a relevant snippet from the best-matching chunk instead of the generic meta description, and content buried deep in a post actually surfaces.

Threshold tuning. The 0.25 cosine similarity cutoff is hand-tuned. Too low and irrelevant results creep in. Too high and you miss valid matches. There's no perfect number — it depends on the corpus and the kinds of queries people ask.

CDN dependency. Transformers.js and the ONNX Runtime WASM load from jsDelivr; the model files load from HuggingFace via Transformers.js's Cache API. If either CDN is down, the page shows an error with a link to keyword search.

No conversational LLM. You could generate natural-language answers on top of the embeddings, but even small LLMs need 1-4 GB downloads and WebGPU support. For finding a blog post, a ranked list with teasers does the job.

Tips if you're doing this#

Reuse your existing content boundary. If you already have data-pagefind-body or similar markup, use it as the extraction boundary for embeddings too. One source of truth for "what counts as content."
Chunk the body, prepend the title. Don't feed the model raw HTML or entire articles — MiniLM silently truncates past 512 tokens. Split the body into overlapping ~1000-character chunks, prepend the title to each, and embed separately. At query time, score every chunk and keep the best match per page. This surfaces content that's deep in long posts and gives you a relevant snippet for free.
Lazy-load everything. Don't download the model on page load. Most visitors will never use semantic search. Load on first interaction and show a progress bar.
Ship both search types. Keyword and semantic search solve different problems. Cross-link between them so users can switch when one doesn't find what they need.
Set a similarity threshold. Without a cutoff, every query returns results — even nonsense queries. Start at 0.25 and adjust based on your corpus.

What I'd explore#

~~Show snippets, not just teasers.~~ Done. The build script now splits each post into overlapping chunks and embeds them separately. Results show the best-matching chunk's snippet instead of the generic meta description. Storage grew from 727 KB to 2 MB for vectors.json (~600 KB gzipped), but the results are noticeably better — queries about topics mentioned only deep in a post now surface correctly.

Shrink the vectors. Each embedding is 384 float32 values (1,536 bytes). Binary quantization thresholds each value to a single bit and uses Hamming distance instead of cosine similarity. That's a 32x size reduction — the vectors in vectors.json would go from ~700 KB to ~4 KB. Models trained with Matryoshka representation learning (like mxbai-embed-xsmall-v1) let you also truncate dimensions — 384 down to 128 with ~85% quality retained. Combine both and each embedding becomes 16 bytes. For 88 documents this barely matters, but for thousands of chunks it would.

Eliminate the ONNX runtime with static embeddings. Model2Vec distills a transformer into a lookup table — tokenize, index into a matrix, average, normalize. No neural network inference, no WASM runtime. The browser download would drop from ~30 MB to ~4-15 MB and query-time inference would be instant. I tested the potion models (2M, 4M, and 8M parameters) against MiniLM-L6-v2 on my actual content, though, and the results were disappointing. For queries like "improving search on a static site," MiniLM correctly finds the two search-related posts. All three potion models miss both entirely. On "design systems," potion returns the 404 page, Privacy Policy, and Colophon — pages with short generic text that become false attractors after mean pooling. The Jaccard overlap between MiniLM's top results and potion-8M's was about 32% across my test queries. On MTEB benchmarks, potion-base-8M scores ~89% of MiniLM's average, but that gap matters more on a small corpus where the margin between a good result and garbage is thin. If static embedding models keep improving — and they are — this could change fast.

Merge keyword and semantic results more deeply. Keyword and semantic search now live on the same page — semantic is an opt-in below keyword results. The next step would be to load the embedding model in a background Web Worker and merge the two result sets automatically when the model is ready. The user always sees keyword results immediately instead of watching a progress bar, and semantic results appear alongside when ready. Sift does exactly this — it stores FTS5 keyword indexes and vector embeddings in a single SQLite file, shows keyword results first, then upgrades to semantic. It also uses HTTP range requests to read only the index pages it needs, which would matter for larger sites.

For now, it's two search modes on one page on a static site with no backend — overkill for a personal blog, but a useful sketch for how this could work on sites where search actually matters. Try it.

Related posts:

Site search without a search service — the Pagefind keyword search this builds on
Collaborate on any webpage with a bookmarklet — another "do it in the browser" project from the same week
A simpler, faster site: moving to pure Eleventy v3 — the foundation this all runs on

Site search without a search service

2026-02-28T00:00:00.000Z

This site has full-text search with no backend service. The index is generated at build time from the same HTML that Eleventy produces, and queries run in the browser. A small JS module fetches the relevant index fragments with plain HTTP GETs — no search API, no Cloudflare Worker.

tl;dr#

Pagefind indexes my HTML and produces a chunked search index

A data-pagefind-body attribute controls what gets indexed

An eleventy.after hook runs async so dev rebuilds aren't blocked

Replaced my aging Lunr.js setup (unmaintained since 2020, 204 KB upfront download)

Full diff on GitHub

Why not stick with Lunr.js?#

I previously used Lunr.js, which had the right idea: build-time indexing, client-side querying, no external service. Lunr was modeled after Apache Solr (same inverted-index approach, TF-IDF ranking) just small enough to run in the browser. But Lunr hasn't had a release since 2020.

Pagefind uses BM25 for ranking, the same algorithm behind Elasticsearch and modern Lucene. It's an evolution of TF-IDF that handles term frequency saturation and document length normalization better. The search runs as a Rust binary compiled to WASM, so queries execute in the browser without a server round-trip. The migration PR has the full diff.

Why I switched to Pagefind#

Pagefind's integration comes down to one HTML attribute. Add data-pagefind-body to your main content wrapper and Pagefind indexes only that element. Pages without it (social cards, redirect stubs, anything outside your base layout) are automatically excluded.

For boilerplate within content pages (comments sections, previous/next navigation), data-pagefind-ignore on that wrapper keeps it out of the index.

The build integration is an eleventy.after hook:

let pagefindChild = null;
config.on('eleventy.after', () => {
  const cmd = 'pagefind --site build --exclude-selectors "pre, code"';
  if (isDev) {
    if (pagefindChild) {
      pagefindChild.kill();
      pagefindChild = null;
    }
    pagefindChild = exec(cmd, (err) => {
      pagefindChild = null;
      if (err && !err.killed) console.error('Pagefind index build failed');
    });
  } else {
    execSync(cmd, { stdio: 'inherit' });
  }
});

In production, execSync so the build waits for the index. In dev, exec (async) so rebuilds aren't blocked. Search catches up a few seconds after each save.

The search page is about 80 lines of JavaScript. Here's the key part — Pagefind lazy-loads as an ES module the first time someone searches:

async function init() {
  if (!pagefind) {
    pagefind = await import('/pagefind/pagefind.js');
    await pagefind.options({ excerptLength: 30 });
  }
  return pagefind;
}

The rest handles debounced input, escapes output with textContent instead of innerHTML, and reads the URL parameter so the 404 page can redirect to search. One thing I discovered post-launch: code examples were showing up in search excerpts as raw HTML. Adding --exclude-selectors "pre, code" to the Pagefind command fixed that. You can also use data-pagefind-ignore on individual elements, but the CLI flag is cleaner for a global rule.

Before and after#

Metric	Lunr.js	Pagefind
Initial download (gzip)	204 KB	~10 KB JS (+75 KB WASM on first search)
Per-query download	0	~10-30 KB
Unmaintained dependencies	3	0

The download difference is obvious. The tradeoff is per-query cost: Lunr loaded everything upfront and searched instantly, while Pagefind fetches index fragments on demand. For a site this size, the fragments are small enough that you'd never notice.

Tips if you're doing this#

Use data-pagefind-body rather than listing exclusions. Add it to your main content wrapper and everything else is excluded by default. Much cleaner than maintaining a list of things to ignore.
Exclude code blocks from indexing. Run Pagefind with --exclude-selectors "pre, code" unless you want raw HTML from code examples showing up in search excerpts.
Run Pagefind async in dev mode. Use exec (not execSync) in your dev build hook so Eleventy rebuilds aren't blocked. Search lags a few seconds behind each rebuild, which is fine for development.
Kill previous Pagefind runs on rebuild. In dev mode, overlapping builds can corrupt the index. Track the child process and kill it before spawning a new one.
Add a <noscript> fallback. A link to DuckDuckGo site:yoursite.com costs nothing and handles the JS-disabled case.

Tradeoffs#

Pagefind isn't without cost. It loads a ~75 KB WASM module, not pure JS like Lunr was. You also get less control over the indexing pipeline; Lunr let you customize tokenization and stemming, while Pagefind's index is more of a black box.

The chunked architecture means each search makes network requests to load index fragments on demand. Lunr was one-and-done after the initial load. For a site this size you'd never notice, but the tradeoff is real.

It's also another build tool, though it replaced a three-dependency Node script, so net complexity went down.

The best search for a static site is still the idea Lunr had ten years ago: index at build time, query in the browser, skip the external service. Pagefind does the same thing with a chunked index and active maintenance. If your site search hasn't been touched in a while, the migration PR might be a useful reference. I'd be curious to hear if you've run into anything different.

Update, 2 March 2026: Getting Pagefind working got me curious about what's possible beyond keyword matching. I've since added semantic search — same philosophy (no API keys, runs in the browser), but it uses vector embeddings to match by meaning instead of exact words. Try it out.

Collaborate on any webpage with a bookmarklet and URL state

2026-02-25T00:00:00.000Z

I regularly send webpages to colleagues for feedback — staging sites, published posts, someone else's work I want a second opinion on. The ask is always simple: look at this page and tell me what you'd change.

Tools for this are not easy and low-friction. Every platform I found wants accounts on both sides. I don't want to sign up for a SaaS tool, and I definitely don't want to make a colleague create an account just to tell me a heading is wrong. Screenshots go stale. Slack messages turn into "the third paragraph under the hero, on the left side, below the thing."

I wanted something with no friction: point at things on a live page, leave comments, hand someone a link. With AI-assisted coding, I put together Pinment in a couple of hours — a bookmarklet that does exactly that. (The name is "pin" plus "comment." A naming decision I already regret.)

Try Pinment View on GitHub

Pinment running on this site, with a pin placed on the heading and the comment panel open.

How it works#

Grab the bookmarklet, navigate to any page — published, staging, localhost, behind auth — and click it. A panel appears.

Click anywhere to drop a numbered pin. Add a comment. Drop more pins. Hit Share. Pinment compresses everything into the URL fragment.

The recipient opens the link, clicks the bookmarklet, and sees the full annotated view reconstructed. No server, no login. The URL carries the entire review session.

URL as the entire state layer#

This extends the URL-as-state idea I've mentioned before. With Pinment URL fragment holds the entire review session.

A review with 15–20 annotations fits under 4 KB. The practical ceiling is around 50 pins before browsers complain about URL length.

Pins that follow the DOM#

Screenshots anchor to pixel coordinates. Resize the window and they're meaningless. Pinment anchors to the DOM instead. It generates CSS selectors for each pinned element, preferring stable hooks (IDs, data-testid) over fragile positional chains. Pins reposition on resize.

If the DOM changes and a selector can't resolve, Pinment falls back to the original coordinates with a warning badge.

Bookmarklet, not extension#

A browser extension requires installation, review queues, and separate builds per browser. A bookmarklet is a bookmark. Drag it to the bar, done.

The bookmark itself is a tiny loader (~200 characters) that fetches the full script from the host. Updates ship without reinstalling anything.

What you can do with it

Beyond placing pins and sharing URLs, Pinment handles a few things that come up in real review workflows:

Thread replies — reply to any pin to start a back-and-forth
Categories — label pins as text, layout, missing content, or question
Resolved status — mark issues as resolved without deleting the pin
Filter and sort — filter by category, status, or author when the pin count grows
JSON import/export — save a session to a file and reload it later, useful for reviews that span multiple days or exceed URL length limits
Element highlighting — hover a pin or its panel entry and the anchored DOM element outlines on the page
Drag to reposition — move pins after placing them without starting over
Keyboard shortcuts — Escape for browse mode, N for pin mode, arrows to navigate between pins

Standing on shoulders

I borrowed ideas from several tools:

Hypothesis proved open web annotation is a viable concept, though it's built around text selection and a centralized backend
Marker.io and Pastel showed the product need for visual webpage review, but both require accounts, cost money, and capture screenshots rather than annotating live pages
Inkash demonstrated the bookmarklet annotation approach
Buffertab showed that lz-string compression can fit useful state into URL fragments without a backend
Ahmad El-Alfy's writing on URL-as-state shaped how I think about what belongs in a URL

None of them did everything I wanted. Hypothesis selects text, not visual elements. Marker.io and Pastel capture screenshots, not live pages. Buffertab proved the URL compression trick but isn't built for annotation. So I took the parts that worked.

Try it#

Pinment is on GitHub and the bookmarklet hub is live. Drag the bookmarklet to your bar and try it on any page. If a selector breaks, a pin lands in the wrong spot, or you hit the URL length ceiling sooner than expected — file an issue.

It's not as bulletproof as marking up a PDF, but it's lighter, faster to set up, and nobody has to create an account to collaborate.

A browser extension would be more reliable on pages with strict Content Security Policy, and I may build one eventually — but then everyone has to install it. The bookmarklet keeps the barrier at zero.

Try it out

If nothing else, it's a chance to rediscover bookmarklets. They're a useful bit of web tech that's gone unloved since peaking around 2011.

Google Trends for "bookmarklet" -- peaked around 2011 and has been sliding since. Source.

Related posts:

URLs are the state management you should use — the URL-as-state philosophy behind Pinment's sharing model
Feedback buttons without JavaScript, using a 1990s web pattern — another project using URL fragments as state
PDF-A-go-slim: a browser-based PDF optimizer — same build season, same "do it in the browser" ethos
Two-way communication beats another shipped feature — the tension between shipping and landing

Feedback buttons without JavaScript, using a 1990s web pattern

2026-02-20T00:00:00.000Z

I wanted to add a "Was this useful?" button to my blog posts. The site runs on GitHub Pages. No backend. No database. No server-side anything. And I didn't want JavaScript in the interaction itself.

The solution turned out to be three decades(!) old.

tl;dr

Skip to the setup tutorial

A Cloudflare Worker handles feedback clicks via HTTP redirect — no client-side JS needed

The pattern is identical to how 1994 web rings counted click-throughs

CSS :target shows a "Thanks!" message after the redirect without page navigation

An SVG endpoint returns just the number — the 1996 hit counter, reborn

The Worker source is in the worker/ directory of this site's repo

Constraints as a design tool#

This site already uses a CSS-only toggle to disable all styles with a checkbox. The search form works without JavaScript. URLs carry state instead of client-side stores. The pattern is clear: HTML and CSS do the work; JavaScript is an enhancement, not a dependency.

That's not accidental — it's why the site runs on Eleventy, a static site generator that ships zero client-side JavaScript by default. The framework's position is that HTML is the deliverable; everything else is opt-in.

Feedback buttons should follow the same rule. Click a link, register the vote, done. No fetch() calls, no framework, no hydration. If JavaScript fails to load, the feedback still works.

The problem is obvious: the site is static HTML, so where do we put the brain?

What would a 1998 webmaster do?#

In 1998, your personal page on GeoCities was static HTML — just like GitHub Pages today. You had no backend. But you wanted interactivity: hit counters, guestbooks, polls. So you used other people's CGI scripts — small programs that ran on a web server, handled one HTTP request, and returned a response. An <img> tag could point to a CGI script on someone else's server that generated a counter image. A <form> action could submit to a remote script that appended to a flat file and redirected back.

The web was always a composition of origins. Your static page was the frontend; the internet was the backend.

Web rings used this exact architecture. The "Next site" button was a link to a central CGI script:

http://www.webring.org/cgi-bin/webring?ring=navships;id=002;next

Click it, and the script would increment a counter, look up the next site, and return a 302 Found redirect. The user barely noticed the hop. This pattern worked in Mosaic. It still works in every browser today. It's pure HTTP.

Replace "next site in the ring" with "the post you just read" and "click-through count" with "thumbs-up count." The architecture is identical.

The redirect-count-redirect pattern#

Here's what happens when a reader clicks the thumbs-up button:

Reader clicks "👍 Yes" on a blog post
  → GET https://feedback.allaboutken.com/up/posts/my-post/
  → Worker increments counter in KV storage
  → Worker returns: 302 Location: https://www.allaboutken.com/posts/my-post/#thanks
  → Browser follows redirect back to the same post
  → CSS :target reveals "Thanks for the feedback!" message
  → Reader never truly left the page

The #thanks fragment in the redirect URL is doing real work. It's URL-as-state again — the fragment triggers a :target CSS rule that reveals a thank-you message that was always in the HTML, just hidden. No JavaScript needed to show it.

The Worker itself is under 200 lines. It handles three route families:

/up/posts/slug/ — increment a KV counter, 302 redirect back to the post
/count/posts/slug.svg — return the count as an SVG number (image/svg+xml, 2-second cache). Drop it in an <img> tag. Add ?color=white for light text on dark backgrounds; defaults to black. Not CSS-styleable from the page since it's a separate document.
/count/posts/slug/ — return the count as plain text (text/plain, 2-second cache). Use this for build-time fetches, a small JS enhancement that injects the number into a <span> you can style, or scripting.

The SVG endpoint is the 1996 hit counter pattern. An <img> tag pointing to a script that returns a dynamically generated image:

<img src="https://feedback.allaboutken.com/count/posts/my-post.svg" alt="47 people found this useful">

The browser thinks it's loading a normal image. The Worker is secretly running code. This is exactly what <img src="/cgi-bin/counter.pl"> did in 1996, except the "CGI script" runs on a global edge network instead of a Pentium II under someone's desk.

Aside: The current implementation tracks positive feedback only — a single "Yes, this was useful" button. The Worker supports /down/ routes too, but the UI doesn't expose them yet. Binary up/down adds complexity (what does the count mean? net? total?) without much signal for a personal blog. A future version may add star ratings via ISMAP (see What's next at the end of this post).

Demo

A plain <a> link. No JavaScript. The Worker handles the rest. aria-live="polite" on the thank-you message announces it to screen readers when it appears.

👍 Yes, this was useful

<a href="https://feedback.allaboutken.com/up/posts/20260220-feedback-buttons-cgi-pattern/" rel="nofollow">👍 Yes, this was useful</a>
<span id="thanks" class="kh-feedback-thanks" aria-live="polite">Thanks for the feedback!</span>

SVG count (no JavaScript)

The SVG returns just the number. Set height:1.5em and it sits inline with text at any font size. Add ?color=white for dark backgrounds.

people found this useful

Because the height is in em, it scales with the surrounding text:

Small: people

Large: people

Plain text count

Returns just the number. Use for build-time fetches, shell scripts, or data export.

curl https://feedback.allaboutken.com/count/posts/20260220-feedback-buttons-cgi-pattern/
# → a number

Styled with a JS enhancement

If you're OK with a bit of JS, fetch the plain text count and inject it into a <span> you control.

... people found this useful

<span id="js-feedback-count">...</span> people found this useful
<script>
fetch('https://feedback.allaboutken.com/count/posts/20260220-feedback-buttons-cgi-pattern/')
  .then(r => r.text())
  .then(n => {
    document.getElementById('js-feedback-count').textContent = n.trim();
  });
</script>

Musing: Cloudflare Workers are the new CGI script#

The idea here keeps showing up: old patterns, new infrastructure. A Cloudflare Worker runs on someone else's server, handles one HTTP request, reads/writes a small data store, and returns a response. The only differences from 1998:

It runs on a global edge network instead of a single machine
The "flat file" is a KV store instead of /var/www/data/counter.txt
The free tier is 100,000 requests/day instead of "whatever the sysadmin allows"
You deploy via wrangler deploy instead of FTPing a Perl script to /cgi-bin/

The fundamental patterns haven't changed. The infrastructure got better. If you need interactivity on a static site, think like it's 1998 and point your links at someone else's server. That server just happens to be a globally distributed edge network now.

The Worker source code is in this site's repo — under 200 lines of JavaScript, no dependencies beyond Wrangler. The pattern works for anything: polls, reactions, RSVP counters, hit counters. Sage Weil built it in 1994. I'm just running it on better hardware.

Setting this up on your own site#

You'll need to deploy your own Worker — you can't point your feedback links at mine. The Worker hardcodes a redirect back to a single site origin, so it's one Worker per site by design.

Required: a free Cloudflare account. Suggested: a domain on Cloudflare DNS is needed for custom domains; without it, you'll use the default workers.dev URL.

1. Copy and edit the Worker. Grab my worker/ directory (three files). The comments in wrangler.toml list everything you need to change, but in short:

SITE_ORIGIN in src/index.js — your site's URL
pattern in wrangler.toml — your subdomain (e.g. feedback.yourdomain.com)
id under [[kv_namespaces]] in wrangler.toml — replace with your own namespace ID (step 3)

If your domain isn't on Cloudflare DNS, remove the [[routes]] block entirely. Your Worker will be available at feedback-worker.<your-account>.workers.dev instead.

2. Install and authenticate. Wrangler is Cloudflare's CLI for deploying and managing Workers. npm install pulls it in as the only dependency.

cd worker
npm install
npx wrangler login

wrangler login opens a browser window for Cloudflare OAuth.

3. Create a KV namespace. This is the data store for vote counts.

npx wrangler kv namespace create FEEDBACK_COUNTS

Wrangler prints a namespace ID. Paste it into wrangler.toml as the id value, replacing the one from the repo.

4. Deploy.

npx wrangler deploy

If you have a [[routes]] block with a custom domain, the deploy provisions the DNS record automatically. You should see your Worker appear in the Cloudflare dashboard under Workers & Pages. If the custom domain doesn't provision on deploy, add it manually: Workers & Pages → your worker → Settings → Domains & Routes.

5. Test it.

curl -v https://feedback.yourdomain.com/up/posts/test/

You should get a 302 redirect back to your site. If you're using the default workers.dev URL, substitute that.

If you get a "could not resolve host" error on a custom domain, DNS may still be propagating — flush your local cache (sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder on macOS) and try again.

6. Add the HTML to your templates.

<a href="https://feedback.yourdomain.com/up/posts/my-post/"
   rel="nofollow">👍 Yes, this was useful</a>
<p id="thanks" style="display:none">Thanks for the feedback!</p>

And the CSS:

#thanks:target { display: block; }

rel="nofollow" keeps crawlers from following the links. The Worker handles bot filtering, rate limiting, and the redirect.

7. CI/CD (optional). The Worker is unlikely to change often — npx wrangler deploy from your machine is fine for occasional updates. If you do want automated deploys, add a GitHub Actions workflow that runs wrangler deploy when worker/** changes. Two repository secrets needed:

CLOUDFLARE_API_TOKEN — create via Cloudflare dashboard → API Tokens → "Edit Cloudflare Workers" template
CLOUDFLARE_ACCOUNT_ID — visible on your Cloudflare dashboard overview

Free tier limits: 100,000 Worker requests/day, 1,000 KV writes/day. The writes are the constraint — 1,000 feedback clicks per day, more than enough for most sites.

What's next#

Star ratings via ISMAP. The current implementation is positive-only — a single "Yes, this was useful" button. Star ratings are the natural next step, and the approach is too good not to mention: HTML's server-side image maps. Wrap an <img> in an <a> with the ismap attribute, and clicking the image appends ?x,y coordinates to the URL. The Worker calculates which star from the X coordinate. Server-side image maps were first supported in NCSA Mosaic 1.1 (1993). They still work in every browser.

<a href="https://feedback.allaboutken.com/rate/posts/my-post/">
  <img src="/images/five-stars-empty.svg" ismap
       alt="Rate this post from 1 to 5 stars">
</a>

A popularity index from my own data. Because the Worker and KV namespace are mine, I can crawl every counter at build time and rank posts by feedback count. An Eleventy data file that calls wrangler kv key list or hits the /count/ endpoints, sorts the results, and generates a "most useful posts" page — no third-party analytics dependency, no JavaScript on the client. The data is already there; it just needs a build step.

A community web ring for Eleventy sites. The architecture generalizes. If multiple Eleventy sites each ran their own feedback Worker, a shared index could aggregate the counts — "top rated Eleventy posts this month" in the spirit of a classic web ring. Each site keeps its own data, the index just reads the public /count/ endpoints. The pattern is cooperative, not centralized: no shared database, no sign-up, just HTTP.

Behind the decisions#

Privacy by design

No consent banner needed. The Worker increments a counter in KV storage — no IP addresses stored, no User-Agent logged, no cookies set. GoatCounter's GDPR analysis applies here with even more confidence: if aggregate-only page view counting falls under legitimate interest, then an anonymous integer counter certainly does.

Rate-limiting uses a SHA-256 hash of the IP address, stored as a KV key with a 24-hour TTL. The hash is not reversible and expires automatically. No persistent identifier is created.

Keeping bots honest

The obvious concern: what stops a crawler from wandering onto feedback.allaboutken.com/up/posts/my-post/ and registering a false vote?

Five layers of defense, from prevention to cleanup:

Don't advertise the paths. Feedback links carry rel="nofollow", so search engines won't follow them from the post to the Worker.
Return nothing indexable. Vote URLs return 302 redirects — no HTML, no content for a crawler to store. Count endpoints return raw SVG or plain text, not pages.
Server-side filtering. The Worker checks User-Agent against known bot signatures and validates request headers. Simple crawlers don't send Referer or Accept-Language headers that real browsers do.
Rate limiting. One vote per IP per post per 24 hours, enforced by the Worker via KV TTL keys. A SHA-256 hash of the IP and path is stored with a 24-hour expiration — if it exists, the redirect still works but the counter doesn't increment.
Data cleanup. KV counters can be reset with wrangler kv key delete. If a bot swarm hits, zero the affected counters and move on.

An earlier design used GoatCounter page views as the counting mechanism, with a <noscript> tracking pixel as a JS-disabled fallback. That pixel is actually a bot magnet — simple crawlers load images but skip JavaScript, so the pixel counts bots while the JS-based counter filters them out. The Worker approach sidesteps this entirely: counting happens server-side, before any HTML is returned.

Standing on shoulders

I'm not the first person to think of this. Two projects proved different halves of the solution:

Andrew Walpole built a like button for his Eleventy blog using Cloudflare Workers and KV storage. He deployed it, ran it in production, and wrote about the experience. It proved the Eleventy + Workers + KV infrastructure works. But his approach uses client-side JavaScript — petite-vue renders the button, and fetch() API calls communicate with the Worker.

poll.fizzy.wtf is a Cloudflare Worker (written in Rust, MIT-licensed) that implements the redirect-count-redirect pattern with SVG result widgets. It's the 1994 web ring architecture applied to voting. No client-side JavaScript. Here's what using it looks like:

<a href="https://poll.fizzy.wtf/vote?allaboutken-feedback-post.standing-on-shoulders=yes&redirect=https://www.allaboutken.com/posts/20260220-feedback-buttons-cgi-pattern/%23standing-on-shoulders" rel="nofollow" class="kh-button kh-button--sm">👍 Yes <img src="https://poll.fizzy.wtf/count?allaboutken-feedback-post.standing-on-shoulders=yes" alt="Yes votes" style="display:inline;vertical-align:middle"></a>
<a href="https://poll.fizzy.wtf/vote?allaboutken-feedback-post.standing-on-shoulders=no&redirect=https://www.allaboutken.com/posts/20260220-feedback-buttons-cgi-pattern/%23standing-on-shoulders" rel="nofollow" class="kh-button kh-button--sm">👎 Not really <img src="https://poll.fizzy.wtf/count?allaboutken-feedback-post.standing-on-shoulders=no" alt="No votes" style="display:inline;vertical-align:middle"></a>

Try poll.fizzy.wtf live — was this section of the post clear?

👍 Yes 👎 Not really

Why not just use poll.fizzy.wtf directly? You could — and if you want the quickest path to feedback buttons, you probably should. It's MIT-licensed and ready to deploy. I built my own because I wanted a few things it doesn't do:

No cookies. poll.fizzy.wtf deduplicates votes with cookies. My Worker uses a hashed IP with a 24-hour TTL — no cookies set, ever.
Bot filtering. poll.fizzy.wtf trusts all requests. My Worker checks User-Agent, Accept-Language, and Referer headers before counting.
Single-tenant. My Worker hardcodes one site origin and rejects requests referred from anywhere else. poll.fizzy.wtf is designed as a shared service.
Data ownership. My KV namespace, my data. I can list all keys with wrangler kv key list, export counts to CSV, or wipe individual counters. With poll.fizzy.wtf the data lives on someone else's KV store.

On the flip side, poll.fizzy.wtf does something mine doesn't: arbitrary key-value voting. Its ?key=value query parameter approach lets you create any poll on the fly — multiple questions, multiple answers, no code changes. My Worker only counts one signal per post (positive feedback). That's a deliberate scope constraint for now, but if you need flexible multi-question polls, poll.fizzy.wtf has the better architecture for it.

If those tradeoffs don't matter to you, poll.fizzy.wtf is a perfectly good choice and saves you the setup.

Approaches I considered but didn't choose

The Worker wasn't the first idea. The design process explored five approaches. The ones I passed on are interesting because they reveal the design space.

GoatCounter page-view counting. The most obvious approach: feedback links go to static thank-you pages generated by Eleventy, and GoatCounter (already on the site) counts the page view. The URL path encodes the vote — /feedback/up/posts/my-post/ is a thumbs-up. Zero new dependencies. But it navigates the reader away from the post, the data mixes with analytics noise, and there's no way to show counts without a build-time API call. The Worker wins on UX, data quality, and bot resistance.

CSS :target with a tracking pixel. The most technically creative approach. Anchor links trigger :target, which reveals a hidden <span> whose background-image points to a GoatCounter counting pixel. The browser loads the image when the element becomes visible — CSS as an analytics transport. The problem: browsers may skip background-image loads on previously-hidden elements, especially with display: none to display: block transitions. It's fragile to test, unreliable across browsers, and raises accessibility concerns since screen readers may not announce the state change. Fascinating, but too brittle for production.

Mastodon retoots and favourites. The Eleventy community has a well-established pattern here: publish a post, toot the link, then pull Mastodon interactions back into the site via the Mastodon API or Webmentions with Bridgy. Boosts and favourites become your feedback signal; replies become comments. Max Böck, Sia Karamalegos, and others have written detailed implementations. It's a real solution and I may add it later as a complementary signal. But it's not feedback on the post — it's feedback on the toot. Readers who don't use Mastodon can't participate, and the signal measures social reach more than content usefulness. The Worker captures a direct "was this useful?" from any reader, regardless of what social networks they use.

External form services. Formspree, Basin, Google Forms — a <form method="POST"> pointing at a third-party service. True form submission, data stored somewhere you control (sort of). But it's a new SaaS dependency, the free tiers have submission limits, it redirects to a third-party confirmation page, and it runs against this site's self-hosted philosophy. Cloudflare Workers is technically also "someone else's server," but the code is ours, the data is ours, and the free tier is generous enough to be effectively permanent for a personal blog.

The feedback buttons are live on this post — scroll down and try them. If you set this up on your own site, I'd genuinely like to hear how it goes.

Further reading on the web patterns mentioned here:

What Were CGI Scripts? — Rick Carlino's primer on how CGI worked and why it mattered
Webring History: Social Media Before Social Media — Tedium on the rise and fall of web rings
What Were Server-Side Image Maps? — how ISMAP worked in the Mosaic era
Cameron's World — a collage of GeoCities pages, the ecosystem where these patterns thrived
RFC 3875: The Common Gateway Interface (CGI) v1.1 — the spec behind everything on this page

Related posts:

Exposing HTML: The No-JS nudist CSS toggle — same "no JavaScript required" philosophy
URLs are the state management you should use — the #thanks fragment is URL-as-state
Your browser utility wants to be a floating palette — old UI patterns, new infrastructure
Measuring success beyond the page view — why "Was this useful?" matters more than page views
How to measure impact when analytics lie — privacy-respecting signals over surveillance

PDF-A-go-slim: a browser-based PDF optimizer

2026-02-16T00:00:00.000Z

PDF bloat is everywhere. A clean 32 KB PDF was edited in Adobe Illustrator for a minor layout tweak. After saving it was 198 KB — a 6x increase for a cosmetic change.

A simple deletion of an element resulted in the new embedding of full TrueType copies of Helvetica and Courier, layers of application metadata, and duplicated font references in multiple formats.

Sure, editing in a different way might not have done this — but how to ensure PDFs were adequately de-bloated?

So I built PDF-A-go-slim — an open-source optimizer that runs entirely in the browser, where files never leave your machine.

tl;dr

A clean 32 KB PDF ballooned to 198 KB after one Illustrator edit

Tried Ghostscript, qpdf, iLovePDF, Smallpdf — none covered everything in-browser

8 optimization passes, three presets (Lossless, Web, Print)

Auto-detects PDF/A, PDF/UA, and tagged PDFs; preserves conformance

All processing in a Web Worker — files stay private

Why this exists#

The project grew out of PDF-A-go-go, an embeddable PDF viewer for the web. While building a small showcase PDF for its demo page, I hit a problem that turns out to be universal: creative tools silently bloat PDFs.

All desktop PDF editors and makers seem to embed unnecessary fonts, duplicate objects, and inject application-private metadata. A simple "Save As PDF" routinely doubles or triples the file size.

This makes them more versatile, but less ideal when you want to optimize.

I tried the obvious tools:

Ghostscript got it to 96 KB but couldn't strip the redundant standard font embeddings
qpdf barely moved the needle (194 KB) — it optimizes structure but doesn't touch content
iLovePDF got it to 62 KB — decent, but requires uploading to a third-party server
Smallpdf — paywalled before you can even try

What my tool does#

PDF-A-go-slim runs eight optimization passes in sequence:

Stream recompression — decompress and recompress all streams with optimal Flate settings
Image recompression — re-encode raster images at user-chosen quality (lossy, opt-in)
Standard font unembedding — remove embedded copies of the 14 base PDF fonts that every reader already includes
Font subsetting — subset embedded fonts to only the glyphs actually used in the document
Object deduplication — hash-based deduplication of identical streams
Font deduplication — consolidate duplicate embedded fonts
Metadata stripping — remove XMP, Illustrator, and Photoshop application-private bloat
Unreferenced object removal — delete objects not reachable from the document catalog

Three presets control how aggressive the optimization gets:

Lossless (default) — visual output is identical to the original
Web — lossy, 75% JPEG quality, 150 DPI max — optimized for screen viewing
Print — lossy, 92% JPEG quality, 300 DPI max — high quality for physical output

An object inspector shows a before/after breakdown of every PDF object by category, so you can see exactly what changed and why.

The object inspector breaks down savings by category -- this 7.9 MB presentation dropped to 1.7 MB after the eight optimization passes.

Privacy and accessibility#

Files never leave the browser. All processing runs in a Web Worker off the main thread. No accounts, no uploads, no file size limits beyond available RAM.

Fast, reliable and convenient — everything that makes a tool useful.

It auto-detects PDF/A conformance, PDF/UA, and tagged PDFs. When it finds them, it disables font unembedding and XMP stripping to preserve what conformance requires. Structure trees, ToUnicode CMaps, and language tags are carried through. 57 tests verify compression and accessibility preservation across a range of test fixtures.

A dedicated Accessibility palette shows what the optimizer finds: a pass/fail checklist for tagged structure, document title, display title (different than the former), language declaration, and conformance standards. The document title, display title, and marked-status checks were inspired by PDFcheck by Jason Morris. Three lightweight audits check ToUnicode coverage (can screen readers extract text?), image alt text in the structure tree, and structure tree depth. The palette also links to external validators — veraPDF, PAC, PDFcheck — for deeper conformance testing.

The Accessibility palette flags missing traits and runs lightweight audits -- this PDF has no tagged structure, no language declaration, and poor ToUnicode coverage.

I haven't fully vetted every edge case, though. If you're working with accessibility-critical documents, test the output. Bug reports in this area are especially welcome.

How it's built#

The core engine uses four open-source libraries:

pdf-lib — low-level PDF object access (MIT)
fflate — pure-JS zlib compression (MIT)
jpeg-js — pure-JS JPEG encoder (BSD 3-Clause)
harfbuzzjs — WASM font subsetting, lazy-loaded (MIT / Apache 2.0)

The optimization engine runs in a Web Worker so the UI stays responsive during processing. The WASM font subsetter loads as a separate chunk only when font subsetting is needed.

Why it looks like Mac OS 8!?#

The UI borrows its visual structure from Mac OS 8 — floating palettes, striped title bars, WindowShade collapse, warm cream surfaces. It's a design experiment: do late-90s desktop paradigms (persistent tool palettes, dense layouts, always-visible information) suit single-purpose browser utilities better than modern minimal convention?

I wrote a companion post on the design rationale if you want the full argument. Short version: browser tools are used in focused bursts, not browsed casually — the same use pattern floating palettes were designed for. The retro is a thin styling layer; the tool works without it.

But this was a side project and I felt like I wanted a bit of creativity on the side of the side.

Try it, break it, improve it#

PDF-A-go-slim is MIT licensed and on GitHub. If you hit a compression edge case, an accessibility concern, or just have opinions on the floating palettes — I'd like to hear about it.

The Preview palette uses PDF-A-go-go for before/after PDF comparison, so the two projects keep feeding each other. If you've been following the PDF-A-go-go and EmbedPDF posts, this is where the PDF tooling thread goes next. Full credits for inspirations and tools that informed the project are in the README.

Your browser utility wants to be a floating palette

2026-02-16T00:00:00.000Z

Modern browser utilities default to progressive disclosure and minimal surfaces. Cards, centered content, generous whitespace, hidden settings. These patterns work for browsing — for exploring, scrolling, discovering. But single-purpose tools used in focused bursts may work better with the opposite: dense layouts, always-visible information, persistent tool palettes. I built PDF-A-go-slim to try it out.

tl;dr

Browser utilities are used in focused bursts, not browsed casually

Mac OS 8 floating palettes were designed for exactly this use pattern

PostHog and Poolsuite show retro desktop metaphors work for developer audiences

"Structure over skin" — borrow the layout grammar, not pixel art

The hypothesis#

Most web tools today follow the same playbook: a clean hero area, a single primary action, settings tucked behind a gear icon, results replacing the input. This works when users are exploring. It falls apart when they're doing one job.

When someone drops a PDF on an optimizer, they want to see settings, progress, results, and file details simultaneously. They're not exploring. They're not browsing. They opened a tab, did one thing, and closed it. The whole interaction lasts maybe 30 seconds.

Progressive disclosure assumes the user needs guidance through a sequence. Utility users already know what they want. They need information density, not a funnel. Everything on screen at once — the same way a carpenter wants all their tools on the bench, not locked in drawers.

Floating windows were designed for this#

The Apple Macintosh Human Interface Guidelines (1995) — the "Platinum" HIG — dedicated a section to floating windows (Chapter 5, pp. 105-106). These were specified for tool palettes: thinner chrome than document windows, always visible alongside the main content, brought to front on click but never stealing focus.

The intent was explicit: tool settings should stay visible while you work on the document. Color picker, brush options, layers panel — all on screen at once, no tabs or menus required.

PDF-A-go-slim borrows this directly. A main document window with a persistent drop zone, and five floating draggable palettes: Settings, Results, Inspector, Preview, and Accessibility. Each palette uses WindowShade — double-click the title bar to collapse it to just a strip. Arrange your workspace once and everything stays put.

This isn't nostalgia. The HIG solved a real interaction problem: how to keep secondary controls visible during a focused task. That problem didn't go away when we moved to the browser.

PostHog validated the direction, Poolsuite showed the path#

In 2025, PostHog — a developer analytics company — redesigned their entire marketing site as a Windows-style desktop OS in the browser. Draggable windows, a start menu, a screensaver, a functional text editor, games in the trash folder. The project was built by @ninepixelgrid over six months.

A serious developer tools company independently chose the retro desktop metaphor and committed to it fully. That's worth paying attention to. The Hacker News discussion was largely positive — developers liked the personality and craft.

Poolsuite showed the complementary lesson. Retro charm doesn't require heavy 3D bevels and pixel-perfect OS recreation. Thin borders, warm cream colors, and minimal chrome. It feels vintage without feeling heavy. That shaped PDF-A-go-slim's initial direction.

Structure over skin#

Three design principles guide the retro direction:

1. Borrow the layout grammar, not pixel art. The Mac OS 8 reference is here for its spatial model — floating palettes, persistent tool windows, information always on screen. No pixel fonts, no full OS recreation.

2. Visual elements provide function. Striped title bars distinguish palettes from the document window. Sunken panels mark input areas. A status bar at the bottom shows what's happening. These are borrowed because they work, not because they look retro. Typically even the playful extras give functional boost.

3. Modern underneath. It uses system fonts, CSS custom properties, semantic HTML, and responsive layout. The aesthetic is a styling layer. The app works without it.

Concrete HIG patterns applied: WindowShade for palette collapse. Upfront information display (inspector categories expand by default, stats always visible). Dense property-sheet layouts with compact controls. Rich status bars showing pass labels and file counters during processing. A persistent drop zone that stays visible — just dimmed — during optimization.

The result is a zero-scroll, single-page environment. Five palettes, an object inspector, an accessibility audit, a live PDF preview, optimization controls, theme switching, and desktop icons for sample PDFs — all visible at once without scrolling. A conventional stacked layout would need a long page and constant back-and-forth to show the same information. Floating palettes give you the space for both serious functionality and playful extras without either one crowding the other out.

On mobile, the palettes stack vertically. Still collapsible, not draggable. It works because the underlying HTML is semantic — the floating palette positioning is just CSS.

What not to borrow#

The HN criticism of PostHog provides useful guardrails:

Don't override native browser behavior. PostHog's custom right-click menu broke the browser context menu. PDF-A-go-slim leaves native interactions alone.
Keyboard-accessible controls. All buttons, tabs, and interactive elements are reachable by keyboard. Drag is a convenience, not a requirement.
Small bundle. PostHog's implementation caused high CPU during drags and slow mobile loads. PDF-A-go-slim uses vanilla JS for dragging; the WASM font subsetter lazy-loads only when needed.
Semantic HTML underneath. Screen readers should see a form with fieldsets, not a desktop operating system.

Remove the CSS and you still have a functional, accessible tool. The retro is a layer on top, not load-bearing.

Since launch, the retro direction keeps pulling in more: a Mac OS 8-style menu bar, classic system sounds (Sosumi, Quack, Wild Eep — the originals, curated by Steven Jay Cohen), a Stickies palette, and a CRT scanline overlay. Each one started as a joke and turned out to make the tool more engaging to use.

An experiment, not a manifesto#

This is one tool testing one hypothesis: that dense, always-visible layouts suit focused utility work better than progressive disclosure. The density feels right for something you open, use for 30 seconds, and close. Whether it scales to more complex tools is a different question. I don't have metrics to validate any of this — it's a side project, and honestly, I also just wanted to have some fun building something with personality.

If you want to try the tool, go have fun.

In hindsight, I should have used an existing browser window manager instead of rolling my own — the same way real desktop apps lean on OS-level window management rather than reimplementing it. That would push the "web as OS" idea from aesthetic into architecture.

You can read about how it approaches PDF stripping in the companion introduction post. Full credits for design inspirations, sound sources, and tools that informed the project are in the README.

The practitioner's guide to planning digital transformation (Parts 3-4)

2026-02-05T00:00:00.000Z

You've been tasked with "digital transformation." Senior leadership wants it. The budget committee needs an ROI. The technical team wants requirements. And you're the one who has to make sense of it all — whether your title is business analyst, project manager, product owner, or just "the person who figures things out." You're translating between stakeholders, documenting requirements, and turning vague goals into actionable plans.

This is Parts 3-4 of my digital transformation series. Start with Parts 1-2: Digital transformation for complex organizations for the strategic framework.

Most digital transformation projects fail — McKinsey puts the success rate at only 30% — usually not because of bad technology, but because of poor requirements, unclear success criteria, and no baseline assessment. The vague becomes vaguer. Budgets balloon. Stakeholders disengage.

This guide covers the mechanics that prevent that: assessment, requirements, business case development, resource planning, and risk management. It's the tactical companion to strategic frameworks — the part that answers "how do we actually plan and execute this?"

tl;dr#

Part 3: Assess & Define — Baseline your digital maturity, elicit requirements from stakeholders, and set measurable success criteria.

Part 4: Plan & Execute — Build the business case around avoided costs, secure dedicated capacity, and manage the risks that actually derail initiatives.

Part 3: Assess & Define#

Before you can plan transformation, you need to know where you are, what stakeholders actually need, and what success looks like. This section covers assessment, requirements, and success criteria.

1. Digital maturity assessment: Know where you are#

You can't build a roadmap without a baseline. Yet most transformation initiatives skip assessment and jump straight to solutions. This creates two problems: you're solving for unknown gaps, and you have no way to measure improvement.

Assessment prevents "solutions looking for problems" and creates shared understanding of what actually needs to change.

Assessment dimensions#

I use a lightweight framework based on industry models (BCG, Deloitte, Google/BCG) adapted for content-heavy organizations. Five dimensions, each scored Yes/Partial/No:

Content & Publishing

Do you measure task completion (not just pageviews)?
Is content structured with semantic metadata?
Can editors articulate audience tasks for their content?

Measurement & Analytics

Do you track beyond pageviews (findability, downstream impact)?
Are metrics tied to business objectives?
Can you demonstrate content ROI?

Technology & Infrastructure

Does your content and data platform — whether a CMS like Drupal, a custom backend, or a database-driven system — support disciplined content (clear purpose, measurable goals)?
Do you have machine-readable taxonomies (structured labels systems can process)?
Can you emit JSON-LD or schema markup?

Governance & Process

Do you have documented content workflows?
Is there clear accountability for content outcomes?
Are there incentives for adopting new practices?

People & Skills

Do editors understand user-centered content principles?
Do developers know semantic HTML and accessibility?
Does senior leadership understand digital metrics beyond traffic?

Scoring#

15+ Yes: Mature — focus on optimization and innovation
8-14 Yes: Emerging — establish infrastructure systematically
0-7 Yes: Nascent — start with foundational changes

This isn't about judgment. A nascent organization isn't a failing — it's just at a different starting point. The assessment tells you where to focus effort.

How to conduct the assessment#

Method 1: Stakeholder workshop (fastest)

Gather cross-functional group (senior leaders, technologists, editors)
Walk through each question together
Discuss and score collaboratively
Captures different perspectives but can be political

Method 2: Individual interviews (most thorough)

Interview 10-15 people across roles
Score independently
Analyze gaps between groups (senior leaders say "Yes," editors say "No")
Takes longer but reveals organizational misalignment

Use the scores as conversation starters, not final verdicts. If senior leadership thinks measurement is strong but editors can't access analytics, that's valuable signal.

2. Requirements elicitation: What you need from stakeholders#

Digital transformation means different things to different stakeholders. Senior leadership wants strategic outcomes. Technologists want specifications. Editors want their jobs to be easier. Your job is to translate between them and document requirements that all three groups can validate.

This isn't about writing a 100-page requirements document. It's about using structured techniques to surface what each group actually needs — then documenting it in a way that guides decisions.

The three stakeholder groups#

Senior leadership wants clarity, predictability, accountability. They need strategic aims converted into testable digital outputs — things they can report on, defend, and explain to boards.

Technologists want feasibility, requirements, constraints. They need technical jargon translated into choices and trade-offs that non-technical people can actually decide on.

Editors (content creators, publishers) want simplicity, relevance, speed. Someone needs to advocate for them — even when no one else in the room is.

Elicitation techniques for each group#

For Senior Leadership: Structured interviews

Senior leaders are time-constrained. Prepare focused questions that extract strategic intent, not just aspirations.

Sample questions:

"What does 'digital transformation' success look like in 12 months? What would you report to the board?"
"What metrics do you currently track? How could digital work support those?"
"What content or digital failures have you experienced? What caused them?"
"How much investment can you justify without demonstrated ROI?"

The goal is to translate "we need better digital presence" into "we need to increase discoverability for policy briefs by 30% as measured by government domain referrals."

For Technologists: Document analysis + observation

Don't just ask developers what's possible — observe what's actually happening.

Review:

Platform documentation (what features exist vs. what's used)
Current architecture diagrams
Analytics setup (what's being tracked)
Integration points (what systems talk to each other)

Ask:

"What's technically feasible with our current stack?"
"What would require platform changes?"
"Where do you spend most time on manual work?"
"What breaks most often?"

This surfaces hidden constraints. The platform might technically support structured metadata, but if the API is so slow that editors won't use it, that's a real constraint.

For Editors: Observation + focus groups

Editors will tell you what they think you want to hear. Watch them work instead.

Observation technique:

Sit with an editor for 2 hours while they create content
Don't interrupt — just note where they struggle
Ask "why did you do that?" when they use workarounds
Document manual processes that should be automated

Focus group questions:

"What takes the most time in your workflow?"
"What questions can't you answer?" (e.g., "Is anyone reading this?")
"What would make your job easier?"
"When do you ignore the official process? Why?"

This reveals the gap between documented workflow and actual practice. If editors copy-paste content into Word to check formatting, your platform's preview isn't working.

Documenting requirements#

Use standard BA categories: functional, non-functional, constraints.

Sample functional requirements (what the system must do)

FR-001: System shall allow editors to tag content with audience tasks
FR-002: System shall measure task completion rates per page
FR-003: System shall generate semantic metadata automatically from editor inputs

Sample non-functional requirements (quality attributes)

NFR-001: Task completion tracking shall not slow page load by >100ms
NFR-002: Editor training shall take <2 days per person
NFR-003: Metadata system shall integrate with existing platform without data migration

Sample constraints

Cannot replace current platform (must work within existing systems)
Must comply with accessibility standards (WCAG 2.1 AA)
Must not disrupt current publishing workflows during pilot phase
Budget cannot exceed $X for first 6 months

Prioritize requirements using MoSCoW (Must/Should/Could/Won't):

Must have: Task completion tracking, semantic HTML
Should have: Automated metadata generation, editor dashboards
Could have: AI-powered taxonomy suggestions
Won't have (this phase): Full content inventory migration, new platform

3. Success criteria: Specific, measurable targets#

Vague goals produce vague results. "Improve digital presence" isn't measurable. "Increase task completion rate by 25% on top-traffic pages within 6 months" is.

Success criteria should be specific enough that anyone can verify whether you achieved them. Use the OKR framework: Objectives (directional goals) supported by Key Results (measurable outcomes).

Framework: OKRs for digital transformation#

Objective 1: Make content measurably useful

KR1: 80% of editors can articulate the audience task for their content (measured via spot checks)
KR2: Task completion tracking implemented on 100% of top-traffic pages
KR3: Measured task completion rate improves 25% from baseline

Objective 2: Establish AI-ready content infrastructure

KR1: 100% of new content uses semantic HTML (validated via automated checks)
KR2: 50% of existing high-value content has JSON-LD markup
KR3: Citation/reference mentions in AI-generated responses increase 2x from baseline

Objective 3: Demonstrate ROI

KR1: Editorial efficiency improves by 15 hours/week (quantified time savings)
KR2: Content discoverability improves 20% (measured via organic search increase from target audiences)
KR3: Avoided cost: Prevent $100K+ in low-performing content investment through early measurement

Phase-based acceptance criteria#

Break objectives into phases with clear gates. Each phase ends with GO/NO-GO decision.

Pilot Phase (Months 1-3)

✅ 5 pages have audience task documentation (what task + how to measure)
✅ Task completion tracking implemented on pilot pages
✅ 10 editors trained and using framework
✅ Baseline metrics captured for all pilot pages
✅ GO criteria: Measurable improvement in 2+ pilot metrics; editor satisfaction >7/10

Rollout Phase (Months 4-9)

✅ 50% of content inventory assessed with audience task framework
✅ Semantic metadata on 100 high-priority pages
✅ All editors trained (200+)
✅ Documented 10% improvement in key metrics vs. baseline
✅ GO criteria: Adoption rate >80%; metrics trending positive; sponsor approves scale

Optimization Phase (Months 10-12)

✅ Full measurement → improvement cycle operational
✅ AI-generated responses cite content 2x baseline
✅ ROI case study documented with quantified benefits
✅ Governance model established and operating independently

The GO/NO-GO gates are critical. If the pilot doesn't demonstrate improvement, you iterate or cancel — you don't keep something that doesn't work.

This phase-gate approach builds in permission to learn and adjust. You're not aiming for the complete solution upfront — you're shipping something focused and high-quality, gathering feedback, and letting audience demand guide what comes next. Teams need to feel safe surfacing problems early.

Celebrate what you learned, not just what you shipped.

Part 4: Plan & Execute#

You've assessed where you are, gathered requirements, and defined success criteria. Now you need to secure budget, plan resources, and manage risks.

Build the business case#

Finance won't approve "better digital presence." They'll approve "invest $X to save $Y in editorial efficiency and prevent $Z in failed content spend."

Frame benefits as avoided costs, not speculative gains. Senior leadership responds to "prevent $200K in failed content investment" more than "possibly gain traffic." The former is concrete; the latter is speculative.

The benefit categories that matter most:

Time savings: Editorial efficiency improvements (quantify with time studies)
Risk reduction: Catching underperforming content in pilot phase instead of after full investment
Reach improvement: Increased discoverability — directionally significant even when hard to monetize

The cost categories to account for:

Labor: Staff time for training, implementation, ongoing work (often underestimated)
Technology: Platform upgrades, tools, integrations
Opportunity cost: What else could the team do with this time?

Most transformation initiatives underestimate labor costs and overestimate technology costs. The real investment is people's time.

Resource realities#

"We'll do this with existing staff in their spare time" rarely works. Transformation requires dedicated capacity — not full-time necessarily, but protected time.

Key roles to fill (can be fractional):

Someone who owns the initiative and manages stakeholders
Someone who understands content strategy and can train editors
Someone who can implement technical standards (semantic HTML, structured data)
Someone tracking requirements and progress (that's you)

What derails initiatives#

The gap that kills most initiatives isn't technical. It's change management. Editors resist workflow changes without visible incentives and demonstrated time savings.

Three risks appear in nearly every digital transformation:

Leadership attention fades. Secure 12-month commitment upfront. Show quick wins by month 3. Brief leadership monthly with metrics, not just activity.

Editors resist workflow changes. This is the highest-probability risk. Mitigate by involving editors in framework design, tracking time savings during pilot, and making adoption visible and celebrated.

Scope creeps beyond budget. Lock scope for pilot phase. Use phase gates — require a new business case for scope additions rather than absorbing them.

The critical path#

Some work can happen in parallel. Some cannot. The sequence that cannot slip:

Stakeholder alignment → enables requirements elicitation
Business case approval → enables team formation
Pilot validation → enables rollout approval

Everything else can flex. Training and technical infrastructure can run in parallel. Documentation and governance development can overlap.

Build 20% buffer into timelines. Identify dependencies early. The critical path runs through validation gates, not deliverable dates.

Putting it together#

This guide covers the mechanics that strategic frameworks often skip: how to assess, how to elicit requirements, how to quantify ROI, how to plan resources, and how to manage risks.

The strategic framework tells you what to establish (stakeholder alignment, audience task frameworks, measurement systems, AI-ready infrastructure). This guide tells you how to plan and execute it.

Key success factors:

Start with baseline assessment — don't skip this
Build the business case with quantified benefits (time savings + avoided costs)
Use phase gates to validate before scaling
Involve stakeholders early and often (especially editors)
Document everything (requirements, decisions, learnings)

Common pitfalls:

Starting implementation without requirements
Building business case without baseline metrics (makes ROI impossible to prove)
Underestimating change management (editors resist without incentives)
Skipping pilot validation (rolling out something that doesn't work)
Treating this as pure technology project (it's mostly about people and process)

Digital transformation is as much about requirements discipline and stakeholder management as it is about technology. The skills that matter here — elicitation, documentation, risk management, change impact analysis — are what make the vague concrete and the aspirational measurable.

If you're planning a digital transformation initiative and need help with requirements, business case development, or implementation planning, I'd love to hear about your challenges.

Digital transformation for complex organizations (Parts 1-2)

2026-01-30T00:00:00.000Z

Digital transformation isn't blocked by technology. It needs senior leadership, technologists, and your audience to understand each other well enough to move forward.

The symptoms of that disconnect are everywhere. I've seen 200-page PDF reports published with zero tracking or machine readability considerations. I've seen senior leaders ask "Can AI tell us?" believing AI is a magic spice to make sense of content that humans already struggle to find. I've been in rooms where technologists explain what the content and data platform can do — whether that's Drupal, a custom backend, or a database-driven system — and communicators explain what the content should do, and neither realizes they're talking past each other.

This post is a sketch of what I've learned about modernizing digital work. It's organized in two parts: the groundwork (what transformation actually requires) and the process (what you need to sustain it).

tl;dr#

Part 1: The Groundwork — Translation between senior leadership, technologists, and your audience. Use the Content–Action Model to align everyone around audience tasks and measurable outcomes.

Part 2: The Process — Establish a digital value loop: disciplined content → discoverability → actions → measurement → improvement. Measure task completion (not pageviews), make content AI-ready, and use small wins to build momentum.

Part 1: The Groundwork#

Governance can be heavy, teams are often split, incentives vary wildly, and "digital transformation" can mean everything and nothing. This section covers the groundwork that makes progress possible.

1. The bridge-builder model#

The core work is translation — between senior leadership, technologists, and your audience.

Senior leadership wants clarity, predictability, accountability. They need strategic aims converted into testable digital outputs — things they can report on, defend, and explain to boards.

Technologists want feasibility, requirements, constraints. They need technical jargon translated into choices and trade-offs that non-technical people can actually decide on.

Your audience wants simplicity, relevance, speed. Someone needs to advocate for them — even when no one else in the room is.

In practice, most digital transformation work is making these three groups talk to each other:

Converting vague "we need better digital presence" into specific deliverables
Turning "can we use AI?" into "here are three options with trade-offs"
Building lightweight governance that nudges behavior without paralyzing teams

When stakeholders have competing priorities — and they will — staying focused on goals and measurement creates common ground. You iterate, you measure, you argue with evidence instead of opinions. Compromise happens, but it happens around facts.

This is the part no AI can automate — and probably the most valuable skill in organizational digital work. Whether your title is business analyst, project manager, product owner, or something else entirely, this translation work is what makes transformation possible.

2. Information for success at scale#

The mistake many organizations make: they think digital is about publishing. In reality, digital is about helping someone do something.

The Content–Action Model asks two questions of every page, product, and asset:

What is this content helping someone do?
How would we know if they did it?

This sounds simple. It isn't.

Most organizational content exists because someone decided to publish it, not because anyone identified an audience need it was meant to serve.

When you apply this model consistently, several things happen:

Sites get smaller. Content that can't answer these questions gets archived or merged.
Duplication reduces. You can't justify three pages about the same topic serving the same action.
Publishing roles clarify. Editors become responsible for specific audience outcomes, not just "their content."
SEO improves. Search engines reward content that demonstrably serves audience intent.
Analytics become meaningful. You're measuring actions, not just visits.

I've helped this model scale to organizations with dozens of editors at institutions like EMBL-EBI — it works because it gives everyone a shared framework for evaluating content decisions, regardless of their specific domain expertise.

Part 2: The Process#

The groundwork in Part 1 is about human alignment. But alignment alone doesn't produce sustainable change — you also need systems that operationalize the vision. This section covers what to foster and institutionalize.

3. The digital value loop#

The future for complex organizations isn't "make more content." It's building a self-reinforcing loop:

Disciplined content → enables
Better discoverability (web + search + AI) → drives
Clear audience actions → generates
Measurable impact → informs
Continuous improvement → produces better disciplined content

Each step feeds the next. Organizations that establish this loop — even imperfectly — outpace those still treating digital as a simple output function to mirror PDF documents.

The following sections unpack each element of the loop: what to measure, what to put in place, and how to implement while staying on track.

4. Measuring what matters#

The default metrics in many public-sector or research organizations aren't actually meaning.

Pageviews, impressions, PDF downloads, newsletter "reach" — none of these answer the question: did anyone find what they needed?

Better measurement focuses on:

Findability: Are people reaching this content through the pathways we expect? Internal referrals, search queries, and navigational success tell you whether your information architecture is working.

Task completion: Did they take the action the content was designed for? This could be downloading a resource, submitting a form, or clicking through to a deeper page.

Quality of engagement: Not just time-on-page, but scroll depth, interaction with expandable content, return visits.

Downstream impact: Citations, reuse, machine readability. Does your content propagate through the systems that matter to your mission?

For content that feeds AI systems, "computed reach" — how often your content appears in AI-generated responses — is becoming an important signal. Current approaches: manually query AI systems for your key topics, use emerging monitoring tools that track AI citations, and watch for referral traffic from AI-assisted search. The measurement is directional rather than precise, but ignoring it means flying blind as AI intermediates more discovery.

This is where digital work is heading: measuring how content flows, not just how it sits.

5. AI-ready content infrastructure#

Most organizations still publish content like it's 2008. A page gets written, formatted, maybe tagged with a category, and shipped.

The assumption is that humans will find it through search or navigation.

That assumption is breaking down. AI systems now intermediate much of how people discover and consume information. If your content isn't structured for machine consumption, it's increasingly invisible.

What AI-ready means in practice:

Content is structured, not just visually formatted. Headings, lists, and semantic HTML aren't decoration — they're data.
Content is accessible. Semantic HTML, ARIA labels, and proper heading hierarchy serve both assistive technologies and AI systems. What helps screen readers helps machine learning models.
Metadata is semantic, not decorative. Tags and categories should map to controlled vocabularies, not ad-hoc labels.
Taxonomies are machine-readable. SKOS-aligned concept schemes let AI systems understand relationships between topics.
Pages emit structured data. JSON-LD schema markup tells search engines and AI systems what your content is, not just what it says.
Assets generate machine-actionable outputs. PDFs should have metadata. Data should be queryable. Reports should have structured abstracts.

This isn't about being innovative. It's about being discoverable in a world where fewer humans reach your website directly.

AI systems read your content even when your audience doesn't. Give them something meaningful to read.

6. Making it work: Implementation patterns#

The loop from section 3 is the goal. Here's what I've seen work — and fail — when trying to establish it across complex organizations like UNDRR and EMBL.

Note: I may expand these patterns into detailed guides in future posts — each could become its own case study with templates and examples.

What works#

Replace a "traditional content output" mindset with audience+task mindset. The shift from "we need to publish this" to "we need to help our audience do X" changes every content decision downstream.

Establish centralized but flexible governance. Design systems that offer multiple integration paths — full adoption, partial adoption, visual-only — spread faster than mandated standards.

Create KPIs that senior leadership can relate to. Connect technical metrics to organizational outcomes. Page speed affects reach in bandwidth-constrained regions. Structured metadata improves citation rates.

Introduce data literacy gently, but consistently. Not everyone needs to read dashboards, but everyone should understand what "this content achieved X" means and trust the measurement.

Use small wins to prove value. Structured metadata for one content type. Performance improvements on one high-traffic page. These create appetite for larger transformation.

Avoid totalism — iterate instead. You don't need to solve everything at once. Ship something focused and high-quality that doesn't do everything, gather feedback, and let audience demand guide what comes next. This builds momentum and proves value faster than waiting for the complete solution.

Treat AI as an amplifier, not a replacement. AI tools can speed up content production, improve discoverability, and automate taxonomy tagging. They can't replace human judgment about what matters to your audience.

Examples of what to avoid#

Big-bang rebuilds without political buy-in. Platforms live or die on adoption. A technically perfect system that teams won't use is worthless.

Strategy divorced from technical feasibility. The communications team's vision needs to survive contact with your platform's actual capabilities.

Building platforms without a metadata plan. If you don't design for disciplined content from the start, you'll never retrofit it effectively.

Publishing PDFs with zero tracking. If you can't measure whether anyone read it, you can't justify making more of them.

Assuming editors will change workflows without incentives. People do what's easy and rewarded. Make the right behavior both.

Underestimating cost and timeline realities. Transformation always costs more and takes longer than initial estimates. Build the business case around small, demonstrable wins that justify continued investment — not aspirational end-states that may never materialize. (I'll cover business case development, ROI frameworks, and resource planning in a follow-up post.)

Everything here is about making progress in environments where change is slow.

Putting it together#

This framework isn't theoretical. I've used these patterns at UNDRR, EMBL, and across public-sector digital teams.

Part 1 — the groundwork — is about translation: making senior leadership, technologists, and your audience understand each other well enough to move forward. It's the human skill that no platform purchase or consultancy can replace.

Part 2 — the process — is what makes that understanding operational: measurement systems, disciplined content, AI-ready architecture, and implementation patterns that survive contact with organizational reality.

Part 3 & 4 — the execution — covers the tactical side: how to assess where you are, build the business case, plan resources, and manage risks. That post is coming in a week or two.

Neither part works alone. Brilliant strategy without process produces reports that gather dust. Perfect process without alignment produces platforms that no one adopts.

Digital transformation in complex organizations isn't about buying the right technology. It's about building shared language, lightweight governance, and measurement that connects technical work to organizational outcomes — and then building systems that sustain it.

If you're working through similar challenges — or if you've found different approaches that work — I'd love to hear about it.

VR Productivity finally almost surpasses physical displays

2026-01-24T00:00:00.000Z

I've wanted the same thing from VR for years: virtual big screens strapped to my head. Not gaming, not social spaces — just an excess of screen real estate and the freedom to sit however I want without fussing with monitor height. After trying various headsets and apps across Windows, Linux, and now Mac, I finally have a setup that works well enough to use daily.

tl;dr#

Quest 3 + Immersed on Mac works better than other combinations I've tried

Resolution and settings that give the best productivity experience

The unexpected ergonomic freedom of a screen that follows your posture

Trade-offs and quirks, plus what's still missing for that serene workspace feeling

A quest for VR productivity#

For years I've eyed options. The Immersed Visor looked promising but still hasn't shipped. I picked up Rokid AR glasses — lightweight, unobtrusive — but the display just isn't big enough or sharp enough for a full workspace, or to qualify my "big screen strapped to face" requirement. It's fine for a movie on a plane, not for staring at code all day.

In early 2025, Quest 3 seemed like the best hope, but the experience was too temperamental on Windows and Linux — apps would crash, connections would drop, and I'd spend more time troubleshooting than working.

When I switched to back to the Mac, something clicked. Immersed was more stable. Still not perfect, but stable enough that I could actually get work done instead of fighting with the software.

What finally worked#

Here's the setup that got me to 90% happy:

Hardware:

Meta Quest 3
Bobo VR S3 Pro head strap (in "halo" mode)
Single USB-C cable from Mac to headset (power + data)

Software:

Immersed on macOS 15.5
Single virtual display: 5120 × 1440 pixels
Black desktop background and black Immersed environment

The single-cable setup is key. With the Quest 3, one USB-C cable handles both power and data. Compare that to Vision Pro, where you'd need the data cable plus a separate battery pack cable dangling around.

One underrated Immersed advantage: it connects directly to your Mac over the local network without tunneling through an external server. Most VR desktop apps require a connection to their cloud service to broker the local link, which gets blocked on restrictive corporate or institutional networks. Immersed just works on the local network, making it one of the few options viable in those environments.

The display configuration#

I settled on 5120 × 1440 after experimenting. Immersed maxes out at 5760 × 1200, but the slightly less wide aspect ratio of 5120 × 1440 feels more balanced. I'd prefer about 30% more vertical space, but recent versions of Immersed on Mac don't offer realistic custom screen sizes.

I used to disable the MacBook's built-in display entirely, but I've since changed my approach:

MacBook screen: Left on, appears above my virtual screen in Immersed
External monitor: Kept connected on the right, unused in VR
VR environment: Set to black, along with the desktop background

I don't use either physical screen while in VR, but leaving them connected makes it trivial to switch between VR and desk mode — just take off the headset and everything's already there. No reconnecting displays, no window shuffling.

There's an ergonomic bonus here too. With physical monitors, you're locked into whatever height and angle the stand allows. With a virtual screen, you can recline in your chair, shift your posture, lean back — and the screen stays exactly where you need it. No more hunching forward to see a monitor that's slightly too low.

Head strap setup matters#

My Quest 3 with Bobo VR S3 Pro halo strap. Face padding removed for visor mode, battery kept attached for counterbalance.

The Bobo VR S3 Pro in halo mode distributes weight well. I keep the battery attached even though I don't use it — the extra weight counterbalances the headset so it doesn't slide down toward my nose, and I don't have to over-tighten the strap.

I initially removed the face padding to run it in visor mode — being able to see my keyboard and desk peripherally helps with long sessions. But I've since added it back. Even though I don't love the feel of foam on my face, it keeps the headset aligned better. Without it, the display drifts slightly as the headset shifts, and you end up micro-adjusting more than you'd like.

The real friction points#

This setup works, but it's not seamless. Some pain points are technical, others are social.

Audio flakiness: Immersed's audio handling is temperamental. It often stops working when reconnecting the headset. I've learned to just restart the app when this happens.

Fiddly experience: This feels like a Linux-circa-2010 experience — functional but requiring occasional manual intervention. It's a leap from the "just works" polish you'd expect from something like Vision Pro.

Resolution limitations: While 5120 × 1440 is plenty of horizontal space, I'd love more vertical pixels. Unfortunately, Immersed doesn't currently support truly custom resolutions on recent macOS versions.

The webcam problem: This is a bigger deal than I expected. You can't really share your real face on video calls with a giant device strapped to your head. Immersed offers VR avatar integration, but for many colleagues, this is even more creepy than showing your webcam with the Quest on your face. It's a very real chafing point for collaborative work.

Reduced mobility: It's harder to step away from your desk or quickly grab a notepad. You're more in the VR space than the real world. That mental shift has friction — you can't just glance at your phone or look out the window without taking the headset off.

What's missing#

Immersed is genuinely the best VR productivity app I've tried. The virtual screen quality is good, the Mac integration works, and the core experience is solid. But it still feels like productivity software, not a place you want to be.

There's no sense of serenity. The environments are functional but not beautiful. The UI is utilitarian. When something glitches — and it will — you're reminded you're wrestling with software rather than just working. Compare that to the promise of VR: you could be in a mountain cabin, a minimalist studio, a quiet library. Instead, you're in a black void with a floating rectangle, which works but doesn't inspire.

The gap between "this functions" and "this feels great" is where VR productivity still falls short. I want to forget I'm wearing a headset and just be somewhere calm with my work. We're not there yet.

The Vision Pro question#

I've considered Vision Pro. Beyond the technical specs, there's another angle: aesthetics and social acceptability.

Vision Pro looks stylish. It's a fashion and status statement, not a weird cybernerd tech look. That might sound shallow, but it matters when you're on video calls or working in shared spaces. The Quest 3 — even in visor mode — screams "I'm deep in VR land." Vision Pro whispers "I'm using premium spatial computing tools."

Whether that's worth the price premium is another question. The technical reasons I haven't switched:

Cost: It's significantly more expensive than Quest 3 + accessories
Cable situation: You'd need both a data cable and a battery pack cable, making it less elegant than Quest 3's single-cable approach
Uncertainty: For pure productivity work (no hand tracking, no spatial apps), I'm not convinced the experience would be meaningfully better

I'd still love to try a Vision Pro for a few days to see if the seamlessness justifies the cost. But for now, Quest 3 delivers enough value at a fraction of the price.

The Steam Frame wildcard#

Valve's upcoming Steam Frame headset is one I'm watching. A standalone headset running SteamOS with wireless PC streaming — similar to Quest 3's approach but with Valve's ecosystem. Expected in early 2026 at around $1,200, it's likely to sit between Quest 3 and Vision Pro in price, but exceed both in flexibility.

For productivity, the interesting question is whether someone builds a polished workspace app for it. Valve's focus is gaming, but SteamOS is Linux-based, which could open doors for creative productivity tools. It's speculative, but if the hardware is good and the wireless streaming is solid, it could become a compelling option for those of us who want more than what Immersed currently offers.

Happiness level: 90%#

This is the best VR productivity setup I've found. It's stable enough for daily work, comfortable enough for multi-hour sessions, and flexible enough to tweak when needed.

The remaining 10%? That's audio flakiness, occasional connection hiccups, wishing for more vertical pixels, and the awkwardness of video calls.

But those are minor compared to how well this setup lets me focus and how good it feels to sit. There's something about working in a black void with just your screen and your thoughts — no desk clutter, no peripheral distractions, no visual noise from the room around you.

I can recline, shift positions, sit however my back needs that day, and the screen is always perfectly placed. And when I'm done, I unplug one cable and the whole office fits in a bag.

If you've been waiting for VR productivity to "just work," it's not quite there yet. But if you're willing to tolerate some fiddliness and you work mostly solo, Quest 3 + Immersed on Mac gets you most of the way.

All about Ken Hawkins

Blog art that belongs

Semantic search on a static site, no API keys required

tl;dr#

How vector search works#

The build-time half#

The browser half#

What the model sees#

Pagefind and semantic search compared#

Tradeoffs#

Tips if you're doing this#

What I'd explore#

Site search without a search service

tl;dr#

Why not stick with Lunr.js?#

Why I switched to Pagefind#

Before and after#

Tips if you're doing this#

Tradeoffs#

Related posts#

Collaborate on any webpage with a bookmarklet and URL state

How it works#

URL as the entire state layer#

Pins that follow the DOM#

Bookmarklet, not extension#

What you can do with it

Standing on shoulders

Try it#

Feedback buttons without JavaScript, using a 1990s web pattern

Constraints as a design tool#

What would a 1998 webmaster do?#

The redirect-count-redirect pattern#

Demo

SVG count (no JavaScript)

Plain text count

Styled with a JS enhancement

Musing: Cloudflare Workers are the new CGI script#

Setting this up on your own site#

What's next#

Behind the decisions#

Privacy by design

Keeping bots honest

Standing on shoulders

Approaches I considered but didn't choose

PDF-A-go-slim: a browser-based PDF optimizer

Why this exists#

What my tool does#

Privacy and accessibility#

How it's built#

Why it looks like Mac OS 8!?#

Try it, break it, improve it#

Your browser utility wants to be a floating palette

The hypothesis#

Floating windows were designed for this#

PostHog validated the direction, Poolsuite showed the path#

Structure over skin#

What not to borrow#

An experiment, not a manifesto#

The practitioner's guide to planning digital transformation (Parts 3-4)

tl;dr#

Part 3: Assess & Define#

1. Digital maturity assessment: Know where you are#

Assessment dimensions#

Scoring#

How to conduct the assessment#

2. Requirements elicitation: What you need from stakeholders#

The three stakeholder groups#

Elicitation techniques for each group#

Documenting requirements#

3. Success criteria: Specific, measurable targets#

Framework: OKRs for digital transformation#

Phase-based acceptance criteria#

Part 4: Plan & Execute#

Build the business case#

Resource realities#

What derails initiatives#

The critical path#

Putting it together#

Digital transformation for complex organizations (Parts 1-2)

tl;dr#