Building a SaaS layout
Compose PyColors UI primitives into a scalable, production-ready SaaS layout.
OverviewLink to section
Most UI libraries stop at components.
Real SaaS products require structure:
- navigation
- header
- content orchestration
- responsive behavior
- long-term scalability
This guide shows how to compose PyColors primitives into a real product layout that survives growth.
Core idea
Layout is not a component. It is a composition of responsibilities that evolve over time.
What you’re buildingLink to section
Navigation
Persistent sidebar for desktop, adaptive navigation for mobile.
Context
Header provides page context, actions, and user controls.
Content
Flexible surface for data-heavy and configuration views.
Mental modelLink to section
<AppShell>
<Sidebar />
<Main>
<Header />
<Content />
</Main>
</AppShell>This is not an API. It is a separation of concerns:
- navigation → where users go
- header → where users understand context
- content → where users act
StepsLink to section
Define layout responsibilitiesLink to section
Do not start with components. Start with responsibilities:
- navigation (global)
- context (page-level)
- content (feature-level)
This prevents premature abstractions.
Build desktop-first navigationLink to section
Desktop layout should:
- keep sidebar visible
- preserve vertical scanning
- support dense views (tables, dashboards)
Mobile layout should:
- move navigation into a Sheet
- prioritize content
- expose navigation via a trigger
Keep header lightweightLink to section
Header should contain:
- page title
- optional description
- primary action
- user menu
Avoid turning the header into a control panel.
Support multiple content typesLink to section
Your layout must handle:
- data views (tables, lists)
- settings flows (forms, tabs)
- modal interactions (dialogs)
A good layout does not change when content changes.
Core primitivesLink to section
| Primitive | Role |
|---|---|
| Button | actions and triggers |
| Sheet | mobile navigation |
| Dropdown Menu | contextual actions |
| Tabs | settings navigation |
| Table | structured data |
| Dialog | confirmations |
Key principle
You don’t need a “layout system”. You need reliable primitives and good composition.
Responsive strategyLink to section
Sidebar visible • persistent navigation • dense layout • full-height views
Sidebar hidden • Sheet navigation • header trigger • content-first layout
Real product examplesLink to section
Data pageLink to section
- Table
- Filters
- Row actions
- Pagination
Settings pageLink to section
- Tabs
- Forms
- Dialogs
- Validation
Same layout. Different content.
Decision guideLink to section
Prefer
- composition over abstraction
- clear separation of concerns
- mobile-first adaptability
- small reusable primitives
Avoid
- monolithic AppShell too early
- hardcoded layout logic
- coupling navigation with content
- over-engineered abstractions
When to introduce an AppShellLink to section
Create your own AppShell when:
- layout repetition becomes real
- multiple teams contribute
- navigation complexity grows
- consistency becomes critical
Not before.
SummaryLink to section
- Layout is composition, not a component
- Keep responsibilities separated
- Use primitives, not magic abstractions
- Scale structure only when needed
Next step
Combine this layout with async states and forms to reach production-level UX.