Navegação e layout de páginas

​

Estrutura da barra lateral

​

Sub-rotas sob um registro pai

/agents/[id]/config
/agents/[id]/tools
/agents/[id]/mcp
/agents/[id]/runs

/campaigns/[id]/overview
/campaigns/[id]/audience
/campaigns/[id]/schedule
/campaigns/[id]/runs

/journeys/[id]/graph
/journeys/[id]/triggers
/journeys/[id]/runs

​

Breadcrumbs

​

Modo automático (o padrão)

// Nenhuma prop necessária — automático é o padrão.
<PageHeader title="Runs" />

• Os segmentos de rota mapeiam de forma clara para rótulos legíveis (o caso comum).
• Você já está dentro de uma hierarquia de registro pai/filho já cadastrada no registro.

​

Modo explícito

<PageHeader
  title="Reply drafting"
  breadcrumbs={[
    { label: "Inbox", href: "/inbox" },
    { label: contact.displayName, href: `/inbox/${conv.id}` },
    { label: "Draft" },
  ]}
/>

• A URL não reflete o local mental do usuário (por exemplo, rotas modais, wizards).
• Você precisa exibir um rótulo que ainda não está no registro e não quer adicioná-lo.
• Você está renderizando uma página pontual (migrações, ferramentas administrativas) em que manter o registro atualizado não vale o esforço.

​

Abas de filtro vs. abas de conteúdo

​

FilterTabs — controle segmentado

• Estiver alternando entre visualizações do mesmo conjunto de dados subjacente (por exemplo, All / Draft / Pending / Approved em templates).
• Você quiser um visual de controle segmentado que não sugira “páginas” separadas.
• For navegação de sub-rota para um registro de detalhe (config | tools | mcp | runs).

<FilterTabs
  value={status}
  onValueChange={setStatus}
  options={[
    { value: "all", label: "All" },
    { value: "draft", label: "Draft" },
    { value: "approved", label: "Approved" },
  ]}
/>

​

Tabs — regiões de conteúdo

• As abas renderizam interfaces estruturalmente diferentes (por exemplo, Overview vs. JSON vs. Logs).
• Cada aba tem conteúdo substancial — tabelas, formulários, gráficos.
• De outra forma, seria necessário dividir em rotas irmãs, mas as telas estão fortemente acopladas demais para justificar navegação em nível de URL.

​

Cards vs. seções — composição de página

1. PageHeader no topo — título, descrição, breadcrumbs, ação principal.
2. Seções simples abaixo — um <h2> (ou um pequeno componente de cabeçalho de seção) seguido de conteúdo diretamente sobre o fundo da página.
3. Card apenas para painéis laterais, seletores modulares, ou coisas que genuinamente precisam de um contêiner com borda.

​

Prefira seções simples

<PageHeader title="Agent configuration" />

<section className="space-y-4">
  <h2 className="text-lg font-semibold">Prompt</h2>
  <PromptEditor ... />
</section>

<section className="space-y-4">
  <h2 className="text-lg font-semibold">Tools</h2>
  <ToolList ... />
</section>

​

Use Card quando

• Painéis laterais — um resumo na coluna direita ao lado do conteúdo principal.
• Seletores modulares — seletor de modelo, seletor de template, caixa de filtro de audiência. Widgets autocontidos que podem viver em qualquer lugar da página.
• Estados vazios e prompts de onboarding — um único elemento centralizado em uma página, do contrário, vazia.
• Blocos de dashboard — cards de métrica em páginas de visão geral.

// Bom: painel lateral
<div className="grid grid-cols-[1fr_320px] gap-6">
  <AgentRunsTable ... />
  <Card>
    <CardHeader>
      <CardTitle>Recent alerts</CardTitle>
    </CardHeader>
    <CardContent>...</CardContent>
  </Card>
</div>

​

Checklist rápido para novas páginas

• PageHeader é o primeiro elemento; breadcrumbs está ou omitido (automático) ou é um array explícito — nunca os dois.
• As sub-rotas sob um registro usam FilterTabs conectadas a URLs reais, e não Tabs de página.
• A entrada na barra lateral é simples, a menos que existam 3 ou mais rotas irmãs, caso em que se torna um grupo recolhível com um ícone apropriado.
• A estrutura de nível superior é PageHeader + seções. Card aparece apenas para painéis laterais, seletores, estados vazios ou blocos de dashboard.
• Todo novo segmento [id] tem um loader de rótulo registrado em /apps/app/lib/breadcrumbs.ts (ou breadcrumbs explícitos são passados em cada ponto de uso).

​

Entregue neste projeto

• BORD-329 — grupos recolhíveis na barra lateral para Agents / Campaigns / Journeys ✅
• BORD-330 — abas de sub-rota por registro (config | tools | mcp | runs e afins) ✅
• BORD-331 — breadcrumbs auto-derivados com um pequeno registro + escape hatch de override explícito ✅
• BORD-332 — refatoração da gramática de página: PageHeader + seções, Card rebaixado para função de painel lateral ✅
• BORD-333 — este documento + uma limpeza de design tokens no CTA da landing page /web ✅