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.
What Are Surfaces?
A surface is a distinct area of your project 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.
The Two Types
Catalyst organizes surfaces into two categories:
Product Surfaces
What your users see. These are the surfaces you ship — your public website, authenticated app, login pages, and presentations.
Catalyst Surfaces
Your development toolkit. Documentation, examples, demos, and project management — everything at /~/*.
Why This Matters
Surfaces solve real problems in growing applications:
Right experience per audience
Visitors vs users vs your team. 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, dev tools in Catalyst.
Easy to add or remove
Self-contained by design. Need a new admin area? Add it. Don't need presentations? Delete the folder.
Product Surfaces
These are the surfaces you ship to users:
Web
Product SurfaceYour public website. Marketing pages, content, blogs, portfolios — anything visitors access without logging in.
App
Product SurfaceYour core product. The dashboard, settings, and features users interact with after logging in.
Auth
Product SurfaceLogin, signup, and password reset. Clean, focused pages for authentication flows.
Present
Product SurfaceSlide presentations. Share progress, decisions, and outcomes with stakeholders.
Docs
Product SurfaceYour product documentation. Guides, tutorials, and reference material for your users.
Catalyst Surfaces
Your development toolkit — everything under /~/
Catalyst Dev Surface
Catalyst SurfaceThe unified dev namespace containing Catalyst documentation, reference examples, design demos, and project management tools.
How to Choose
The distinction is simple:
Is the audience your users?
→ Product Surface
Web, App, Auth, Present, Docs
Is the audience your team?
→ Catalyst Surface
/~/docs, /~/examples, /~/catalyst
Note: The Docs surface is a product surface — it's documentation for your users. Catalyst documentation (what you're reading now) lives at /~/docs.
Delete What You Don't Need
Each surface is self-contained. Don't need presentations? Delete app/(present). Ready to ship without dev tools? Delete app/(~). The pattern scales down as well as up.
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.
For AI Agents
Key rules:
- Product surfaces = user-facing content (Web, App, Auth, Present, Docs)
- Catalyst surfaces = dev toolkit at
/~/* - New pages go in the appropriate surface based on audience (public → Web, authenticated → App, dev tools → Catalyst)
- Each surface has its own shell — don't mix shell components across surfaces
- Surface-specific components go in
_surface/, shared components incomponents/ - Read the surface's
SURFACE.mdfile before making changes
Next Steps
Learn about each surface: