# start here

> 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](https://beamline.io/connect).

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.

```bash
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](https://beamline.io/docs/install):

1. **Install the package** (`npm i ./package/beamline-ui-<version>.tgz`), import one stylesheet, import components by
   path (`@beamline/ui/order-book`). No Tailwind needed.
2. **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](https://beamline.io/docs/customize)) and connect your data
([docs/DATA-INTEGRATION.md](https://beamline.io/docs/data-integration)).

## 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](https://beamline.io/docs/limitations): 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.