From a mockup to a working theme

A theme with Claude Design

Q: Can I use a ready theme instead?

Yes. Start from a theme with demo content , replace the texts and photos, and ask Claude Design only for changes to the look.

Claude Design turns a mockup, a screenshot or a few words about the look into a design you can see and change. With HERON it makes the theme: the templates and styles that draw every page of your site from its text files.

The texts stay in your pages, the look stays in the theme. That is why a theme made in Claude Design works with any content, including pages that do not exist yet, and why the agents that write your pages never touch it.

What to give Claude Design

Your mockup or a description

A Figma frame, a screenshot of a site you like, or a paragraph: colours, mood, fonts, what matters on the first screen.

Tip: Show the home page and one inner page. Two layouts are enough to set the style.
Words work too: «Calm, light, lots of air, dark blue and sand colours, rounded corners» is enough to start.
Brand: Logo file, brand colours and fonts if you have them; put the files into theme/assets/.
Both modes: Say if you want a dark version; HERON themes can switch light and dark.

The designer rules

How a HERON theme is built: where templates go, how blocks get their content, what may not be in a template.

Role: Designer
Guide: Theme and design
The key rule: No texts of the site inside templates: texts live in pages, so the same theme works for any content.
Where it writes: Only theme/. Pages, site.yaml and scripts stay untouched.
Skill: With npx skills add FMSTM/HERON, the heron-designer skill brings these rules on its own.

The page types of your site

Which pages exist and which blocks each has. They are listed in theme/theme.yaml of your site. The designer draws a template for each type and a module for each kind of block.

Blocks: All section forms with examples
Example: A clinic site has home, service, doctor and page; each needs its own template.
Real content to test: Ask the designer to build the theme on your actual pages, not on demo text: long titles and empty fields show problems early.
Check: heron build . --env prod --strict must pass on your site with the new theme.

Copy the brief

Attach the mockup, then paste:

Design a HERON theme for this site from the attached mockup. Use the heron-designer skill.
Page types: home, page, contacts. Blocks: steps, questions, cards, table, prices.
Work only in theme/. No page texts in templates; interface texts go to i18n; every block must look right when part of its content is missing; light and dark versions; readable on a phone.

From design to a working site

1
Look and adjust in Claude Design

Ask for changes until the home page and the inner page look right.
2
Put the theme into the site

The designer role writes the files into theme/ of your site folder, and only there.
3
Run the strict build

heron build . --env prod --strict names every page type without a template and every block without a module.
4
Check on real content

Open localhost:8000 with heron serve . and go through every page type. A theme that works with demo text and breaks on yours is caught here.

What a theme contains

File	What it does
`theme/theme.yaml`	Page types and the blocks each type shows
`theme/templates/`	One template per page type
`theme/modules/`	One module per block form: steps, cards, questions, table
`theme/i18n/`	Interface texts in every language: buttons, labels
`theme/assets/`	Styles, fonts, scripts

Questions

Can I use a ready theme instead?

Yes. Start from a theme with demo content, replace the texts and photos, and ask Claude Design only for changes to the look.

Will the theme slow the site down?

The theme decides the weight of the page. The starter theme gets 100 in Lighthouse on a phone with a 3 KB home page. Ask Claude Design to keep images in media/, so HERON makes WebP and AVIF of every size, and to avoid heavy scripts.

Can Claude Design write the texts too?

The texts belong in the pages, not in the theme. Give them to the content role: Content with Claude Code.