Academy · Claude heads-up

Von Block × Claude: heads-up for the MCP connector

You are connected to a WordPress site that runs Von Block: a block builder with its own CSS framework and the MCG grid (Margins, Columns, Gutters). Read this before you build or convert anything. The goal is always the same: put the design into the framework, not around it.

For people: start your chat with this

Before we start, read https://www.vonblock.com/claude-heads-up/ and follow it whenever you work on my Von Block site through the connector.

1. First moves, every time

Before writing a single block:

get_framework: the breakpoints, the class families, the typography and the colours.
get_framework_settings (all sections): what the framework is compiled from (rule sets, colours, typography styles, composite classes, keyframes, grid-unit properties, custom properties, fonts).
list_places: the pages, the header and footer parts, the templates and the patterns.
list_global_css: the hand-written CSS that already exists.
search_classes for anything you are about to use. A class that is not in the framework styles nothing and is refused.

Then say back, in a few lines, what the site already has and what is missing for the job.

2. The MCG grid in one minute

Each breakpoint (a rule set) has a screen width, a margin m, a gutter g and 12 columns c.
One column is c = (W − 2m − 11g) / 12. A width of c6 is 6c + 5g.
Units are page-global. A width-c3 inside a width-c6 is still 3 columns + 2 gutters of the page grid, not a quarter of its parent. That is what keeps everything on one grid.
Classes end in the notation: width-c6, max-width-c8, gap-g1, padding-inline-m1, width-m1c6g1, and so on (whole units only).
Breakpoint prefixes override downwards: width-c3 md-width-c6 sm-width-c12 (the band names come from the site’s own rule sets; check them).
A full-width section is a group with bleed plus padding-inline-m1, so its content still lines up with the grid.

3. Converting a design (Figma, a screenshot, or any live site)

Work in this order. Do not jump straight to building the page.

a. Inventory the source

Breakpoints: the frame or viewport widths, and each one’s side margin and gutter.
Colours: every distinct colour, named by role (ink, surface, accent…), not by hex.
Text styles: for each role (display, h2, h3, lead, body, small, eyebrow/mono, nav, button…), the family, weight, size per breakpoint, line-height, letter-spacing and case.
Spacing scale: the paddings, margins and gaps that repeat.
Repeating patterns: cards, chips, buttons, framed images, list rows, stat blocks, quote boxes…
Layout intent: which widths are grid-based (they snap to columns) and which are fixed px.
Motion: what fades or slides in as it comes into view, from which side, and what is visible at once.

b. Set up the framework first

What you found	Where it goes
Breakpoint widths, margins, gutters	`rule_sets` (`update_framework_settings`)
Colours	`colors`. Mark one `body_text` and one `body_background`.
Fonts	`add_google_font` (served locally)
Text styles, with per-breakpoint sizes	`typography_styles` (or `ensure_typography_style` for a single one). Make one of them the default (body copy).
Values that repeat across many blocks (spacing steps, radii, display, flex helpers…)	`properties_custom`: one class per value
Widths, gaps and paddings that follow the grid	already generated from `properties_grid_units` (width, max-width, gap, padding-inline, margins)
A repeated bundle of declarations (card, chip, button skin, image frame)	`composite_classes`
Something inside a block (a button’s link, a list’s bullets, the image in a card)	a composite-class state that is a path of children: `> .wp-block-button__link`, `:hover > .wp-block-button__link`, `> li::before`. Each step is `>` and a tag, `*` or classes.
A variant of a text style (on dark, a lighter weight)	a second typography style named after the first (`card-title-on-dark` beside `card-title`) with only what differs, worn beside it. A plain colour change is a colour class beside the style.
Entrance animations (fade or slide in)	`keyframes`, played by a composite class with `animation: <name> 0.6s ease-out both`. The site starts with `animate-from-left`, `animate-from-right` and `animate-from-bottom`.
A section used on several pages	a pattern (`ensure_pattern`)
Header and footer	the `part:header` and `part:footer` places, not page content
Menus	`ensure_menu`, then `core/navigation`. Von Block Builder 1.5.0 also has a menu block of its own (`vonblock/menu`: links written by hand, folding into a panel from the right at a breakpoint); the connector does not write it yet, so leave one that is on a page as it is.

c. Then build

Lay out with classes: display-flex flex-wrap-wrap justify-content-space-between, width-c*, gap-g*, the typography classes and the colour classes. A block can wear several typography classes: a variant beside its base style.
Animate with a class: put animate-from-bottom (or another class that plays a keyframe) on the block. It plays once as the block comes into view, and not at all for visitors who asked for less motion.
Use a block’s customStyles (per breakpoint) for genuine one-offs: a single background image, an unusual padding, a hover on one block.
Put the right tags on things: section, header, nav, footer, heading levels. Add anchors for in-page links.

d. Global CSS is the last resort

ensure_global_css is for what the framework cannot say: descendant selectors, prefers-reduced-motion, @supports, styling third-party markup. Not @keyframes: those go in the keyframes section. Never dump a whole design into global CSS: the framework then can’t help, the editor won’t show it, and nobody can maintain it.

4. Rules and gotchas

update_framework_settings replaces a whole section. Read it first and send it back complete, with your change in it.
It asks first. Framework and global-CSS writes return a confirm token. Say what will change, wait for the person to agree, then resend the identical payload with the token. Every save is versioned and can be reverted.
Composite classes compile without the mcg- prefix (.card, .hud), while generated utilities are .mcg-*. Global CSS must target them accordingly.
A class is on the block’s wrapper. What is inside it is styled with a state that is a path of children: a button has no look of its own until a class styles its > .wp-block-button__link.
What wins: typography styles are written first, sorted by name; composite, utility and colour classes come after them. So a variant named after its base wins over it, and a colour or utility class beside a typography class wins too.
Animations: leave them off the hero and anything in the first screen, which should be there at once. Don’t add animation-timeline: view(): tying many blocks to the scroll makes a long page stutter.
core/buttons is not flex by default in the builder theme: give it display-flex flex-wrap-wrap gap-g1.
Set block margins explicitly (margin-bottom-* classes or a customStyles margin). Don’t rely on WordPress block-gap.
A colour value never goes into properties_custom: a # can’t be part of a class name, and it breaks the build. Colours belong in colors.
Grid units are whole units. If a design value isn’t on the grid (e.g. a 420 px image height), keep it as px in customStyles rather than forcing a wrong unit.
Images: upload_media fetches from a public URL. Upload first, then use the media id and url in core/image.
core/html saves exactly what you write and carries no classes. Wrap it in a group when it needs them, and prefer real blocks.

5. From Figma (with the Figma connector)

The Figma connector gives exact values. Map them directly:

Variable modes for the grid (e.g. m1, g1, c1…c12, one mode per breakpoint) become rule_sets. Read the frame widths and the layout-grid settings.
Widths bound to c* variables become width-c* classes for that breakpoint. Bound paddings and gaps become padding-inline-m1, gap-g1 and so on.
Colour variables become colors.
Text styles, and the font-size variables per mode, become typography_styles with per-breakpoint sizes.
Auto layout: horizontal + space-between becomes display-flex justify-content-space-between; wrap becomes flex-wrap-wrap; fill/hug becomes width classes or none; spacer frames become margins.
Repeated frames (cards, chips, framed images) become composite_classes.
Images: download_assets on the top frame returns every raw image. Pass those URLs straight to upload_media.
Compare all breakpoint frames to work out what changes per band, and write only those overrides (md-…, sm-…).

6. From any live site

Open it at each breakpoint width and read the computed styles: colours, font families and sizes, the container width and its side padding.
Derive the margin and gutter from where the content starts and how wide the columns are, then express widths in MCG units.
Collect what repeats, and turn it into typography styles, colour slugs and composite classes, as in section 3.

7. Check your work

check_layout: rows that overflow at any breakpoint (pure arithmetic).
preview_page or a browser at each breakpoint width: compare against the source, section by section.
Publish only once it has been looked at (create_page makes drafts; publish_page puts them live).

8. Don’t

Don’t put everything into global CSS or into one-off inline styles.
Don’t invent class names: search_classes first.
Don’t overwrite framework sections, headers, footers or pages that other content depends on without saying what will change and getting a yes.
Don’t approximate grid widths with percentages when an MCG unit fits.