/building-settings-ui

name: building-settings-ui
description: >-
  Use this skill when adding or modifying settings UI in Tambo Cloud. Covers where a new settings
  section belongs (Agent tab vs Settings tab), and the component patterns used across both pages
  (card layout, toasts, confirmation dialogs, destructive styling, save behavior conventions).
  Triggers on "add a new settings section", "where should X go?", "settings UI", "settings page",
  "agent page", or any work touching apps/web/components/dashboard-components/project-details/,
  project-settings.tsx, or agent-settings.tsx.
  Not for full-stack feature building (DB, tRPC, tests); those patterns will get their own skills.
metadata:
  internal: true

Building Settings UI

Guide for placing and styling settings sections in the Tambo Cloud dashboard. Covers two concerns: where a feature belongs (which tab/page), and how to build the UI component to match existing patterns.

Architecture

Settings are split across two top-level tabs in the project layout:

• **Agent tab** (`/[projectId]/agent`) - How the AI agent behaves
• **Settings tab** (`/[projectId]/settings`) - Project infrastructure and access

Each tab renders a flat vertical stack of Card components. There is no sidebar navigation; each page is short enough to scroll naturally.

Tab layout

Overview | Observability | Agent | Settings

• Layout file: `apps/web/app/(authed)/(dashboard)/[projectId]/layout.tsx`
• Agent page: `apps/web/app/(authed)/(dashboard)/[projectId]/agent/page.tsx`
• Settings page: `apps/web/app/(authed)/(dashboard)/[projectId]/settings/page.tsx`

Gotchas

1. **Do not add a new top-level tab** without explicit team alignment. Current tabs (Overview, Observability, Agent, Settings) have been stable. 2. **`EditWithTamboButton` goes inside `CardTitle`**, not as a sibling of `CardHeader`. It must have a `description` prop explaining what the section configures. 3. **Invalidate the query before toasting** in `onSuccess`. Reversing the order can show a success toast while the UI still displays old data. 4. **Use `DeleteConfirmationDialog`**, never inline `AlertDialog` for destructive confirmations. 5. **Use `text-destructive` semantic color**, never `text-red-500`. Cancel/discard buttons are NOT destructive.

---

Feature Placement

Agent Tab Sections

| # | Section | What it configures | Component | | --- | ------------------- | -------------------------------------------------- | -------------------------------- | | 1 | Model | Provider + model selection, API key, custom params | `provider-key-section.tsx` | | 2 | Custom Instructions | System prompt, prompt override toggle | `custom-instructions-editor.tsx` | | 3 | Skills | Skill definitions and imports | `skills-section.tsx` | | 4 | Tool Call Limit | Max tool calls per response | `tool-call-limit-editor.tsx` | | 5 | MCP | MCP server URLs + headers | `available-mcp-servers.tsx` |

**Container:** `apps/web/components/dashboard-components/agent-settings.tsx`

Settings Tab Sections

| # | Section | What it configures | Component | | --- | -------------- | ------------------------------ | -------------------------- | | 1 | Name | Project display name | `project-name-section.tsx` | | 2 | API Keys | API key list + create | `api-key-list.tsx` | | 3 | Authentication | OAuth mode, token requirements | `oauth-settings.tsx` | | 4 | Danger Zone | Project deletion | `danger-zone-section.tsx` |

**Container:** `apps/web/components/dashboard-components/project-settings.tsx`

All section components live in `apps/web/components/dashboard-components/project-details/`.

Placement Decision Tree

1. **Configures AI agent behavior?** (model selection, prompts, tools, memory, context) -> **Agent tab** 2. **Configures project infrastructure?** (API keys, naming, deletion, billing, webhooks) -> **Settings tab** 3. **Configures who can access?** (auth, tokens, team members, permissions) -> **Settings tab** 4. **Monitoring or debugging view?** -> **Observability tab** 5. **High-level summary or status?** -> **Overview tab** 6. **None of the above?** -> Ask the user.

Conditional and Dependent Settings

Some settings only apply when another setting is in a specific state. Follow these patterns:

**Show but warn (soft dependency).** The section renders normally but displays an `Alert` when the dependency isn't met. The user can still see and configure the setting. Use this when the feature exists but won't work at runtime.

Example: Skills section shows a provider compatibility notice when the selected provider doesn't support skills:

// skills-section.tsx
const isProviderSupported = SKILLS_SUPPORTED_PROVIDERS.has(
  defaultLlmProviderName,
);
// Renders full skills UI + warning Alert if !isProviderSupported

**Conditionally pass props (data dependency).** The parent reads one setting and passes it as a prop so the child can adapt its behavior. Use this when the child's content or options change based on the parent's state.

Example: MCP servers section receives `providerType` to toggle agent-mode-specific UI:

// agent-settings.tsx
<AvailableMcpServers providerType={projectData?.providerType} />;
// available-mcp-servers.tsx
const isAgentMode = providerType === AiProviderType.AGENT;

Example: Custom LLM parameters change available suggestions based on provider and model:

// provider-key-section.tsx passes selectedProvider to the parameter editor
<CustomLlmParametersEditor selectedProvider={selectedProvider} />

**Rules for new dependent settings:**

1. Never hide a section entirely based on another setting's state. Always render the