Design rules

DESIGN-RULES.md is written by hand from the crawl report and the screenshots. It is judgment work, not extraction: the crawl gives you the counts, and the rules say what to do with them. On the first site it took about a day.

In Claude Code

The hubspot-audit skill of the bb-hubspot plugin loads when you write or extend the rules. It enforces numbered, append-only rules derived from this site's crawl.

The shape

The same structure works on any site:

1. Archetypes at a glance. One table with a row per archetype: page count, header variant, opener module and theme, body pattern, closer, and range of section counts. The first site had twelve, from partner pages to case studies to a one-off homepage.
2. Global rules, which apply to every archetype:
   • The chassis: how panels and bands relate to each other.
   • Rhythm: how light and dark alternate, counted from the crawl.
   • Header, footer and H1 placement.
   • Copy conventions, including the site's own list of eyebrow words.
   • Copy shape → module, a decision table: title + paragraph + image goes to one module, 3–12 short items to a card grid, numbers to stats, quotes to testimonials, Q&A to an accordion, logos to a logo strip.
   • Layout mechanics worth knowing (nested columns, rails, band padding).
3. Per-archetype recipes: the opener, the body sections in order (each with module, theme and band), and the closer.
4. Style-tab cheat sheet: the settings actually used on the live site, module by module, with instance counts.
5. Anti-patterns seen in the crawl, so new pages don't repeat them.
6. Style-tab guidance: what editors really set on each high-use module, plus the asset library (background renders, photos) to reuse.

Number every rule

The generator cites rule numbers in its gap report, and each review round appends new rules instead of rewriting old ones. That makes every draft decision traceable to a rule, and every rule traceable to the round that added it. On the first site the file went from the first crawl to rule 30 in two days, over three rounds of draft review.

The rules belong to the client

Don't copy another site's rules. Two sites built with this same process came out with different chassis:

	Site A	Site B
Where light/dark lives	On the section wrapper	On each module (style.theme.mode); the section is a band behind it
Sections	Full-bleed coloured blocks	Plain, fixed-image, black, darker, hero-bg and video bands
Vertical rhythm	Section padding	The modules' own external padding; plain sections have 0 vertical padding

Example rules

These are generic examples of the level of detail that pays off. Write your own from your site's crawl.

• The light/dark carrier. Say where light and dark live: on each module panel (a theme field on the module) or on the section behind it. Every later rule depends on this one.
• Alternate light and dark. For example, dark for heroes, problems, the offer, stats, testimonials and closers; light for capabilities, approach and narrative.
• The opener depends on page type. Name the opening module and theme for each archetype. One H1, always in the opener.
• Some archetypes have their own grammar. Case studies, for instance, often follow a fixed sequence (hero, lede with logos, challenge with a stats rail, gallery, results, testimonial) and end without a call-to-action closer. Give each one its own assembler in the generator.
• Columns follow text length. Use the most columns at which the longest label still fits: one line for tags, two for card titles.
• Never invent copy. Eyebrows and headings come from the copy doc or the site's own vocabulary list.
• Headings go in the Title field, never typed into the description rich text. Crawls of edited sites often find this on a large share of panels.