I'm skipping the "why" here (short version: a self-publishing friend kept telling me AI covers are always bland). These are notes on how the library itself got built, since that was most of the work.

Step one was a text file

Before any code, there was a file called taxonomy.txt. One style per line, pipe-delimited:

id | era | category | name | definition | seed hints (optional, verify)

A real line looks like this:

giant-type-fills-cover|modern|Typographic|Giant Type Fills the Cover|Title set so large it occupies most of the cover, often broken across lines, minimal or no image|A Little Life? Fleishman Is in Trouble; Normal People US

The question marks in the seed hints are on purpose. They're guesses about which famous books might show the style, and the header says it right there: verify. The playbook rule was to check each one before it went in.

The seed list started around two hundred styles. It ended at 247, and 28 of the final styles say in their notes that they absorbed or merged an older one. For example, a "Personal Finance Bold Money" style got folded into Giant Type Fills the Cover because the covers looked the same once they were side by side.

A playbook, because the cataloguing ran in batches

Filling in a style means finding real covers, saving thumbnails, and writing up what the style actually is. I wrote a playbook for the AI agents doing that work in batches, and it ended up being the most useful file in the repo. The main rules:

• 10 to 20 real covers per style, aiming for 12 to 15. Famous or award-winning books preferred.
• For modern styles, editions from 2006 to 2026. A recent reissue of an old book counts.
• Max three books from one author or series, unless the style is a series design.
• The edition matters. The right cover is one specific printing, so search by ISBN when possible.

The final spread is 10 to 25 covers per style, median 14.

Where the images came from

A small Python script, covertool.py, does the fetching. It can grab a cover by ISBN from Open Library (falling back to an Amazon image by ISBN-10), by Open Library cover id, or from any direct URL. Every image gets converted to WebP at quality 78 and shrunk to 400px tall max. It also throws away anything under 60px, because Open Library hands back a 1x1 placeholder when it has no cover.

Sources shifted mid-run. Open Library's search started returning 502s through the proxy, Goodreads blocked now and then, and the Apple iTunes Search API turned out to be the reliable one. Its ebook art usually matches the print jacket, and you can swap 100x100bb for 600x900bb in the artwork URL to get a bigger image. There's also a local catalog of about 1,200 designer-picked covers from 2015 to 2025, pulled from Literary Hub's best-covers roundups, with designer credits in the captions and searchable by regex.

Counting by source URL in the final data, a bit over half the covers came through Goodreads' image CDN, then Open Library, then the LitHub catalog and Apple. 1,337 of the covers have a designer credit.

The check that mattered most: look at the picture

Metadata lies. An ISBN can return the UK edition, a movie tie-in, a blank placeholder, or a totally different book. So the playbook made one step mandatory: covertool.py sheet <style> builds a contact sheet of every thumbnail in a style, and someone has to actually look at it. Anything wrong gets deleted and replaced, then the sheet gets rebuilt and checked again.

The style write-up also had to be based on what's in the contact sheet, not on what the style is "supposed" to look like. That one rule did more for prompt quality than anything else, because the descriptions came from real covers instead of vibes.

What a style record holds

Each style is a style.json with a fixed shape: summary, genres, designers, and a visual_dna block covering composition, typography, palette, imagery, texture and mood. Then do and don't lists, and the prompt fields.

The prompt template uses placeholders: {TITLE}, {AUTHOR}, {SUBJECT}, {GENRE} and optionally {PALETTE}. Two rules for templates:

• Front cover only, portrait 2:3 (1600x2400), title and author spelled exactly.
• Never name a real book, designer or artist inside the prompt. Describe the look instead.

That second rule keeps the prompts usable for anyone's book and avoids asking a model to copy a specific person's work.

Each style also has a negative prompt. The romantasy one starts with "misspelled text, extra words, gibberish lettering, watermark, 3D book mockup" and gets more specific from there.

validate.py checks every style for required fields, valid JSON, and that every image file appears in the examples list and the other way around.

Then a prompt for every single cover

A style prompt describes the whole family of covers, but sometimes you love one particular cover in it. So there's a second pass: a prompt per reference cover, stored as library/per_cover/<style>.json, a map from image filename to prompt. A merge script copies them into the site data and prints how many covers got one. It reads 3,642 of 3,642 now.

Static pages from the same data

The app is one page, but each style also gets a prerendered page at /style/<id>/ so search engines can read it. build_style_pages.py writes them from styles.json and nothing else, so there's no hand-written copy to drift. Then validate_site.py fails the build if the page count doesn't match the style count, if any two pages share a title or description, if a page has more than one H1, or if a page is missing from the sitemap. It runs on every push in GitHub Actions before the Cloudflare Pages deploy.

What I'd tell someone building a similar library

Write the rules down before you collect anything. Look at the images yourself. Keep one data file as the source and generate everything else from it. And let the build fail loudly when the counts don't line up, because a quiet mismatch between data and pages is the kind of bug nobody notices for months.

The library is free at https://covers.yuriystasyuk.com if you want to poke at it.

When we started building Elemon, a free browser card game where every element is a monster, the type chart was the part I worried about most. Every one of the 118 elements needed exactly one type. The types had to come from the real periodic table. And the matchups had to be fair enough that a kid picking sodium has the same shot as a kid picking iron.

I got it wrong the first time. Here's how the chart went from four types to nine, and what I did to keep it true.

The three starters: chlorine, sodium and iron. Each one is a different type.

Version one was a neat little circle

The earlier rules file had four types in a loop. Salt beat Soft, Soft beat Life, Life beat Hard, and Hard beat Salt. Salt was the halogens, Soft was the reactive metals of groups 1 and 2, Life was the nonmetals and metalloids, and Hard was everything else.

It was easy to explain. The trouble was "everything else." Hard ended up with 86 of the 118 cards. It held the transition metals, the noble gases, the lanthanides, the actinides and the lab-made superheavies all at once. Helium, a gas that barely reacts with anything, was on the same team as aluminum. A kid could win every match with that chart and still learn nothing about where helium lives on the table.

Version two follows the table's neighborhoods

The current chart has nine types, and each one is a region you can point to on a printed periodic table:

In code it's one small function that takes the atomic number and returns a type. Superheavies get checked first, then the lanthanide and actinide ranges, then short lists for the other families, and anything left over is Metal.

Checking superheavies first settles a real edge case. Tennessine, element 117, sits in the halogen column, and in the four-type version it was a Salt card. But it's a lab-made atom that falls apart almost instantly, so now it battles as Synthetic, and astatine is the last Acid. I'd rather have one clear rule a kid can learn ("104 and up is Synthetic") than a footnote.

Every matchup says whether it's real

This was the rule I cared about most. If the game says Blast beats Life, a kid will believe it, so the reason had better be true.

Each matchup in the rules file carries a real flag and a one-line reason. Most of them are real chemistry. Blast beats Life because reactive metals react violently with water, and living things are mostly water. Acid beats Metal because halogens corrode many metals. Rare Earth beats Metal because rare-earth magnets pull hard on iron. Metal beats Nuclear because dense metals like lead shield against radiation.

A few matchups are there for balance, and I didn't want to dress them up as science. Metal beating Crystal ("brittle crystals shatter against metal") and Crystal beating Noble gas ("precision pierces evasion") are game rules, and the Elemondex and the types guide label them that way. A kid can learn the chart and also learn which parts are pretend.

Synthetic got the strangest treatment. Every Synthetic hit rolls half, normal or double damage, and nothing is strong or weak against it. The rolls come from the match's own seed, so a replay of the same match plays out the same way.

Sodium's stats come from real properties. Toughness 7 because you can cut it with a knife, Power +3 because it explodes in water.

Stats from chemistry, on a budget

Types decide who hits whom for double. Stats decide everything else, and I wanted those to be real too.

Each element gets three stats. Toughness comes from density, hardness and stability. Power comes from how eagerly it reacts. Speed comes from how light the atom is. A build script scores all 118 elements on each one, ranks them, and gives every element the same 6-point budget, so its best stat is a 3 and its worst is a 1.

That budget kept the chart from collapsing into "pick the strongest thing." Caesium hits as hard as anything in the game and goes down fast. Osmium, the densest element, can take a beating but barely hits back. Sodium shows up as Toughness 7, Power +3, and each number carries a plain reason a kid can read ("So soft you can cut it with a knife," "Explodes in water").

Some of those facts are pinned down in tests. One test checks that osmium lands in the top Toughness tier, hydrogen in the top Speed tier, caesium in the top Power tier, and oganesson in the bottom Toughness tier. If I ever tweak a formula and osmium turns squishy, the test fails.

Balancing with bots

I can't playtest nine types by hand. So there's a simulation script that plays the computer trainer against itself on random balanced teams and reports win rates by type, stat shape, move and seat.

The October run looked like this for 3,000 Normal vs Normal games. Every type won between 47.7% and 54.3% of its games, with Nuclear at the top and Noble gas at the bottom. The first seat won 50.0%. Matches ran about 16 to 17 rounds with no stalls. Rare Earth runs a little low when both sides play on Hard, around 46%.

Solo practice got one deliberate tilt. On Easy and Normal, the kid's cards get 2 extra HP against the computer. Friend matches stay even.

Keeping the move facts honest

Every card has three moves, and every move has a one-sentence "why" that's a true fact about the element. Sodium's Salt Bond is real because sodium and chlorine make table salt. Its Orange Lamp move is the glow of old sodium street lamps.

The game reads each move's name to give it a job. A move with "Shield" in it guards, a move with "Fuel" charges up. The three jobs on one card are always different, and a test checks that for all 118.

Facts still slip through. One of my commits from October just says "fix nitrogen fact (78% of the air)." Another one removes some claims about mixing elements that the game didn't back up. The site has a contact page, and if a kid or a teacher spots a wrong fact, I fix the data file and every page that uses it rebuilds from there.

Where it runs

Elemon is a static site on Cloudflare Pages with a small Worker that acts as referee for matches. The rules engine lives in the Worker, and the browser draws the table and sends moves. There's no account, no download and no ads, and there's no chat between players, only game moves.

If you want to see the type chart in action, it's at elemon.win. Tap a type on the home page and it shows you who it beats and why.

This post is about how I write and check those notes, and about the batch I got wrong.

A food page. The numbers are the easy part. The note underneath is where you can hurt someone.

The first version read too confident

The first round of food notes was generated in batches, one JSON file per batch, and compiled into a single file the site reads at build time. Each entry had a verdict label like "Recommended" or "Limit," a few sentences of explanation, and a list of sources for the whole entry.

They read fine. Clean, friendly, sure of themselves. Too sure. When I audited the site this October, I kept tripping over phrases like "completely safe," "no risk," and cooking that "eliminates" the risk. Dozens of food pages had some version of it.

Nobody can honestly say a food is completely safe in pregnancy. The CDC and FDA guidance I was citing doesn't say that either. It talks about safer and riskier choices, temperatures, washing, pasteurization. My copy had rounded careful advice up into a promise.

Sources per claim, not per page

The fix changed the data shape. Each entry now has a claims array, and each claim is a sentence or two with its own source attached, name and URL. The page renders the source link right after the sentence it supports.

Here's how cooked shrimp reads now. FDA lists shrimp as a Best Choice. For pregnancy, FDA advises 2 to 3 servings of 4 ounces a week from the Best Choices list in total, not that amount of shrimp on top of other fish. FDA says the flesh of cooked shrimp should be opaque (milky white). The CDC line about raw or undercooked shellfish gets its own link.

That "in total" bit was a real bug in the old copy. It made shrimp sound like its own separate allowance.

Kale was the entry I used as the pattern for the rest. The nutrient figures cite PregNut's own data notes on the About page, and the copy says those numbers describe a food sample, "not a suggested serving or a guarantee about your own preparation." The CDC line says washed-then-cooked produce is safest, and then the entry says plainly that boiling doesn't guarantee every microbe is gone.

Writing it this way is slower. You can't hide a vague sentence when it has to point at a specific page that backs it up.

A validator that rejects my worst habits

There's a small script that checks every batch before it's compiled. It fails an entry if it's missing a verdict, explanation or sources. It wants roughly three or four sentences. It also has a list of banned patterns: "superfood," "powerhouse," "crucial role," "studies show," "experts recommend," em and en dashes, and the generic "Always consult your doctor."

I'm not against that advice. I banned the phrase because when it's pasted onto every page, nobody reads it. The site has one clear line in the footer and on the About page saying PregNut is not medical advice, and the food notes spend their sentences on specifics instead.

Labeling what isn't official

Some numbers on PregNut aren't official targets, and the site says so in the place you'd see them. There's no U.S. RDA for DHA, so 300 mg is labeled a comparison benchmark. The 70 g protein figure is labeled a benchmark too. Choline and potassium are adequate intakes, not RDAs.

The About page also says some guides were drafted with AI assistance and edited before publication, and that medical review is only credited when it actually happened. I'd rather be upfront about that than have someone assume a doctor signed off on a page they didn't.

Salmon on a phone, with the benchmark wording right where you'd look.

What I'd tell another builder

If your site touches health, read your own copy the way a worried person would at 11pm. Search for absolute words. Make every claim point somewhere specific, and put an "Updated" date on the page so people can see how fresh it is. Give readers a way to report a wrong number; my contact form has "Correction or source issue" as its own topic.

PregNut is free at pregnut.com. It's an educational reference and doesn't replace your doctor or midwife. If you find a note that still overreaches, tell me and I'll fix it.

I wanted my kids to get the good teaching channels without any of those doors. So the first real problem in building WiseTube was boring and specific. How do you take an embed that YouTube controls and make every exit go nowhere?

This is how I ended up doing it, plus the stuff I'd tell anyone trying the same thing.

The front door. Everything behind it plays inside WiseTube.

Start with the player settings

WiseTube loads YouTube's IFrame Player API and points it at youtube-nocookie.com. The player vars do a lot of the first pass: controls: 0 (no native controls, so no logo or "Watch on YouTube" link), disablekb: 1, fs: 0, iv_load_policy: 3 for annotations, and rel: 0.

I expected rel: 0 to turn off suggestions. It doesn't. These days it only limits the suggestions to the same channel. They still appear. So settings alone were never going to be enough.

Three layers on top of the iframe

The crop. The iframe is 240px taller than the visible frame, 120px hanging off the top and 120px off the bottom, inside a box with overflow: hidden. The video letterboxes into the middle and whatever chrome YouTube still draws at the edges lands outside the window.

The shield. A transparent div sits over the whole iframe. The iframe itself gets pointer-events: none, tabindex="-1" and aria-hidden. Clicking the video hits the shield, which toggles play and pause. Right-click is blocked on the player. Nothing inside YouTube's frame can be clicked or focused, so there's no link to follow.

The cover. Whenever the film isn't playing or buffering, an opaque WiseTube panel covers the player. It shows a dimmed thumbnail and a big play button. That's what hides YouTube's pause-screen suggestions. And the end screen never gets a chance to render, because when the player reports ENDED, the page swaps the player out for its own end panel.

What "no autoplay" means in code

When a film finishes, WiseTube shows a calm end panel with three picks from the same library, plus replay. Nothing counts down. Nothing starts until a kid taps something.

One honest wrinkle here. Inside the player, autoplay is set to 1. That's for the film the kid already chose, so it starts when they open it. If the browser blocks that, the code checks the player state after about a second and shows WiseTube's own play button. Autoplay of the next thing is what I removed, and that's the one that was walking my kids into weird channels.

Building your own controls

Turn off YouTube's controls and you own all of them. Play, pause, seek, volume, mute, speed, fullscreen, the keyboard shortcuts. I rebuilt the familiar keys (space and k, j and l, the arrows, f, m) on WiseTube's own container. Speed and volume get saved to localStorage so they stick between films.

Fullscreen was annoying. Some browsers won't let you fullscreen a plain div, so if requestFullscreen is missing or fails, the player switches to a CSS "fake fullscreen" that fills the window instead.

Curation is a list, on purpose

The library is driven by an explicit allowlist of channels kept in a JSON file, with age groups set per channel. The importer reads a channel's public Videos tab. Shorts and live streams live on separate YouTube tabs, so they never come in. The catalog tests fail the build if an import lets in a Short, a duplicate, an unknown topic, or a channel I ruled out.

I tried some automated screening along the way. It was useful for flagging, but I don't trust it to make the final call for kids, so the allowlist stays manual.

A topic shelf. Every channel on it got there by hand.

Tradeoffs I live with

Some creators turn off playing outside YouTube. Those films throw error 101 or 150. WiseTube says "This film won't play here" in kid language and hides that film on the device. Error 100 means it was taken down. Other errors get a retry.

There's no backend. Profiles, progress, the parent PIN and settings all live in the browser on that device. That means no accounts and no email. It also means switching tablets starts fresh, which is why there's export and import in the parent settings.

WiseTube runs no ads of its own, but a creator's video can still carry a YouTube ad. I can't seal that part. The site also uses Google Analytics to count visits.

The whole thing is a static React + Vite build on Cloudflare Pages. A _redirects file sends app routes like /watch/... to the app shell so refresh works.

If you want to poke at the player, it's at wisetube.yuriystasyuk.com. Pause a film and see what you get. If you find a way out, I'd like to know.