Surfaces
Different experiences for different audiences — all in one project.
Read this when you're setting up a new project, adding a new audience, or deciding how to structure your UI.
Useful for anyone planning the architecture of a Catalyst application.
What Are Surfaces?
A surface is a distinct area of your product designed for a specific audience. Your marketing site, your app dashboard, your documentation — each is a surface with its own layout, styles, and purpose.
This separation prevents the common problem where marketing pages, user dashboards, and developer docs all compete for the same design constraints. Each surface can be optimized for its audience without compromising the others.
Why This Matters
Surfaces solve real problems in growing applications:
Right experience per audience
Visitors vs users vs developers. Each audience has different needs. Surfaces let you optimize for each.
Work fast without breaking
Parallel development. Teams can work on different surfaces simultaneously. Changes to marketing won't affect the app.
Clear purpose
Everyone knows where things go. Public pages in Web, user features in App, reference material in Docs.
Easy to add or remove
Self-contained by design. Need a new admin area? Add it. Don't need presentations? Delete the folder.
How Surfaces Work Together
Surfaces form a complete narrative for your product:
Web
Your public website — pages visitors see without logging in
App
Delivers value — the actual product experience
Docs
Documents value — how things work and why
Examples
Proves value — reference implementations that work
Present
Tells the story — decisions, progress, outcomes
Available Surfaces
Catalyst includes six surfaces out of the box:
Web
(web)Your public website. Marketing pages, content, blogs, portfolios — anything visitors access without logging in.
App
(app)Your core product. The dashboard, settings, and features users interact with after logging in.
Auth
(auth)Login, signup, and password reset. Clean, focused pages for authentication flows.
Docs
(docs)Documentation and reference material. Where you explain how things work and why.
Examples
(examples)Working examples and patterns. Proven implementations you can copy and adapt.
Present
(present)Slide presentations. Share progress, decisions, and outcomes with stakeholders.
Surface Structure
app/(surface-name)/
├── layout.tsx # Sets the shell
├── surface.css # Surface-specific styles
├── SURFACE.md # Documentation
├── _surface/ # Shell components
│ └── surface-shell.tsx
└── pages/ # Your pages
└── page.tsxEach surface is self-contained. Delete the folder to remove it entirely.
Start with what you need, customize from there. The included surfaces are starting points. Remove what you don't need, rename to match your domain, or add new surfaces for specific audiences. The pattern scales down as well as up.
Next Steps
Learn about each surface: