Building Zictionary: an interactive dictionary for AI terms

I wanted a place where AI jargon stops being a vocabulary list and becomes something you can push on. The result is Zictionary: 70 words, each explained in plain English at three levels, 13 of them with a small Playground, and a map where the words hang together as draggable bubbles.

This post is the build log: what it is, how it is put together, and how I try to keep 70 entries honest.

The shape of it

Each word is one page with a fixed anatomy: a hero (the word, aliases, a one-liner that changes by level, and a small map of connected words), a real-life example, an optional Playground, three "where the analogy breaks" points, a full related-words map and a footer.

The three levels are the same idea at different depth. Beginner is a metaphor. Builder is a precise definition. Deep names the mechanism and the real actor (the harness, the sampler, the provider). A level dial switches the copy and the Playground's detail without a reload.

Architecture

It is a static Astro site. No backend, no database, no real model calls.

• Content as data. Every word is one MDX file whose frontmatter holds all the copy, validated by a zod schema. A missing or wrong field fails the build.
• One source for the word list. clusters.ts holds the 7 groups and all 70 words (hue, emoji, order). The home page, the "Coming soon" fallback pages and the previous/next links all derive from it, so there is nothing to keep consistent by hand. I used to hand-write previous/next in each file and ended up with seven places where two words pointed at the same one.
• A build gate. npm run build first runs a content checker and the Playground tests, and stops if either fails.
• Generated share images. A script renders a 1200×630 card per word with a real browser, so every link preview is specific.

The Playground system

The first Playground (the "backpack" for context window) was hand-built. For the next twelve I wanted a cheap way to add more, so I made a shared frame and a loader:

• a shared frame (title, level dial, reset, "try this" shortcuts, an honesty note),
• a kind per idea (token, sampling, embedding, rag, chunking, caching, agent, tool use, injection, rate limit, chain of thought), each loaded lazily so a page only downloads its own,
• pure logic (softmax, nucleus cut, retrieval scoring, cache-prefix matching, token bucket, backoff, injection odds) in a plain file with its own tests.

Every Playground teaches one idea, and every number in it that is not a measurement is labelled "illustrative". The Token one is the exception: it uses a real tokenizer, so those counts are real.

The jelly map

The map view is 70 pill-shaped bubbles plus seven group hubs. It is a small hand-written physics loop: each word is pulled to its group's hub by a spring, related words are linked with weaker springs, bubbles collide as rectangles (pills are wide), and each one squashes and stretches with its speed and wobbles when poked. Hovering lights a word and its neighbours; dragging one pulls its group along.

Two details mattered. The loop goes to sleep when things settle (my first version burned 60 frames a second forever), and under prefers-reduced-motion it draws one static layout and skips the wobble.

Keeping 70 entries honest

With 70 entries and 13 simulations, nobody can eyeball it all. What I would tell anyone building a content site: writing is the cheap part, and checking is the work. A pile of confident entries is easy to produce. Making them trustworthy needs machinery.

What caught real problems:

• A format checker. Its first run found 30 mistakes: examples with five sentences, one-liners too long, relation labels over the limit, a "break" with no explanation.
• A hyphen bug. My text wrapper cut "AI-generated" into "AI- generated". Invisible until I scanned all entries.
• Tests on the lessons, not just the code. One checked that every scripted retrieval question behaves as the lesson claims. Another walked the real example text and found that my "just right" chunk size cut the answer in half.
• A browser run that clicks through every Playground and asserts the outcome (for example: with the send-email tool removed, no run can cause damage).

Performance and accessibility

Local mobile Lighthouse runs on the home page score 100 / 100 / 100 / 100. The heaviest Playground page started at 70 for performance, with 1.5 seconds of blocking time from a 2 MB tokenizer loading eagerly. Switching it to hydrate only when scrolled into view took it to 97 with no blocking time. Lighthouse also flagged two contrast failures (a grey that was 4.41:1 instead of 4.5:1, and white text on the orange centre bubble), now fixed.

What it isn't, yet

Not all of it has been reviewed by experts yet, and that review is in progress. The About page says so plainly, each entry shows the month it was last checked, and the Playgrounds' numbers are made up for illustration. I would rather hear about a wrong claim than a compliment. A way to suggest edits through GitHub issues is coming soon; until then, tell me here or through the contact on this site.

Other known edges: emoji icons look different per OS, the map is dense on small phones, and I have not finished a keyboard-only pass on every Playground.

What's next

More Playgrounds (next-token prediction as a game, a streaming-versus-waiting race, a thinking-budget slider), the review pass, and maybe a rotating 3D globe version of the map.

Try it

dictionary.sabbiramin.dev. Start with Context Window, then drag around the Map view. If a word is wrong or unclear, tell me. I will keep writing about what I learn building it right here on sabbiramin.dev.