Building WordPress Block Themes using AI

I recently rebuilt wsform.com from a classic PHP theme into a WordPress block theme with the help of AI.

Along the way, I learned that AI can be remarkably good at theme development. It can also be remarkably good at building bad websites.

The difference usually comes down to how much direction you give it.

Give AI a vague instruction to build a website and it will happily make decisions about your design, accessibility, SEO, architecture, CSS, responsive behavior, and just about everything else.

Give it a design system, clear project rules, accessibility and SEO requirements, and small problems to solve, and the results can be very different.

This article covers what I learned rebuilding a real production site with AI, how I would approach an AI-assisted block theme today, and some of the mistakes I would avoid if I were starting again.

AI Is Very Good at Building Bad Websites

Ask an AI coding assistant to “build me a modern website” and there is a good chance you’ll know it was built with AI before the page has finished rendering.

You’ll often get the enormous hero heading, gradients, rounded cards, excessive shadows, arbitrary animations, and many of the same visual patterns you’ve seen on other AI-generated sites.

The problem isn’t necessarily AI. The problem is the prompt.

If you haven’t told AI what your brand looks like, how your website should behave, or how the code should be structured, you’ve effectively made it your developer, designer, accessibility consultant, SEO specialist, and brand director at the same time.

It will fill in the blanks. And there are a lot of blanks.

I’ve found AI works much better when I make the important decisions and ask it to implement them.

Before you ask AI to build a homepage, establish what the website is supposed to look like, how it should be built, and what standards every piece of work must meet.

Start With Your Brand, Not Your Theme

Before writing any code, give your AI coding assistant a clear description of the site’s visual identity.

At a minimum, define:

• Your logo and any variants that can be used.
• Your primary and secondary colors.
• Text, background, border, and muted colors.
• Fonts and font weights.
• Heading styles.
• Button styles.
• Border radiuses.
• Content and wide content widths.
• General spacing preferences.
• Examples of websites or design styles you like.
• Design trends you specifically do not want.

Be opinionated.

If you don’t like gradients, say so. If every button should have a small border radius, specify it. If headings should be relatively light rather than bold, tell it.

Don’t assume AI will infer your preferences from the rest of the site. Tell it what those preferences are and make them part of the project.

AI design tools can also be useful before you start implementing anything. I’ve found tools such as Claude useful for working through how a hero, pricing section, navigation, cards, or other components might look.

The important thing is that I don’t ask AI to invent an entire site and then accept whatever comes back.

I’ll work on a component, decide what I like, refine it, and then use those decisions when implementing it in the actual theme.

AI needs direction. The more visual decisions you make up front, the fewer it has to invent for you.

Make Accessibility a Requirement From Day One

Accessibility should be part of the design system, not something you check once the website is finished.

This is particularly important when working with AI because an AI assistant can generate an enormous amount of markup and styling very quickly. If accessibility isn’t part of its instructions, it can generate accessibility problems just as quickly.

Tell your AI assistant from the beginning that accessibility requirements are non-negotiable.

For example, your project rules might require the site to target WCAG 2.2 AA and include requirements for:

• Sufficient color contrast.
• A logical heading hierarchy.
• Meaningful alternative text for informative images.
• Appropriate treatment of decorative images.
• Visible keyboard focus states.
• Keyboard-accessible navigation and controls.
• Buttons for actions and links for navigation.
• Semantic HTML wherever possible.
• Form controls with appropriate labels and instructions.
• Content that doesn’t rely on color alone to communicate meaning.

Accessibility also affects the visual decisions you make before any code is written.

A color that looks good in a brand guide may not have enough contrast for normal text. On wsform.com, for example, one of the lighter grays used in the logo wasn’t suitable for body copy on a white background. Our accent blue also wasn’t appropriate for every small-text use.

Those aren’t problems you want AI discovering halfway through the project. They belong in the design system.

If accessibility is included in your rules from the start, AI can consider it while building each component instead of you having to retrofit it across an entire theme later.

Make SEO Part of the Build Too

I would treat SEO in much the same way as accessibility.

Don’t wait until the website is finished and then ask AI to “SEO optimize it.”

Make good technical SEO part of the rules governing everything it creates.

That doesn’t mean telling AI to stuff keywords into headings. It means making sure the underlying site is built in a way that search engines and other systems can understand.

Depending on the project, your rules might require AI to consider:

• Correct use of semantic HTML elements.
• One clear primary H1 where appropriate and a logical heading hierarchy beneath it.
• Descriptive page titles and meta descriptions.
• Canonical URLs.
• Open Graph and other relevant social metadata.
• Appropriate structured data using Schema.org vocabulary.
• Valid JSON-LD where structured data is required.
• Descriptive link text.
• Useful image alternative text rather than keyword stuffing.
• Internal linking where it genuinely helps users understand or navigate the content.
• Performance and Core Web Vitals.

Structured data is a good example of something that’s easy to forget when you’re concentrating on how a page looks.

If you’re building an article template, product page, FAQ, organization information, breadcrumbs, or another type of content for which structured data is appropriate, tell AI to consider whether the corresponding schema markup should be implemented.

Also tell it not to invent structured data simply because it can. Schema should accurately describe content that actually exists on the page.

The broader rule I now prefer is simple:

Anything we build should be accessible, semantic, responsive, performant, and SEO-friendly by default.

That gives AI a much better definition of “finished” than simply making something look right in a browser.

Give AI Rules, Not Just Prompts

This is one of the most useful things I learned during the project.

There is a big difference between the instructions for the task you’re doing now and the rules for the project as a whole.

A prompt might say:

Build the header using the design we agreed on.

But there are dozens of decisions I don’t want to repeat every time I write a prompt.

Use rem instead of pixels. Use colors defined in theme.json. Prefer native WordPress blocks. Don’t add arbitrary CSS when a block setting will do the job. Follow our naming conventions. Meet WCAG 2.2 AA. Use semantic markup. Consider SEO and structured data. Don’t redesign something unrelated to the current task.

Those are rules, not prompts.

Most AI coding environments now provide a way to store persistent project instructions.

• Cursor has Project Rules, which can be stored as .mdc files.
• GitHub Copilot in VS Code supports repository-wide instructions in .github/copilot-instructions.md, as well as path-specific instruction files.
• Claude Code can use a project-level CLAUDE.md file.

The implementation varies, but the principle is the same:

Your AI should not start from zero every time you give it a new task.

Persistent rules give the AI context about how your particular project should be built.

This is much more reliable than trying to remember to add “use our theme colors, prefer native blocks, meet WCAG requirements, use semantic HTML, consider SEO, use rem, and don’t touch the homepage” to every prompt.

Your Rules Should Evolve With the Project

You don’t need to create the perfect set of rules before you start.

Begin with what you know.

Define your coding conventions, theme architecture, accessibility requirements, SEO requirements, naming conventions, design principles, and a few hard boundaries.

Then add rules as you work.

This is where they become really useful.

If AI uses CSS where a block setting would have worked, that becomes a rule.

If it changes a finished page while working on something unrelated, that becomes a rule.

If WordPress shows an Attempt Recovery dialog because serialized block attributes don’t match the saved HTML, the reason becomes a rule.

If a theme CSS class collides with a plugin class, your new naming convention becomes a rule.

If it generates an inaccessible component, the reason it failed becomes a rule.

If it forgets required structured data on a particular content type, that becomes a rule too.

When AI makes a mistake you don’t want it to make again, don’t just fix the code. Fix the rules.

I started thinking of these rules as the project’s institutional memory.

AI coding assistants are incredibly fast, but I don’t assume a new conversation will understand every architectural decision made during dozens of previous conversations. Persistent rules give the agent that context.

Avoid filling your rules with vague aspirations such as:

Write high-quality code. Follow WordPress best practices. Make the website look professional.

Those sound sensible, but they don’t provide many useful constraints.

A rule such as this is much more useful:

Use block settings for spacing, typography, colors, alignment, and layout before writing custom CSS.

And a rule learned from an actual problem is even better:

Do not add spacing attributes to serialized block markup unless the wrapper HTML contains the corresponding inline styles expected by WordPress.

Rules should encode decisions and pain, not aspirations.

Build Your Design System Before Your Pages

If your project rules tell AI how you build, theme.json tells it how the site looks.

I would establish theme.json before spending much time building pages.

Define your palette, typography, font sizes, content widths, wide widths, shadows, and the editor controls you want available.

On wsform.com, for example, I use a custom palette rather than exposing the default WordPress palette. Font sizes are in rem. The site uses a system font stack. Content and wide widths are defined centrally.

I also disabled the default spacing presets because I wanted spacing to use concrete rem values.

The principle is simple:

If AI has to decide what blue, border radius, content width, heading size, or spacing to use every time it creates a block, you haven’t given it a design system.

Once those decisions exist in theme.json, make your AI rules tell the agent to use them.

Block settings should generally come before CSS. If WordPress can control spacing, typography, color, alignment, or layout as a block attribute, use that instead of immediately writing another CSS rule.

I now treat custom CSS as the last option rather than the first.

Give AI Access to the Project

You can build a theme by copying snippets between a browser-based AI chat and your editor, but an AI-enabled coding environment makes this type of work considerably easier.

I used Cursor for the wsform.com conversion. VS Code with an appropriate AI coding extension can provide a similar workflow.

The important difference is context.

An agent working inside the project can inspect theme.json, existing blocks, templates, CSS, PHP, naming conventions, and other code before making a change.

Combine that repository context with persistent project rules and the output becomes considerably more consistent.

Think About the Cost of AI Development

There is also a practical consideration: tokens.

Theme development can consume a surprising number of them.

The agent isn’t just generating a few lines of PHP. It may repeatedly read theme.json, templates, block definitions, CSS, PHP, JavaScript, and other files to understand how a change fits into the project.

Working directly against an AI API can therefore get expensive.

At the time of writing, tools such as Cursor offer plans that bundle model usage, which can make this type of sustained development more economical than paying directly for every API token.

Pricing and allowances change, so I wouldn’t choose a tool based purely on today’s token limits. But if you’re going to use AI heavily for development, the economics of the environment are worth considering.

Start Small, Then Layer

One of the easiest mistakes is giving AI too much to do in a single prompt.

Don’t start with:

Build a complete block theme for my software company with a homepage, pricing page, documentation, account area, responsive navigation, integrations, and checkout.

You might get something impressive in five minutes. You’ll probably spend considerably longer untangling it.

Instead, layer the work:

1. Define the brand.
2. Define your accessibility and SEO requirements.
3. Create your initial AI project rules.
4. Set up theme.json.
5. Create the basic theme structure.
6. Build the header.
7. Get the navigation working properly with a mouse, keyboard, and touch on desktop and mobile.
8. Build the footer.
9. Establish the default page template.
10. Build one page section.
11. Test it.
12. Refine it.
13. Extract patterns or custom blocks only when a genuine need emerges.
14. Keep updating your AI rules as you learn.

Smaller prompts are easier to understand, review, test, and undo.

They also stop AI from making architectural decisions five steps ahead of you.

How We Migrated wsform.com

The old wsform.com theme was a conventional classic theme. It had PHP templates, shortcodes, ACF, Easy Digital Downloads, Yoast, Redirection, and a large style.css that had accumulated years of styling.

It worked.

The problem was that more and more pages had become one-off implementations. Changing layouts often meant changing PHP. Shortcodes hid content from the editor. CSS continued to grow.

I wanted the block editor to be the CMS, rather than a UI sitting on top of a PHP theme.

I started the conversion on staging and kept the classic theme untouched as a reference.

That reference was important because AI loves improving things you didn’t ask it to improve.

During a migration, I recommend getting the new site to match the old site before redesigning anything.

Match widths. Match colors. Match font weights. Convert pixel values to rem where appropriate. If the old site uses a font weight of 300, don’t let AI decide that headings obviously need to be 700.

That lesson became another project rule:

Match the existing site before improving it.

Migration and redesign are two different projects.

Let Templates Be Templates

One of the biggest architectural changes was getting content out of templates.

The new templates are deliberately boring.

Header. Full-width main. Footer.

The actual marketing layouts live in post_content, where they can be edited using blocks.

I use Groups to establish constrained content widths. On wsform.com, the normal content width is 992px and the wide width is 1400px.

Between the header and footer, the canvas itself is full width. That means a hero, guarantee banner, or other full-bleed section can reach the viewport edge without fighting against padding imposed by the theme.

Mobile gutters belong on the appropriate blocks rather than in a global CSS rule that adds page padding everywhere.

This sounds like a small distinction. It prevents an enormous number of CSS battles later.

Use Fewer Templates

I also resisted creating a template for every page.

There are templates for genuinely different structures, such as the default layout, pages where the designed H1 lives in the content, the knowledge base sidebar, account pages, and relevant custom post type archives and singles.

There isn’t a page-pricing.html, page-features.html, and page-whatever-we-build-next.html.

The layout for those pages belongs on the page.

The WordPress title can remain a clean title for navigation, document structure, and SEO purposes. If I want a more elaborate H1 with partially bold text and a subtitle, that can be created in the content using a pattern and native formatting.

Use Native Blocks First

Another rule that emerged was to use native WordPress blocks whenever possible.

Groups, Columns, Headings, Paragraphs, Lists, Buttons, Images, Query blocks, Navigation, and Template Parts can do a lot.

Custom blocks should solve a problem, not become the default way to build everything.

For editable content inside custom components, I use InnerBlocks where appropriate. Dynamic data, such as prices or custom post type queries, is a better candidate for server rendering.

Where possible, PHP-rendered blocks can compose native WordPress blocks rather than inventing another layout system in custom HTML.

The same applies to plugins.

Easy Digital Downloads already provides native blocks for checkout and other commerce functionality, so I used those rather than dragging old shortcode implementations into the new theme.

Don’t Just Move Your Shortcodes

If you’re converting an existing site, make an inventory of your shortcodes before you start.

But don’t simply replace every shortcode with a Shortcode block and declare victory.

Ask what the shortcode actually does.

If it outputs static presentation, it may now be better represented by native Groups, Columns, Headings, Buttons, and other core blocks.

If it represents reusable editorial content, a synced pattern might be more appropriate.

If it queries dynamic data, a server-rendered custom block may make sense.

And if the plugin that originally provided the shortcode now has a native block, use it.

We built an HTML-to-block converter for much of the classic wsform.com content, with special handling for pages that needed more attention.

That made the migration much faster, but I still treated it as a content migration rather than an excuse to redesign everything.

Use Patterns Deliberately

Synced patterns worked particularly well for content that appears in multiple places but needs to remain editable.

Our money-back guarantee is a good example.

The layout wrapper can control alignment and spacing while the synced pattern owns the actual words. Edit that content once and it changes wherever the pattern is used.

That is much cleaner than hard-coding shared marketing copy into PHP.

It also establishes an important boundary: theme code can provide the structure, but once editors own content, deployments shouldn’t casually overwrite their changes.

Understand What WordPress Considers the Source of Truth

This caught me more than once.

Once somebody customizes a template, template part, or navigation in the Site Editor, WordPress stores that customization in the database.

That database version overrides the file in your theme.

You can therefore make a perfectly valid change to parts/header.html, deploy it, clear your caches, stare at the browser, and wonder why absolutely nothing changed.

The customized database version is what WordPress is rendering.

Once the new site was live, I treated WordPress as the source of truth for pages, posts, custom post types, navigation, and Site Editor customizations.

Theme deployments became file deployments.

This distinction is particularly important if you’re asking an AI agent to “fix the header.” It needs to understand that changing a file doesn’t necessarily change what the live site is rendering.

Let Block Recovery Teach You

The WordPress “Attempt Recovery” dialog became an unexpectedly effective teacher.

Serialized block markup is unforgiving.

The attributes in the block comment need to agree with the HTML produced by the block’s save() function.

For example, if block attributes say a Group has padding but the wrapper doesn’t contain the corresponding inline style, WordPress can decide that the block is invalid.

Recovery can then remove attributes that appear completely unrelated to the original problem.

My rule became simple: don’t hand-author approximate block markup and assume WordPress will sort it out.

When in doubt, create the block correctly in the Site Editor, save it without a recovery warning, open the Code editor, and use the markup WordPress actually produced.

There are other traps.

HTML comments cannot contain --, which matters when you’re tempted to put CSS custom properties into block comment JSON.

Header and footer template parts already produce their respective wrapper elements, so adding another header or footer tag to the inner Group can result in duplicate elements.

Navigation has its own collection of interesting behaviors, particularly around mobile overlays and environment-specific navigation references.

Each time we discovered one of these things, I added it to the AI rules.

That meant the next block was less likely to repeat the mistakes of the previous one.

Don’t Let AI Wander Around Your Project

AI coding agents can be very enthusiastic.

At one point I could ask AI to fix a card in the knowledge base and discover it had also decided the Pricing page needed some attention.

This behavior can occasionally be useful early in a project. Later, it’s dangerous.

Once an area of the site is finished, tell the agent it is finished. Make it explicitly off-limits unless the current task requires changing it.

The same applies to CSS.

Scope styles tightly enough that fixing one component doesn’t unexpectedly alter three other pages.

AI is fast enough to create regressions considerably faster than you can find them.

Test What AI Builds

AI producing working code doesn’t mean the task is finished.

Treat AI-generated work exactly as you would code written by somebody else. Review it and test it.

Depending on what has changed, that can include:

• Desktop and mobile layouts.
• Different viewport sizes.
• Keyboard navigation.
• Focus states.
• Color contrast.
• Heading structure and semantic HTML.
• Screen reader behavior where appropriate.
• HTML validity.
• Structured data validity.
• Page metadata.
• Performance.
• Block validation in the WordPress editor.

AI is excellent at getting you to a working implementation quickly. Human review is still important for deciding whether that implementation is actually good.

A Day-One Checklist for AI Theme Development

If I were starting another block theme tomorrow, I would do these things before building the homepage:

1. Document the visual identity, including colors, typography, logos, widths, spacing, buttons, and things I explicitly don’t want.
2. Define accessibility requirements, including WCAG 2.2 AA as a baseline.
3. Define technical SEO requirements, including semantic HTML, metadata, structured data, and performance expectations.
4. Create the initial project-level AI rules.
5. Create theme.json and establish the design tokens.
6. Define naming conventions for theme PHP, CSS classes, and custom blocks.
7. Decide what belongs in content, templates, patterns, and custom blocks.
8. Build the basic site chrome before individual page designs.
9. Give AI small, reviewable tasks.
10. Test each piece before building on top of it.
11. Turn lessons and repeated mistakes into new rules as the project develops.

Example AI Project Rules for a WordPress Block Theme

The following is a simplified version of the rules I accumulated while rebuilding wsform.com.

You can use these as a starting point for Cursor Project Rules, GitHub Copilot repository instructions, Claude Code project instructions, or another AI coding environment.

Don’t treat them as a magic prompt. Adapt them to your project and, most importantly, keep adding to them as you work.

You are building or converting a WordPress block theme. Follow these rules unless I explicitly override them.

CORE REQUIREMENTS

- Everything created must be accessible, semantic, responsive, performant, and SEO-friendly.
- Target WCAG 2.2 AA.
- Use semantic HTML appropriate to the content and behavior.
- Maintain a logical heading hierarchy.
- Use buttons for actions and links for navigation.
- Provide visible keyboard focus states.
- Ensure interactive components are keyboard accessible.
- Never communicate meaning through color alone.
- Normal text should have a contrast ratio of at least 4.5:1.
- Use meaningful alt text for informative images and appropriate empty alt attributes for decorative images.
- Consider SEO implications whenever creating templates, content structures, navigation, or components.
- Use appropriate metadata and structured data where required.
- Structured data must accurately describe content that exists on the page.
- Do not add schema markup simply because a schema type exists.

ARCHITECTURE

- Marketing and page layout belong in post_content, not PHP templates and not one HTML template per slug.
- Templates are chrome: header, full-width main, footer.
- Do not constrain or pad main in the template.
- Set width with Group blocks using contentSize and wideSize from theme.json.
- Side gutters belong in block spacing attributes or a full-bleed block's inner wrapper.
- Never add a theme CSS page-padding rule that fights full-bleed sections.
- Spacing before the footer belongs on the parent content Group, not the footer.
- Keep WordPress titles plain.
- Designed H1s, including partial bold text and subtitles, live in content using native formatting where appropriate.
- Prefer a small number of structural templates over page-{slug}.html templates.

NATIVE BLOCKS FIRST

- Use core blocks such as Group, Columns, Heading, Paragraph, List, Buttons, Image, Query, Navigation, and Template Part before creating custom blocks.
- Use InnerBlocks for editable content in custom blocks.
- Use render.php only for dynamic data or markup core blocks cannot reasonably express.
- Compose server output using core blocks when practical.
- Do not reinvent a layout system in HTML and CSS.
- Custom block CSS belongs with that block.
- Theme style.css is for site chrome and genuinely global utilities.
- Create shared CSS only when multiple components genuinely share the same styling.

THEME.JSON IS THE DESIGN SYSTEM

- Define the palette, font sizes, content widths, wide widths, and shadows as presets.
- Disable default presets that should not be exposed in the editor.
- Prefer rem units where appropriate.
- Do not reference presets unless they actually exist in theme.json.
- Use the project's established typography.
- Use block settings first for spacing, typography, color, alignment, and layout.
- Write custom CSS last.
- Do not invent new colors, spacing conventions, border radiuses, or typography when existing design tokens can be used.

VALID BLOCK MARKUP

- Block comment JSON attributes must match the HTML WordPress save() produces.
- Attribute and HTML mismatches can cause invalid content and Attempt Recovery.
- Do not hand-author incomplete block HTML.
- When uncertain, create and save the block in the Site Editor, confirm there is no recovery warning, then inspect the markup from Code view.
- HTML comments cannot contain --.
- Never place CSS custom properties containing -- inside wp block comment JSON.
- Header and footer template parts already emit their semantic wrapper elements.
- Preserve required Navigation block settings.
- Do not assume an empty Navigation block will resolve to the intended menu.

ACCESSIBILITY

- Target WCAG 2.2 AA.
- Check text and UI contrast.
- Do not use decorative light grays for body copy.
- Check hover, active, and focus states.
- Check text placed over colored or image backgrounds.
- Maintain a logical heading order.
- Use semantic landmarks appropriately.
- Use buttons for actions and links for navigation.
- Use meaningful alternative text.
- Provide visible focus states.
- Ensure controls can be operated using a keyboard.
- Do not communicate meaning through color alone.
- Do not add ARIA where native semantic HTML already provides the correct behavior.
- Accessibility is part of the definition of done, not a later optimization.

SEO AND STRUCTURED DATA

- Use semantic HTML to describe the structure and purpose of content.
- Maintain a logical heading hierarchy.
- Ensure page titles and meta descriptions can be managed appropriately.
- Preserve canonical URL functionality.
- Consider Open Graph and other relevant metadata.
- Consider whether the content type requires Schema.org structured data.
- Prefer valid JSON-LD when implementing structured data.
- Structured data must accurately represent visible page content.
- Do not invent reviews, ratings, FAQs, authors, prices, availability, or other structured data.
- Use descriptive link text.
- Avoid unnecessary duplicate content.
- Consider crawlability and indexability when creating navigation or dynamic content.
- Do not sacrifice accessibility or readability for keyword placement.

PERFORMANCE

- Avoid unnecessary JavaScript.
- Avoid unnecessary CSS.
- Do not load libraries when native browser or WordPress functionality can solve the problem.
- Avoid layout shifts where practical.
- Provide image dimensions where appropriate.
- Use appropriately sized and optimized images.
- Lazy-load content where appropriate without harming usability or important above-the-fold content.
- Consider Core Web Vitals when implementing components.
- Do not add animation unless it has a purpose.
- Respect reduced-motion preferences where animation is used.

SOURCE OF TRUTH

- After editors customize templates, template parts, or navigation, database versions can override theme files.
- Editing a theme file will not alter an existing database customization.
- Navigation block reference IDs can differ between staging and production.
- Prefer portable approaches instead of copying environment-specific IDs.
- Theme file deployments do not deploy post_content.
- Never synchronize repository page content onto production unless explicitly instructed.
- Do not import or export ACF field groups during routine theme work unless explicitly requested.

PLUGINS AND COMMERCE

- Prefer a plugin's native blocks over classic shortcodes when suitable blocks are available.
- Never invent or migrate customers, orders, licenses, or product posts as part of a theme conversion.
- Reference existing product IDs where required.
- Do not assume server-side conditional output is safe behind a CDN cache.
- Call out caching implications rather than silently relying on PHP conditions.

CSS AND NAMING

- Prefix theme classes and PHP helpers so they cannot collide with plugins installed on the same site.
- Scope custom block CSS beneath the block's class.
- Do not dump component styles into the main theme stylesheet.
- When migrating an existing site, match its existing sizes, weights, and colors before improving them.
- Convert pixel measurements to rem where appropriate.
- Do not assume headings should be bold if the existing design uses lighter font weights.
- Reuse design tokens rather than creating arbitrary values.

HOW TO WORK

- Inspect existing project code before creating a new implementation.
- When I provide classic PHP or HTML, convert it to appropriate blocks and theme.json tokens.
- Do not simply wrap old markup in a Custom HTML block.
- Do not restyle completed pages while working on unrelated tasks.
- Scope changes so completed areas cannot regress.
- Make the smallest change necessary to complete the requested task.
- Do not redesign unrelated components.
- If you create a custom block, include all required block files and register it correctly.
- After changing serialized template HTML, remind me to open it in the Site Editor and confirm WordPress does not show Attempt Recovery.
- Test responsive behavior.
- Test keyboard behavior where relevant.
- Check accessibility.
- Check semantic markup.
- Consider SEO implications.
- Validate structured data when it is added.
- Consider performance implications.
- If a mistake reveals a reusable lesson, recommend adding that lesson to these project rules.

What I’d Do Differently

If I were starting the wsform.com rebuild again, I would spend more time defining the design system before writing page code.

I would establish the AI rules earlier.

I would put accessibility and SEO requirements into those rules from day one.

I would migrate smaller pieces at a time.

I would write less CSS.

I would distinguish more clearly between migrating a design and redesigning it.

And whenever AI makes a mistake twice, I would stop correcting the output and start correcting the instructions.

AI Works Best When You Make the Decisions

Block themes aren’t classic themes with the block editor bolted onto them. They require a different way of thinking about where layout, design, content, and functionality belong.

AI turned out to be extremely useful in making that transition.

But the best results didn’t come from asking AI to build a website for me. In fact, the process took more than 180 different AI conversations.

The results came from deciding how I wanted the website to look, defining how I wanted the theme to be built, establishing accessibility and SEO as requirements rather than afterthoughts, turning those decisions into persistent rules, and then letting AI help me build one small piece at a time.

That’s the biggest lesson I took from the project.

AI is very good at writing code. It’s much more useful when you first tell it what good code means for your particular website.