For agents

Read this first. Bridge is many apps for venture networks (Bridge OS first, then Intros, Portfolio, Raise and others), all built on one package, @brdgapp/ui. Each app has its own frame and habits, so start from the app's page under Apps, and tell plan_screen which app you're building for. The look is calm and dense: Mulish, frosted glass cards over a dot-grid background, light and dark, and one blue button per group. Bridge OS as it is today is the standard, with the inconsistencies settled on 2 November 2026; DESIGN.md records it, and where code and DESIGN.md disagree, DESIGN.md wins.

Examples use a sample network: you are Ana Ruiz, Platform Lead at Lanternfield Capital, and you know people like Leah Okonkwo (Saltmarsh Partners) and Priya Natarajan (Quillbase). The sample's today is 16 September 2026. Write copy like that: real people, real intros, sentence case.

AI coding agents (Claude Code, Cursor and others) read this handbook the same way people do, but through a connection made for them. Everything they get comes from the same files these pages are built from, so agents and people never see different rules.

Agents can only read. Nothing here changes a file in your app.

The handbook runs an MCP server at https://apps-bridge-design-system-handbook.vercel.app/mcp. It's open: no login or key.

Bridge OS is already set up: its move onto the package (the open merge request) adds this server to its .mcp.json, so agents in Bridge OS find it on their own once that merges.

Claude Code

Run this in the app's folder. It writes a .mcp.json file you can commit, so everyone on the app gets the server.

claude mcp add --transport http --scope project bridge-handbook https://apps-bridge-design-system-handbook.vercel.app/mcp

Or write .mcp.json yourself:

{
  "mcpServers": {
    "bridge-handbook": {
      "type": "http",
      "url": "https://apps-bridge-design-system-handbook.vercel.app/mcp"
    }
  }
}

The Claude app (desktop or claude.ai)

For designing or asking questions outside a code editor. In Settings → Connectors, choose Add custom connector, name it bridge-handbook and paste https://apps-bridge-design-system-handbook.vercel.app/mcp. On Team and Enterprise plans, an owner may need to add it for the organization first.

Cursor

Add .cursor/mcp.json to the app's folder (or ~/.cursor/mcp.json for every project):

{
  "mcpServers": {
    "bridge-handbook": {
      "url": "https://apps-bridge-design-system-handbook.vercel.app/mcp"
    }
  }
}

Tools that only start local servers

Some tools can't connect to a web address. mcp-remote bridges the gap:

{
  "mcpServers": {
    "bridge-handbook": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://apps-bridge-design-system-handbook.vercel.app/mcp"]
    }
  }
}

get_skill returns a step-by-step workflow. There are these:

Agents fall back in this order:

1. The MCP server, https://apps-bridge-design-system-handbook.vercel.app/mcp.
2. https://apps-bridge-design-system-handbook.vercel.app/llms.txt: the brief, how to build, every rule, the Never list and an index of every page.
3. https://apps-bridge-design-system-handbook.vercel.app/llms-full.txt: all of that plus every component, pattern and template in full, DESIGN.md and the tokens.
4. The repository itself: registry/rules.ts for rules and each component's guidance.ts.

Paste this into the app's CLAUDE.md (Claude Code) or AGENTS.md (Cursor and others), so agents use the handbook without being asked.

## Design system

This app uses Bridge's design system: the `@brdgapp/ui` package and its handbook at https://apps-bridge-design-system-handbook.vercel.app.

- Before building any screen, call the `bridge-handbook` MCP server: `orient` first, then `plan_screen` with the Bridge app the screen is for.
- If the MCP server isn't available, read https://apps-bridge-design-system-handbook.vercel.app/llms.txt (short) or https://apps-bridge-design-system-handbook.vercel.app/llms-full.txt (everything).
- Import only from `@brdgapp/ui`. Never hand-make a button, tag, menu, tooltip, dialog or table.
- Colors only as role tokens (`bg-[var(--surface-secondary)]`). No hex, no palette classes, no `dark:` fixes.
- `className` on a package component is for layout only; the look comes from `variant` and `size`.
- Every data region goes through `DataState` with a same-size skeleton.
- Copy is sentence case and real: real-sounding people, intros and organizations. Never Lorem, "Click here" or "Submit".
- Before finishing, run `check_code` on what you wrote and walk the screen recipe.

For a one-off screen, start the agent with this and fill in the first line.

Build this screen for Bridge <app, e.g. Bridge OS>: <describe the screen>.

Use the bridge-handbook MCP server (https://apps-bridge-design-system-handbook.vercel.app/mcp). Call orient first, then plan_screen with my description and the app (and the app I'm coming from, if I name one).
Read every template, pattern and component it names with get_page, and copy from get_examples.
Import only from @brdgapp/ui. If no component fits a job, tell me instead of making one.
Write sentence-case copy with real-sounding people and intros (the handbook's sample network), never Lorem or "Click here".
When you're done, run check_code on your code, fix what it finds, and walk the screen recipe.
Tell me which template you used, which checks you ran, and anything the checker couldn't judge.

• Call orient first, then plan_screen for a new screen, then get_page for every template, pattern and component you will use.
• Import only from @brdgapp/ui. If search doesn't return a component for the job, don't invent one: use the closest, or say what's missing.
• Start every screen from a template (Picking a template); never invent a new page frame.
• Give every data region its loading, empty and error state through DataState.
• Write real copy in sentence case: real-sounding people, intros and organizations (the sample network: Ana Ruiz, Leah Okonkwo, Priya Natarajan…). Never Lorem, "Click here", "Submit" or Title Case.
• Run check_code on what you wrote, fix what it reports, then walk the screen recipe.

Built from each component's own guidance (its first "when to use" line).

Agents walk this before calling a screen done. It's the same list on Build a screen.

1. It sits in the app shell: the top bar and page background come from the shell; the page sets only its width (LAYOUT_*).
2. Every control is a package component; nothing is hand-made. (One of each)
3. No component is restyled: className only for layout. (The look comes from props)
4. Colors are tokens: no hex, no palette classes, no dark: fixes. (Colors are tokens)
5. One blue button per group of actions. (One blue button per group)
6. Every data region goes through DataState and loads on its own; make it slow and make it fail to check. (Each part loads on its own)
7. Nothing jumps when data arrives: skeletons are measured. (Reserve the space)
8. Counts come from the list they count; a failed count never shows 0. (Counts match what's shown)
9. No glass inside glass. (Glass, once)
10. Copy: sentence case, verbs on buttons, one date format, no words from the avoid list. (Sentence case)
11. Text is 11px or larger (except the Badge); numbers in columns use tabular-nums. (Nothing below 11px)
12. Tab through it: everything reachable, focus always visible, every control named. (Every control has a name)
13. Check dark mode, 390px and 1440px.

Until these are settled, follow Bridge OS as it is today.

• How app-cc-mobile (React Native) agents should use the handbook, since the package is web-only.

Where Bridge OS code differs from this page today. Follow the page, not the gap.

• The Bridge skills (bridge-design-system and the others) still carry their own design rules. Decided 2026-11-02: they point at this handbook instead. The new versions are drafted and waiting to be uploaded.

• The tool list is read from the handbook's own MCP server when this page builds.
• The Always list, job map, recipe and Never list come from the same files the MCP server and llms.txt use.
• Setup formats checked against the Claude Code MCP docs (code.claude.com/docs/en/mcp) and Cursor MCP docs (cursor.com/docs/context/mcp) on 2 November 2026.
• Decisions 2026-11-02: #12 (skills point at the handbook), #13 (components.md keeps only Bridge OS's product components), the Bridge OS consistency picks.
• Sample network: sample/network.ts.