docs: design spec + implementation plan for the Integrations Hub redesign

[oxedom]

Docs only — no code changes. This lands the approved design spec and a task-by-task implementation plan for a frontend-only redesign of the Integrations tab's browse surface.

What's being proposed

The Integrations tab today is a "logo wall": compact tiles (logo + name + status badge) under stacked category headers, where clicking a tile opens a full-page detail view. The redesign:

• Two-pane layout — a left single-select category rail over our existing taxonomy, beside a card grid.
• Header pills — N available / N connected, plus a per-category AVAILABLE n.
• Self-contained cards — logo, name, category tag, blurb, and a Details + Connect pair, carrying the Connected / Manage / Soon / Request states.
• Details modal — read-only capability browser over the catalog's existing static actions[]. No tabs; Cabinet has no "triggers" concept.
• Connect modal — re-houses the entire current detail view (brand hero, SetupGuide, trust note, live ConnectPanel) rather than rebuilding it.

Layout and wireframes are borrowed from a reference integrations product; all styling stays on Cabinet's own design tokens.

Constraints held

• Frontend-only: no new API routes, no new dependencies, no backend change. Data stays the static preview-catalog.ts plus the existing /api/agents/config/mcp-catalog fetch.
• Scope-fenced: only the Integrations tab. The MCPs and API Keys tabs are untouched.
• Deep-linking preserved: still route-driven — #/integrations/{id} opens the Connect modal, close/back clears the slug.
• Suite routing (connectTargetFor, coveredBy, integrationVia, workAccountOnly) is preserved verbatim.

Plan shape (9 TDD tasks)

The derivation rules currently inline in the gallery (card state, filtering, counts, suite-slug routing) move to a React-free hub-view-model.ts with 16 node:test unit tests. IntegrationDetailPage splits into a container-agnostic IntegrationDetailBody so the same body serves the modal; LayoutGallery → LayoutGrid; both old files are deleted.

On testing: this repo has no component-test harness — no @testing-library, no vitest/jest, zero .test.tsx. Rather than add one unasked, the plan pushes the logic worth testing into a pure module (unit-tested) and covers the rendered surface with the Playwright harness that already exists (new e2e/integrations-hub.spec.ts).

Two deviations from the reference, recorded in the plan

Both are cases where the borrowed pattern didn't survive contact with our model:

1. The N connected pill counts connected cards, not the raw connected-id set. That set holds MCP ids that may have no card, and one Google Workspace OAuth lights three cards (Workspace, Gmail, Calendar) — so its size would disagree with the green cards on screen.
2. The card's Connecting… button is clickable and reopens the modal, where the reference's is a disabled spinner. Because setup now happens inside the modal, a disabled spinner would strand a user mid-OAuth with no way back in. Reopening is also what lets ConnectPanel clear a stale flag, so no timer is needed.

Review focus

The plan is meant to be executable by someone with no context on this codebase, so the useful review question is whether any task is under-specified — particularly Task 2 (the detail-body extraction, which must not change ConnectPanel runtime behavior) and Task 7 (the wiring + deletions).

🤖 Generated with Claude Code