Start here: Beamline docs

Part of the documentation that comes with Beamline's complete system (START-HERE.md in the kit). Your coding agent can do all of this for you through Beamline's MCP server: connect it.

Dark-first React 19 components and screens for SaaS tools, trading interfaces, dashboards and AI-agent products. One design language, one stylesheet, one brand colour. You get the editable source of everything, an installable package built from that same source, and a reference application that runs on it.

What is in this folder

folder	what it is
`package/`	`@beamline/ui` as an npm tarball: compiled ES modules, type declarations, one stylesheet. Install it like any package.
`source/ui/`	The editable TypeScript and CSS the package is built from: components, blocks (whole screens), hooks, helpers, styles, and each entry's examples (`demo.tsx`).
`reference-app/`	A complete React 19 + Vite application using the package: navigation, connected screens, data adapters and a brand change. The complete bundle has five screens; a standalone pack keeps the screens of the blocks it carries (a pack without blocks has no app and starts from `examples/`). Start here to see how the pieces fit.
`examples/`	Smaller focused apps: Beamline added to an existing app without touching its styles (`embed-in-existing-app`), and editable source with Tailwind (`source-app`, when this bundle carries its elements).
`catalog/index.html`	Searchable catalog of every element: what it is for, what to use instead, import path, props, keyboard. Opens offline.
`previews/`	Screenshots of every entry and, in the complete bundle, the full interactive gallery (`previews/gallery/index.html`).
`docs/`	Install, upgrade, customise, data integration, dependencies and licences, known limitations, changelog, conventions and design language.
`tools/beamline.mjs`	Adds single elements as editable source to your app (with exactly the parts they import), and upgrades them later without overwriting your edits.
`AGENTS.md`, `agents/`	Instructions and a small skill for coding agents (Claude Code, Codex and others) working with this system.
`LICENSE.md`, `THIRD-PARTY-LICENSES.md`, `NOTICE`	The licence for Beamline itself, and every third-party package it can bring in with its licence and obligations.
`MANIFEST.json`	Exact version, source revision, entry list and a checksum for every file in this bundle.

Run the reference app (5 minutes)

Needs Node 20 or newer.

cd reference-app
npm install
npm run dev

Open the address it prints. The screens run on demonstration data that is labelled as such on screen; nothing calls an external service. reference-app/README.md shows where each screen's data comes in and where your backend goes.

Use it in your app

Two supported ways, both described step by step in docs/INSTALL.md:

Install the package (npm i ./package/beamline-ui-<version>.tgz), import one stylesheet, import components by path (@beamline/ui/order-book). No Tailwind needed.
Copy the source (source/ui/) into your app when you want to edit components directly. Needs Tailwind v4 and one path alias.

Then set your brand colour (docs/CUSTOMIZE.md) and connect your data (docs/DATA-INTEGRATION.md).

Find the right element

Open catalog/index.html and search by job ("pick a date range", "show an order book", "ask for approval"). Every entry says what to use instead when it is the wrong fit. Agents can run node agents/skills/beamline-ui/scripts/find.mjs <job>.

Before you rely on it

Read docs/LIMITATIONS.md: it lists what is demonstration-only, which layouts are verified, which browsers were exercised, and where your own backend has to do the work. The UI never pretends an external action succeeded; your handlers decide what the screens show.