Breakout Grid

A CSS Grid layout system for content that "breaks out" of containers. No build step required—just CSS.

Inspired by Kevin Powell's video, Ryan Mulligan's Layout Breakouts, and Viget's Fluid Breakout Layout.

Features

- Pure CSS - No JavaScript, no build step, no dependencies
- 5 content widths - From optimal reading width to full viewport
- Responsive gaps - Automatic scaling based on viewport
- CSS variables - Customize by overriding :root properties
- Visual configurator - Optional tool for experimenting and exporting

Installation

$3

Download the CSS file and include it directly:

``html

`

$3

`bash
npm install github:astuteo-llc/breakout-grid
`

Import the CSS in your build:

`js
import '@astuteo/breakout-grid'
// or
import '@astuteo/breakout-grid/css'
`

For the visualizer:

`js
import '@astuteo/breakout-grid/visualizer'
// or lite version
import '@astuteo/breakout-grid/visualizer-lite'
`

Quick Start

1. Add the CSS (see Installation above)

2. Use the grid:
`html


Reading width (optimal for text)

Wider for images

Edge to edge


`

Column Widths

From narrowest to widest:

`
┌─────────────────────────────────────────┐
│ ╔══════════col-full════════════╗ │ Full width (with gap)
│ ╚══════════════════════════════╝ │
│ ╔════col-feature═══════╗ │ Extra wide
│ ╚══════════════════════╝ │
│ ╔═══col-popout══════╗ │ Slightly wider
│ ╚═══════════════════╝ │
│ ╔══col-content═══╗ │ Reading width (default)
│ ╚════════════════╝ │
└─────────────────────────────────────────┘
`

Classes

$3


- .grid-cols-breakout - Main centered grid
- .grid-cols-breakout-subgrid - CSS subgrid for nested alignment
- .grid-cols-{feature|popout|content}-{left|right} - Asymmetric layouts

$3

- .col-full - Edge to edge
- .col-feature - Wide content (images, videos)
- .col-popout - Slightly wider than content
- .col-content - Reading width (default)
- .col-full-limit - Full width with max-width cap

$3

- .col-start-{full|feature|popout|content|center}
- .col-end-{full|feature|popout|content|center}
- .col-{area}-left / .col-{area}-right - Asymmetric spans

$3

- .p-gap, .px-gap, .m-gap, etc. - Gap-based spacing
- .p-breakout, .px-breakout - Responsive padding
- .-mx-gap, .-mx-breakout - Negative margins

Customization

Override CSS variables in your own stylesheet:

`css
:root {
--base-gap: 1.5rem;
--content-max: 50rem;
--popout: minmax(0, 3rem);
}
`

$3

| Variable | Default | Description |
|----------|---------|-------------|
| --base-gap | 1rem | Minimum gap (mobile) |
| --max-gap | 15rem | Maximum gap |
| --content-min | 53rem | Min content width |
| --content-max | 61rem | Max content width |
| --content-base | 75vw | Preferred content width |
| --full-limit | 115rem | Max width for col-full-limit |

See the CSS file header for the complete list.

Visual Configurator

Want to experiment with values before committing? Use the visualizer:

`html


`

Press Ctrl+G / Cmd+G to toggle. Adjust values interactively, then click Export CSS to download your customized stylesheet.

$3

If your project already uses Alpine, import the visualizer before Alpine.start():

`js
import Alpine from 'alpinejs'

if (import.meta.env.DEV) {
await import('@astuteo/breakout-grid/visualizer')
}

Alpine.start()
`

Two versions available:

| Version | Size | Use Case |
|---------|------|----------|
| breakout-grid-visualizer.js | ~124 KB | Config editing + CSS export |
| breakout-grid-visualizer-lite.js | ~31 KB | Read-only debugging |

Common Patterns

$3


`html

Article Title

Body text at comfortable reading width.

Pull quote with slight emphasis.

Full-width section

`

$3

`html

Product Title

Description on the right side.

`

Browser Support

Requires CSS Grid + clamp():
- Chrome 79+
- Firefox 75+
- Safari 13.1+
- Edge 79+

Migration from Tailwind Plugin

If you were using the Tailwind plugin:

1. Remove from tailwind.config.js:
`diff
- import breakoutGrid from '@astuteo/tailwind-breakout-grid'
plugins: [
- breakoutGrid({ ... })
]
`

2. Add the CSS file:
`html

`

3. All class names are identical—no HTML changes needed.

4. If you had custom config, use the visualizer to export matching CSS.

Documentation

- Visualizer - Full configurator with CSS export
- Visualizer Lite - Lightweight read-only version
- Migration Guide - Integrating with existing projects
- Nested Grids - breakout-to-*` modifiers
- Layout Examples - Real-world patterns

License

MIT