Build Custom Pages
Custom pages are for app-specific user experiences. They should make Cessy workflows easier to operate, not create a second business system beside the model.
Good page design
A good custom page:
- centers the user’s business task
- reads from generated projections
- executes generated commands
- shows validation and command failures clearly
- avoids hidden policy or permission logic in the frontend
- keeps layout stable across preview and runtime contexts
Data access
Use generated runtime contracts for data:
- projections for lists, details, dashboards, and operational views
- commands for business actions
- GraphQL when the page benefits from flexible UI-shaped queries
- a BFF only when page orchestration genuinely belongs outside the event model
Do not query design-time internals from a runtime page.
Actions
Buttons and forms should map to command names users can understand. When a command needs confirmation or a reason, make that part of the command input instead of hiding it in component state.
Page preview
Use the Builder UI and Design MCP page-preview tools to verify pages before publish. Check:
- empty states
- loading states
- validation failures
- permission failures
- narrow mobile widths
- realistic projection data
Agent bubble and refresh
Runtime agents can use page refresh tools to keep a custom page aligned after agent actions. Use this for visible state changes, not as a substitute for reactive data loading in the page.
Handoff
A page handoff should name the projections and commands the page uses, the target environment, the preview URL or page slug, and any BFF endpoints involved.