Ten AI pages, ten different buttons. How I kept 82 pages consistent

A friend of mine, a senior engineer, told me what everybody notices by now: ask AI for UI and you get something different every time. His answer was to use a design system, because that scales. He's right, and I had one, sort of.

For close to ten years I've carried the same CSS from project to project, adding things and throwing them out. What goes out stays out, but I've been through that round many times. It's around 200KB now, 23KB gzipped, and I can slice pretty much any design with it. The pages go back 7 or 9 years too, and so does the idea of doing all of it with no JavaScript. I never had the resources to finish it.

Then I started working with Claude. I'd built the pages first, and it only added a few fresh ones. What it took on was the grind I never had time for: taking the JavaScript out, the layouts, the themes, the checks. That's how it became Alloy, 82 pages with no JavaScript.

The annoying part was rarely wrong code. Claude understood my rules fine, but only after I'd repeated them many, many times. And it kept adding classes. A page needed something slightly different, a new class appeared, and every single one looked reasonable. I want this file as small as I can get it, because every class is one more thing somebody has to read. So I kept deleting. At some point I found scroll-locked-[breakpoint] on the roadmap and asked why on earth we need that for every screen. Later we dropped scroll-locked completely, since modals already lock the page.

Some things I just refuse. There's no button-cart and no button-checkout. A cart button is a button. If you want a name for it, make a component in Rails or Vue or whatever you use. And consistent doesn't mean one button everywhere. Each product has its own look, and that lives in the product's brand or in a component holding its set of utilities. Put all of it in the CSS and the CSS bloats for nothing.

Some names I won't touch either. has-bg-img and bg-img have been fine for seven years. We looked at renaming them to cover-img and I said no, it adds nothing.

I love all of it, but skeleton is the brilliant one. Usually you build a card, then a second skeleton version of that card, and you keep the two in sync forever. Here you put .skeleton on the real card. Build once, maintain once. A test measures it with and without, and nothing is allowed to move.

Since nobody can review everything an AI writes, we made machines complain. A class that doesn't exist fails the build. The stylesheet has a size budget, so anything new has to fit or something else goes. Those checks run on every push and block the deploy. They blocked me twice this week over one Buy link. The slow ones I run before a release: every page with scripts off, 4 widths, 3 themes, 3 browser engines.

You don't need my CSS for any of this. Keep few values, put your rules in a file the AI reads every time, and write a script that fails when one gets broken. And say no a lot, that part is still on you.

Mine is called Alloy, it's $29, and all of it is live at alloyhtml.com.