space.vars.productName pages need to work on desktop, tablet, and mobile. This guide covers the layout system and the patterns that adapt cleanly across screen sizes.
## The Grid System
### Column-Based Layout
The Grid component supports 1 to 12 columns. Common configurations:
| Columns | Best For |
| ------- | ---------------------------------------------------------- |
| 1 | Single-column content (works well on all screen sizes) |
| 2 | Two-column layouts (sidebar + content, side-by-side cards) |
| 3 | Three-column dashboards, product grids |
| 4 | Four-column metric bars, product grids |
Grid cells are uniform — every block placed inside a Grid takes one cell. Use a smaller `numColumns` plus full-width nested layouts when you want one prominent block alongside smaller ones (e.g. an outer 1-column section with a chart, then a separate Grid below it for the smaller tiles).
## Responsive Behavior
### Automatic Responsiveness
The Page Builder includes built-in responsive behavior:
* **Grid columns collapse.** Below 768px screen width, a multi-column Grid stacks into a single column. Above 768px, the Grid renders the configured number of columns.
* **Rows wrap.** Items in a Row that do not fit horizontally wrap to the next line.
* **Components adjust.** Some components (like Stats) have their own internal breakpoints and reflow independently of the surrounding Grid.
### Verifying responsive behaviour
Before publishing, verify your layout at multiple widths. Resize the browser window or open the published page on the actual devices your users will use.
| Width | Typical device |
| ---------------- | -------------- |
| 1200px and wider | Desktop |
| Around 768px | Tablet |
| Around 375px | Mobile phone |
{% hint style="info" %}
The Page Builder canvas approximates the runtime experience but isn't pixel-identical. For final verification, view the published page in a real browser at the target sizes.
{% endhint %}
### Common Responsive Issues
| Issue | Cause | Solution |
| ---------------------------- | ---------------------------------- | -------------------------------------------------------- |
| Content overflows on mobile | Components have fixed widths | Use relative widths or let components grow to fill space |
| Too much scrolling on mobile | Content spread across many columns | Reduce columns or use stacking |
| Text too small on mobile | Fixed font sizes | Use the theme's built-in responsive sizing |
| Buttons too small to tap | Small button sizes | Use at least "medium" size buttons |
## Designing for Mobile
### Mobile-First Approach
When building pages that will be used on phones or tablets:
1. **Start with a single column.** Everything stacks vertically on mobile.
2. **Add columns for larger screens.** A multi-column Grid will collapse to a single column below 768px and render at the configured column count above that.
3. **Prioritize content.** Put the most important content at the top of the page.
4. **Use large touch targets.** Buttons should be big enough to tap comfortably with a finger.
### Mobile-Specific Tips
* **Pick the right tile component.** Stats reflows to one column below 1024px on its own; Card/Card Link tiles in a Grid collapse to one column below 768px. Pick the one whose breakpoint matches your target screen sizes.
* **Simplify navigation.** Complex navigation is hard to use on small screens. Rely on the sidebar menu.
* **Use full-screen pop-ups on mobile.** Configure Modal size to "full-screen" for workflows used heavily on phones.
* **Test scrolling.** Make sure users can scroll through long content without getting stuck.
## Layout Patterns by Screen Size
### Sidebar + Content
| Screen | Layout |
| ------- | ------------------------------------------------------- |
| Desktop | Sidebar (25%) next to Content (75%) |
| Tablet | Sidebar (30%) next to Content (70%) |
| Mobile | Full-width content with sidebar as a toggleable overlay |
The Catalog Layout component handles this pattern automatically.
### Metric Bar
The **Stats** component renders its own internal grid: a single column below 1024px and two columns above. Drop one Stats block onto the page and configure its items — you don't need to wrap it in a Grid.
For tile-style metric strips that scale linearly (4 across on desktop, fewer on smaller screens), use **Card** or **Card Link** blocks inside a Grid. The Grid will collapse to a single column below 768px.
### POS Layout
| Screen | Layout |
| ------- | ----------------------------------------------------------- |
| Desktop | Order Lines (65%) next to Summary/Payment (35%) |
| Tablet | Order Lines (60%) next to Summary/Payment (40%) |
| Mobile | Order Lines (full width) above Summary/Payment (full width) |
> **Tip:** For POS on mobile, consider using tabs (order entry tab, payment tab) rather than stacking.
## Spacing and Alignment
### Consistent Spacing
Use consistent spacing throughout your pages:
| Spacing | When to Use |
| --------------------- | ------------------------------------------------------------------ |
| Small (8px) | Between closely related items (buttons in a row, fields in a form) |
| Medium (16px) | Between standard components |
| Large (24px) | Between major content sections |
| Extra large (32-40px) | Between distinct page sections |
### Alignment Tips
* **Left-align text** for readability.
* **Center-align headings** sparingly — only for hero sections or centered layouts.
* **Right-align numbers** in tables and stats for easy comparison.
* **Vertically center** items in a Row for clean horizontal layouts.
## Performance
Layout complexity affects how quickly pages render. The basics:
* **Keep nesting shallow** — 3 levels is typical, 5+ is a smell.
* **Prefer Grid over nested Rows** — a 3-column Grid is cleaner than 3 nested Rows.
* **Avoid empty wrappers** — a Column containing one component is usually unnecessary.
For the full performance and pre-publish checklist, see [Best Practices](/client-admin-guide/getting-started/best-practices.md).
## Related
| Layout Components | The Row, Column, Grid, Flex, and Space blocks this guide describes. | Layout Components |
| Common Patterns | Layout recipes for dashboards, order forms, and POS pages. | Common Page Patterns |
| Best Practices | The full pre-publish checklist. | Best Practices |