Get Started
AGENTS.md
A vendor-neutral instruction file for AI coding agents (Claude, Cursor, Copilot, Cline, Continue). Drop it at the root of any consumer project so agents know how to install Twigs components, which tokens to use, and what already exists.
Why this file
Most coding agents look for a markdown rules file at the repo root. AGENTS.md is the emerging cross-tool convention; Claude Code, Cursor, and several others read it without configuration. One file replaces tool-specific equivalents like CLAUDE.md, .cursor/rules/*, or .github/copilot-instructions.md.
Add it to your project
From the root of your consumer project, fetch the latest version directly:
bash
curl -o AGENTS.md https://twigs.globirdenergy.com.au/AGENTS.mdRe-run periodically to pick up new components. Or use Copy file above.
Contents
Auto-generated from the registry — the component list stays in sync as items are added.
markdown
# AGENTS.md
This project consumes the **GloBird Twigs** design system. Read this file before creating any UI.
Source of truth: https://twigs.globirdenergy.com.au
## Rules
1. **Never write raw colours, spacing, or radius values.** Always use the semantic tokens from `tokens.css` (e.g. `bg-primary`, `text-foreground`, `rounded-md`, `p-4`). If a design needs a value the tokens don't cover, raise it with the design-systems team — do not add a one-off.
2. **Check the registry before creating a new component.** A component you need probably already exists. The full list is at the bottom of this file.
3. **Install components via the shadcn CLI**, never by hand-copying source. The CLI wires up dependencies, tokens, and import aliases automatically.
4. **Do not modify installed component source** beyond what the design brief requires. Treat `components/ui/*` as vendored — local edits will fight future updates.
5. **For React Native / Vue / Svelte projects:** copy the React + Tailwind source from the registry, then translate. Preserve prop APIs and token names exactly.
## Setup (one-time, per consumer project)
Initialise shadcn:
```bash
npx shadcn@latest init
```
Register Twigs as a namespaced registry by adding this to `components.json`:
```json
{
"registries": {
"@twigs": "https://twigs.globirdenergy.com.au/r/{name}.json"
}
}
```
Install the tokens (required by every component):
```bash
npx shadcn@latest add @twigs/tokens
```
## Adding a component
```bash
npx shadcn@latest add @twigs/button
npx shadcn@latest add @twigs/input @twigs/dialog
```
The CLI fetches the source, installs npm deps (`class-variance-authority`, `@base-ui/react`, etc.), and writes files to `components/ui/`.
## Tokens at a glance
Use these Tailwind utility classes — they're wired to CSS variables defined by `@twigs/tokens`:
- **Colour:** `bg-primary`, `bg-secondary`, `bg-destructive`, `bg-muted`, `bg-accent`, `bg-background`, `bg-card`, `bg-popover`. Each has a matching `text-*-foreground`.
- **Border / ring:** `border`, `border-input`, `ring-ring`.
- **Radius:** `rounded-sm`, `rounded-md`, `rounded-lg`, `rounded-xl`, `rounded-full`.
- **Typography:** the default font stack and `text-*` sizes inherit from the tokens — no need to set `font-family`.
Dark mode is handled by adding `class="dark"` to `<html>`. Token variables flip automatically.
## Available components
| Slug | Category | Description |
|---|---|---|
| `accordion` | navigation | A vertically stacked set of interactive headings that each reveal a section of content. |
| `alert` | feedback | Displays a callout for user attention. |
| `alert-dialog` | overlay | A modal dialog that interrupts the user with important content and expects a response. |
| `aspect-ratio` | layout | Displays content within a desired aspect ratio. |
| `avatar` | display | An image element with a fallback for representing a user. |
| `badge` | display | Displays a small status descriptor. |
| `breadcrumb` | navigation | Displays the path to the current resource using a hierarchy of links. |
| `button` | form | Displays a button or a component that looks like a button. |
| `calendar` | form | A date field component that allows users to enter and edit date. |
| `card` | layout | Displays a card with header, content, and footer. |
| `carousel` | display | A carousel with motion and swipe built using Embla. |
| `checkbox` | form | A control that allows the user to toggle between checked and not checked. |
| `dialog` | overlay | A window overlaid on either the primary window or another dialog window. |
| `input` | form | Displays a form input field. |
| `input-otp` | form | Accessible one-time password component with copy paste functionality. |
| `label` | form | Renders an accessible label associated with controls. |
| `progress` | feedback | Displays an indicator showing the completion progress of a task. |
| `radio-group` | form | A set of checkable buttons where only one can be checked at a time. |
| `select` | form | Displays a list of options for the user to pick from. |
| `separator` | layout | Visually or semantically separates content. |
| `skeleton` | feedback | Use to show a placeholder while content is loading. |
| `slider` | form | An input where the user selects a value from within a given range. |
| `switch` | form | A control that allows the user to toggle between checked and unchecked states. |
| `tabs` | navigation | A set of layered sections of content, also known as tab panels. |
| `textarea` | form | Displays a form textarea or a component that looks like a textarea. |
| `tooltip` | overlay | A popup that displays information related to an element when it receives keyboard focus. |
To install any of these, run `npx shadcn@latest add @twigs/<slug>`. Source previews live at https://twigs.globirdenergy.com.au/docs/components/<slug>.
## When the agent is unsure
- Need a component not in the table? Ask before building one. The design-systems team owns the registry; one-offs in product repos defeat the purpose.
- Need a token not covered? Same — raise it, don't paper over.
- Building for a non-React stack? Pull the React source from `https://twigs.globirdenergy.com.au/r/<slug>.json`, port it, and keep token class names verbatim.