Tree 1: Page vs Tab vs Modal vs Drawer
Use this decision tree whenever you need to present new content or a workflow to the user.1
Is this a top-level workflow or a full data view?
Yes — Use a Page. Pages are for primary workflows that deserve their own URL and back-button entry in history. Examples: Manage Agents list, Knowledge Base view, Billing dashboard.
2
Is this a sub-section of an existing page with peer sections?
Yes — Use a Tab. Tabs are for parallel content within a single context. The user should be able to switch between tabs without losing state. Examples: Agent Info / Prompt Config / Conversations within Manage Agent.
3
Is this a short, focused interaction (confirmation, small form, alert)?
Yes — Use a Modal. Modals block the background and demand a decision. They should contain fewer than 5 form fields and a clear primary + cancel action. Examples: Delete confirmation, rename dialog, disconnect confirmation.
4
Is this a longer form or detail view that relates to the current page?
Yes — Use a Drawer (slide-in panel). Drawers keep the parent page visible and are ideal for 5-10 field forms or detail previews. Examples: Edit user details, file preview in KB, agent quick-edit.
Quick Reference
Tree 2: CTA Hierarchy
Every view follows a strict CTA priority order. Walk through this tree from top to bottom to assign button types.1
Primary Action
The single most important action on the page. Uses Primary Button (navy, 48px). Limit: one per view. Examples: “Save Agent”, “Create Knowledge Base”, “Publish”.
2
Destructive Action
An action that deletes data or disconnects an integration. Uses Disconnect Button (red outlined ghost) or red Primary Button variant. Always requires confirmation. Examples: “Delete Agent”, “Disconnect Instagram”, “Remove User”.
3
Secondary Action
Supporting actions that complement the primary. Uses Secondary Button (outlined, 37px). Can have multiple per view. Examples: “Cancel”, “Export CSV”, “Duplicate Agent”.
4
Ghost / Tertiary Action
Low-emphasis actions like “Learn more”, “View docs”, or contextual helpers. Uses ghost button styling (text-only, no border). Examples: “Optimise Prompts” (with sparkle), inline “Edit” links.
Follow this exact priority order when multiple action types appear on the same view. Primary is always rightmost in button groups.
Never style a destructive action as a Primary Button without the red color treatment. Users must visually distinguish creation from destruction.
Tree 3: Navigation and Back Behavior
Rules governing how users move through the application and return to previous states.Rule 1: Every non-root page has a back arrow
Rule 1: Every non-root page has a back arrow
The top navigation bar shows a back arrow on all pages except the dashboard root. Clicking it returns to the previous page via browser history.
Rule 2: Deep links fall back to dashboard
Rule 2: Deep links fall back to dashboard
If a user arrives via deep link (shared URL, bookmark) and there is no browser history, the back arrow navigates to the main dashboard.
Rule 3: Tabs do not create history entries
Rule 3: Tabs do not create history entries
Switching between tabs within a page (e.g., Agent Info to Prompt Config) does not push a new history entry. The back arrow still returns to the parent list page.
Rule 4: Modals and drawers close on Esc and back
Rule 4: Modals and drawers close on Esc and back
Pressing Escape or the browser back button closes any open modal or drawer without navigating away from the page. The overlay is dismissed, not the page.
Rule 5: Unsaved changes trigger a guard
Rule 5: Unsaved changes trigger a guard
If the user has unsaved form changes and attempts to navigate away (back arrow, tab switch, browser back), a confirmation dialog appears: ‘You have unsaved changes. Discard or save?’
Rule 6: Wizard flows use step indicators, not history
Rule 6: Wizard flows use step indicators, not history
Multi-step wizards (e.g., Create Agent) show a step indicator and internal back/next buttons. The browser back arrow exits the wizard entirely (with unsaved changes guard).
Tree 4: Form Design
Use field count to determine the correct container for your form.Forms with file uploads always require at least a drawer. Inline file uploads create too much visual complexity within a page flow.
Global Do’s and Don’ts
Destructive Actions
Always require a confirmation step (modal with explicit “Delete” / “Cancel” buttons) before any data-destroying operation.
Show what will be deleted in the confirmation dialog. Never use vague language like “Are you sure?” without context.
Never place a destructive button as the first or leftmost action in a button group. Destructive actions go left; the primary (safe) action goes right.
Never use
--color-destructive on non-destructive actions. Red means irreversible or dangerous — no exceptions.Color Usage
Use
--color-navy for primary interactive elements and high-emphasis text. It is the default “action” color.Use
--color-purple exclusively for focus states and AI-related accents. It signals “intelligence” in the system.Never use brand colors (
--color-brand-orange, --color-brand-salmon) for status communication. They are decorative, not semantic.Never use
--color-success (green) for buttons or interactive elements. Green is reserved for status indicators and confirmation messages.AI Configuration
Always show the current value of AI parameters (temperature, model, token limits) as editable fields, never as hidden defaults.
Provide contextual help text explaining what each AI parameter does, using
--type-caption below the input.Never auto-apply AI configuration changes without the user explicitly saving. AI parameters affect production agent behavior.