Design review

Divi 5 Design Review

Two modes — detect from the arguments:

Arguments	Mode
layout.json only (+ optional --keyword)	QA mode — structural + SEO + design audit of the JSON
layout.json --spec brief.md (or --spec mockup-description)	Spec compliance mode — post-import check: does the page deliver what was planned?

---

QA mode

Audit an existing Divi 5 JSON export — generated by anyone, not just this plugin — and report what to fix, or fix it when asked.

Workflow

1. Mechanical pass. Run the bundled validator:

   node ${CLAUDE_SKILL_DIR}/scripts/validate.js <layout.json> [--keyword "<primary keyword>"]
   

   This checks structure (nesting, builderVersion, balance, preset/colour references) and SEO (single h1, heading outline, alt text, keyword placement).

2. Design pass. Read the layout's content and assess it against the checklist below. The validator can't see design quality — this pass is judgement against explicit rules.

3. Report. Produce a review with three sections: FAIL (must fix — broken import or SEO), WARN (should fix — design/UX), PASS (confirmed good). For each FAIL/WARN, state the fix concretely (which module, which attribute, what value).

4. Fix (only if asked). Apply fixes by regenerating or patching the JSON, then re-run the validator to confirm clean.

---

Spec compliance mode

Used after the page has been imported into WordPress and re-exported (or after a Playwright screenshot). Compares the live/exported result against the original plan, brief, or mockup to confirm the page delivers what was specified.

When to run

After /divi5-deploy completes and the page is live, either:

• Export the page JSON from Divi (Divi Library → Export) and pass it here with --spec, or
• Pass the generated page JSON (pre-import) with --spec to do the check before going live

Spec input formats

--spec accepts any of:

• A markdown brief file (e.g. brief.md, spec.md) — sections, CTAs, copy requirements
• The Stage 2 HTML preview file (preview-[brand].html) — compare structure against the approved mockup
• A plain text description of requirements pasted inline

Spec compliance checks

For each item in the spec/brief, check the layout and report:

Sections

• PASS: section present with appropriate module type (hero, features, testimonials, etc.)
• FAIL: section listed in brief is missing from the page
• WARN: section present but content diverges significantly from spec (wrong CTA, wrong copy intent)

CTAs

• PASS: primary and secondary CTAs match the brief's action and label
• FAIL: CTA missing or points to wrong action
• WARN: CTA copy doesn't match agreed wording

Content completeness

• PASS: key claims, offers, and value props from the brief appear in the page
• FAIL: a required content element (pricing, guarantee, social proof count) is absent
• WARN: content present but weaker than spec called for

Section order

• PASS: sections appear in the order the brief specified (or a logical equivalent)
• WARN: section order diverges from brief without an obvious UX reason

SEO targets

• PASS: primary keyword appears in h1, first 100 words, meta title
• FAIL: keyword absent from h1 or meta title
• WARN: keyword density lower than spec required

Spec compliance report format

SPEC COMPLIANCE REPORT
======================
Layout:  [filename]
Spec:    [filename or "inline brief"]
Checked: [N] spec items

FAILS ([N]):
  ✖ Missing section: "Pricing" — listed in brief as required, not found in layout
  ✖ CTA mismatch: hero CTA reads "Learn More" — brief specified "Book a Free Call"

WARNINGS ([N]):
  ⚠ Section order: FAQ appears before Testimonials — brief had Testimonials first
  ⚠ Social proof: brief asked for "500+ clients" stat — not found in layout

PASSES ([N]):
  ✓ Hero section present with h1 containing primary keyword
  ✓ Features section present with 3 blurb cards as specified
  ✓ Contact form section present with email field

VERDICT: COMPLIANT / NON-COMPLIANT

If NON-COMPLIANT, list the generator script changes needed to add missing sections or fix CTA copy, and offer to apply them.

Design checklist

Typography

• Clear hierarchy: h1 noticeably larger AND heavier than h2 than body (hero h1 should be 3–4x body size)
• Exactly one h1; section headings h2; card titles h3; no skipped levels
• Eyebrow labels: uppercase, 2–3px letter-spacing, accent colour, rendered as text not headings
• Max two font families; body 16–18px desktop, ≥16px phone, line height 1.7–1.8em
• Phone breakpoint sizes on all headings (~35% smaller than desktop)

Colour

• No pure black text (#000) — minimum #1A1A1A; body on light #444–#666
• No pure white body on dark — #BBB–#CCC body, #FFF headings only
• Accent used sparingly: CTAs, eyebrows, icons — not body text or large fills everywhere
• Contrast ≥4.5:1 body, ≥3:1 large text

Layout & rhythm

• Section backgrounds alternate — never two same-coloured sections adjacent
• Hero padding 7–8em desktop / 4em phone; content sections 5–7em / 3.5–4em
• Text rows constrained to 700–800px maxWidth; card rows ≤1200px
• Cards have lift: background contrast with section, radius, 2em internal padding
• Consistent column gaps (30px standard)

Responsive

(full rules: divi5-page-generator/references/responsive-rules.md)

• Rows wrap on phone/phoneWide (flexWrap: wrap)
• Non-full-width columns get flexType: 24_24 on phone/phoneWide
• Section padding reduces ~40% on phone — or better, uses the fluid clamp() ramp
• Spacing is clamp()-based, not fixed px repeated per breakpoint — WARN on fixed-px section/hero padding with per-breakpoint overrides doing what one clamp() would
• Font sizes clamp()-based — WARN on per-breakpoint phone: { size } overrides that just shrink the scale (a deliberate display-size break is fine)
• Background images do not persist to phone — WARN when a section relies on a bg image (or gradient-over-image) at phone breakpoint for looks or text contrast; mobile should get a solid colour
• When a hero/split row stacks on phone, the primary CTA column stacks above decorative images — WARN if the CTA lands below the fold behind an image column
• Images declare an aspect ratio (Divi 5.5+) to reserve space and avoid CLS — WARN when missing (skip until the generator can emit it; see responsive-rules.md verification table)

Module choice (Divi 5.6+)

• Chronology/process/history content built as blurb or text stacks — WARN: suggest the Timeline module
• Long-form pages (roughly >1,500 words or >6 h2 sections) without a Table of Contents module — WARN
• Inline vector graphics faked with image modules — suggest the SVG module

Buttons & components

• Exactly two button styles (primary filled, ghost outlined); correct inversion on accent backgrounds
• Blurb cards: icon in accent, bold title, muted body
• adminLabel set on every section

Divi 5 technical

• Presets defined and referenced via modulePreset (maintainability)
• Global colours defined and used via $variable()$ references rather than repeated hex values
• Context matches import destination (et_builder page vs et_builder_layouts library)

Report format

## Divi 5 Review — <file>

### Must fix (import/SEO)
1. <issue> — <module/location> — <fix>

### Should fix (design/UX)
1. <issue> — <fix>

### Confirmed good
- <pass summary>

Verdict: <ready to import | fix musts first | needs design rework>