Feat/ai implementations

.agents/skills/coss/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: coss
+description: Helps implement coss UI components correctly. Use when building UIs with coss primitives (buttons, dialogs, selects, forms, menus, tabs, inputs, toasts, etc.), migrating from shadcn/Radix to coss/Base UI, composing trigger-based overlays, or troubleshooting coss component behavior. Covers imports, accessibility, Tailwind styling, and common pitfalls.
+compatibility: Requires Tailwind CSS v4 and @base-ui/react. Designed for React projects using the coss component registry.
+license: MIT
+metadata:
+  author: cosscom
+---
+
+# coss ui
+
+coss ui is a component library built on Base UI with a shadcn-like developer experience plus a large particle catalog.
+
+## What this skill is for
+
+Use this skill to:
+
+- pick the right coss primitive(s) for a UI task
+- write correct coss usage code (imports, composition, props)
+- avoid common migration mistakes from shadcn/Radix assumptions
+- reference particle examples to produce practical, production-like patterns
+
+## Source of truth
+
+- coss components docs: `apps/ui/content/docs/components/*.mdx`
+  - `https://github.com/cosscom/coss/tree/main/apps/ui/content/docs/components`
+- coss particle examples: `apps/ui/registry/default/particles/p-*.tsx`
+  - `https://github.com/cosscom/coss/tree/main/apps/ui/registry/default/particles`
+- coss particles catalog: `https://coss.com/ui/particles`
+- docs map for agents: `https://coss.com/ui/llms.txt`
+
+## Out of scope
+
+- Maintaining coss monorepo internals/build pipelines.
+- Editing registry internals unless explicitly requested.
+
+## Principles for agent output
+
+1. Use existing primitives and particles first before inventing custom markup.
+2. Prefer composition over custom behavior reimplementation.
+3. Follow coss naming and APIs from docs exactly.
+4. Keep examples accessible and production-realistic.
+5. Prefer concise code that mirrors coss docs/particles conventions.
+6. Assume Tailwind CSS v4 conventions in coss examples and setup guidance.
+
+## Critical usage rules
+
+Always apply before returning coss code:
+
+- Do not invent coss APIs. Verify against component docs first.
+- For trigger-based primitives (Dialog, Menu, Select, Popover, Tooltip), follow each primitive's documented trigger/content hierarchy and composition API; do not mix patterns across components.
+- Preserve accessibility labels and error semantics.
+- Consult primitive-specific guides for component invariants and edge cases.
+- For manual install guidance, include all required dependencies and local component files referenced by imports.
+- Prefer styled coss exports first; use `*Primitive` exports only when custom composition/styling requires it.
+
+Rule references (read on demand when the task touches these areas):
+
+- `./references/rules/styling.md` — Tailwind tokens, icon conventions, data-slot selectors
+- `./references/rules/forms.md` — Field composition, validation, input patterns
+- `./references/rules/composition.md` — Trigger/popup hierarchies, grouped controls
+- `./references/rules/migration.md` — shadcn/Radix to coss/Base UI migration patterns
+- `./references/portal-props.md` — optional `portalProps` on composed popups and toast providers (`keepMounted`, `container`, which surfaces support it)
+
+## Component discovery
+
+All 53 primitives have dedicated reference guides at `./references/primitives/<name>.md`. To find the right one for a task, consult the component registry index:
+
+- `./references/component-registry.md`
+
+## Usage workflow
+
+1. Identify user intent (single primitive, composed flow, form flow, overlay flow, feedback flow).
+2. Consult `references/component-registry.md` to identify candidate primitives.
+3. Select primitives from coss docs first; avoid custom fallback unless needed.
+4. Check at least one particle example for practical composition patterns. Particle files live at `apps/ui/registry/default/particles/p-<name>-<N>.tsx` (e.g. `p-dialog-1.tsx`).
+5. Write minimal code using documented imports/props.
+6. Self-check accessibility and composition invariants.
+
+## Installation reference
+
+See `./references/cli.md` for full install/discovery workflow.
+
+Quick CLI pattern:
+
+```bash
+npx shadcn@latest add @coss/<component>
+```
+
+Quick manual pattern:
+
+- install dependencies listed in the component docs page
+- copy required component file(s)
+- update imports to match the target app alias setup
+
+## Primitive Guidance
+
+Every primitive has a reference guide at `./references/primitives/<name>.md` with imports, minimal patterns, inline code examples, pitfalls, and particle references. Use the component registry to find the right file.
+
+High-risk primitives (read these guides first -- they have the most composition gotchas):
+
+- `./references/primitives/dialog.md` — modal overlays, form-in-dialog, responsive dialog/drawer
+- `./references/primitives/menu.md` — dropdown actions, checkbox/radio items, submenus
+- `./references/primitives/select.md` — items-first pattern, multiple, object values, groups
+- `./references/primitives/form.md` — Field composition, validation, submission
+- `./references/primitives/input-group.md` — addons, DOM order invariant, textarea layouts
+- `./references/primitives/toast.md` — toastManager (not Sonner), anchored toasts, providers
+
+## Output Checklist
+
+Before returning code:
+
+- imports and props match coss docs
+- composition structure is valid for selected primitive(s)
+- accessibility and explicit control types (`button`, `input`, etc.) are present
+- migration-sensitive flows are verified (type/lint, keyboard/a11y behavior, and SSR-sensitive primitives like Select/Command)

.agents/skills/coss/references/cli.md

@@ -0,0 +1,110 @@
+# coss CLI Reference (Focused)
+
+Use this guide when installing, previewing, or discovering coss components via the shadcn CLI.
+
+## CLI Safety Rules
+
+- Always use the project's package runner:
+  - `npx shadcn@latest ...`
+  - `pnpm dlx shadcn@latest ...`
+  - `bunx --bun shadcn@latest ...`
+- Do not invent flags. Use only documented CLI flags.
+
+## Core Commands for coss Usage
+
+### Recommended bootstrap paths
+
+```bash
+# New projects (recommended — includes Inter + Geist Mono fonts + full theme)
+npx shadcn@latest init @coss/style
+
+# Existing projects - all primitives
+npx shadcn@latest add @coss/ui
+
+# Existing projects - full theme setup
+npx shadcn@latest add @coss/style
+
+# Existing projects - primitives + color tokens
+npx shadcn@latest add @coss/ui @coss/colors-neutral
+```
+
+`@coss/style` automatically installs `@coss/fonts` (Inter for `--font-sans` and `--font-heading`, Geist Mono for `--font-mono`), which configures all three font variables in `layout.tsx`. No manual font wiring needed.
+
+### `add` (primary)
+
+```bash
+shadcn add @coss/<component>
+```
+
+Examples:
+
+```bash
+npx shadcn@latest add @coss/dialog
+npx shadcn@latest add @coss/select
+npx shadcn@latest add @coss/toast
+```
+
+### `add` preview mode (recommended)
+
+```bash
+npx shadcn@latest add @coss/dialog --dry-run
+npx shadcn@latest add @coss/dialog --diff
+npx shadcn@latest add @coss/dialog --view
+```
+
+Use preview mode when:
+
+- user asks what will change
+- component might already exist locally
+- you need to inspect output before writing files
+
+### Optional discovery helpers (use when available)
+
+```bash
+npx shadcn@latest search @coss -q "dialog"
+npx shadcn@latest view @coss/dialog
+npx shadcn@latest docs dialog
+npx shadcn@latest info --json
+```
+
+If these are unsupported in the environment, use fallback sources below.
+
+## Discovery Fallback Matrix
+
+### Inside the coss repo (preferred)
+
+- `apps/ui/registry/registry-particles.ts`
+  - `https://github.com/cosscom/coss/blob/main/apps/ui/registry/registry-particles.ts`
+- `apps/ui/registry.json`
+  - `https://github.com/cosscom/coss/blob/main/apps/ui/registry.json`
+- `apps/ui/content/docs/components/*.mdx`
+  - `https://github.com/cosscom/coss/tree/main/apps/ui/content/docs/components`
+
+### Outside the coss repo
+
+- coss particles catalog: `https://coss.com/ui/particles`
+- coss docs catalog: `https://coss.com/ui/`
+
+## Manual Install Path
+
+When users explicitly request manual setup:
+
+1. Read the target component docs.
+2. Install exactly the listed dependencies.
+3. Copy all required files (including transitive local imports).
+4. Adjust imports for target app aliases.
+5. Validate the snippet against docs/particles patterns.
+
+Important:
+
+- CLI setup usually wires required theme tokens automatically.
+- Manual setup must include required additional tokens (`destructive-foreground`, `info`, `success`, `warning` families) from coss styling docs when relevant.
+
+## Quick Output Checklist
+
+Before returning CLI guidance:
+
+1. runner and command are valid for the user's package manager
+2. flags are documented and intentional
+3. fallback source is provided if CLI discovery commands are unavailable
+4. resulting usage guidance matches coss docs and particles patterns

.agents/skills/coss/references/component-registry.md

@@ -0,0 +1,82 @@
+# coss Component Registry Index
+
+Use this file to quickly identify the right coss primitive for a UI task. Each entry includes the component name, a one-line purpose, and the path to its reference guide (relative to the skill root `apps/ui/skills/coss/`).
+
+For optional **`portalProps`** on composed `*Popup` components and **toast** providers (Base UI portal forwarding), see `./references/portal-props.md`.
+
+## Overlays & Popups
+
+- **Dialog** — Centered modal requiring user focus. `./references/primitives/dialog.md`
+- **AlertDialog** — Destructive/critical confirmation modal. `./references/primitives/alert-dialog.md`
+- **Sheet** — Side-panel overlay for settings/details. `./references/primitives/sheet.md`
+- **Drawer** — Bottom/side drawer, often mobile-responsive. `./references/primitives/drawer.md`
+- **Popover** — Anchored non-modal floating content. `./references/primitives/popover.md`
+- **Tooltip** — Short hover/focus hint text. `./references/primitives/tooltip.md`
+- **PreviewCard** — Hover-triggered rich entity preview. `./references/primitives/preview-card.md`
+- **Menu** — Dropdown action list with groups/submenus. `./references/primitives/menu.md`
+- **Command** — Searchable command palette (not cmdk). `./references/primitives/command.md`
+
+## Selection & Input
+
+- **Select** — Single-choice from predefined list (no search). `./references/primitives/select.md`
+- **Combobox** — Searchable selection with filtering. `./references/primitives/combobox.md`
+- **Autocomplete** — Free-text with suggestions. `./references/primitives/autocomplete.md`
+- **Input** — Single-line text entry. `./references/primitives/input.md`
+- **Textarea** — Multi-line text entry. `./references/primitives/textarea.md`
+- **InputGroup** — Input with addons (icons, buttons, badges). `./references/primitives/input-group.md`
+- **OTPField** — One-time passcode segmented slots. `./references/primitives/otp-field.md`
+- **NumberField** — Numeric entry with stepper controls. `./references/primitives/number-field.md`
+- **Slider** — Continuous/ranged numeric control. `./references/primitives/slider.md`
+- **Calendar** — Date picker / calendar views. `./references/primitives/calendar.md`
+
+## Forms & Validation
+
+- **Form** — Form validation/submission with Zod. `./references/primitives/form.md`
+- **Field** — Label + description + error wiring. `./references/primitives/field.md`
+- **Fieldset** — Grouped form controls with legend. `./references/primitives/fieldset.md`
+- **Label** — Accessible label for controls. `./references/primitives/label.md`
+
+## Toggle & Choice
+
+- **Checkbox** — Single boolean toggle. `./references/primitives/checkbox.md`
+- **CheckboxGroup** — Multiple-selection set. `./references/primitives/checkbox-group.md`
+- **RadioGroup** — Mutually exclusive single choice. `./references/primitives/radio-group.md`
+- **Switch** — Binary on/off preference toggle. `./references/primitives/switch.md`
+- **Toggle** — Pressable two-state command button. `./references/primitives/toggle.md`
+- **ToggleGroup** — Grouped pressed-state controls. `./references/primitives/toggle-group.md`
+
+## Layout & Navigation
+
+- **Tabs** — Mutually exclusive tabbed panels. `./references/primitives/tabs.md`
+- **Accordion** — Collapsible content sections. `./references/primitives/accordion.md`
+- **Collapsible** — Single expand/collapse region. `./references/primitives/collapsible.md`
+- **Sidebar** — Persistent app shell navigation. `./references/primitives/sidebar.md`
+- **Breadcrumb** — Hierarchical navigation trail. `./references/primitives/breadcrumb.md`
+- **Pagination** — Paged navigation controls. `./references/primitives/pagination.md`
+- **Toolbar** — Grouped command/action strip. `./references/primitives/toolbar.md`
+- **ScrollArea** — Styled scroll container. `./references/primitives/scroll-area.md`
+
+## Content & Display
+
+- **Card** — Content container with sections. `./references/primitives/card.md`
+- **Frame** — Bordered content surface. `./references/primitives/frame.md`
+- **Table** — Tabular data presentation. `./references/primitives/table.md`
+- **Avatar** — User/entity profile image. `./references/primitives/avatar.md`
+- **Badge** — Status indicator / label. `./references/primitives/badge.md`
+- **Kbd** — Keyboard shortcut hints. `./references/primitives/kbd.md`
+- **Separator** — Visual/semantic divider. `./references/primitives/separator.md`
+- **Group** — Connected control cluster. `./references/primitives/group.md`
+- **Empty** — Empty-state placeholder. `./references/primitives/empty.md`
+
+## Feedback & Status
+
+- **Alert** — Inline persistent status message. `./references/primitives/alert.md`
+- **Toast** — Transient notification (toastManager). `./references/primitives/toast.md`
+- **Progress** — Task completion / async progress bar. `./references/primitives/progress.md`
+- **Meter** — Bounded scalar measurement. `./references/primitives/meter.md`
+- **Spinner** — Indeterminate loading indicator. `./references/primitives/spinner.md`
+- **Skeleton** — Loading placeholder. `./references/primitives/skeleton.md`
+
+## Actions
+
+- **Button** — Primary/secondary action trigger. `./references/primitives/button.md`

.agents/skills/coss/references/portal-props.md

@@ -0,0 +1,21 @@
+# Portal forwarding (`portalProps`)
+
+Several composed coss primitives wrap Base UI **`Portal`** inside `*Popup` (or dialog-style) components, and toast exposes the same for **`ToastProvider`** / **`AnchoredToastProvider`**. Those surfaces accept an optional **`portalProps`** object, which is spread onto the internal `Portal`.
+
+Use it when you need portal-level behavior from Base UI, for example:
+
+- **`keepMounted`** — where the component’s `Portal` type supports it (see Base UI typings/docs for that component).
+- **`container`** — render portaled content into a specific DOM node (stacking contexts, micro-frontends, shadow DOM setups).
+- Other props accepted by that component’s **`Portal.Props`** (including `className` / `ref` when applicable).
+
+## Surfaces that expose `portalProps`
+
+- **Modals / overlays:** `DialogPopup`, `AlertDialogPopup`, `SheetPopup`, `DrawerPopup`, `CommandDialogPopup`
+- **Floating layers:** `MenuPopup`, `PopoverPopup`, `TooltipPopup`, `PreviewCardPopup`, `AutocompletePopup`, `ComboboxPopup`, `SelectPopup`
+- **Toast (providers, not a `*Popup` name):** `ToastProvider`, `AnchoredToastProvider` — `portalProps` is forwarded to the internal `Toast.Portal` for the stacked and anchored viewports, respectively
+
+Only these surfaces accept `portalProps`. Any other registry component that portals content but is not listed here keeps the portal internal and is out of scope for this prop—compose Base UI parts yourself if you need direct portal control.
+
+## Positioner vs portal
+
+`portalProps` only affects the **portal** node. To tweak **placement** or **positioner** styling, use the existing `side`, `align`, `sideOffset`, etc., or compose Base UI **`Positioner`** / pass through future **`positionerProps`** if the wrapper adds them.