Imperial Arachno Academy · Est. 1440
Learn to build better webs with Von Block
A free course in the Von Block Editor. Start with the basic ideas (the grid, classes and custom styles), then work through the lessons one at a time until you can lay out any page with confidence.
Tip: make your browser window narrower and wider as you read. The examples on this page respond to its width, just as your own pages will.
On this page
Seven concepts, one at a time
Each concept builds on the one before, so they are best read in order. After them come three things beginners get wrong, and then the Example page, where one real hero is taken apart in the Von Block Editor, concept by concept.
1
The grid
Margins, columns and gutters: the three units, m, c and g, that every size in Von Block is measured in.
2
Breakpoints
How the grid changes with the size of the screen, and how a prefix such as lg- makes a class apply only there.
3
Colors
Name a color once, and get its classes, a CSS variable and a swatch in the editor’s color picker.
4
Fonts
Font files kept on your own site, one per style where you can, for typography classes to use by name.
5
Typography classes
A named way of setting text, with its sizes for every breakpoint, turned into a class you put on a block.
6
Utility classes
One property, one value, one class, made for every breakpoint: the classes a block’s layout is written in.
7
Composite classes
Several declarations that belong together, under a name of your own: a card, a button, a band of the page.
Concept 1
The grid: margins, columns, gutters
Everything in Von Block is measured on one grid, the same kind you draw in Figma. It has three parts, and they give the framework its old name, MCG. Switch the grid on with the button in the bottom-right corner, and scroll: every section of this page is laid out on it.
m margins
The space on each side of the page. It keeps its size in pixels. m1 is one margin, so padding-inline-m1 lines content up with the page.
c columns
This site has 12. Columns are the only part that stretches with the page. c6 is six columns and the five gutters between them.
g gutters
The fixed space between two columns. g1 is one gutter, which makes gap-g1 the gap that keeps things on the grid.
This grid is also what makes Claude’s translations from Figma to WordPress, through the Von Block MCP connector, come out perfect. The design and the page share one grid, so every margin, column and gutter in a Figma frame maps straight to an MCG class: nothing to guess, nothing to round.
Here is that grid, laid over the page the way Figma lays a layout grid over a frame. It is this page’s own grid at your window’s width: the blue bands are the margins, the red stripes the 12 columns, and the clear strips between them the gutters. Under it is a small real layout: a wrapper across the whole page with two containers inside, each built with nothing but the classes written on it.
The classes in this example, such as width-c2g2, padding-g1 or display-flex, are so-called utility classes: each one sets a single property to a single value. They get a chapter of their own later; for now, watch what their MCG units do.
display-flexflex-flow-rowjustify-content-space-betweenpadding-bottom-50pxpadding-inline-m1c2padding-top-150pxwidth-m2c12lg-padding-inline-m1c1md-flex-flow-columnmd-gap-g1md-padding-inline-m1
Some of these classes carry a breakpoint’s name in front: they take over at that breakpoint and below. Make your browser window narrower and watch the example change at 1024px (lg) and again at 767px (md), with the grid over it following along.
- width:
width-m2c12spans the whole page.width-c2g2andwidth-c3g2size the blocks in columns plus outer gutters; thegnumber never counts the gutters between the columns.lg-width-c3g2widens the first block on smaller screens, andmd-width-c12makes it full width on phones. - display, flex-flow and justify-content:
display-flex,flex-flow-row,md-flex-flow-columnandjustify-content-space-betweenare utility classes too. A utility class can be set up from any value a property takes, not only numbers and MCG units: words like flex, row or space-between work just the same. - padding, margin and gap:
padding-inline-m1c2keeps the wrapper’s content off the margin and first two columns on each side.margin-left-c1g1andmargin-right-c1g1move the blocks in by a further column and gutter, andpadding-g1sets their content exactly on the columns. Thelg-andmd-versions retune this for smaller screens;md-margin-left-0drops the margin where the first block is full width, andmd-gap-g1keeps a gutter between the blocks once they stack. - padding-top and padding-bottom:
padding-top-150pxandpadding-bottom-50pxuse plain pixels. Utility classes take regular CSS units as well:px,%,rem,vhor whatever the property accepts. The grid is a tool, not a dogma: use MCG units where a measure belongs to the grid, and any other unit where it does not.
Units are always written in the order m, c, g, and a unit you don’t need is left out: c3g2, not m0c3g2. c12 is everything inside the margins, and m2c12 is the whole page. The units work on every property that has the “MCG Units” box ticked in your framework’s Utility Classes; here that is width, margin-left, margin-right, padding, padding-inline, gap and max-width.
Make the window narrower and watch the grid: the margins and gutters keep their size, and only the columns shrink. Every measure follows, because a class like width-c6 is worked out from the grid, not stored in pixels.
Concept 2
Breakpoints: the grid, adjusted to every screen size
A breakpoint says how the grid behaves up to a certain width. You can set up as many breakpoints as your designs need, at whatever screen widths they need them, and name each one as you please: the name becomes the prefix of its classes, so tablet-width-c6 works just as well as lg-width-c6.
This site uses three breakpoints
Make your browser window wider and narrower, and watch the three boxes: the one that glows is the breakpoint this page is in right now. Switch the grid on with the button in the bottom-right corner as well, and you will see the margins and gutters jump at 1280px, 1024px and 767px, while the columns stretch or shrink to fill what is left.
● You are here
default
Every width, up to a page 1440px wide.
Margin 80px · gutter 30px
One breakpoint can hold more than one layout grid: from 1280px down the margin narrows to 55px, with the same classes.
● You are here
lg-
1024px and below.
Margin 40px · gutter 24px
● You are here
md-
767px and below, phones included.
Margin 20px · gutter 16px
How they are set up
Breakpoints are set on the Von Block settings page in wp-admin. This is that editor, the real one, filled with this site’s three breakpoints: each has a name, a screen width, a margin and a gutter, and the column count is set once for all of them. Try it: change a width, rename one, or add a breakpoint in the empty last row. Nothing is saved here; on your own site, “Apply settings” turns what you set into the stylesheet.
Concept 3
Colors: name them once, use them everywhere
Every color in your design gets a name in the Von Block settings. From that name the framework makes classes, a CSS variable and a swatch in the block editor’s color picker, so changing the color in one place changes it everywhere on the site.
What one color gives you
Take primary, the red of this site. Naming it once gives you three classes, one for each property that takes a color:
Aa
color-primary
the text
Aa
background-color-primary
the background
Aa
border-color-primary
the border
It also gives you the variable --mcg-color-primary, for the places no class reaches. A custom style, a shadow for instance, can take var(--mcg-color-primary) as its color: it is the same red, and follows it if the red ever changes.
And it puts a swatch in the block editor’s color picker, so a paragraph or a button colored by hand uses the same red too.
This site uses twelve colors, named for their jobs
Each name says what the color does, not what it looks like: base is the page background, contrast the text, primary the brand color for buttons and links, surface the light bands, border the lines. If the red turned blue tomorrow, primary would still be the right name.
base is also marked as the page’s background, so <body> takes it. A color can be marked as the page’s text color the same way.
base
page background
#ffffff
contrast
body text
#231c15
contrast-strong
headings, outlines
#16120e
muted
quieter text
#6b6155
primary
brand: buttons, links
#a4161a
primary-dark
primary on hover
#7f0f13
secondary
accents, eyebrows
#c9971c
secondary-light
lighter accents
#e9c25a
secondary-pale
accent backgrounds
#f6e7bf
surface
light bands
#fbf6ea
surface-alt
alternate bands
#f3e9d2
border
lines, card borders
#e6dcc6
How they are set up
This is the Colors part of the Von Block settings page, the real one, filled in with this site’s colors. Try it: add a color, rename one, change a value. Nothing here is saved.
Each color has an opacity as well as its red, green and blue, so a see-through black for shadows or overlays is a color like any other.
Naming colors
Four rules, the same ones professional design systems follow.
Name them for their job, not their hue
primary, surface and border still make sense after a rebrand; red doesn’t, once the red turns blue. Material Design names its colors this way, and so does Figma’s own interface. WordPress asks for base (the background) and contrast (the text) too, and Von Block hands your names to the editor’s color picker.
Use the same names as in Figma
Designers keep two layers of color variables: raw colors named by hue and shade, like red/500, and roles that point to them, like bg/brand or text/default. Von Block’s colors are the roles. The class already names the element, so Figma’s bg/primary is background-color-primary. Keep the names the same, and a design translates to the site one to one.
Change the color, not the name
The name is in every class you have used. Change the value of primary and every red on the site follows; rename it, and blocks still asking for color-primary get nothing.
Primary, secondary, accent
In interface design, primary is the main brand color, used for the key actions such as buttons; secondary supports it; an accent is for small highlights. It is not the 60% of the 60-30-10 rule, which is usually a neutral background: here that is base and surface.
Concept 4
Fonts: your own files, served by your own site
A font in Von Block is a set of files you keep on your own site. Upload them once in the settings, say what each file is, and every typography class can use the family by name. Visitors never ask Google, or anyone else, for them.
What a font face is
Each file you upload is one face: one cut of a family. Beside the file you say what it is, in the same words CSS uses for it:
font-family
The name typography classes ask for. Here that is fraunces for the headings and work-sans for the text.
font-weight
One weight, such as 700, or a range, such as 400 700, for a variable font: one file that draws every weight in between.
font-style
normal or italic. An italic is a file of its own, or a second range of a variable font.
font-display
What happens while the file loads. swap shows the text at once in a fallback font and swaps it when the file arrives, so nothing waits on a font.
unicode-range
Which characters the file draws. Needed only when a font is split into subsets: it tells the browser which file to fetch for which letters.
This site uses two fonts, one file each
Both are variable fonts, so a single file covers every weight the site uses, and each file holds the Latin alphabet together with the letters of German, Hungarian, Czech and the other Central European languages. The samples say the same thing in English, German, Hungarian and Czech.
Fraunces
The headings. fraunces, weights 700 900, one file of 58 KB.
Fraunces 700
Stronger webs · Stärkere Netze · Erősebb hálók · Silnější sítě
Fraunces 800
Stronger webs · Stärkere Netze · Erősebb hálók · Silnější sítě
Fraunces 900
Stronger webs · Stärkere Netze · Erősebb hálók · Silnější sítě
Work Sans
The text, the buttons and the labels. work-sans, weights 400 700, one file of 76 KB.
Work Sans 400
Learn to build better webs · Lerne, bessere Netze zu bauen · Tanulj meg jobb hálókat építeni · Nauč se stavět lepší sítě
Work Sans 500
Learn to build better webs · Lerne, bessere Netze zu bauen · Tanulj meg jobb hálókat építeni · Nauč se stavět lepší sítě
Work Sans 600
Learn to build better webs · Lerne, bessere Netze zu bauen · Tanulj meg jobb hálókat építeni · Nauč se stavět lepší sítě
Work Sans 700
Learn to build better webs · Lerne, bessere Netze zu bauen · Tanulj meg jobb hálókat építeni · Nauč se stavět lepší sítě
How they are set up
This is the Fonts part of the Von Block settings page, the real one, with this site’s two files. Try it: upload a font file from your computer and fill in its family and weight. The file stays in your browser, and nothing here is saved.
Good to know
One file per style, when you can
A variable font draws every weight from one file, so the whole family is one download. Declare it with its range, 400 700, rather than as one face per weight pointing at the same file.
Subsets need their ranges
Google cuts fonts into subsets: latin holds A to Z, latin-ext the letters such as č, ő and ł, and not A to Z. Keep them as one combined file, or give each its unicode-range; without it, the later file hides the earlier one, and the settings page warns you.
Your files, on your server
Loading fonts from Google’s servers hands every visitor’s IP address to Google. In 2022 a court in Munich awarded a visitor damages for exactly that. A font kept on your own site sends nothing anywhere.
Claude can add one for you
Ask for a Google font by name, with the weights you want, and Claude fetches it, keeps it on your site as one file per style, and adds it to the settings, ready for a typography class.
Concept 5
Typography classes: every kind of text, named once
A typography style is a named way of setting text: its font, size, weight, line height, colour and anything else text needs, with its own sizes for each breakpoint. Von Block turns each one into a class, so typo-h-xl on a heading makes it this site’s big heading on every screen.
This site’s styles, as they are
Each line below is set in the style it names. Make the window narrower: the headings step down in size at each breakpoint, because the sizes are part of the style, not something you add per block.
typo-hero
56px · 44px in lg · 34px in md
Build better webs
typo-h-xl
46px · 40px in lg · 30px in md
Every heading has a name
typo-h-lg
38px · 34px in lg · 28px in md
Styles for every screen
typo-h-md
21px at every width
A heading for a card
typo-lead
20px · 18px in md
One style, written once, for every screen the page will ever meet.
typo-copy-lg
18px · 16px in md
Larger text, for an introduction.
typo-copy
16px at every width
Ordinary text, for everything else on the page.
typo-eyebrow
13px at every width
Concept 5 · Typography
typo-nav-main
15px at every width
Features · Install · Pricing · FAQ
typo-btn-red
16px at every width
The last one is a button style with a state: move the mouse over it and it turns darker. A style can say what changes on :hover, on :focus, or in a ::before, so a button needs no custom style of its own.
What one style gives you
Take h-xl: Fraunces, 700, 46px on 54px, a dark colour and a touch of negative letter spacing; 40px in lg and 30px in md. From that one style you get:
typo-h-xl
The whole style on one block: font, size, weight, line height, colour, spacing, at every breakpoint.
typo-h-xl-font-size
Only the size, still following the breakpoints, for a block that should be as big as a heading but keep its own look.
A style named after a tag
Call a style h2 or p and it styles every h2 or p on the site, with no class at all. This site names its styles by role instead, so nothing is styled by accident.
The default style
One style is marked as the default, here base: it gives the whole page its ordinary text, so a block with no typography class still reads right.
How they are set up
This is the Typography part of the Von Block settings page, the real one, with five of this site’s 28 styles: the default, a heading, the lead, the text and a button. Change a size for md, add a property for :hover. Nothing here is saved.
Good to know
Name them for their role
h-xl, lead, nav-main: like colours, a style named for what it is for survives a redesign. A name like red-46 does not.
Sizes live in the style
Give a style its size for each breakpoint once, and every block that uses it follows. There is no need for a class per band on each heading.
A few styles go a long way
Most sites need a handful of headings, a lead, a text size or two, a label and the buttons. This site has twenty-eight, and this page, one of its longest, uses fifteen.
One per block
A block takes one typography class; putting on another replaces it. Two would not stack in an order you could see on the block, so for a base and a variant split the work: the shape in a composite class, the type and its colours in the typography class. A red button here is btn with typo-btn-red.
Concept 6
Utility classes: one property, one value, one class
A utility class does one job. width-c6 sets a width, display-flex makes a row, gap-g1 puts a gutter between things. You stack as many as a block needs, and each breakpoint has its own copies, so a block’s whole layout is written in its list of classes.
Reading a block’s classes
A row of three, laid out with nothing but utility classes. The row carries display-flex, gap-g1 and md-flex-direction-column; each tile carries its own width. Make the window narrower than 767px and the row turns into a column.
width-c4
md-width-c12
width-c4
md-width-c12
width-c4
md-width-c12
display-flexandmd-flex-direction-columnare value classes: a property and one of the values listed for it.gap-g1,width-c4andmd-width-c12are grid-unit classes: a property and a measure of the grid, which follows the grid at every width.- Three
c4and the two gutters between them make exactlyc12, the width of the page, so the row fits with nothing left over.
How a class gets its name
Nobody writes utility classes out. You say which properties you want and which values, and the framework makes every class, for every breakpoint, following the same few rules.
Grid units
A property and a measure: width-c4, padding-m1c1g1, margin-left-0. Every combination the grid allows is made for each property on the list; this site lists 7 of them.
Values
A property and a value: display-flex, padding-top-150px. A % is written pct, so 100% is width-100pct, and anything else a class name cannot hold becomes a dash: repeat(3, 1fr) is grid-template-columns-repeat-3-1fr.
A breakpoint in front
Every class is made again for each breakpoint, with its name in front: md-width-c12 is width-c12 at 767px and narrower.
Aliases, when a name is long
A property can be given a shorter name for its classes. With the alias ml, margin-left-m1c2g1 becomes ml-m1c2g1. Two properties never share one.
mcg- on the page
You write width-c4; on the page it is mcg-width-c4. Von Block adds the prefix to every class it makes, so they never clash with a theme’s or a plugin’s.
How they are set up
This is the Classes part of the Von Block settings page, the real one, with this site’s 23 properties. A row is a property: tick grid units and it gets every grid measure, type values and it gets a class for each. Nothing here is saved.
Good to know
Only what is in the settings exists
A class the framework does not make does nothing at all. The Von Block Editor refuses one it could never make, and offers to add the value when it could, as the Editor page shows.
When two classes disagree
The later kind wins: a utility class beats a composite class, so card padding-top-30px is a card with less padding at the top; a typography class beats a utility class that sets the same thing; the colour classes come last and beat both. Within one kind, the narrower breakpoint wins.
Add values as designs need them
Each value is one class for every breakpoint, three here. Adding the values a design really uses keeps the stylesheet small; adding every value that might come in handy does not.
Concept 7
Composite classes: your own recipes, written once
Some blocks want the same handful of declarations every time: a card’s background, border, corners, shadow and padding. A composite class is that handful under a name you choose, with its own values for each breakpoint and for states such as :hover. Write it once, and every block that carries the name looks the same.
One name, many declarations
Every gold number on this page, like the ones in the summary at the top, is circle-num. Here is all of it, and what it looks like:
.circle-num { width: 60px; height: 60px; border-radius: 50%; background-color: #c9971c; border: 2px solid #16120e; text-align: center; flex-shrink: 0; margin: 0;}
7
Eight declarations, one class: circle-num.
A base, and the adjustments
Composite classes come first in the stylesheet, so a utility class on the same block adjusts them: the composite class is the base, the utility class the change for this one block.
circle-num background-color-primary
7
The same circle in the primary colour: the colour class wins over the circle’s own gold.
stack gap-16px
one
two
three
stack makes a column; gap-16px decides how far apart its blocks are, block by block.
section
Every band of this page. Its padding shrinks with the screen: 100px, then 80px in lg, then 60px in md, all in one class.
Which kind of class?
Three kinds, three jobs. Most blocks carry some of each.
One property, one value
A utility class: display-flex, width-c6, padding-top-60px. It is made for you, for every breakpoint.
A way of setting text
A typography class: typo-h-xl, typo-lead. Font, size, weight and colour, with sizes per breakpoint.
Several declarations that belong together
A composite class: card, section, stack. Written out by you, under a name of your own.
No prefix
A composite class is written as you name it: card on the page, not mcg-card. Names starting with mcg- or wp- are refused, and so is the name of a class the framework ships.
The framework’s own: bleed
Every site has it. A block with it keeps its content on the grid while its background runs to both edges of the window, as the coloured bands of this page do.
Names are yours, collisions too
A card in your theme or a plugin styles the same blocks as your own card. Before you name one, check the theme does not already use the name.
How they are set up
This is the Composite Classes part of the Von Block settings page, the real one, with four of this site’s 43: section, section-compact, stack and circle-num. On a real site the framework’s own, such as bleed, are listed under them, read-only. Add a declaration for md, or a :hover; nothing here is saved.
In the block editor, the Von Block Editor shows a block’s composite classes as pills beside “block”. Choose one, and what you type goes into that class, for every block that carries it, and the framework is rebuilt; + composite puts a class on the block, or starts a new one.
Before you start
Three things beginners get wrong
A row has to add up
Four blocks of width-c4 is valid CSS and still wrong: three fit, the fourth wraps. Count the columns and the gaps: four c3 and three g1 gaps make c12.
Don’t count the inner gutters
c6 already includes the five gutters between its columns. Only gutters outside the columns are written: c6g1.
Breakpoints reach down
An lg- class still applies on a phone. If phones need something else, give them an md- class too.
Next
One hero, concept by concept
You know the concepts. The Example page puts them together: a real café hero, live, and then taken apart in the Von Block Editor, one concept at a time.
Try it now
Take the reins yourself
Reading about it is one thing; ruling it is another. Pick your way in: build by hand in a WordPress that runs right in your browser, or take a real demo site for an hour and let Claude build it while you give the orders. Nothing to install and no account in either.
WP Playground (no Claude)
A whole WordPress with Von Block that runs right in your browser. It is never busy, and what you change stays in your browser. Everything works there except Claude, which cannot reach a site inside your browser: take the hero apart here while the demo sites are taken.
Claude enabled demo site
A real WordPress site with Von Block, yours for an hour. Connect Claude to it and ask for a page. It requires a Claude subscription, and you connect to the site through a Claude Connector in Settings → Connectors.
There are only a few of these sites, so at times they are all taken; the button says when the next one is free.