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.md

Re-run periodically to pick up new components. Or use Copy file above.

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. |
| `button-group` | form | Groups related buttons and controls into a single connected action surface. |
| `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. |
| `chart` | data | Composable chart primitives powered by Recharts and semantic theme tokens. |
| `checkbox` | form | A control that allows the user to toggle between checked and not checked. |
| `collapsible` | layout | An interactive region that expands and collapses content. |
| `combobox` | form | A searchable select input for choosing from a list of options. |
| `command` | navigation | A command menu for fast search, navigation, and actions. |
| `context-menu` | overlay | A menu triggered by right click or long press for contextual actions. |
| `date-picker` | form | A calendar-based date selection pattern using popover and calendar primitives. |
| `dialog` | overlay | A window overlaid on either the primary window or another dialog window. |
| `direction` | layout | A direction provider for left-to-right and right-to-left interface contexts. |
| `drawer` | overlay | A panel that slides from the edge of the screen, commonly used on mobile. |
| `dropdown-menu` | overlay | Displays a menu of actions or links from a trigger. |
| `empty` | feedback | A reusable empty state pattern for missing or incomplete content. |
| `field` | form | Composable field, fieldset, label, description, and error primitives. |
| `hover-card` | overlay | Shows rich contextual content when a user hovers or focuses a trigger. |
| `input` | form | Displays a form input field. |
| `input-group` | form | Composes inputs with prefixes, suffixes, buttons, and helper controls. |
| `input-otp` | form | Accessible one-time password component with copy paste functionality. |
| `item` | display | A structured row primitive for lists, settings, and action groups. |
| `kbd` | typography | Displays keyboard shortcuts and command hints. |
| `label` | form | Renders an accessible label associated with controls. |
| `menubar` | navigation | A horizontal application menu with nested actions. |
| `native-select` | form | A styled native select control for platform-native option picking. |
| `navigation-menu` | navigation | A responsive navigation menu with rich dropdown content. |
| `pagination` | navigation | Pagination controls for moving through a collection of pages. |
| `popover` | overlay | Displays floating content anchored to a trigger. |
| `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. |
| `resizable` | layout | Resizable panel groups for split views and editor-like layouts. |
| `scroll-area` | layout | Custom scrollable areas with consistent scrollbar styling. |
| `select` | form | Displays a list of options for the user to pick from. |
| `separator` | layout | Visually or semantically separates content. |
| `sheet` | overlay | A side panel for secondary workflows and focused tasks. |
| `sidebar` | navigation | A complete, collapsible application sidebar system. |
| `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. |
| `sonner` | feedback | Toast notifications for success, loading, warning, and error feedback. |
| `spinner` | feedback | A compact loading indicator for pending UI states. |
| `switch` | form | A control that allows the user to toggle between checked and unchecked states. |
| `table` | data | Displays tabular data with headers, rows, cells, and captions. |
| `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. |
| `toast` | feedback | Legacy toast guidance represented here with the current Sonner implementation. |
| `toggle` | form | A two-state button that can be pressed or unpressed. |
| `toggle-group` | form | A set of two-state buttons for mutually exclusive or multi-select options. |
| `tooltip` | overlay | A popup that displays information related to an element when it receives keyboard focus. |
| `typography` | typography | Readable prose, headings, lists, and inline text treatments. |

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.

AGENTS.md

Why this file

Add it to your project

Contents