How Breaking Bedrock Simplifies Layout Design

There’s a moment in every design system’s life when the small compromises add up—one more alias, one more “temporary” prop, one more legacy fallback. Over time, those conveniences stop being conveniences. They become friction.

This release is about clearing that friction out. It’s a tightening pass on Bedrock Layout: fewer legacy props, clearer semantics, and a stronger alignment with native CSS.

The shape of the change

We’re not trying to be clever here. The breaking changes are intentionally boring—in the best way. They make the system easier to reason about and easier to teach.

Gap means gap

The old gutter prop is gone. We now use gap everywhere. That’s the vocabulary CSS already gives us, and it’s the one everyone already understands.

Migration:

• Replace gutter with gap anywhere you’re using layout primitives.

Columns now say what they mean

columns was ambiguous. colCount isn’t. It reads like a config value, not a layout command. That clarity matters.

Migration:

• Replace columns={...} with colCount={...}.

Custom spacing without a theme provider

The docs now emphasize the simplest, most portable path: if you want to plug in your own spacing tokens, use CSS custom properties directly.

Example:

<Stack gap="var(--space-3)">{...}</Stack>

No magic. No wrapper. Just your tokens.

Column offsets now match the CSS API

We aligned offset variables to the CSS-side naming (--offset-start / --offset-end). It’s a consistency fix—no behavioral change—but it eliminates a mismatch that was easy to trip over.

Components removed to reduce surface area

Some components have been removed rather than kept as thin wrappers. The goal is to keep the core primitives focused and avoid maintaining redundant APIs. This means AppBoundary and PadBox Components are gone. MasonryGrid has also been removed, as the new native Masonry layout spec is being developed.

Migration:

• Replace removed components with the recommended primitives (e.g., layout primitives plus style or small wrapper components).

Utility hooks moved to a separate repo

Legacy utility hooks have been migrated from this repo to a dedicated package. They’re still available, just no longer part of the core Bedrock Layout surface.

Migration:

• Install and import the hooks from the new utilities package rather than from the main Bedrock Layout repo.

Why we’re doing this

The core goal is to make Bedrock Layout boringly predictable. That means:

• fewer aliases,

• fewer “legacy” escape hatches,

• and fewer places where the docs disagree with the code.

If you’re upgrading, the migration is straightforward and mechanical. But the payoff is bigger than a clean diff: it’s a layout system that’s easier to explain, easier to onboard to, and easier to keep stable long-term.