If you want an AI-ready design system, the first step is unglamorous: write your decisions down as plain text before any model touches your files. Smashing Magazine ran a piece on this recently, built on a guide by Hardik Pandya from Atlassian, and the diagnosis will sound familiar to anyone who maintains client themes. AI output drifts because of small undocumented choices, hard-coded values nobody cleaned up, and the habit of handing a model a mockup and hoping it works out the rest.
The good news for WordPress developers is that we already ship half of what that guide asks for. Block themes have a token layer in theme.json, and most stores have years of template markup a model can extend. What is usually missing is the spec file, the audit, and someone who keeps both current.
Spec files are what make a design system AI-ready
There are two ways to get markup out of a model. The common one is mockup-first: paste a screenshot or a Figma frame, ask for a component, and accept whatever spacing and hover states it invents. The other is spec-first. You keep structured Markdown files that state spacing rules, color choices, which component to use when, and what to avoid, and the model reads them on every generation. The Smashing piece makes the cost argument plainly: text specs are cheaper and more accurate than asking a model to recognize patterns in a mockup, and extending existing code tends to beat generating new code from a picture.
On a WooCommerce store that second point matters more than in most places, because product and checkout templates carry markup contracts. Strip the woocommerce_after_shop_loop_item hook or the product loop classes and the plugins that attach to them stop working, usually without a visible error. My rule for AI work on stores is narrow: the model extends existing templates and block markup, and generating a page from a screenshot is out of scope.
A spec that enforces the rule can be one page:
# Button spec, store theme
Use wp-block-button for every call to action. Do not create custom button classes.
- Background: var(--wp--preset--color--primary)
- Hover: var(--wp--preset--color--primary-dark)
- Stacked spacing: var(--wp--preset--spacing--40)
- Product loops: keep the woocommerce_after_shop_loop_item hook and the product loop classes
- No inline styles. If a variant is missing, register a block style.
Reviewed against theme.json 1.2.Pandya’s guide treats design decisions as infrastructure: anything that matters should end up in a file the model reads. The same thinking shows up in tooling. The Penpot MCP server exists so a model reads real design context instead of a flattened image.
The token layer you probably already have
The guide’s second layer is a token list the model must choose from, a closed set of named variables instead of plausible values invented on the spot. Block themes already have one. theme.json turns your palette, spacing scale, and font sizes into CSS custom properties like var(--wp--preset--color--primary), and any spec that references those presets keeps generation inside the system. The theme.json reference on developer.wordpress.org lists everything you can expose this way.
Classic themes are the other case. Hex values scattered through a stylesheet give the model nothing to anchor on, so for those sites I keep a tokens section at the top of the spec that names each value and where it is allowed. And when a variant is genuinely missing, the fix is registering a block style rather than letting the model write CSS, because one-off CSS is how design systems drift on sites nobody audits.
Auditing, and keeping the spec honest
The third layer is the audit. On the design side the article points to FigmaLint, a free Figma plugin that flags detached instances, missing interactive states, tokens that are not bound, and hard-coded values. Run it before you accept a vendor’s component library. I have not tested it against a WordPress workflow, and it is Figma-centric, so treat it as a design-side tool. On the code side the equivalent is cheap: a grep for hex values and inline styles across your templates tells you how much drift exists between the spec and the code it is supposed to describe.
Then there is keeping it current. The guide recommends a sync routine that flags which spec files were written against an outdated system version, and I get the same result with less machinery: each spec names the theme.json version it was reviewed against, and any bump to that version puts the spec on the review list. For a sense of what this looks like at scale, Atlassian and Carbon publish llms.txt files that hand LLMs their current documentation in plain text.
If your theme has years of accumulated templates and you want a spec and token layer that an AI can work against without breaking WooCommerce hooks, that is the kind of work I do. I am glad to look at what you have before anyone commits to a rebuild.
On a client site this week I would keep it small. Export the palette and spacing presets from theme.json into a tokens file, write a one-page spec for the two components AI touches most, buttons and product cards, then grep the templates for hard-coded colors so the spec is not lying on day one. That is a day of work, and it changes what every later AI session produces.
