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 card; use an Alert or disabled state to communicate the dependency.
2. The warning message must name the dependency and tell the user what to change (e.g., "Switch to a supported provider to enable skills").
3. Keep dependency checks in the section component, not the container. The container (agent-settings.tsx, project-settings.tsx) should pass data, not make visibility decisions.
4. If a setting depends on state from a different tab, pass it through the shared project query (api.project.getProject) rather than cross-tab state.

Adding a New Section

1. Create the component in project-details/ following the Card layout pattern below.
2. Import and render in the correct container (agent-settings.tsx or project-settings.tsx).
3. Update the skeleton in settings-skeletons.tsx (either AgentPageSkeleton or SettingsPageSkeleton).

---

Component Patterns

Card Layout

Every settings section uses Card, CardHeader, CardTitle, CardDescription, CardContent from @/components/ui/card.

<Card>
  <CardHeader>
    <CardTitle className="text-lg font-semibold">
      Section Name
      <EditWithTamboButton description="Configure section settings..." />
    </CardTitle>
    <CardDescription className="text-sm font-sans text-foreground">
      Description of what this section does.
    </CardDescription>
  </CardHeader>
  <CardContent className="space-y-4">{/* Content */}</CardContent>
</Card>

Toast Notifications

Every mutation shows a toast on both success and error. Import useToast from @/hooks/use-toast.

const mutation = api.someRoute.someMutation.useMutation({
  onSuccess: async () => {
    await utils.someRoute.someQuery.invalidate();
    toast({ title: "Success", description: "Setting updated successfully" });
  },
  onError: () => {
    toast({
      title: "Error",
      description: "Failed to update setting",
      variant: "destructive",
    });
  },
});

Never skip the error toast.

Confirmation Dialogs

All destructive actions use DeleteConfirmationDialog from @/components/dashboard-components/delete-confirmation-dialog:

const [alertState, setAlertState] = useState<{
  show: boolean;
  title: string;
  description: string;
  data?: { id: string };
}>({ show: false, title: "", description: "" });

<DeleteConfirmationDialog
  mode="single"
  alertState={alertState}
  setAlertState={setAlertState}
  onConfirm={handleConfirmDelete}
/>;

Title includes the item name (Delete "${name}"?). Description warns the action cannot be undone.

Destructive Action Styling

<Button
  variant="ghost"
  size="icon"
  className="text-destructive hover:text-destructive hover:bg-destructive/10"
>
  <Trash2 className="h-4 w-4" />
</Button>

Use Trash2 from lucide-react. Use hover:bg-destructive/10 for ghost variant hover.

Save Behavior

Toggles: Immediate save. onCheckedChange fires the mutation directly. Include aria-label with state context.

Form fields: Edit/Save/Cancel. Track isEditing, savedValue, and displayValue state. Cancel reverts to savedValue. Save button disabled during mutation, shows "Saving...". autoFocus on first input when entering edit mode.

Reference implementations: custom-instructions-editor.tsx (edit/save/cancel), tool-call-limit-editor.tsx (simpler form), project-name-section.tsx (basic edit/save/cancel).

Danger Zone Pattern

For irreversible destructive actions, use the Danger Zone card pattern:

<Card className="border-destructive/50">
  <CardHeader>
    <CardTitle>Danger Zone</CardTitle>
    <CardDescription>Warning about permanence.</CardDescription>
  </CardHeader>
  <CardContent>
    <Button
      variant="ghost"
      className="text-destructive hover:text-destructive hover:bg-destructive/10"
      aria-label="Delete this project"
    >
      Delete this project
    </Button>
  </CardContent>
</Card>

The DeleteConfirmationDialog should be owned by the parent component that handles the mutation and post-delete navigation.