Layout System

How building blocks are arranged on the page using the grid, grouping, and sizing system.

This page explains how building blocks are arranged on the page. The grid, grouping, and sizing system.

What Is the Layout System?

The layout system decides where things go on the page. It controls:

How wide each section is.
Whether things sit side by side or stacked on top of each other.
How much space is between them.

Think of it like arranging boxes on a table. You decide how big each box is, whether to line them up in a row or stack them, and how much gap to leave between them.

The 12-Column Grid

The page is divided into 12 invisible columns of equal width. Every building block takes up a certain number of these columns.

Here is how it works:

Columns used	How wide it looks
12	Full width (the entire page)
9	Three-quarters of the page
6	Half the page
4	One-third of the page
3	One-quarter of the page
2	One-sixth of the page

Example: On a typical desktop search results page:

The filter panel takes up 3 columns (one-quarter of the page).
The product grid takes up 9 columns (three-quarters of the page).
Together they fill all 12 columns.

|--- 3 cols ---|---------- 9 cols -----------|
|              |                             |
|   Filters    |      Product Grid           |
|              |                             |

Horizontal vs Vertical

Building blocks inside a group can be arranged in two directions:

Horizontal

Building blocks are placed side by side in a row, from left to right.

[ Filters ] [ Product Grid ]

This is the typical desktop layout.

Vertical

Building blocks are placed on top of each other, from top to bottom.

[ Filters button ]
[ Product Grid   ]

This is the typical mobile layout.

Grouping with Containers

Sometimes you need to put several building blocks together inside a group. The SDK uses containers for this.

A container is like a box that holds other building blocks (or even other containers). It does not show anything visible itself. It just groups things together and controls their arrangement.

Example: On the search results page, the right side (next to the filters) might contain:

A container holding the result count and sorting side by side.
Below that, the product grid.
Below that, the pagination.

+------ Right side (9 columns) ------+
| [ Result count ]  [ Sorting v ]    |   <- horizontal container
|                                    |
| +--------+  +--------+  +--------+ |
| |Product |  |Product |  |Product | |   <- product grid
| +--------+  +--------+  +--------+ |
|                                    |
|       [ < 1  2  3  4  5  > ]       |   <- pagination
+------------------------------------+

Containers can be nested. A container can hold another container, which holds another container. This lets you create complex layouts by combining simple pieces.

Spacing (Gap)

You can control the space between building blocks inside a container. The gap goes from 0 (no space) to 10.

Gap value	Actual space
0	No gap
1	Very small (0.25rem)
2	Small (0.5rem)
4	Medium (1rem)
8	Large (2rem)
10	Extra large (2.5rem)

Alignment

Inside a container, you can control how building blocks are aligned:

Alignment	What it means
Start	Everything is pushed to the left (or top).
End	Everything is pushed to the right (or bottom).
Center	Everything is centered.
Between	Items are spread out with equal space between them. The first item is at the start, the last item is at the end.
Around	Items are spread out with equal space around each one.

Example: If you have a result count on the left and a sorting dropdown on the right, you would use the “between” alignment:

[ 85 results for "shoes" ]           [ Sort by: Price v ]
^                                                       ^
start                                                 end

Putting It All Together: A Desktop Example

Here is how a typical desktop search results page is built from the layout system:

+============== Main container (12 columns, horizontal) ==============+
|                                                                     |
| +-- 3 cols --+  +-------------- 9 cols --------------------------+  |
| |            |  |                                                |  |
| |            |  | [ Result count ]              [ Sort by: v ]   |  |
| |            |  |                                                |  |
| |  Filters   |  | [ Brand: Nike x ] [ Color: Black x ]           |  |
| |            |  |                                                |  |
| |  Brand     |  | [ ~~~ Banner - header position ~~~ ]           |  |
| |  Price     |  |                                                |  |
| |  Color     |  | +--------+  +--------+  +--------+  +------+   |  |
| |  Size      |  | |Product |  |Product |  |Product |  |Prod. |   |  |
| |            |  | +--------+  +--------+  +--------+  +------+   |  |
| |            |  | +--------+  +--------+  +--------+  +------+   |  |
| |            |  | |Product |  |Product |  |Product |  |Prod. |   |  |
| |            |  | +--------+  +--------+  +--------+  +------+   |  |
| |            |  |                                                |  |
| |            |  | [ ~~~ Banner - footer position ~~~ ]           |  |
| |            |  |                                                |  |
| |            |  |          [ < 1  2  3  4  5  > ]                |  |
| +------------+  +-------------------------------------------------+ |
|                                                                     |
+=====================================================================+

And here is how a mobile version might look:

+==== Main container (12 columns, vertical) ====+
|                                               |
| [ Filters ]              [ Sort by: v ]       |
|                                               |
| [ Brand: Nike x ] [ Color: Black x ]          |
|                                               |
| +----------+  +----------+                    |
| | Product  |  | Product  |                    |
| +----------+  +----------+                    |
| +----------+  +----------+                    |
| | Product  |  | Product  |                    |
| +----------+  +----------+                    |
|                                               |
|            [ Load more ]                      |
|                                               |
+===============================================+

Summary

Concept	What it means
12-column grid	The page is divided into 12 equal columns. Each building block takes up some of those columns.
Horizontal	Building blocks sit side by side in a row.
Vertical	Building blocks are stacked on top of each other.
Containers	Invisible boxes that group building blocks together. Can be nested.
Gap	The space between building blocks inside a container.
Alignment	How building blocks are positioned inside their container (start, center, between, etc.).

Configuration Reference (for developers)

Each node in the layout tree is a plain object. The RenderComponent function in src/components/render-component/render-component.jsx recursively walks the tree. Container nodes (main, separator, mainSearchbox) render a Separator wrapper and recurse into their children. Leaf nodes render the actual building block via getComponentByName().

Each building block receives its options through the LayoutProvider (src/providers/layout-provider.jsx), which merges componentOptions from the layout config with DEFAULT_OPTIONS from src/providers/constants.js.

Layout node properties

{
  component: 'productList',       // The building block name or container ('main', 'separator')
  width: 12,                      // Number of columns out of 12
  viewMode: 'horizontal',         // 'horizontal' or 'vertical'
  children: [ /* ... */ ],        // Child nodes (only for containers)
  justifyContent: 'between',      // 'start', 'end', 'center', 'between', 'around', 'evenly', 'stretch'
  alignItems: 'center',           // Cross-axis alignment
  gap: 2,                         // 0-10 spacing (each unit = 0.25rem)
  styleId: 'my-section',          // Custom identifier for CSS targeting
  componentOptions: { /* ... */ },// Settings passed to the building block
}

Container types

Container string	Role
`main`	The root container. Every layout tree starts with one.
`separator`	A generic grouping container. Can be nested to create complex grids.
`mainSearchbox`	Root container specifically for the search input replacement layout.