> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainstormer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Neo Decision Frameworks

> Decision trees for layout selection, CTA hierarchy, navigation behavior, and form design in the Neo design system.

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### Quick Reference

| Criteria                 | Page        | Tab           | Modal       | Drawer      |
| ------------------------ | ----------- | ------------- | ----------- | ----------- |
| Needs own URL            | Yes         | No            | No          | No          |
| Blocks background        | No          | No            | Yes         | Partial     |
| Form fields              | Any         | Any           | 1-4         | 4-10        |
| Preserves parent context | No          | Yes           | Yes         | Yes         |
| Back button behavior     | History pop | No navigation | Close (Esc) | Close (Esc) |

***

## Tree 2: CTA Hierarchy

Every view follows a strict CTA priority order. Walk through this tree from top to bottom to assign button types.

<Steps>
  <Step title="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".
  </Step>

  <Step title="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".
  </Step>

  <Step title="Secondary Action">
    Supporting actions that complement the primary. Uses **Secondary Button** (outlined, 37px). Can have multiple per view. Examples: "Cancel", "Export CSV", "Duplicate Agent".
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Check>
  Follow this exact priority order when multiple action types appear on the same view. Primary is always rightmost in button groups.
</Check>

<Danger>
  Never style a destructive action as a Primary Button without the red color treatment. Users must visually distinguish creation from destruction.
</Danger>

***

## Tree 3: Navigation and Back Behavior

Rules governing how users move through the application and return to previous states.

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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?'
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>

***

## Tree 4: Form Design

Use field count to determine the correct container for your form.

| Field Count | Container                | Layout                                        | Example                                 |
| ----------- | ------------------------ | --------------------------------------------- | --------------------------------------- |
| 1-3 fields  | **Inline** (within page) | Single column, no container border            | Rename dialog, search filters           |
| 4-7 fields  | **Modal or Drawer**      | Single column in modal; 1-2 columns in drawer | Edit user, quick agent settings         |
| 8+ fields   | **Full Page**            | Multi-section with headings, 1-2 columns      | Agent creation wizard, KB configuration |

<Tip>
  When a form spans multiple concerns (e.g., basic info + advanced settings), split into sections with `--type-heading-sm` headers and `--space-8` gaps between sections.
</Tip>

<Note>
  Forms with file uploads always require at least a drawer. Inline file uploads create too much visual complexity within a page flow.
</Note>

***

## Global Do's and Don'ts

### Destructive Actions

<Check>
  Always require a confirmation step (modal with explicit "Delete" / "Cancel" buttons) before any data-destroying operation.
</Check>

<Check>
  Show what will be deleted in the confirmation dialog. Never use vague language like "Are you sure?" without context.
</Check>

<Danger>
  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.
</Danger>

<Danger>
  Never use `--color-destructive` on non-destructive actions. Red means irreversible or dangerous -- no exceptions.
</Danger>

### Color Usage

<Check>
  Use `--color-navy` for primary interactive elements and high-emphasis text. It is the default "action" color.
</Check>

<Check>
  Use `--color-purple` exclusively for focus states and AI-related accents. It signals "intelligence" in the system.
</Check>

<Danger>
  Never use brand colors (`--color-brand-orange`, `--color-brand-salmon`) for status communication. They are decorative, not semantic.
</Danger>

<Danger>
  Never use `--color-success` (green) for buttons or interactive elements. Green is reserved for status indicators and confirmation messages.
</Danger>

### AI Configuration

<Check>
  Always show the current value of AI parameters (temperature, model, token limits) as editable fields, never as hidden defaults.
</Check>

<Check>
  Provide contextual help text explaining what each AI parameter does, using `--type-caption` below the input.
</Check>

<Danger>
  Never auto-apply AI configuration changes without the user explicitly saving. AI parameters affect production agent behavior.
</Danger>