gaia-ui: Instructions file for Codex

AGENTS.md

Hey there! Welcome to the Gaia UI library. This guide will walk you through everything you need to know about adding new components, maintaining design consistency, and keeping things beautiful.

Quick Start: Adding a New Component

When you add a new component, you'll need to touch a few places. Here's the checklist:

1. Create the Component File

Add your component to registry/new-york/ui/your-component.tsx. This is where the actual component code lives.

registry/
└── new-york/
    └── ui/
        └── your-component.tsx  ← Your new component

2. Register It

Open registry.json in the project root and add your component to the items array:

{
  "name": "your-component",
  "type": "registry:ui",
  "title": "Your Component",
  "description": "A brief, compelling description of what this component does.",
  "dependencies": ["any-npm-packages"],
  "registryDependencies": ["icons", "other-gaia-components"],
  "files": [
    {
      "path": "registry/new-york/ui/your-component.tsx",
      "type": "registry:ui"
    }
  ]
}

3. Add Preview Components

Create preview examples in components/previews/your-component/:

components/
└── previews/
    └── your-component/
        ├── default.tsx          ← Basic usage example
        ├── with-variants.tsx    ← Different variants
        └── custom-example.tsx   ← Any other demos

4. Write the Documentation

Create a docs page at content/docs/components/your-component.mdx:

---
title: Your Component
description: What it does and why someone would use it.
---

<ComponentPreview name="your-component/default" />

## Usage

Show how to use it.

## Installation

<Tabs defaultValue="automatic" className="mt-4">
  <!-- Add both automatic and manual installation options -->
</Tabs>

## Props

Document all the props in a table.

5. Update Navigation (if needed)

If you're adding a new category or the component needs special placement, update lib/navigation.ts.