Blocks and components

Building blocks visually

Build a block lets you make a block by clicking. Every choice comes from your design tokens, and every change is a small, exact edit to the block’s file.

Build a block is a workshop for the files in blocks/. You add pieces to a live preview, pick an element, and choose its layout, spacing, colour and type from your design tokens. Each choice is written straight into the block's file, so the result is the same file you would have written by hand.

Opening the builder

Use the cube button in the bar, Build a block in the page menu on a phone, or the command palette. To change a block that's already on the page, open the More menu on its handle and choose Change this block.

Opened on its own, the builder asks what you want to do:

  • Start from scratch makes an empty block at page width.
  • Start from an existing block makes a copy with a new name, so pages that use the original don't change.
  • Change a block you have opens it. Each block says how many pages it's on, and changes show on all of them.

Name a new block the way you'd say it, like “Project facts”. The file gets a tidy name, blocks/project-facts.html.

The preview shows the block the way it sits on a page: with the head of its page type, and inside the same elements as the block area it's used in. A block that lives on a white panel is shown on that panel. Fields show their labels and images show a placeholder. Click any element to select it. View code shows the file as it stands. Close the builder, or press Escape, and the page reloads with your changes.

Adding pieces

The Elements list shows the block as a tree. Select an element, and the pieces below it are added inside it, or after it when it holds words. Each piece that holds content arrives as a field with a name that isn't taken yet, and the builder asks you to name it, like “Price”.

GroupPieces
LayoutBox, Row, Column
Words and picturesHeading, Small heading, Text, Rich text, Image, Link, Button, Quote, and Fixed words, which are the same everywhere the block is used
ListsBlock area, List of pages, List of items, Count of pages, and Previous and next pages once the block has a list split into pages
This pageIts title, date, description and tags
Every pageText on every page, a shared field
Each page in the listInside a list of pages: its title, date, description, image, one of its fields, a link to it, and its tags

Inside a list of items, every item gets what you add, and you can't add another list or a block area there.

The tools at the top of the Elements list move the selected element up or down, make a copy, wrap it in a box, unwrap it, or remove it. The outer element can't be removed, because a block needs one; delete the file to remove the whole block. Renaming a field moves the words on pages along with it. Removing a field that pages have filled in says which pages lose words, with an Undo button.

Lists and conditions

Lists and conditions show in the Elements list too. Select one to change it.

  • A list of pages chooses its folder, its order (newest, oldest, A to Z, Z to A, or the order in the site view), how many to show and how many to leave out first. It can leave out the page it's on, split into pages, and keep only pages with a tag or a field that's filled in, empty or set to a value. When there are none holds the words to show instead. See Lists of pages.
  • Show only when…, in an element's Content section, shows it only when a field is filled in, is empty, is a value or isn't. Otherwise show picks nothing, some words, or the element after it.
  • A list of items is a repeater. Name it, like “People”, and writers add items on the page with Add to People. Build one item, and every item looks the same.

Choosing styles

The inspector shows the choices for the selected element:

SectionChoices
ContentThe field's name, a date's format, how much of a text to show, which tools a rich text field allows, and whether writers choose a background or text colour on the page
ShapeFor images: as it is, landscape, square, portrait or wide. Pictures are cropped to fit
WidthFor the outer element: full width, or page width to line up with the rest of the site
LayoutRow, column, stack or grid. A grid sets its columns for phones, tablets and desktops; a row or column lines its children up across and down
SpacingPadding, gap and margin, drawn as a ruler of your spacing tokens
ColourBackground and text, as swatches of your colour tokens
TypeTypeface, size, weight and line height, each shown in its own style
Corners and shadowRounding and your shadow tokens
ClassesThe element's whole class list. Choices above change only their own part of it

There is no box for typing a value. Everything comes from the tokens Elevate knows about, so a block built here can't drift from the design system. Add a token in the Design panel and it is offered the next time you open the builder. Choosing the value that is already set turns it off.

Screen sizes

The switch at the top lists All sizes and then every one of the site's screen sizes, narrowest first. With All sizes chosen, a choice applies everywhere. Choose Tablets and the preview narrows to where tablets start (768px, scaled down if your window is smaller), and the next choice applies from there up: the builder writes it after the /md/ marker at the end of the class list.

At a size, the inspector shows what's set for that size. A choice with a dashed outline is one the element gets from a smaller size: pick something else to change it from here up. A dot on a size in the switch means the selected element has its own styles there.

<section class="col gap:d4 pd:d6 /md/ row gap:d8 pd:d10">

Surgical edits

The builder never rewrites a file from scratch. Each change is made at an exact place in the source: one class swapped inside one class attribute, one element inserted, moved or removed. Everything else stays byte for byte as it was, including your indentation, comments, attribute order, fields, conditions and classes the builder has no picker for.

So you can go back and forth. Build a block by clicking, refine it by hand in your editor, and open it in the builder again: your hand-written parts are left alone. A git diff after a builder change shows only the class or element that changed.

Before a change is written, Elevate checks the new class string. A choice that would make an invalid class is refused with Elevate's own message, and nothing is written. Classes that were already wrong aren't blamed on the choice.

Deleting a block

Choose the block and press the bin in the builder's header. If no page uses it, its file is deleted. If pages do use it, Verso says how many and asks first; Delete it everywhere removes the file and takes the block off every page, shared area and starting layout. A block that's part of a saved component has to come out of the component first.

What it doesn't do

  • Edit page templates. The builder works on blocks/ only.
  • Offer every Elevate property. Borders, positioning, transitions and states like @hover are written by hand, and the builder keeps them.
  • Fill in fields. Writers do that on the page, like any other.