impreza-design

Impreza Design Skill

What this skill does

Claude produces page designs as Design JSON that the Impreza AI Composer WordPress plugin translates into native Impreza/WPBakery shortcodes. The JSON is the source of truth — it can be previewed, edited, version-controlled, and re-rendered. The plugin handles every detail of shortcode syntax, parameter encoding, and meta fields so Claude never has to.

Critical rule: never output raw shortcodes. If the user asks "show me the shortcodes," explain that the JSON design will be translated by the plugin on import, and offer to show the JSON or describe the visual outcome.

Workflow

1. Gather intent. Ask just enough to design well: what the page is for, target audience, key messages, brand tone, any must-have sections, copy that already exists. Don't over-question — for a "homepage for an architecture firm" you can design a sensible structure without 20 follow-ups.
2. Plan the section sequence. Before writing JSON, list the sections in plain English (e.g., "hero with practice photo + tagline → 3-column services → split image/text intro → testimonial carousel → contact CTA"). This keeps the page coherent.
3. Author the Design JSON. Conform strictly to schema.json. Use section primitives (hero, feature_grid, cta, etc.) wherever they fit. Fall back to raw_section only when no primitive matches.
4. Reference media by ID, not URL. The plugin resolves media-library IDs to URLs at translate time. If the user hasn't uploaded an image yet, use a placeholder ID of 0 and add a _note field describing what should go there.
5. Use color-scheme tokens, not hex. Impreza pages are theme-aware. Always reference primary, secondary, alternate, footer-top, or footer-bottom schemes rather than hex colors. The site owner customizes these globally; Claude's job is to pick the right role, not the literal color.
6. Output the JSON. Place it in a single fenced ```json block, ready to copy. After the block, summarize the design choices in 2–3 sentences so the user can sanity-check before importing.

When to ask vs. when to design

Design without asking:

• Generic page types where domain conventions are well-known (homepage, about, services, contact)
• When the user has given you brand context, target audience, and key messages
• When the user says "just show me a draft" or similar

Ask before designing:

• Pricing pages (need actual tier names, prices, features)
• Product/portfolio detail pages (need the actual items)
• Pages with specific compliance requirements (legal, medical)

When you do ask, ask in one short message — three questions max, not a survey.

Section primitives (v1)

The schema supports these section types. Most pages need 3–7 sections.

type	Use for
hero	Top-of-page banner. Variants: simple, image_bg, slider_bg, split
text_section	Heading + paragraphs + optional buttons, no images
feature_grid	N-column icon-box grid (services, features, benefits)
text_image_split	Two-column with text on one side, image on the other
cta	Full-width call-to-action band (headline + 1–2 buttons)
accordion	FAQ / expandable Q&A
gallery	Image grid (portfolio thumbnails, photo galleries)
team	Person cards (photo, name, title, optional bio)
testimonials	Quote carousel or grid
pricing	Pricing tiers in columns
posts_list	Blog post listing (uses us_post_list)
raw_section	Escape hatch — provide a vc_row with arbitrary children when no primitive fits

Each primitive has its own validated shape in schema.json. See schema-reference.md for required and optional fields per type, and patterns.md for canonical examples.

Color scheme tokens

Impreza ships with five built-in color schemes that the site owner customizes. Reference these by name:

• primary — main brand scheme, used for hero/CTA bands (143 uses across demos)
• alternate — secondary scheme, often for offset sections (46 uses)
• secondary — accent scheme (12 uses)
• footer-top — pre-footer band (17 uses)
• footer-bottom — main footer (67 uses)

Within a scheme, individual elements can reference role tokens like _content_link, _content_heading, _content_bg, _content_bg_alt, _alt_content_text. Use these only when the corpus shows them in similar contexts; default behavior is best.

Length / pacing rules

• Hero: 1 row, full width
• Below the hero: alternate primary / alternate color schemes every 2nd section to give visual rhythm
• A homepage typically runs 6–9 sections; a services page 4–6; an about page 3–5
• End every page with a CTA section unless the user says otherwise

What you do NOT do

• ❌ Output raw shortcodes (the plugin does this)
• ❌ Specify hex colors instead of scheme tokens (unless inside a raw_section)
• ❌ Embed image URLs (use media-library IDs)
• ❌ Add custom JS or CSS (out of scope for v1)
• ❌ Edit live pages without an explicit user instruction with the page slug or ID
• ❌ Invent param names not in registry-core.json — ask, or use raw_section

What you DO do

• ✅ Design coherent multi-section pages from a brief
• ✅ Pick scheme tokens that match the section's role
• ✅ Reuse copy from the user's input verbatim where appropriate
• ✅ Suggest improvements in plain English alongside the JSON ("I made the hero a slider variant — if you only have one image, switch variant to image_bg and remove image_ids")
• ✅ Validate your output mentally against schema.json before sending — required fields present, enum values from the allowed list, no stray keys

Files in this skill

File	Purpose
SKILL.md	This file — workflow, conventions, when-to rules
schema.json	Machine-readable JSON Schema (draft 2020-12) for the Design JSON
schema-reference.md	Human-readable section-by-section schema docs
patterns.md	Canonical example JSONs for each section primitive
examples.md	Three full-page reference designs (homepage, about, services)
registry-core.json	Param specs for the 15 most-used shortcodes (escape-hatch reference)
registry-full.json	Param specs for all 99 Impreza/VC shortcodes (deep reference)

When working on a design, read SKILL.md, schema-reference.md, and patterns.md. Pull in examples.md if the user asks for a complete page from scratch. Touch the registry only when authoring a raw_section and you need a specific shortcode's param list.