Skip to content

docs(repo): readme with npm badges, install steps and a package table with versions #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fnLog0 merged 1 commit into from
Oct 27, 2026
Merged

docs(repo): readme with npm badges, install steps and a package table with versions #47

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 48 additions & 29 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,56 +4,75 @@
</picture>

<p align="center">
<a href="https://design.locusgraph.com">Docs</a> ·
<a href="https://www.npmjs.com/package/@locusgraph/components"><img alt="npm" src="https://img.shields.io/npm/v/@locusgraph/components?label=npm&color=111111&style=flat-square"></a>
<a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-111111?style=flat-square"></a>
<a href="https://design.locusgraph.com/r/registry.json"><img alt="shadcn registry" src="https://img.shields.io/badge/shadcn-registry-111111?style=flat-square"></a>
</p>

<p align="center">
<a href="https://design.locusgraph.com"><b>Docs</b></a> ·
<a href="https://www.npmjs.com/org/locusgraph">npm</a> ·
<a href="https://design.locusgraph.com/DESIGN.md">DESIGN.md</a> ·
<a href="https://design.locusgraph.com/r/registry.json">shadcn registry</a> ·
<a href="https://www.npmjs.com/package/@locusgraph/components">npm</a>
<a href="https://design.locusgraph.com/generative-ui">Generative UI</a> ·
<a href="apps/example-next">Examples</a>
</p>

# Locus Design

A design system for agent products: React components
on Radix, product blocks, Loop (agent UI with the human in the loop), brand assets, and one theme
with light and dark modes. Icons are Phosphor (`@phosphor-icons/react`), bold weight.

| Package | What it is |
|---|---|
| [`@locusgraph/components`](packages/components) | React components on Radix, Rule Grid, the App and Docs shells and the theme. Start here |
| [`@locusgraph/blocks`](packages/blocks) | `Usage`, `UsageAlert`, `Wallet`, `TopUp`, `Plans` and `Keys`, with matching skeletons |
| [`@locusgraph/loop`](packages/loop) | Agent UI: chat, thinking, tools, approvals, memory and cost, on Vercel AI SDK message parts |
| [`@locusgraph/tokens`](packages/tokens) | The theme as CSS (palette, square radius, hairlines, fonts, motion) and as TypeScript values |
| [`@locusgraph/brand`](packages/brand) | The LocusGraph and SpendGraph marks, app icon, social card, and the Google and GitHub marks |
| [`@locusgraph/email`](packages/email) | Transactional email templates in the same style |
| [`@locusgraph/utils`](packages/utils) | Money, counts, dates and quota helpers |
| [`@locusgraph/config`](packages/config) | Biome, TypeScript and Vitest settings, replacing `@spendgraph/config` |
A design system for agent products. React components on Radix, product blocks, and Loop, the agent
UI where a person approves what the agent does. One square, ruled theme in light and dark.
React 19, Tailwind 4, Phosphor icons.

Examples: [Next.js App Router](apps/example-next) and [React with Vite](apps/example-react).

- **Docs** ([apps/design](apps/design)): every component with a live playground, usage and props,
at [design.locusgraph.com](https://design.locusgraph.com).
## Install

```bash
pnpm add @locusgraph/components
pnpm add @locusgraph/components @locusgraph/blocks @locusgraph/loop
```

```css
@import "tailwindcss";
@import "@locusgraph/components/theme.css";
@import "@locusgraph/blocks/sources.css";
@import "@locusgraph/loop/sources.css";
```

```tsx
import { Button } from "@locusgraph/components";
import { ApprovalGate, useApprovalGate } from "@locusgraph/loop";
```

The theme's CSS variables are all `--locus-*`, so they never clash with an app's own. An app that
also uses its own shadcn components adds `@import "@locusgraph/components/shadcn.css";` after the
theme to point the shadcn variables (`--background`, `--primary`, `--muted-foreground`, …) at ours.
Theme variables are all `--locus-*`, so they never clash with an app's own. An app that also uses
its own shadcn components adds `@import "@locusgraph/components/shadcn.css";` after the theme.

Or copy the source into your app with the shadcn CLI. Every component, block and Loop part is in the
registry at [design.locusgraph.com/r/registry.json](https://design.locusgraph.com/r/registry.json):
### Or copy the source with shadcn

Every component, block and Loop part is in the
[registry](https://design.locusgraph.com/r/registry.json):

```bash
pnpm dlx shadcn@latest add https://design.locusgraph.com/r/theme.json https://design.locusgraph.com/r/approval.json
```

For AI agents, [design.locusgraph.com/DESIGN.md](https://design.locusgraph.com/DESIGN.md) lists every page
with a Markdown version of each.
## Packages

| Package | Version | What it is |
|---|---|---|
| [`@locusgraph/components`](packages/components) | [![npm](https://img.shields.io/npm/v/@locusgraph/components?label=&color=111111&style=flat-square)](https://www.npmjs.com/package/@locusgraph/components) | React components on Radix, Rule Grid, the App and Docs shells and the theme. Start here |
| [`@locusgraph/blocks`](packages/blocks) | [![npm](https://img.shields.io/npm/v/@locusgraph/blocks?label=&color=111111&style=flat-square)](https://www.npmjs.com/package/@locusgraph/blocks) | Product sections: `Usage`, `Quota`, `Wallet`, `TopUp`, `Plans` and `Keys`, with skeletons |
| [`@locusgraph/loop`](packages/loop) | [![npm](https://img.shields.io/npm/v/@locusgraph/loop?label=&color=111111&style=flat-square)](https://www.npmjs.com/package/@locusgraph/loop) | Agent UI with the human in the loop: chat, tools, approvals, decision log, memory and cost |
| [`@locusgraph/json-render`](packages/json-render) | [![npm](https://img.shields.io/npm/v/@locusgraph/json-render?label=&color=111111&style=flat-square)](https://www.npmjs.com/package/@locusgraph/json-render) | A [json-render](https://json-render.dev) catalog and registry, so a model can lay out screens as JSON |
| [`@locusgraph/tokens`](packages/tokens) | [![npm](https://img.shields.io/npm/v/@locusgraph/tokens?label=&color=111111&style=flat-square)](https://www.npmjs.com/package/@locusgraph/tokens) | The theme as CSS (palette, type, hairlines, motion) and as TypeScript values |
| [`@locusgraph/brand`](packages/brand) | [![npm](https://img.shields.io/npm/v/@locusgraph/brand?label=&color=111111&style=flat-square)](https://www.npmjs.com/package/@locusgraph/brand) | Marks, wordmarks, app icon, social card, and the Google and GitHub marks |
| [`@locusgraph/email`](packages/email) | [![npm](https://img.shields.io/npm/v/@locusgraph/email?label=&color=111111&style=flat-square)](https://www.npmjs.com/package/@locusgraph/email) | Transactional email templates with inline styles from tokens |
| [`@locusgraph/utils`](packages/utils) | [![npm](https://img.shields.io/npm/v/@locusgraph/utils?label=&color=111111&style=flat-square)](https://www.npmjs.com/package/@locusgraph/utils) | Money, counts, dates, quota and balance helpers. No dependencies |
| [`@locusgraph/config`](packages/config) | [![npm](https://img.shields.io/npm/v/@locusgraph/config?label=&color=111111&style=flat-square)](https://www.npmjs.com/package/@locusgraph/config) | Biome, TypeScript, Vitest and PostCSS settings |

Examples: [Next.js App Router](apps/example-next) and [React with Vite](apps/example-react).

## For AI agents

[DESIGN.md](https://design.locusgraph.com/DESIGN.md) lists every page with a Markdown version: add
`.md` to any docs path.

## Develop

Expand Down
Loading