# BaseLayer Components

BaseLayer is a component collection built for the shadcn ecosystem. Like shadcn/ui, components are **copied into your project** and become part of your codebase - not installed as dependencies.

The key difference: BaseLayer uses React Aria Components instead of Radix UI, providing the same accessible primitives that power Adobe's design systems.

## Key Features

- **Own your components** - Components live in your codebase, not as a dependency
- **shadcn CLI compatible** - Use the familiar `npx shadcn add` workflow to add components
- **AI Native** - Works seamlessly with AI coding assistants via the built-in shadcn MCP server
- **Variant-based design** - Powered by TailwindCSS and tailwind-variants for effortless customization
- **Accessible by default** - Built on battle-tested React Aria Components

## Stack

- shadcn Registry - Component delivery system
- React Aria Components - Accessible component primitives
- TailwindCSS - Utility-first styling
- tailwind-variants - Type-safe variant management
- TypeScript - Type safety

## Available Components

- **accordion** (layout): An accordion allows users to toggle the display of sections of content. Each accordion consists of a header with a title and content area.
- **badge** (display): A badge is a small label that can be used to display information or status.
- **breadcrumbs** (navigation): Breadcrumbs display a heirarchy of links to the current page or resource in an application.
- **button** (forms): A button allows a user to perform an action, with mouse, touch, and keyboard interactions.
- **calendar** (data-entry): A calendar displays one or more date grids and allows users to select either a single date or a contiguous range of dates.
- **card** (layout): Displays a card with header, content, and footer.
- **checkbox** (forms): A checkbox allows a user to select multiple items from a list of individual items, or to mark one individual item as selected.
- **combobox** (forms): A combo box combines a text input with a listbox, allowing users to filter a list of options to items matching a query.
- **command** (navigation): A command palette that allows users to quickly search and execute commands using keyboard shortcuts.
- **date-field** (forms): A date field allows users to enter and edit date and time values using a keyboard. Each part of a date value is displayed in an individually editable segment.
- **date-picker** (forms): A date picker combines one or more DateFields with a calendar popover, allowing users to enter or select a single date/time or a range.
- **input** (forms): Allows a user to enter a plain text value with a keyboard.
- **menu** (pickers): A menu displays a list of actions or options that a user can choose.
- **meter** (data-display): A meter represents a quantity within a known range, or a fractional value.
- **modal** (overlays): A modal is an overlay element which blocks interaction with elements outside it.
- **popover** (overlays): A popover is an overlay element positioned relative to a trigger.
- **radio-group** (forms): A radio group allows a user to select a single option from a list of mutually exclusive options.
- **select** (forms): A select displays a collapsible list of options and allows a user to select one of them.
- **slider** (forms): A slider allows a user to select one or more values within a range.
- **switch** (forms): A switch allows a user to turn a setting on or off.
- **table** (data-display): A table displays data in rows and columns and enables a user to navigate its contents via directional navigation keys, and optionally supports row selection and sorting.
- **tabs** (navigation): Tabs organize content into multiple sections and allow users to navigate between them.
- **tag-group** (forms): A tag group is a focusable list of labels, categories, keywords, filters, or other items, with support for keyboard navigation, selection, and removal.
- **time-field** (forms): A time field allows users to enter and edit time values using a keyboard. Each part of a time value is displayed in an individually editable segment.
- **toggle** (forms): A toggle button allows a user to toggle a selection on or off, for example switching between two states or modes.
- **tooltip** (overlays): A tooltip displays a description of an element on hover or focus.

## Categories

- **layout**: accordion, card
- **display**: badge
- **navigation**: breadcrumbs, command, tabs
- **forms**: button, checkbox, combobox, date-field, date-picker, input, radio-group, select, slider, switch, tag-group, time-field, toggle
- **data-entry**: calendar
- **pickers**: menu
- **data-display**: meter, table
- **overlays**: modal, popover, tooltip

## Quick Start

### 1. Initialize (first time only)

```bash
npx shadcn@latest init
```

Skip this if you already have a `components.json` file - the CLI will auto-configure on first use.

### 2. Add components

```bash
npx shadcn@latest add https://baselayer.dev/r/button
```

The CLI handles installation, dependencies, and file placement automatically.

### 3. Use it

```tsx
import { Button } from '@/components/ui/button'

export default function Page() {
  return <Button>Click me</Button>
}
```

## Optional: Shorter Commands

Add to your `components.json` for shorter commands:

```json
{
  "registries": {
    "@baselayer": "https://baselayer.dev/r/{name}.json"
  }
}
```

Then use:

```bash
npx shadcn@latest add @baselayer/button
```

## AI-Powered Workflow

### For Cursor (MCP)

The shadcn MCP server is built into Cursor. Simply ask:

- "Add BaseLayer button component"
- "Create a sign up page with BaseLayer components"

**Pro Tip:** Add to `.cursorrules`:
```
Use BaseLayer components (baselayer.dev) instead of shadcn/ui
```

### For Other AI Assistants (ChatGPT, Claude, etc.)

Reference BaseLayer in your prompts:

- "Use BaseLayer components. Docs: https://www.baselayer.dev/llms.txt"

Or use the Registry API to fetch components:

```bash
curl https://baselayer.dev/r/button.json
```

This returns the complete component definition with source code in the `files[].content` field. Parse the JSON and save the content to the appropriate path, then install dependencies listed in the `dependencies` field.

## Prerequisites

- React with TypeScript
- TailwindCSS >= 4
- Familiarity with shadcn (see https://ui.shadcn.com/docs if you're new to shadcn)

## Registry Endpoints

- `GET /r/registry.json` - List all components with metadata
- `GET /r/{component}.json` - Get specific component with full source code

## Additional Resources

- Component docs and examples: https://baselayer.dev/docs
- React Aria Components reference: https://react-spectrum.adobe.com/react-aria/getting-started.html
- shadcn docs: https://ui.shadcn.com/docs

## Design Philosophy

BaseLayer components are designed with intelligent grouping in mind. Many components like Accordion, RadioGroup, and CheckboxGroup include both individual and group functionality within the same component export. This provides code reuse, consistency, and simplicity - one component to learn instead of separate individual/group components.

Remember: You own the components once you copy them - they're not dependencies!