cosscom__coss/apps/ui/.cursorrules

### Adding a new particle component (registry/default/particles)

This guide explains the end‑to‑end steps for adding a new component under `@particles/` and making it available in the app and registry.

—

## 1) Create the component file

- Location: `apps/ui/registry/default/particles/`
- Naming: `particle-{category_shortcode}-{N}.tsx`
  - **category_shortcode**: two-letter key for the component category. Examples: `bu` = button, `in` = input, `to` = toggle, `tg` = toggle group, `tt` = tooltip, `ta` = table, `tb` = tabs, `te` = textarea, `ts` = toast.
  - **N**: progressive number within the category (e.g. `1`, `2`, `3`).
- Export as a functional component:

```tsx
export default function Particle() {
  // ...
}
```

Notes:
- Use Base UI primitives from `apps/ui/registry/default/ui/` (e.g. `input`, `button`, `label`, etc.) as needed.
- If a particle is made of more UI primitives, arbitrarily decide the main category for the file name.
- Keep files minimal and aligned to the docs examples.

## 2) Register in particles index

Edit: `apps/ui/registry/default/particles/index.tsx`

Actions:
- Import your new component file: `import Particle from "./particle-in-6"`
- Add an entry to `particles` array with:
  - **id**: same as filename without extension (e.g. `particle-in-6`).
  - **component**: the imported component.
  - **category**: array of big categories used by this particle. Use the slugs of the UI dependencies from `@ui/` that the component uses (e.g. `["input"]`, `["input", "button"]`).
  - **className** (optional): wrapper utility. For example, for inputs and forms we use:
    `"**:data-[slot=particle-wrapper]:w-full **:data-[slot=particle-wrapper]:max-w-64"`. That's to prevent them spanning the whole width - not every components need a custom class.

Example entry:

```tsx
{
  id: "particle-in-6",
  component: ParticleIn6,
  category: ["input"],
  className:
    "**:data-[slot=particle-wrapper]:w-full **:data-[slot=particle-wrapper]:max-w-64",
}
```

## 3) Add a registry item

Edit: `apps/ui/registry/registry-particles.ts`

For each new particle, add an object with the following fields:
- **name**: the particle id (e.g. `particle-in-6`).
- **description**: concise, ≤ 15 words, clear to end users.
  - Example: `"Ghost button with left arrow icon and hover animation"`.
- **type**: `"registry:block"`.
- **registryDependencies**: URLs or names of required registry items for the UI primitives used.
  - For our particles, reference our hosted registry items such as `https://coss.com/r/input.json`, `https://coss.com/r/button.json`, `https://coss.com/r/label.json`, etc.
- **dependencies**: npm package dependencies if needed (often empty for simple particles).
- **files**: include exactly one file pointing to the particle source:
  - `path`: `"particles/particle-in-6.tsx"`
  - `type`: `"registry:block"`
- **categories**: treat as tags (not big category). Use only from the approved list below.

Example entry:

```ts
{
  name: "particle-in-6",
  description: "Input with helper label",
  type: "registry:block",
  registryDependencies: [
    "https://coss.com/r/input.json",
    "https://coss.com/r/label.json",
  ],
  files: [
    { path: "particles/particle-in-6.tsx", type: "registry:block" },
  ],
  categories: ["input", "label"],
}
```

Schema reference: see `registry-item.json` specification at
`https://ui.shadcn.com/docs/registry/registry-item-json`.

## ) Build the registry

Run from repo root:

```bash
bun run registry:build
```

This updates the built registry JSON in `apps/ui/public/ui/r/`.

—

## Approved categories (tags)

Use these only for the `categories` field in `registry-particles.ts`:

accordion, alert, avatar, badge, banner, breadcrumb, button, calendar, checkbox, checkbox group, collapsible, combobox, command, crop, dialog, dropdown, field, fieldset, form, input, label, notification, otp, pagination, popover, radio, select, slider, sonner, stepper, table, tabs, textarea, timeline, switch, tooltip, alert dialog, authentication, autocomplete, avatar group, back, card, chart, checkout, chip, color, controls, cookies, countdown, counter, copy, credit card, darkmode, date, delete, disabled, drag and drop, emblor, equalizer, error, feedback, file, filter, flag, gdpr, hamburger, helper, hint, hover card, image, info, kbd, like, loading, login, mask, menu, modal, multiselect, native select, newsletter, next, number, onboarding, password, payment, phone, picker, previous, pricing, privacy, profile, radix, range, range calendar, range slider, rating, react aria, react daypicker, read-only, required, reset, resize, sale, search, share, signup, social, sort, status, sticky, subscribe, success, tag, tanstack, team, text editor, time, timezone, toast, toggle, toggle group, tour, tree, upload, user, vertical slider, vertical stepper, vertical table, vertical tabs, vertical timeline, volume, vote, warning, week, zod, zoom

—

## Quick checklist

- Create `registry/default/particles/particle-{category_shortcode}-{N}.tsx` with `export default function Particle()`.
- Import and add it to `registry/default/particles/index.tsx` with correct `id`, `category`, and optional `className`.
- Add an item to `registry/registry-particles.ts` with `name`, `description`, `type`, `registryDependencies`, optional `dependencies`, `files`, and `categories` (tags).
- Run `bun run registry:build` from `apps/ui`