Skip to main content
When you add a new component to Gaia UI, you’ll need to follow a structured workflow to ensure it’s properly registered, documented, and accessible to users. This guide walks you through each step.

​
Component Addition Workflow

1
Create the Component File
2
Add your component to registry/new-york/ui/your-component.tsx. This is where the actual component code lives.
3
import * as React from "react";
import { cn } from "@/lib/utils";

export interface YourComponentProps {
  /** Brief description of this prop */
  variant?: "default" | "outline" | "ghost";
  /** Always include className for customization */
  className?: string;
  /** Children when applicable */
  children?: React.ReactNode;
}

const YourComponent = React.forwardRef<HTMLDivElement, YourComponentProps>(
  ({ className, variant = "default", children, ...props }, ref) => {
    return (
      <div
        ref={ref}
        className={cn(
          "base-classes",
          variant === "primary" && "primary-classes",
          className
        )}
        {...props}
      >
        {children}
      </div>
    );
  }
);
YourComponent.displayName = "YourComponent";

export { YourComponent };
4
The registry follows this structure:
5
registry/
└── new-york/
    └── ui/
        ├── navbar-menu.tsx
        ├── raised-button.tsx
        ├── weather-card.tsx
        └── your-component.tsx  ← Your new component
6
Register in registry.json
7
Open registry.json in the project root and add your component to the items array:
8
{
  "name": "your-component",
  "type": "registry:ui",
  "title": "Your Component",
  "description": "A brief, compelling description of what this component does.",
  "dependencies": ["react-parallax-tilt"],
  "registryDependencies": ["icons"],
  "files": [
    {
      "path": "registry/new-york/ui/your-component.tsx",
      "type": "registry:ui"
    }
  ]
}
9
Real example from the registry:
10
{
  "name": "raised-button",
  "type": "registry:ui",
  "title": "Raised Button",
  "description": "A button with a subtle 3D raised effect and smooth press animation.",
  "files": [
    {
      "path": "registry/new-york/ui/raised-button.tsx",
      "type": "registry:ui"
    }
  ]
}
11
After adding your entry, build the registry:
12
pnpm run registry:build
13
Add Preview Components
14
Create preview examples in components/previews/your-component/. These previews will be shown in the documentation.
15
components/
└── previews/
    └── your-component/
        ├── default.tsx          ← Basic usage example
        ├── with-variants.tsx    ← Different variants
        └── custom-example.tsx   ← Any other demos
16
Example preview component:
17
import { YourComponent } from "@/registry/new-york/ui/your-component";

export default function YourComponentDefault() {
  return (
    <YourComponent variant="default">
      Example content
    </YourComponent>
  );
}
18
Write the Documentation
19
Create a docs page at content/docs/components/your-component.mdx.
20
Your documentation should include:
21
  • Title and description frontmatter
  • Component preview
  • Usage examples
  • Installation instructions (automatic and manual)
  • Props documentation with types and descriptions
  • Examples showing different variants and features
    • 22
    See existing component docs for reference patterns.
    23
    Update Navigation (Optional)
    24
    If you’re adding a new category or the component needs special placement, update lib/navigation.ts.
    25
    For most components, they’ll automatically appear in the components section once documented.

    ​
    Component File Structure

    If your component has multiple parts or requires additional files: 
    registry/new-york/ui/
├── your-component.tsx           // Main component + compound parts
├── your-component.css           // CSS if needed (rare)
└── your-component-utils.ts      // Helper functions if needed
    Example with CSS file: 
    {
  "name": "holo-card",
  "files": [
    {
      "path": "registry/new-york/ui/holo-card.tsx",
      "type": "registry:ui"
    },
    {
      "path": "registry/new-york/ui/holo-card.css",
      "type": "registry:ui"
    }
  ]
}

    ​
    Testing Your Component Locally

    Before submitting, test your component locally: 
    # Start the dev server
pnpm run dev

# In another terminal, test the installation
npx shadcn@latest add http://localhost:3000/r/your-component.json

    ​
    Checklist Before Submitting

    Before you consider a component done:
    • Works in light and dark mode
    • Fully keyboard accessible
    • Has proper ARIA labels
    • Respects reduced motion preferences
    • Uses semantic HTML elements
    • Follows the spacing guidelines
    • No hardcoded colors (uses CSS variables)
    • Registered in registry.json
    • Has preview components
    • Has documentation with props table
    • Types are exported

    ​
    Need Help?

    If something isn’t covered here or you’re unsure about a design decision, look at existing components for patterns. The tool-calls-section, composer, and weather-card components are good references for complex UI.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us