Building Features and Finding Bodies
There is a very specific kind of software development where you start the day thinking:
“Today we're building a Page Builder.”
And several hours later you're staring at a footer wondering why it's sitting in the middle of the fucking website.
This was one of those days.
The original plan was innocent enough. dashboard needed a Page Builder. Something where I could create pages, edit them visually, preview them, eventually save them, and eventually let the public portfolio consume the resulting page definitions.
Simple.
Obviously, this was a lie.
First, I needed a Page Builder
The architecture was actually the responsible part.
I built a canonical page model rather than letting Puck become the application's brain. Puck is the editor infrastructure. Dashboard owns the page model.
There's a schema layer.
There's an adapter between the canonical model and Puck.
There's a component registry.
There's validation.
There's an in-memory Zustand store.
There's a page list.
There's /page-builder, /page-builder/new, and /page-builder/:pageId.
There's even a Hero component.
This is Phase 1, so there is no Firestore yet. No publishing. No public portfolio rendering. No pretending we're already running WordPress from a React dashboard.
Reasonable.
Then Puck arrived.
And Puck had opinions.
Specifically, Puck apparently looked at our carefully constrained editor container and said:
“Nice 636px container. Anyway, I'm 861px tall.”
Because of course it was using 100dvh.
So the editor was technically inside its box while simultaneously trying to escape the fucking building.
I eventually constrained Puck properly and stopped its portal from generating a ridiculous scrollbar.
Victory.
Or so I thought.
Then the footer started moving
At some point I noticed something deeply cursed.
The footer was in the wrong place.
Not actually in the wrong place.
That would've been too easy.
The footer was exactly where the layout told it to be.
The problem was that the page content was escaping the main container.
So the DOM was effectively doing this:
TopNav
main
└── page content
FooterExcept the page content had apparently decided:
main?
never heard of herIt grew beyond the height of main, painted over the footer, and made the footer appear halfway through the page.
The footer wasn't broken.
The footer was an innocent bystander.
It was standing there at the bottom of `main while the page content was committing crimes around it.
I tried the obvious thing
Naturally:
main {
overflow-y: auto;
}And congratulations, I had solved one problem.
I had also broken Blog Posts.
Because Blog Posts had sticky filters that depended on a particular scroll container.
Now the filter bar had a weird gap.
Pagination stopped behaving properly.
The page gained horizontal scrolling.
At this point CSS was no longer a styling language.
It was a hostage negotiation.
The actual answer was embarrassingly simple
The page itself should own its scroll.
Not the entire dashboard.
Not some giant global main.
The page.
So instead of:
main
└── giant page content escaping into the universeI established:
main
└── PageRoot
└── overflow-y: autowith:
flex: 1;
min-height: 0;
overflow-y: auto;That little min-height: 0 is the kind of CSS property that looks completely useless until it becomes the only thing standing between you and several hours of questioning your career choices.
Once Blog Posts became its own scroll container, its sticky filters could simply be:
top: 0;instead of doing interpretive dance around the TopNav with negative margins.
Pagination could stick to:
bottom: 0;And suddenly the page behaved like a page.
Amazing technology.
Then I discovered there were 15 more of these
Once the pattern was obvious, I checked the rest of Dashboard .
And there it was.
Series.
Media.
LinkedIn.
Social Composer.
Analytics.
Integrations.
Roadmap.
Comment Moderation.
Contact.
Social Embeds.
More analytics pages.
Basically anywhere the content could grow vertically, there was a chance it could grow outside main and eventually introduce itself to the Footer.
The Series cards were escaping.
The Social Composer form was escaping.
The analytics blog list was escaping.
The blog detail page was escaping.
The Footer remained blameless.
I fixed the pages individually by giving the appropriate page root ownership of vertical scrolling.
And importantly, I didn't turn the global layout into a giant overflow-y: auto monster.
Because we'd already seen that movie.
It sucked.
I also found the horizontal overflow
While fixing all this, Blog Posts had another little gift.
Negative margins.
The old layout had:
mx: { xs: -2, sm: -3 }which made sense when main had:
p: { xs: 2, sm: 3 }Then I changed the default main padding to 10px.
The negative margins didn't get the memo.
So the page was basically saying:
“The container is 10px wide.”
“Cool. I'll subtract 24px from both sides.”
And then everyone wondered why the page was wider than the viewport.
I removed the old compensation and aligned the page with the new layout contract.
Another tiny CSS crime scene cleaned up.
The Page Builder survived all of this
The funniest part is that the Page Builder itself wasn't the reason the whole dashboard was broken.
It just happened to be the thing that forced us to inspect the layout deeply enough to discover the existing problem.
Building a new feature exposed a systemic bug.
So instead of adding some duct tape specifically for Page Builder, I fixed the underlying page containment model.
That's the kind of accidental refactoring I can tolerate.
The good kind.
The kind where the codebase comes out less haunted than it went in.
And now there's documentation
Because apparently fixing the same CSS problem across 15 pages is how you earn the right to write a document.
So I now have:
docs/PAGE_LAYOUT_SCROLLING.mdIt documents the layout contract, page-level scroll ownership, why minHeight: 0 matters, how sticky elements relate to scroll containers, how to diagnose horizontal overflow, and the anti-pattern of making global main the universal scroll container.
Basically:
Dear future me,
Please don't fucking do this again.
Love, past me.
There is also a full Page Builder architecture document because apparently I had briefly developed optimism.
So what actually shipped?
The staged work ended up being much bigger than "add Puck."
I've got a new Page Builder with a proper page list and editor flow.
I've got the canonical page model.
I've got the Puck adapter.
I've got the Hero component registry.
I've got in-memory page management.
I've got validation.
I've got the Pages navigation entry.
And I fixed the layout containment problem across a pile of existing dashboard routes.
The staged assessment came out to 38 files changed, with the Page Builder accounting for the majority of the new implementation and the layout work touching the affected pages.
The release assessment also correctly separated the two major themes: Page Builder as the new feature, and layout containment as the broad bug-fix effort.
That's a pretty decent accidental side quest.
The important lesson
The lesson isn't "use overflow-y: auto."
That's how you summon another demon.
The lesson is:
The dashboard shell owns the available space. Pages own their scrolling.
Once that contract is explicit, everything gets easier.
The Footer doesn't need to know how tall your page is.
The global Layout doesn't need to know whether you're rendering a table, a form, a grid, or a Puck editor.
The page root says:
“I fit inside this space.”
And then the content scrolls inside it.
That's it.
A surprisingly large amount of frontend engineering is discovering that the thing you needed was one min-height: 0 and a sternly worded CSS boundary.
Meanwhile, I now have a Page Builder.
So that's nice.
I just had to perform a small exorcism on the dashboard first.
2.5.0: Page Builder + Layout Containment.
Apparently the real feature was the friends I made while debugging overflow.
And by friends, I mean CSS properties I now distrust personally.