The Section Studio
The browser tools for previewing, reviewing, composing, and creating sections — written for the person running the site, no code required. Open this manual in one tab and the tools in another; chapter 6 is a guided stress-test you can run end-to-end.
0The map — five tools, five URLs
Each tool is a URL on the site itself. Replace the domain with your site's.
One section (or all) rendered with real data — any skin, any device width.
The quality grid: every section × every skin, with statuses and notes.
One section rendered in all 7 skins, on a single page.
Arrange a page live: reorder / add / remove sections, set layout options.
Specify a brand-new section for an AI agent to build.
Brand tokens, the full section catalog, what each page renders.
wp suds … commands run?
Normally you don't run them — commands marked "(agent side)" belong to the AI agent:
you flag things in the browser, then tell your Claude Code session to "work the board" and it
runs them itself. To poke manually, use Local → right-click the site → Open Site
Shell — that shell has wp pre-wired to the right site, so
wp suds review next just works. Avoid a plain Terminal window: it doesn't know
which Local site to talk to without the agent's long socket-pinned invocation.Background facts the tools assume: the library has 55 sections in 23 categories; most categories offer several interchangeable versions (amenities = grid / chips / feature cards…). One of 7 archetype skins (express · warm · value · commercial · premium · eco · basecamp) restyles everything through design tokens — same sections, different personality.
1Previewing sections
Open /?sbs_preview=<section-id> (ids are listed in the Design System
screen), or /?sbs_preview=all for the whole library in catalog order. The
preview uses the real render path — actual site data, actual CSS, the active skin —
so what you see is exactly what a visitor would get.
The toolbar, explained
&bare=1 to any preview URL to
drop the toolbar — just the rendered section.The home hero — four layouts, one component
The hero isn't a normal section: it's one component that reskins into four layouts. Preview each as its own id:
| URL id | Layout |
|---|---|
hero_split | Copy left, photo + pickup float-card right (the default) |
hero_centered | Centered copy over the band, photo revealed below |
hero_statpanel | Copy beside a glass stats card (B2B voice) |
hero_fullbleed | Copy over a full-bleed photo/texture with a scrim |
hero_form | Copy beside a "schedule a pickup" form card |
form hero pitches pickup
scheduling — on a site with no pickup service it automatically renders as
split instead. The system won't let a layout assert a service that doesn't exist."Hidden on this site" placeholders
Sections render only when their data is real: reviews sections need actual reviews, the locations grid needs 2+ locations, commercial pitches need a commercial service. When the data is missing, the preview shows a labeled placeholder naming exactly what's needed — that's the claim-safety system working, not a bug. On the live page the section simply doesn't appear.
2The Review Board
/?sbs_review=board is the quality grid: one row per section (plus the five
hero layouts), one column per skin — 399 cells, each holding a status. It replaces
"notes in a text file" as the single place where polish feedback lives.
Statuses
| Status | Meaning | Who sets it |
|---|---|---|
| unreviewed | Nobody has looked yet | — |
| needs work | Flagged, with a note (your note auto-records which viewport you were on) | You |
| ready | Fixed / checked — awaiting your sign-off | The agent (or you) |
| approved | Signed off | You |
The polish loop
wp suds review next hands it your oldest flag + the exact URL; it fixes the canonical themeyour steps agent steps
?sbs_review=matrix&sec=<id>) — all 7 skins on one page, each cell
showing its status and note.3The Section Builder — composing pages
/?sbs_compose=home (also about, services,
pricing, faq, contact). The left rail is the page's
section stack; the main pane is the real page. Every change saves immediately and
the page reloads in place — what you see is literally what's saved.
The rail, explained
fixed page openerlayout: form ③services_gridServices↑↓✕ ④steps_numberedHow it works↑↓✕picker, grouped by categorydraftneeds signal: pickup_delivery ⑥section-fields.md.Guardrails, in plain terms
| You try to… | What happens |
|---|---|
| Add a section whose facts aren't true here (e.g. a pickup pitch on a self-service-only shop) | It's greyed out in the picker with the reason; even a forced save drops it server-side |
| Remove every section | The last row won't remove; the server refuses an empty page |
| Type an unsanctioned knob value | Impossible — knobs are dropdowns/toggles validated against a fixed vocabulary |
| Compose a section whose data later disappears | It self-hides at render; the launch check (wp suds qa) warns you |
| Regret everything | Undo (10 steps) or Reset to the archetype default |
Agent/CLI equivalent of everything above:
wp suds compose <page> [<id,id,id> | --reset].
4The Section Designer — creating sections
New sections are real code, built once in the canonical theme, quality-gated, then shipped to every site — never page-builder blobs living in one site's database. That's the core product asset: one reviewed library, many sites. The Designer is how a non-developer starts that pipeline; your part takes about five minutes.
The form (/?sbs_design=new)
| Step | You fill in | Why it matters |
|---|---|---|
| 1 · Identity | Label ("Promo banner"), id (auto), an existing category | The category decides where it can slot; inventing categories is an architecture decision |
| 2 · Placement | Pages it may appear on + one or two sentences of purpose | Your purpose sentence becomes its documentation |
| 3 · Gating | What must be true to render: required data, site signals, or a safe generic fallback | This is the claim-safety contract |
| 4 · Fields | What operators will edit: heading trio, text, images, galleries, repeaters | Picked from a fixed vocabulary, so the editing UI generates itself |
| 5 · Knobs | Layout options (toggles + multiple-choice only) | Constrained by design — no free-form styling |
| 6 · Brief | The layout you imagine + claim-safety notes | This is the instruction the AI author works from |
A live JSON pane shows the spec being built; submitting validates everything and files
a work order (browse them at /?sbs_design=orders, with the exact
hand-off commands). The form can't write code — orders are inert data.
The pipeline from there
your steps agent steps
wp suds section status.5Where everything is edited
| You want to change… | Go to |
|---|---|
| Which sections a page shows, their order, layout options | Section Builder — ?sbs_compose=<page> |
| The words / images inside a section | The WP screen the builder links to (Home fields, Theme Settings, or the Service/Location/FAQ post). Field-by-field reference: section-fields.md |
| The overall look — skin, hero layout, navbar, textures | Theme Settings → Design (or the builder's hero row) |
| Quality sign-off across skins | Review Board — ?sbs_review=board |
| A section that doesn't exist yet | Section Designer — ?sbs_design=new |
| Brand colors/fonts + the catalog reference | wp-admin → Appearance → Design System |
6Stress-test drills
Run these in order on the workbench (not a live client site). Each drill states what to do, what must happen, and what it means if it doesn't. Together they exercise every guardrail in the building system. Budget ~30 minutes.
Previewing & reviewing
Open ?sbs_preview=cta_band, switch the skin dropdown through all 7, then reload the site's home page in another tab.
Every skin renders the band restyled; the real site is unchanged (the dropdown is a lens, not a setting).
If the live site changed skin, Theme Settings was edited — check Design → archetype.
On any preview, click Mobile. Compare with dragging your browser window narrow on the bare URL.
The Mobile button shows a genuinely different layout (stacked, mobile nav bar) because the iframe is a real 390px viewport.
Identical output means the iframe shell didn't load — hard-refresh; check you're not on &bare=1.
Flag any cell with the note "drill-test" while on Tablet. Reopen the board.
The cell is orange; the punch list shows your note with the viewport recorded; wp suds review next (agent side) returns exactly this item. Un-flag by marking it ready/approved after.
A missing viewport label means the chip was clicked outside the preview shell — flag from the board-cell link, not a bare URL.
Composing
In ?sbs_compose=about, move the bottom section to the top. Check the badge. Open /about/ in a normal tab. Then press Undo.
The iframe reloads in the new order; badge flips to OVERRIDDEN; the real page shows the same order; Undo restores the default and the badge returns.
If the real page disagrees with the builder, caching is interfering — the builder busts its own cache, but a server page cache on a live host would need excluding for these URLs.
Remove sections until one remains; try to remove it.
The ✕ is disabled on the last row. (Even a hand-crafted request would be refused server-side.)
An emptied page means the guard failed — file it as a bug; the render would still fall back to the archetype default rather than a blank page.
In the picker, find a greyed section (on a site without pickup service: anything in Pickup & delivery).
It's disabled with the reason ("needs signal: pickup_delivery"). No amount of clicking adds it.
If every section is enabled, this site simply has all signals (the workbench does) — verify on a leaner site, or temporarily unpublish its pickup service and refresh.
Expand services_grid's knobs; set columns 3 → 4; watch the iframe. Then (agent side) try wp suds field-set services_grid columns 7.
The grid re-renders 4-up instantly. The CLI attempt errors: "Invalid value '7'… Allowed: 2, 3, 4." — same vocabulary, both doors.
A saved out-of-vocabulary value would mean the shared validator was bypassed — that's a bug, not a feature request.
On ?sbs_compose=home, set the hero layout to form. Read the note under the dropdown (on a site without pickup).
On a pickup site it just switches. Without pickup it says "form needs the pickup signal — rendering split" and the page shows the split hero.
A form hero rendering on a no-pickup site is a claim-safety failure — flag it on the board immediately.
Creating
In ?sbs_design=new, try to submit with (a) an id that already exists (e.g. cta_band), then (b) a choice knob whose default isn't in its choices list.
Both are rejected with a specific message before anything is filed. The category dropdown never even offers a "new category" — that's an architecture decision by design.
A filed order with an invalid spec means server-side validation drifted from the form — the scaffolder would still refuse it, but report it.
File a small valid spec ("test_banner", category cta). Open ?sbs_design=orders and wp suds section orders.
The order appears in both, with the two hand-off commands printed. Nothing on the site changed — no new section exists until an agent scaffolds it in the canonical theme. Dismiss it after: wp suds section orders --dismiss=test_banner.
If a section appeared from the form alone, the web route wrote code — that's the one thing it must never do.
(With any draft section present) run wp suds section publish <id> --check before its board row is fully approved.
A checklist prints — docs status ✓, lint ✓/✗, board n/7 — and it refuses until lint is clean AND all 7 skins are approved.
A publish that passes at 6/7 approvals is a gate failure; the flip itself is always a canonical-repo edit, never a click.
wp suds qa — it should report the same counts as before you started.7The safety model, in one paragraph
Viewing tools are read-only. Every write requires an editor login and passes the same validated path the AI agents use. Layout knobs only accept sanctioned values. Compositions can't include false claims, and sections still self-hide when their data is missing. The web tools never write code — new sections are specified in the browser but built, linted, board-approved, and published from the canonical theme, so every site runs the same reviewed library. The worst an editor can do in the Studio is arrange a page oddly — and Undo fixes that in one click.
Companion references: section-fields.md
(every field & knob) · sections.md (the library contract, for
agents) · AGENTS.md (the full CLI) · manual.html
(the design-system browser).