From a5955411e68a1e1a4598be5e9782cdc3e5611734 Mon Sep 17 00:00:00 2001 From: pasqualevitiello Date: Sun, 22 Mar 2026 09:32:09 +0100 Subject: [PATCH 01/13] wip --- .../content/docs/(root)/radix-migration.mdx | 46 +++-- apps/ui/content/docs/components/dialog.mdx | 5 + apps/ui/content/docs/components/drawer.mdx | 5 + .../registry/default/particles/p-select-1.tsx | 1 - .../default/particles/p-select-11.tsx | 3 +- .../registry/default/particles/p-select-2.tsx | 3 +- .../registry/default/particles/p-select-3.tsx | 3 +- .../registry/default/particles/p-select-4.tsx | 3 +- .../registry/default/particles/p-select-5.tsx | 3 +- .../registry/default/particles/p-select-6.tsx | 9 +- .../registry/default/particles/p-select-8.tsx | 1 - apps/ui/skills/coss/SKILL.md | 110 +++++++++++ apps/ui/skills/coss/cli.md | 108 +++++++++++ .../ui/skills/coss/primitives/dialog/SKILL.md | 92 +++++++++ apps/ui/skills/coss/primitives/form/SKILL.md | 79 ++++++++ .../coss/primitives/input-group/SKILL.md | 65 +++++++ apps/ui/skills/coss/primitives/menu/SKILL.md | 96 ++++++++++ .../ui/skills/coss/primitives/select/SKILL.md | 90 +++++++++ apps/ui/skills/coss/primitives/toast/SKILL.md | 88 +++++++++ apps/ui/skills/coss/rules/base-vs-radix.md | 181 ++++++++++++++++++ apps/ui/skills/coss/rules/composition.md | 43 +++++ apps/ui/skills/coss/rules/forms.md | 45 +++++ apps/ui/skills/coss/rules/styling.md | 70 +++++++ 23 files changed, 1115 insertions(+), 34 deletions(-) create mode 100644 apps/ui/skills/coss/SKILL.md create mode 100644 apps/ui/skills/coss/cli.md create mode 100644 apps/ui/skills/coss/primitives/dialog/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/form/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/input-group/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/menu/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/select/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/toast/SKILL.md create mode 100644 apps/ui/skills/coss/rules/base-vs-radix.md create mode 100644 apps/ui/skills/coss/rules/composition.md create mode 100644 apps/ui/skills/coss/rules/forms.md create mode 100644 apps/ui/skills/coss/rules/styling.md diff --git a/apps/ui/content/docs/(root)/radix-migration.mdx b/apps/ui/content/docs/(root)/radix-migration.mdx index df1f55d5c..f1979812b 100644 --- a/apps/ui/content/docs/(root)/radix-migration.mdx +++ b/apps/ui/content/docs/(root)/radix-migration.mdx @@ -1,7 +1,7 @@ --- title: Migrating from Radix slug: radix-migration -description: A comprehensive guide for migrating from Radix-based libraries to coss ui components. +description: A practical guide for migrating from Radix-based libraries to coss ui components. --- This guide is for developers who already have applications built on Radix-based libraries — frameworks that wrap Radix primitives — and **want to adopt coss ui**. @@ -22,7 +22,7 @@ This guide is for developers who already have applications built on Radix-based ### The asChild to render Pattern -The most common change across all components is replacing Radix UI's `asChild` prop with Base UI's `render` prop: +One of the most common migration changes is replacing Radix UI's `asChild` prop with Base UI's `render` prop (especially on trigger/close/composed parts): ```tsx title="Radix" @@ -33,6 +33,8 @@ The most common change across all components is replacing Radix UI's `asChild` p ``` +Not every component uses this pattern. Apply it where the coss component supports `render`. + ```tsx title="coss ui" // [!code word:render] @@ -608,15 +610,15 @@ Base UI introduces separate parts — `ProgressLabel`, `ProgressValue`, `Progres **Prop Mapping:** -| Component | Radix UI Prop | Base UI Prop | -| ------------- | ---------------------- | --------------- | -| `Select` | `items` | `items` | -| `SelectValue` | `placeholder` | _removed_ | -| `SelectPopup` | `alignItemWithTrigger` | _no equivalent_ | +| Component | Radix UI Prop | coss ui / Base UI Prop | +| ------------- | ---------------------------------------------- | ------------------------------------------- | +| `Select` | options inferred from `SelectItem` children | `items` prop (recommended for SSR/hydration) | +| `SelectValue` | `placeholder` | `placeholder` (supported on `SelectValue`) | +| `SelectPopup` | _no equivalent_ | `alignItemWithTrigger` | **Quick Checklist:** - Set `items` prop on `Select` -- Remove `placeholder` from `Select` +- Keep placeholder on `SelectValue` when needed - Prefer `SelectPopup` instead of `SelectContent` - If you used `asChild` on parts, switch to the `render` prop @@ -634,7 +636,9 @@ So, for example, if you were using the `default` size in shadcn/ui and you want **Additional Notes:** -Base UI introduces the `alignItemWithTrigger` prop to control whether the `SelectContent` overlaps the `SelectTrigger` so the selected item's text is aligned with the trigger's value text. +`alignItemWithTrigger` controls whether the popup aligns the selected item with the trigger text. In coss ui this prop is available on `SelectPopup` (legacy alias: `SelectContent`). + +`SelectValue` supports a `placeholder` prop. If you need in-popup clearing, prefer adding a `null` option item instead of relying on placeholder alone. **Comparison Example:** @@ -658,13 +662,15 @@ Base UI introduces the `alignItemWithTrigger` prop to control whether the `Selec ```tsx title="coss ui" // [!code word:alignItemWithTrigger={false}] // [!code word:items:2] +const items = [ + { label: "Select a framework", value: null }, + { label: "Next.js", value: "next" }, + { label: "Vite", value: "vite" }, + { label: "Astro", value: "astro" }, +] + - + {items.map(({ label, value }) => ( diff --git a/apps/ui/registry/default/particles/p-select-3.tsx b/apps/ui/registry/default/particles/p-select-3.tsx index 4743569e6..4af5a740d 100644 --- a/apps/ui/registry/default/particles/p-select-3.tsx +++ b/apps/ui/registry/default/particles/p-select-3.tsx @@ -7,7 +7,6 @@ import { } from "@/registry/default/ui/select"; const items = [ - { label: "Select framework", value: null }, { label: "Next.js", value: "next" }, { label: "Vite", value: "vite" }, { label: "Astro", value: "astro" }, @@ -17,7 +16,7 @@ export default function Particle() { return ( - + {items.map(({ label, value }) => ( diff --git a/apps/ui/registry/default/particles/p-select-5.tsx b/apps/ui/registry/default/particles/p-select-5.tsx index 3f2d66c03..d42c1623a 100644 --- a/apps/ui/registry/default/particles/p-select-5.tsx +++ b/apps/ui/registry/default/particles/p-select-5.tsx @@ -7,7 +7,6 @@ import { } from "@/registry/default/ui/select"; const items = [ - { label: "Select framework", value: null }, { label: "Next.js", value: "next" }, { label: "Vite", value: "vite" }, { label: "Astro", value: "astro" }, @@ -17,7 +16,7 @@ export default function Particle() { return ( + + Used for account updates + Please enter a valid email. + + +``` + +## Patterns from coss/Base UI forms + +- **Submission mode**: use `onSubmit` for native `FormData` handling; use `onFormSubmit` when you want parsed form values object from Base UI Form. +- **Field naming**: set `name` on each field/control flow so values are included in submission. +- **Accessible names**: prefer visible labels (`FieldLabel`, `SelectLabel`, etc.); use `aria-label` only when no visible label exists. +- **Grouped controls**: for radio/checkbox groups or multi-control sections, use fieldset-style grouping (`Fieldset` + `Field.Item`) instead of ad-hoc wrappers. +- **Validation rendering**: pair constraints/custom validation with `FieldError`; keep error output semantically tied to the same field. +- **External library integration**: when using RHF/TanStack, forward refs/input refs to the underlying control and map invalid/touched/dirty state into `Field`. + +## Common pitfalls + +- Using `Form` without field-level structure (`Field`, label, error). +- Missing control `name` (field not present in form submission payload). +- Missing input `type` and button `type`. +- Showing validation messages without matching invalid semantics. +- Using grouped checkboxes/radios without proper group legend/structure. +- Not forwarding refs in RHF/TanStack integration, which breaks focus-on-error behavior. + +## Useful particle references + +- `p-form-1` (basic integration) +- `p-form-2` (zod usage) + +## Further reading + +- Base UI Forms handbook: `https://base-ui.com/react/handbook/forms.md` + diff --git a/apps/ui/skills/coss/primitives/input-group/SKILL.md b/apps/ui/skills/coss/primitives/input-group/SKILL.md new file mode 100644 index 000000000..886d7247f --- /dev/null +++ b/apps/ui/skills/coss/primitives/input-group/SKILL.md @@ -0,0 +1,65 @@ +--- +name: coss-input-group +description: Use when composing input-like controls with addons (icons, text, buttons, badges, shortcuts) using coss InputGroup. +user-invocable: false +--- + +# coss Input Group + +## When to use + +- Inputs/textareas that need inline or block addons. +- Input composition with icons, buttons, labels, badges, and shortcuts. + +## Install + +```bash +npx shadcn@latest add @coss/input-group +``` + +Manual deps: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { + InputGroup, + InputGroupAddon, + InputGroupInput, + InputGroupText, +} from "@/components/ui/input-group" +``` + +## Minimal pattern + +```tsx + + + + + + +``` + +## Critical invariant + +`InputGroupAddon` must be after `InputGroupInput`/`InputGroupTextarea` in DOM order for proper focus behavior. + +## Common pitfalls + +- Using `Input`/`Textarea` directly instead of `InputGroupInput`/`InputGroupTextarea`. +- Wrong addon DOM order. +- Missing explicit input types. + +## Useful particle references + +- icon addon + search baseline: `p-input-group-1`, `p-input-group-2`, `p-input-group-13`, `p-input-group-14`, `p-input-group-20` +- prefix/suffix text addons (url/domain/currency): `p-input-group-3`, `p-input-group-4`, `p-input-group-5`, `p-input-group-6` +- interactive addons (buttons/badge/kbd/menu/clear/voice): `p-input-group-7`, `p-input-group-8`, `p-input-group-9`, `p-input-group-10`, `p-input-group-11`, `p-input-group-12`, `p-input-group-18`, `p-input-group-21`, `p-input-group-22`, `p-input-group-23` +- textarea/editor-style layouts with block-end/start addons: `p-input-group-17`, `p-input-group-19`, `p-input-group-27`, `p-input-group-28`, `p-input-group-29` +- stateful/validation patterns (disabled/loading/password strength): `p-input-group-15`, `p-input-group-16`, `p-input-group-24`, `p-input-group-26` + diff --git a/apps/ui/skills/coss/primitives/menu/SKILL.md b/apps/ui/skills/coss/primitives/menu/SKILL.md new file mode 100644 index 000000000..cb2d530ee --- /dev/null +++ b/apps/ui/skills/coss/primitives/menu/SKILL.md @@ -0,0 +1,96 @@ +--- +name: coss-menu +description: Use when building dropdown action menus with coss Menu, including groups, checkbox/radio items, submenus, and alignment. +user-invocable: false +--- + +# coss Menu + +## When to use + +- Contextual action lists and dropdown commands. +- Mixed item types (regular, checkbox, radio, nested submenu). + +## Install + +```bash +npx shadcn@latest add @coss/menu +``` + +Manual deps and theme var from docs: + +```bash +npm install @base-ui/react +``` + +Also include the destructive foreground CSS variable snippet from the coss menu docs when doing manual setup. + +## Canonical imports + +```tsx +import { + Menu, + MenuCheckboxItem, + MenuGroup, + MenuGroupLabel, + MenuItem, + MenuPopup, + MenuRadioGroup, + MenuRadioItem, + MenuSeparator, + MenuShortcut, + MenuSub, + MenuSubPopup, + MenuSubTrigger, + MenuTrigger, +} from "@/components/ui/menu" +``` + +## Minimal pattern + +```tsx + + Open + + Profile + + Shuffle + + +``` + +Use popup positioning props like `align` / `sideOffset` only when a layout needs explicit tuning. + +## Patterns from coss particles + +- Use `MenuTrigger render={ + +``` + +```tsx +// coss/Base UI +}>Open +``` + +### Menu actions: `onSelect` -> `onClick` + +```tsx +// shadcn/Radix +Open +``` + +```tsx +// coss/Base UI +Open +``` + +### Select: `items`-first + placeholder on `SelectValue` + +```tsx +// shadcn/Radix + +``` + +```tsx +// coss/Base UI +const items = [ + { label: "Next.js", value: "next" }, + { label: "Vite", value: "vite" }, +]; + + +``` + +### Toggle Group: `type` -> `multiple` + +```tsx +// shadcn/Radix + + Daily + Weekly + +``` + +```tsx +// coss/Base UI + + Daily + Weekly + +``` + +### Slider: scalar single-value usage in coss + +```tsx +// shadcn/Radix + +``` + +```tsx +// coss/Base UI + +``` + +### Accordion: `type/collapsible` -> coss defaults + +```tsx +// shadcn/Radix + + ... + +``` + +```tsx +// coss/Base UI + + ... + +``` + +## Component coverage index (from migration guide) + +This rule intentionally covers every component section in the Radix migration guide. + +- `Accordion`: `type/collapsible` -> `multiple`/array-based `defaultValue`; prefer `AccordionPanel`. +- `Alert`: includes additional semantic variants (`info`, `success`, `warning`, `error`). +- `AlertDialog`: prefer `AlertDialogPopup`/`AlertDialogPanel`; action/cancel patterns map to `AlertDialogClose`. +- `Avatar`: apply `render` composition only where needed. +- `Badge`: supports `render` composition and coss size/variant differences. +- `Button`: supports `render` composition and coss size/variant differences. +- `Card`: prefer `CardPanel` (legacy `CardContent` may still exist). +- `Checkbox`: apply composition patterns per docs when replacing wrapped elements. +- `Collapsible`: prefer `CollapsiblePanel`; migrate trigger composition patterns. +- `Command`: API differs materially from cmdk-style composition; verify against coss docs. +- `Dialog`: prefer `DialogPopup`/`DialogPanel`; migrate trigger/close composition patterns. +- `Group`: prefer `Group*` names; keep required separators and documented structure. +- `Input`: account for coss size mapping differences. +- `InputGroup`: use `InputGroupAddon` + direct controls; preserve documented DOM order patterns. +- `Menu`: `onSelect` -> `onClick`; prefer `Menu*` names and popup aliases. +- `Popover`: prefer `PopoverPopup`; use title/description/close parts where relevant. +- `PreviewCard`: prefer `PreviewCard*` names over hover-card naming. +- `Progress`: when composing custom children, include required track/indicator parts. +- `RadioGroup`: prefer current `Radio` naming where documented. +- `ScrollArea`: migrate composition patterns and aliases per docs. +- `Select`: prefer `items`-first patterns; `SelectValue` supports `placeholder`; use `SelectPopup`. +- `Sheet`: prefer `SheetPopup`/`SheetPanel`; migrate trigger/close composition patterns. +- `Slider`: verify value-shape semantics and controlled/uncontrolled patterns from coss docs. +- `Switch`: migrate composition patterns where wrapped rendering is used. +- `Tabs`: prefer `TabsTab`/`TabsPanel` naming where documented. +- `Textarea`: account for coss size mapping differences. +- `Toast`: API differs from Sonner patterns; verify provider and action APIs from coss docs. +- `Toggle`: migrate composition patterns where wrapped rendering is used. +- `ToggleGroup`: Radix `type` semantics map to coss `multiple` + current item naming. +- `Tooltip`: prefer `TooltipPopup`; migrate trigger composition patterns. + +For any component above, when uncertain: check component docs + at least one particle before finalizing output. + +## Migration checklist + +1. Confirm the exact coss imports from docs. +2. Confirm child structure requirements (trigger/header/panel/footer/items/groups). +3. Confirm prop names and semantics from the coss docs page. +4. Validate with at least one coss particle example. + +## Anti-patterns + +- Copy/paste shadcn examples and only change import path. +- Using undocumented props because they exist in other ecosystems. +- Omitting required subcomponents in overlays/forms because the source snippet did. + diff --git a/apps/ui/skills/coss/rules/composition.md b/apps/ui/skills/coss/rules/composition.md new file mode 100644 index 000000000..0f1747fd4 --- /dev/null +++ b/apps/ui/skills/coss/rules/composition.md @@ -0,0 +1,43 @@ +# Composition Rules (coss) + +Use this when composing complex UI from coss primitives and particles. + +## Core Rules + +- Prefer composing existing primitives over custom wrappers with duplicated behavior. +- 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. +- Use coss/Base UI trigger APIs consistently (typically `render`-based composition). +- Use complete sub-structures where required (for example title/description regions in dialogs where relevant). + +## Patterns + +### Trigger + Popup + +```tsx + + }>Open + + + Title + + Body + + +``` + +### Grouped Controls + +```tsx + + + + + +``` + +## Anti-patterns + +- Building bespoke dropdown/dialog behavior instead of using primitives. +- Mixing APIs from other ecosystems (`asChild`-only mental model) without checking coss equivalents. +- Omitting key subcomponents that preserve accessibility and layout conventions. + diff --git a/apps/ui/skills/coss/rules/forms.md b/apps/ui/skills/coss/rules/forms.md new file mode 100644 index 000000000..91785e242 --- /dev/null +++ b/apps/ui/skills/coss/rules/forms.md @@ -0,0 +1,45 @@ +# Forms and Inputs Rules (coss) + +Use this when implementing fields, input groups, validation states, and form examples. + +## Core Rules + +- Prefer coss field composition components when available (`Field`, `FieldLabel`, `FieldError`). +- Always specify `type` on input-like controls where relevant (`type="text"`, `type="email"`, etc.). +- Always specify `type` on buttons (`button`, `submit`, or `reset`) instead of relying on browser defaults. +- Preserve accessible labelling: + - visible label association (`Label`, `htmlFor`, `id`) + - `aria-label` when there is no visible label. +- Keep validation signaling aligned between container and control (`aria-invalid`, related field semantics). + +## Input Group Rule + +- In `InputGroup`, place `InputGroupAddon` after `InputGroupInput` or `InputGroupTextarea` in DOM order to preserve focus behavior. + +## Input OTP Rule + +- Keep `maxLength` synchronized with rendered `InputOTPSlot` count. + +## Do / Don't + +```tsx +// Do + + Email + + + + + + {/* ... */} + + +// Don't + + + + {/* ... */} + + +``` + diff --git a/apps/ui/skills/coss/rules/styling.md b/apps/ui/skills/coss/rules/styling.md new file mode 100644 index 000000000..c7fee3385 --- /dev/null +++ b/apps/ui/skills/coss/rules/styling.md @@ -0,0 +1,70 @@ +# Styling Rules (coss) + +Use this guide when writing or updating coss primitives, particles, and docs examples. + +## Core Rules + +- Use semantic tokens (`text-muted-foreground`, `bg-destructive`) over raw palette classes. +- Prefer component variants/size props before custom class overrides. +- Use `flex flex-col gap-*` layouts instead of `space-x-*`/`space-y-*`. +- Use `size-*` for square sizing. +- Use `cn()` for conditional class composition. +- Avoid redundant classes that defaults already cover (for example `border-border` when border color is already inherited). +- Before adding layout classes, check whether the target part already provides that layout. +- Use Tailwind v4 syntax and conventions in coss examples and snippets. + +## coss-specific Expectations + +- Do not use numeric icon `size` props; prefer inherited sizing or `size-*` utility classes. +- For icons, default to `aria-hidden="true"` when icon is decorative/redundant; do not hide icons that carry unique semantic meaning. +- Many primitives already define inner SVG sizing. Check existing component styles before adding icon `size-*` classes. +- Many primitives already define inner SVG opacity (commonly around `opacity-80`). Check existing component styles before adding manual icon opacity classes. +- Prefer data-slot-aware selectors and `in-*` patterns over `group` where available. + +## Global Styling Setup (when relevant) + +Apply this section only when the task touches global theme/layout setup (not normal component usage edits). + +- Preserve coss token architecture. Do not replace coss semantic variables with ad-hoc color classes/tokens. +- When providing manual theme setup, include complete token blocks and variable mappings; avoid partial copy/paste snippets that break variable chains. +- Keep font variables aligned with coss expectations (`--font-sans`, `--font-heading`, `--font-mono`) when changing typography setup. +- For Base UI portal layering, keep an isolated application root wrapper (for example `isolate` on the root container). +- For iOS Safari compatibility, ensure `body` has `position: relative` when configuring global layout for portaled backdrops. + +## Do / Don't + +```tsx +// Do + + + +// Don't + +``` + +## Check Before Finalizing + +1. Any raw color classes that should be semantic? +2. Any duplicate layout/style logic already handled by a primitive? +3. Any icon sizing/opacities violating coss conventions? +4. Any decorative interactive icons missing `aria-hidden="true"`? +5. Any use of `group` that should be replaced with `in-*` + `data-slot`? + From d5e8e4e791eb2f4b7cfb5a4996f9bf0469ef7c3c Mon Sep 17 00:00:00 2001 From: pasqualevitiello Date: Sun, 22 Mar 2026 20:09:19 +0100 Subject: [PATCH 02/13] various improvements --- .../skills/coss/primitives/accordion/SKILL.md | 70 ++++++++++++++ .../coss/primitives/alert-dialog/SKILL.md | 85 ++++++++++++++++ apps/ui/skills/coss/primitives/alert/SKILL.md | 64 +++++++++++++ .../coss/primitives/autocomplete/SKILL.md | 96 +++++++++++++++++++ .../ui/skills/coss/primitives/avatar/SKILL.md | 59 ++++++++++++ apps/ui/skills/coss/primitives/badge/SKILL.md | 61 ++++++++++++ .../coss/primitives/breadcrumb/SKILL.md | 76 +++++++++++++++ .../ui/skills/coss/primitives/button/SKILL.md | 64 +++++++++++++ .../skills/coss/primitives/calendar/SKILL.md | 58 +++++++++++ apps/ui/skills/coss/primitives/card/SKILL.md | 66 +++++++++++++ .../coss/primitives/checkbox-group/SKILL.md | 73 ++++++++++++++ .../skills/coss/primitives/checkbox/SKILL.md | 59 ++++++++++++ .../coss/primitives/collapsible/SKILL.md | 61 ++++++++++++ .../skills/coss/primitives/combobox/SKILL.md | 88 +++++++++++++++++ .../skills/coss/primitives/command/SKILL.md | 94 ++++++++++++++++++ .../ui/skills/coss/primitives/drawer/SKILL.md | 96 +++++++++++++++++++ apps/ui/skills/coss/primitives/empty/SKILL.md | 70 ++++++++++++++ apps/ui/skills/coss/primitives/field/SKILL.md | 80 ++++++++++++++++ .../skills/coss/primitives/fieldset/SKILL.md | 55 +++++++++++ apps/ui/skills/coss/primitives/form/SKILL.md | 5 + apps/ui/skills/coss/primitives/frame/SKILL.md | 65 +++++++++++++ apps/ui/skills/coss/primitives/group/SKILL.md | 66 +++++++++++++ .../coss/primitives/input-group/SKILL.md | 6 ++ .../skills/coss/primitives/input-otp/SKILL.md | 77 +++++++++++++++ apps/ui/skills/coss/primitives/input/SKILL.md | 65 +++++++++++++ apps/ui/skills/coss/primitives/kbd/SKILL.md | 51 ++++++++++ apps/ui/skills/coss/primitives/label/SKILL.md | 52 ++++++++++ apps/ui/skills/coss/primitives/meter/SKILL.md | 57 +++++++++++ .../coss/primitives/number-field/SKILL.md | 79 +++++++++++++++ .../coss/primitives/pagination/SKILL.md | 75 +++++++++++++++ .../skills/coss/primitives/popover/SKILL.md | 74 ++++++++++++++ .../coss/primitives/preview-card/SKILL.md | 60 ++++++++++++ .../skills/coss/primitives/progress/SKILL.md | 57 +++++++++++ .../coss/primitives/radio-group/SKILL.md | 70 ++++++++++++++ .../coss/primitives/scroll-area/SKILL.md | 67 +++++++++++++ .../ui/skills/coss/primitives/select/SKILL.md | 4 + .../skills/coss/primitives/separator/SKILL.md | 57 +++++++++++ apps/ui/skills/coss/primitives/sheet/SKILL.md | 79 +++++++++++++++ .../skills/coss/primitives/sidebar/SKILL.md | 60 ++++++++++++ .../skills/coss/primitives/skeleton/SKILL.md | 51 ++++++++++ .../ui/skills/coss/primitives/slider/SKILL.md | 56 +++++++++++ .../skills/coss/primitives/spinner/SKILL.md | 57 +++++++++++ .../ui/skills/coss/primitives/switch/SKILL.md | 61 ++++++++++++ apps/ui/skills/coss/primitives/table/SKILL.md | 83 ++++++++++++++++ apps/ui/skills/coss/primitives/tabs/SKILL.md | 64 +++++++++++++ .../skills/coss/primitives/textarea/SKILL.md | 63 ++++++++++++ apps/ui/skills/coss/primitives/toast/SKILL.md | 26 +++++ .../coss/primitives/toggle-group/SKILL.md | 66 +++++++++++++ .../ui/skills/coss/primitives/toggle/SKILL.md | 59 ++++++++++++ .../skills/coss/primitives/toolbar/SKILL.md | 79 +++++++++++++++ .../skills/coss/primitives/tooltip/SKILL.md | 65 +++++++++++++ apps/ui/skills/coss/rules/forms.md | 10 +- 52 files changed, 3240 insertions(+), 1 deletion(-) create mode 100644 apps/ui/skills/coss/primitives/accordion/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/alert-dialog/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/alert/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/autocomplete/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/avatar/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/badge/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/breadcrumb/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/button/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/calendar/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/card/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/checkbox-group/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/checkbox/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/collapsible/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/combobox/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/command/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/drawer/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/empty/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/field/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/fieldset/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/frame/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/group/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/input-otp/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/input/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/kbd/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/label/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/meter/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/number-field/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/pagination/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/popover/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/preview-card/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/progress/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/radio-group/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/scroll-area/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/separator/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/sheet/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/sidebar/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/skeleton/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/slider/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/spinner/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/switch/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/table/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/tabs/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/textarea/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/toggle-group/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/toggle/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/toolbar/SKILL.md create mode 100644 apps/ui/skills/coss/primitives/tooltip/SKILL.md diff --git a/apps/ui/skills/coss/primitives/accordion/SKILL.md b/apps/ui/skills/coss/primitives/accordion/SKILL.md new file mode 100644 index 000000000..fd9e86d4c --- /dev/null +++ b/apps/ui/skills/coss/primitives/accordion/SKILL.md @@ -0,0 +1,70 @@ +--- +name: coss-accordion +description: Use when implementing collapsible content sections with coss Accordion (single, multiple, and controlled modes). +user-invocable: false +--- + +# coss Accordion + +## When to use + +- Expandable multi-section content regions. +- FAQs and settings pages with progressive disclosure. + +## Install + +```bash +npx shadcn@latest add @coss/accordion +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { + Accordion, + AccordionItem, + AccordionPanel, + AccordionTrigger, +} from "@/components/ui/accordion" +``` + +## Minimal pattern + +```tsx + + + What is Base UI? + + Base UI is a library of high-quality unstyled React components. + + + +``` + +## Patterns from coss particles + +- **Item invariants**: each `AccordionItem` needs a stable `value`; trigger and panel must be children of the same item. +- **Single vs multiple**: use default single behavior for one-open-at-a-time, add `multiple` when several panels should stay open. +- **Controlled mode**: use `value: string[]` with `onValueChange` for external orchestration (for example, "Open First Two" actions). +- **Default expansion**: use `defaultValue={["..."]}` for pre-opened sections. + +## Common pitfalls + +- Placing `AccordionTrigger`/`AccordionPanel` outside `AccordionItem`. +- Omitting `value` on `AccordionItem`, which breaks item identity and controlled behavior. +- Applying Radix mental models like `type="single" | "multiple"` instead of coss `multiple` + array values. +- Treating controlled `value` as scalar instead of `string[]`. + +## Useful particle references + +- baseline mapped-items accordion: `p-accordion-1` +- single-open static sections: `p-accordion-2` +- multiple-open behavior: `p-accordion-3` +- controlled value + external actions: `p-accordion-4` + diff --git a/apps/ui/skills/coss/primitives/alert-dialog/SKILL.md b/apps/ui/skills/coss/primitives/alert-dialog/SKILL.md new file mode 100644 index 000000000..8f4ddac09 --- /dev/null +++ b/apps/ui/skills/coss/primitives/alert-dialog/SKILL.md @@ -0,0 +1,85 @@ +--- +name: coss-alert-dialog +description: Use when implementing critical confirmation flows with coss AlertDialog, especially destructive actions requiring explicit user intent. +user-invocable: false +--- + +# coss Alert Dialog + +## When to use + +- Critical confirmation flows before destructive actions. +- Blocking decisions that require explicit acknowledgement. + +## Install + +```bash +npx shadcn@latest add @coss/alert-dialog +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { + AlertDialog, + AlertDialogClose, + AlertDialogDescription, + AlertDialogPanel, + AlertDialogFooter, + AlertDialogHeader, + AlertDialogPopup, + AlertDialogTitle, + AlertDialogTrigger, +} from "@/components/ui/alert-dialog" +``` + +## Minimal pattern + +```tsx + + }> + Delete Account + + + + Are you absolutely sure? + + This action cannot be undone. + + + + }>Cancel + }> + Delete Account + + + + +``` + +## Patterns from coss particles + +- **Section structure invariant**: keep `AlertDialogHeader`, optional `AlertDialogPanel`, and `AlertDialogFooter` as direct sections of `AlertDialogPopup`. +- **Action composition**: use `AlertDialogClose render={ +``` + +`Button` defaults to `type="button"` when rendered as the native button part. In form flows, set `type` explicitly (`button` / `submit` / `reset`) to match intent, especially when using `render` composition. + +## Patterns from coss particles + +- **Default**: use the pattern shown in `p-button-1` when this variation is required. +- **Outline**: use the pattern shown in `p-button-2` when this variation is required. +- **Secondary**: use the pattern shown in `p-button-3` when this variation is required. +- **Destructive**: use the pattern shown in `p-button-4` when this variation is required. +- **Destructive Outline**: use the pattern shown in `p-button-5` when this variation is required. + +## Common pitfalls + +- Omitting explicit `type` inside forms/dialogs and triggering unintended submit behavior. +- Using icon-only buttons without `aria-label` on the button. +- Rebuilding button state styling with ad-hoc classes instead of variants/sizes. +- Using `SelectButton` as if it were a general-purpose `Button`; `SelectButton` is a select-flavored trigger helper and should be treated as a `select`/`combobox` pattern. + +## Useful particle references + +- default: `p-button-1` +- outline: `p-button-2` +- secondary: `p-button-3` +- destructive: `p-button-4` +- destructive outline: `p-button-5` +- ghost: `p-button-6` +- link: `p-button-7` +- extra-small size: `p-button-8` diff --git a/apps/ui/skills/coss/primitives/calendar/SKILL.md b/apps/ui/skills/coss/primitives/calendar/SKILL.md new file mode 100644 index 000000000..515116adb --- /dev/null +++ b/apps/ui/skills/coss/primitives/calendar/SKILL.md @@ -0,0 +1,58 @@ +--- +name: coss-calendar +description: Use when implementing calendar patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Calendar + +## When to use + +- Date selection interfaces and calendar-based scheduling UIs. +- Single-date, range, and constrained date picking patterns. + +## Install + +```bash +npx shadcn@latest add @coss/calendar +``` + +Manual deps from docs: + +```bash +npm install react-day-picker +``` + +## Canonical imports + +```tsx +import { Calendar } from "@/components/ui/calendar" +``` + +## Minimal pattern + +```tsx + +``` + +## Patterns from coss particles + +- **Single Date Selection**: follow `p-calendar-2` for this documented variation. +- **Date Range Selection**: follow `p-calendar-3` for this documented variation. +- **Dropdown Navigation**: follow `p-calendar-4` for this documented variation. +- **Select Dropdown for Month/Year**: follow `p-calendar-5` for this documented variation. +- **Combobox Dropdown for Month/Year**: follow `p-calendar-6` for this documented variation. + +## Common pitfalls + +- Using calendar for free-text date input flows better handled by date fields. +- Missing locale/disabled-date constraints for business rules. +- Treating calendar as date-time picker without explicit time UI. + +## Useful particle references + +- single date selection: `p-calendar-2` +- date range selection: `p-calendar-3` +- dropdown navigation: `p-calendar-4` +- select dropdown for month/year: `p-calendar-5` +- combobox dropdown for month/year: `p-calendar-6` diff --git a/apps/ui/skills/coss/primitives/card/SKILL.md b/apps/ui/skills/coss/primitives/card/SKILL.md new file mode 100644 index 000000000..42850bfa2 --- /dev/null +++ b/apps/ui/skills/coss/primitives/card/SKILL.md @@ -0,0 +1,66 @@ +--- +name: coss-card +description: Use when implementing card patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Card + +## When to use + +- Structured surface sections for grouped content. +- Settings, dashboard, and preview layouts with header/panel/footer semantics. + +## Install + +```bash +npx shadcn@latest add @coss/card +``` + +Manual deps from docs: + +```bash +# No extra runtime dependency required for this primitive. +``` + +## Canonical imports + +```tsx +import { + Card, + CardDescription, + CardFooter, + CardHeader, + CardPanel, + CardTitle, +} from "@/components/ui/card" +``` + +## Minimal pattern + +```tsx + + + Title + Description + + Content + Footer + +``` + +## Patterns from coss particles + +- **Baseline usage**: start from `p-card-1` and add only the props/parts needed for the target flow. +- **Variant sizing**: prefer primitive variants/sizes before class overrides. +- **Accessibility**: keep explicit labels and semantic roles when used in interactive contexts. + +## Common pitfalls + +- Skipping `CardHeader`/`CardPanel`/`CardFooter` structure in composed cards. +- Mixing unrelated layout wrappers that break spacing between card sections. +- Using cards as generic wrappers when `Frame` or plain layout would be clearer. + +## Useful particle references + +- core patterns: `p-card-1`, `p-card-2`, `p-card-3`, `p-card-4`, `p-card-5`, `p-card-6`, `p-card-7`, `p-card-8` diff --git a/apps/ui/skills/coss/primitives/checkbox-group/SKILL.md b/apps/ui/skills/coss/primitives/checkbox-group/SKILL.md new file mode 100644 index 000000000..916a4fc25 --- /dev/null +++ b/apps/ui/skills/coss/primitives/checkbox-group/SKILL.md @@ -0,0 +1,73 @@ +--- +name: coss-checkbox-group +description: Use when implementing checkbox group patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Checkbox Group + +## When to use + +- Multi-select option groups with shared label context. +- Collecting multiple values under one field name. + +## Install + +```bash +npx shadcn@latest add @coss/checkbox-group +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { Checkbox } from "@/components/ui/checkbox" +import { CheckboxGroup } from "@/components/ui/checkbox-group" +``` + +## Minimal pattern + +```tsx + + + + + +``` + +For form-bound option groups, prefer `Field` + `Fieldset` composition so legend, labels, and errors are grouped correctly. + +## Patterns from coss particles + +- **Disabled Item**: use `p-checkbox-group-2` as the baseline implementation for this variation. +- **Parent Checkbox**: use `p-checkbox-group-3` as the baseline implementation for this variation. +- **Nested Parent Checkbox**: use `p-checkbox-group-4` as the baseline implementation for this variation. +- **Form Integration**: use `p-checkbox-group-5` as the baseline implementation for this variation. + +## Common pitfalls + +- Using checkbox group when only one option should be selected. +- Missing group label/legend context for assistive technology. +- Incorrectly handling submitted values as scalar instead of array/list. + +## Useful particle references + +- with disabled item: `p-checkbox-group-2` +- parent checkbox: `p-checkbox-group-3` +- nested parent checkbox: `p-checkbox-group-4` +- form integration: `p-checkbox-group-5` +- form composition references: `p-form-1`, `p-form-2`, `p-input-group-24` diff --git a/apps/ui/skills/coss/primitives/checkbox/SKILL.md b/apps/ui/skills/coss/primitives/checkbox/SKILL.md new file mode 100644 index 000000000..220feb588 --- /dev/null +++ b/apps/ui/skills/coss/primitives/checkbox/SKILL.md @@ -0,0 +1,59 @@ +--- +name: coss-checkbox +description: Use when implementing checkbox patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Checkbox + +## When to use + +- Single boolean consent/selection controls. +- Standalone yes/no options with explicit labeling. + +## Install + +```bash +npx shadcn@latest add @coss/checkbox +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { Checkbox } from "@/components/ui/checkbox" +``` + +## Minimal pattern + +```tsx + +``` + +## Patterns from coss particles + +- **Disabled**: use `p-checkbox-2` as the baseline implementation for this variation. +- **Description**: use `p-checkbox-3` as the baseline implementation for this variation. +- **Card Style**: use `p-checkbox-4` as the baseline implementation for this variation. +- **Form Integration**: use `p-checkbox-5` as the baseline implementation for this variation. + +## Common pitfalls + +- Using checkbox for exclusive single-choice options that should be radios. +- Missing visible label association (`Label` or `FieldLabel`) for each checkbox. +- Treating `onCheckedChange` values as plain boolean without handling indeterminate where relevant. + +## Useful particle references + +- disabled: `p-checkbox-2` +- with description: `p-checkbox-3` +- card style: `p-checkbox-4` +- form integration: `p-checkbox-5` diff --git a/apps/ui/skills/coss/primitives/collapsible/SKILL.md b/apps/ui/skills/coss/primitives/collapsible/SKILL.md new file mode 100644 index 000000000..7f92123c7 --- /dev/null +++ b/apps/ui/skills/coss/primitives/collapsible/SKILL.md @@ -0,0 +1,61 @@ +--- +name: coss-collapsible +description: Use when implementing collapsible patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Collapsible + +## When to use + +- Progressive disclosure of optional content. +- Expandable help/settings sections without leaving the page. + +## Install + +```bash +npx shadcn@latest add @coss/collapsible +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { + Collapsible, + CollapsiblePanel, + CollapsibleTrigger, +} from "@/components/ui/collapsible" +``` + +## Minimal pattern + +```tsx + + Can I access the file in the cloud? + + Yes, you can access the file in the cloud. + + +``` + +## Patterns from coss particles + +- **Baseline usage**: start from `p-collapsible-1` and add only the props/parts needed for the target flow. +- **Variant sizing**: prefer primitive variants/sizes before class overrides. +- **Accessibility**: keep explicit labels and semantic roles when used in interactive contexts. + +## Common pitfalls + +- Placing trigger/panel outside the same collapsible root. +- Assuming panel content is always visible/mounted for dependent logic. +- Using modal-like interactions where collapsible disclosure is more appropriate. + +## Useful particle references + +- core patterns: `p-collapsible-1` diff --git a/apps/ui/skills/coss/primitives/combobox/SKILL.md b/apps/ui/skills/coss/primitives/combobox/SKILL.md new file mode 100644 index 000000000..a281187d2 --- /dev/null +++ b/apps/ui/skills/coss/primitives/combobox/SKILL.md @@ -0,0 +1,88 @@ +--- +name: coss-combobox +description: Use when implementing combobox patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Combobox + +## When to use + +- Searchable selection combining text input and list selection. +- Rich option rows with filtering and custom trigger behavior. + +## Install + +```bash +npx shadcn@latest add @coss/combobox +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { + Combobox, + ComboboxEmpty, + ComboboxInput, + ComboboxItem, + ComboboxList, + ComboboxPopup, +} from "@/components/ui/combobox" +``` + +## Minimal pattern + +```tsx +const items = [ + { value: "apple", label: "Apple" }, + { value: "banana", label: "Banana" }, + { value: "orange", label: "Orange" }, + { value: "grape", label: "Grape" }, +] + + + + + No results found. + + {(item) => {item.label}} + + + +``` + +For form-bound comboboxes, prefer `Field` composition (`Field` + `FieldLabel` + `FieldError`) instead of standalone controls. + +## Patterns from coss particles + +- **Field composition**: in forms, wrap combobox with `Field` semantics to align label/error wiring (see `p-form-1` / `p-form-2`). +- **Disabled**: follow `p-combobox-2` for this documented variation. +- **Small Size**: follow `p-combobox-3` for this documented variation. +- **Large Size**: follow `p-combobox-4` for this documented variation. +- **Label**: follow `p-combobox-5` for this documented variation. +- **Auto Highlight**: follow `p-combobox-6` for this documented variation. +- **Clear Button**: follow `p-combobox-7` for this documented variation. + +## Common pitfalls + +- Mixing select and combobox APIs without validating item/value wiring. +- Using object values without stable string serialization where needed. +- Missing empty/loading states for remote or filtered datasets. + +## Useful particle references + +- disabled: `p-combobox-2` +- small size: `p-combobox-3` +- large size: `p-combobox-4` +- with label: `p-combobox-5` +- auto highlight: `p-combobox-6` +- with clear button: `p-combobox-7` +- with groups: `p-combobox-8` +- with multiple selection: `p-combobox-9` +- related search/selection references: `p-autocomplete-1`, `p-select-1`, `p-input-group-1` diff --git a/apps/ui/skills/coss/primitives/command/SKILL.md b/apps/ui/skills/coss/primitives/command/SKILL.md new file mode 100644 index 000000000..bca6e771a --- /dev/null +++ b/apps/ui/skills/coss/primitives/command/SKILL.md @@ -0,0 +1,94 @@ +--- +name: coss-command +description: Use when implementing command patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Command + +## When to use + +- Command palette and keyboard-navigable action menus. +- Fast action discovery for power-user and app shortcut workflows. + +## Install + +```bash +npx shadcn@latest add @coss/command +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { + Command, + CommandCollection, + CommandDialog, + CommandDialogPopup, + CommandDialogTrigger, + CommandEmpty, + CommandFooter, + CommandGroup, + CommandGroupLabel, + CommandInput, + CommandItem, + CommandList, + CommandPanel, + CommandSeparator, + CommandShortcut, +} from "@/components/ui/command" +import { Button } from "@/components/ui/button" +``` + +## Minimal pattern + +```tsx +const items = [ + { value: "linear", label: "Linear" }, + { value: "figma", label: "Figma" }, + { value: "slack", label: "Slack" }, +] + + + }> + Open Command Palette + + + + + + No results found. + + {(item) => ( + + {item.label} + + )} + + + + +``` + +## Patterns from coss particles + +- **Dialog palette scaffold**: start from `p-command-1` and preserve dialog-trigger -> popup -> command list structure. +- **Controlled state**: use controlled open/value state for cross-component flows when needed. +- **Accessibility behavior**: validate keyboard open/close, focus movement, and accessible labels. + +## Common pitfalls + +- Using command list without clear grouping and action labels. +- Binding critical destructive actions without confirmation pathway. +- Missing keyboard accessibility checks for arrow/select/escape interactions. + +## Useful particle references + +- core patterns: `p-command-1`, `p-command-2` +- related search/selection references: `p-autocomplete-1`, `p-select-1`, `p-input-group-1` diff --git a/apps/ui/skills/coss/primitives/drawer/SKILL.md b/apps/ui/skills/coss/primitives/drawer/SKILL.md new file mode 100644 index 000000000..e5a39328b --- /dev/null +++ b/apps/ui/skills/coss/primitives/drawer/SKILL.md @@ -0,0 +1,96 @@ +--- +name: coss-drawer +description: Use when implementing drawer patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Drawer + +## When to use + +- Mobile-first overlay panels and bottom sheets. +- Form-heavy or multi-step overlays where popover is too constrained. + +## Install + +```bash +npx shadcn@latest add @coss/drawer +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { + Drawer, + DrawerCreateHandle, + DrawerClose, + DrawerContent, + DrawerDescription, + DrawerFooter, + DrawerHeader, + DrawerMenu, + DrawerMenuCheckboxItem, + DrawerMenuGroup, + DrawerMenuGroupLabel, + DrawerMenuItem, + DrawerMenuRadioGroup, + DrawerMenuRadioItem, + DrawerMenuSeparator, + DrawerPanel, + DrawerPopup, + DrawerMenuTrigger, + DrawerTitle, + DrawerTrigger, +} from "@/components/ui/drawer" +``` + +## Minimal pattern + +```tsx + + Open + + + Drawer Title + Drawer Description + + Content + + Close + + + +``` + +## Patterns from coss particles + +- **Inset variant**: follow `p-drawer-4` for this documented variation. +- **Straight variant**: follow `p-drawer-5` for this documented variation. +- **Scrollable content**: follow `p-drawer-6` for this documented variation. +- **Nested drawers**: follow `p-drawer-7` for this documented variation. +- **Snap points**: follow `p-drawer-9` for this documented variation. +- **Mobile menu**: follow `p-drawer-11` for this documented variation. + +## Common pitfalls + +- Using drawer for desktop modal flows where dialog/sheet is clearer. +- Forgetting responsive switch logic when drawer is mobile-only variant. +- Breaking section layout by wrapping header/panel/footer without `contents` where required. + +## Useful particle references + +- inset variant: `p-drawer-4` +- straight variant: `p-drawer-5` +- scrollable content: `p-drawer-6` +- nested drawers: `p-drawer-7` +- snap points: `p-drawer-9` +- mobile menu: `p-drawer-11` +- responsive dialog: `p-drawer-12` +- responsive menu: `p-drawer-13` +- cross-overlay references: `p-dialog-1`, `p-popover-1`, `p-menu-2` diff --git a/apps/ui/skills/coss/primitives/empty/SKILL.md b/apps/ui/skills/coss/primitives/empty/SKILL.md new file mode 100644 index 000000000..952710184 --- /dev/null +++ b/apps/ui/skills/coss/primitives/empty/SKILL.md @@ -0,0 +1,70 @@ +--- +name: coss-empty +description: Use when implementing empty patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Empty + +## When to use + +- No-data/no-results states with guidance. +- Action-oriented recovery UIs when content lists are empty. + +## Install + +```bash +npx shadcn@latest add @coss/empty +``` + +Manual deps from docs: + +```bash +# No extra runtime dependency required for this primitive. +``` + +## Canonical imports + +```tsx +import { + Empty, + EmptyContent, + EmptyDescription, + EmptyHeader, + EmptyMedia, + EmptyTitle, +} from "@/components/ui/empty" +``` + +## Minimal pattern + +```tsx + + + + + + No data + No data found + + + + + +``` + +## Patterns from coss particles + +- **Baseline usage**: start from `p-empty-1` and add only the props/parts needed for the target flow. +- **Variant sizing**: prefer primitive variants/sizes before class overrides. +- **Accessibility**: keep explicit labels and semantic roles when used in interactive contexts. + +## Common pitfalls + +- Presenting empty states without actionable next step. +- Using empty state component for loading/error states instead of dedicated primitives. +- Copy-only empty states with no context-specific guidance for recovery. + +## Useful particle references + +- core patterns: `p-empty-1` diff --git a/apps/ui/skills/coss/primitives/field/SKILL.md b/apps/ui/skills/coss/primitives/field/SKILL.md new file mode 100644 index 000000000..318da3009 --- /dev/null +++ b/apps/ui/skills/coss/primitives/field/SKILL.md @@ -0,0 +1,80 @@ +--- +name: coss-field +description: Use when implementing field patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Field + +## When to use + +- Accessible field wrappers with labels, descriptions, and errors. +- Form control state wiring (`invalid`, `required`, touched/error messaging). + +## Install + +```bash +npx shadcn@latest add @coss/field +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { + Field, + FieldDescription, + FieldError, + FieldLabel, + FieldValidity, +} from "@/components/ui/field" +import { Input } from "@/components/ui/input" +``` + +## Minimal pattern + +```tsx + + Name + + Visible on your profile + Please enter a valid name + + {(validity) => ( + {validity.error &&

{validity.error}

} + )} + + +``` + +## Patterns from coss particles + +- **Required Field**: use `p-field-2` as the baseline implementation for this variation. +- **Disabled Field**: use `p-field-3` as the baseline implementation for this variation. +- **Error**: use `p-field-4` as the baseline implementation for this variation. +- **Validity**: use `p-field-5` as the baseline implementation for this variation. +- **Input Group**: use `p-field-6` as the baseline implementation for this variation. +- **Autocomplete Field**: use `p-field-7` as the baseline implementation for this variation. + +## Common pitfalls + +- Rendering errors detached from the related control, breaking context. +- Missing `name` in form flows, causing silent submit omissions. +- Using field wrapper without corresponding label/description/error semantics. + +## Useful particle references + +- required field: `p-field-2` +- disabled field: `p-field-3` +- with error: `p-field-4` +- with validity: `p-field-5` +- input group: `p-field-6` +- autocomplete field: `p-field-7` +- combobox field: `p-field-8` +- combobox multiple field: `p-field-9` +- form composition references: `p-form-1`, `p-form-2`, `p-input-group-24` diff --git a/apps/ui/skills/coss/primitives/fieldset/SKILL.md b/apps/ui/skills/coss/primitives/fieldset/SKILL.md new file mode 100644 index 000000000..f17a41e1c --- /dev/null +++ b/apps/ui/skills/coss/primitives/fieldset/SKILL.md @@ -0,0 +1,55 @@ +--- +name: coss-fieldset +description: Use when implementing fieldset patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Fieldset + +## When to use + +- Grouped related controls under one legend/description. +- Complex forms requiring semantic grouping for radios/checkboxes. + +## Install + +```bash +npx shadcn@latest add @coss/fieldset +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset" +``` + +## Minimal pattern + +```tsx +
+ Fieldset legend +
+``` + +## Patterns from coss particles + +- **Semantic group scaffold**: start from `p-fieldset-1` with `FieldsetLegend` as the accessible group heading. +- **Validation integration**: pair labels/descriptions/errors with the same control context. +- **Value-shape correctness**: keep controlled state types aligned with the primitive API. + +## Common pitfalls + +- Using ad-hoc div wrappers instead of semantic fieldset for grouped controls. +- Omitting `FieldsetLegend`, reducing accessibility context. +- Placing unrelated controls inside one fieldset, hurting form clarity. + +## Useful particle references + +- core patterns: `p-fieldset-1` +- form composition references: `p-form-1`, `p-form-2`, `p-input-group-24` diff --git a/apps/ui/skills/coss/primitives/form/SKILL.md b/apps/ui/skills/coss/primitives/form/SKILL.md index 703ac623a..0ef445896 100644 --- a/apps/ui/skills/coss/primitives/form/SKILL.md +++ b/apps/ui/skills/coss/primitives/form/SKILL.md @@ -50,6 +50,10 @@ import { Input } from "@/components/ui/input" ``` +## Patterns from coss particles + +- `Form` usage in particles is intentionally lightweight; use the Base UI forms handbook patterns below for deeper validation/library integrations. + ## Patterns from coss/Base UI forms - **Submission mode**: use `onSubmit` for native `FormData` handling; use `onFormSubmit` when you want parsed form values object from Base UI Form. @@ -57,6 +61,7 @@ import { Input } from "@/components/ui/input" - **Accessible names**: prefer visible labels (`FieldLabel`, `SelectLabel`, etc.); use `aria-label` only when no visible label exists. - **Grouped controls**: for radio/checkbox groups or multi-control sections, use fieldset-style grouping (`Fieldset` + `Field.Item`) instead of ad-hoc wrappers. - **Validation rendering**: pair constraints/custom validation with `FieldError`; keep error output semantically tied to the same field. +- **Textarea integration**: use coss `Textarea` directly inside `Field`; it already integrates with Base UI field control semantics, so `FieldControl render={...}` is not required for standard textarea usage. - **External library integration**: when using RHF/TanStack, forward refs/input refs to the underlying control and map invalid/touched/dirty state into `Field`. ## Common pitfalls diff --git a/apps/ui/skills/coss/primitives/frame/SKILL.md b/apps/ui/skills/coss/primitives/frame/SKILL.md new file mode 100644 index 000000000..597d651fe --- /dev/null +++ b/apps/ui/skills/coss/primitives/frame/SKILL.md @@ -0,0 +1,65 @@ +--- +name: coss-frame +description: Use when implementing frame patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Frame + +## When to use + +- Bordered app surfaces around content blocks. +- Container wrapper for data components like table, cards, and panes. + +## Install + +```bash +npx shadcn@latest add @coss/frame +``` + +Manual deps from docs: + +```bash +# No extra runtime dependency required for this primitive. +``` + +## Canonical imports + +```tsx +import { + Frame, + FrameDescription, + FrameFooter, + FrameHeader, + FramePanel, + FrameTitle, +} from "@/components/ui/frame" +``` + +## Minimal pattern + +```tsx + + + Title + Description + + Content + Footer + +``` + +## Patterns from coss particles + +- **Separated Panels**: use the pattern shown in `p-frame-3` when this variation is required. +- **Surface consistency**: use `Frame` to normalize border/radius around heterogeneous inner content. +- **Composed containers**: pair frame with footer/header parts when controls live around content. +## Common pitfalls + +- Using nested frames excessively, causing dense double borders. +- Applying frame as layout grid replacement instead of content surface wrapper. +- Forgetting to align inner component width expectations (table/list full width). + +## Useful particle references + +- separated panels: `p-frame-3` diff --git a/apps/ui/skills/coss/primitives/group/SKILL.md b/apps/ui/skills/coss/primitives/group/SKILL.md new file mode 100644 index 000000000..f7d95abb3 --- /dev/null +++ b/apps/ui/skills/coss/primitives/group/SKILL.md @@ -0,0 +1,66 @@ +--- +name: coss-group +description: Use when implementing group patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Group + +## When to use + +- Connected controls with shared visual boundary. +- Composed action clusters using buttons, toggles, and menu triggers. + +## Install + +```bash +npx shadcn@latest add @coss/group +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { Button } from "@/components/ui/button" +import { Group, GroupSeparator } from "@/components/ui/group" +``` + +## Minimal pattern + +```tsx + + + + + +``` + +## Patterns from coss particles + +- **Input**: use the pattern shown in `p-group-2` when this variation is required. +- **Small Size**: use the pattern shown in `p-group-3` when this variation is required. +- **Large Size**: use the pattern shown in `p-group-4` when this variation is required. +- **Disabled Button**: use the pattern shown in `p-group-5` when this variation is required. +- **Default Buttons**: use the pattern shown in `p-group-6` when this variation is required. + +## Common pitfalls + +- Forgetting `GroupSeparator` between controls in connected groups. +- Mixing control sizes/variants that break shared group silhouette. +- Using standalone controls where a grouped action model is expected. + +## Useful particle references + +- with input: `p-group-2` +- small size: `p-group-3` +- large size: `p-group-4` +- with disabled button: `p-group-5` +- with default buttons: `p-group-6` +- with start labeled text: `p-group-7` +- with end text: `p-group-8` +- vertical: `p-group-9` diff --git a/apps/ui/skills/coss/primitives/input-group/SKILL.md b/apps/ui/skills/coss/primitives/input-group/SKILL.md index 886d7247f..082e1c6b3 100644 --- a/apps/ui/skills/coss/primitives/input-group/SKILL.md +++ b/apps/ui/skills/coss/primitives/input-group/SKILL.md @@ -49,6 +49,12 @@ import { `InputGroupAddon` must be after `InputGroupInput`/`InputGroupTextarea` in DOM order for proper focus behavior. +## Patterns from coss particles + +- **Icon/text addons**: use `InputGroupAddon` + `InputGroupText` for static prefixes/suffixes (search, URL, currency, domains). +- **Interactive addons**: compose buttons, menu triggers, clear actions, and shortcut hints inside addon slots when actions belong to the input context. +- **Textarea/editor layouts**: use `InputGroupTextarea` with block-start/block-end addons while keeping input/textarea first in DOM order. + ## Common pitfalls - Using `Input`/`Textarea` directly instead of `InputGroupInput`/`InputGroupTextarea`. diff --git a/apps/ui/skills/coss/primitives/input-otp/SKILL.md b/apps/ui/skills/coss/primitives/input-otp/SKILL.md new file mode 100644 index 000000000..8b850f00e --- /dev/null +++ b/apps/ui/skills/coss/primitives/input-otp/SKILL.md @@ -0,0 +1,77 @@ +--- +name: coss-input-otp +description: Use when implementing input otp patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Input Otp + +## When to use + +- One-time passcode entry with segmented slots. +- Verification code flows with strict length formatting. + +## Install + +```bash +npx shadcn@latest add @coss/input-otp +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react input-otp lucide-react +``` + +## Canonical imports + +```tsx +import { + InputOTP, + InputOTPGroup, + InputOTPSeparator, + InputOTPSlot, +} from "@/components/ui/input-otp" +``` + +## Minimal pattern + +```tsx + + + + + + + + + + + + + +``` + +## Patterns from coss particles + +- **Large**: use `p-input-otp-2` as the baseline implementation for this variation. +- **Separator**: use `p-input-otp-3` as the baseline implementation for this variation. +- **Label**: use `p-input-otp-4` as the baseline implementation for this variation. +- **Digits Only**: use `p-input-otp-5` as the baseline implementation for this variation. +- **Invalid**: use `p-input-otp-6` as the baseline implementation for this variation. +- **Auto Validation**: use `p-input-otp-7` as the baseline implementation for this variation. + +## Common pitfalls + +- Slot count mismatch with `maxLength`, causing broken OTP UX. +- Missing `aria-label` when no visible label is present. +- Using OTP slots for arbitrary text input instead of fixed verification codes. + +## Useful particle references + +- large: `p-input-otp-2` +- with separator: `p-input-otp-3` +- with label: `p-input-otp-4` +- digits only: `p-input-otp-5` +- invalid: `p-input-otp-6` +- auto validation: `p-input-otp-7` diff --git a/apps/ui/skills/coss/primitives/input/SKILL.md b/apps/ui/skills/coss/primitives/input/SKILL.md new file mode 100644 index 000000000..f2dc5702a --- /dev/null +++ b/apps/ui/skills/coss/primitives/input/SKILL.md @@ -0,0 +1,65 @@ +--- +name: coss-input +description: Use when implementing input patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Input + +## When to use + +- Single-line text entry with variants and addons. +- Email/password/search/file and other typed input flows. + +## Install + +```bash +npx shadcn@latest add @coss/input +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { Input } from "@/components/ui/input" +``` + +## Minimal pattern + +```tsx + +``` + +Always set `type` explicitly on `Input` (`text`, `email`, `password`, `search`, `file`, etc.). Do not rely on browser defaults. +For form fields, prefer wrapping `Input` with `Field` + `FieldLabel` + `FieldError` instead of standalone usage. + +## Patterns from coss particles + +- **Small Size**: use `p-input-2` as the baseline implementation for this variation. +- **Large Size**: use `p-input-3` as the baseline implementation for this variation. +- **Disabled**: use `p-input-4` as the baseline implementation for this variation. +- **File**: use `p-input-5` as the baseline implementation for this variation. +- **Label**: use `p-input-6` as the baseline implementation for this variation. +- **Button**: use `p-input-7` as the baseline implementation for this variation. +- **Field composition**: use `Field` wrappers for form-bound inputs (see `p-form-1` / `p-form-2`). + +## Common pitfalls + +- Omitting explicit `type` and relying on browser defaults. +- Using icon-only affordances without label/aria context. +- Applying heavy class overrides before using built-in size/variant props. + +## Useful particle references + +- small size: `p-input-2` +- large size: `p-input-3` +- disabled: `p-input-4` +- file: `p-input-5` +- with label: `p-input-6` +- with button: `p-input-7` +- form integration: `p-form-1` diff --git a/apps/ui/skills/coss/primitives/kbd/SKILL.md b/apps/ui/skills/coss/primitives/kbd/SKILL.md new file mode 100644 index 000000000..edeaf3777 --- /dev/null +++ b/apps/ui/skills/coss/primitives/kbd/SKILL.md @@ -0,0 +1,51 @@ +--- +name: coss-kbd +description: Use when implementing kbd patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Kbd + +## When to use + +- Keyboard shortcut keycaps near commands. +- Single or grouped key hint display in action UIs. + +## Install + +```bash +npx shadcn@latest add @coss/kbd +``` + +Manual deps from docs: + +```bash +# No extra runtime dependency required for this primitive. +``` + +## Canonical imports + +```tsx +import { Kbd, KbdGroup } from "@/components/ui/kbd" +``` + +## Minimal pattern + +```tsx +K +``` + +## Patterns from coss particles + +- **Input Group**: use the pattern shown in `p-input-group-11` when this variation is required. +- **Shortcut pairs**: use `KbdGroup` for multi-key shortcuts (`cmd` + key) instead of cramming into one badge. +- **Action adjacency**: keep key hints adjacent to the command they trigger. +## Common pitfalls + +- Placing multi-key sequences in a single `Kbd` when `KbdGroup` is clearer. +- Using decorative keycaps without tying them to nearby actionable controls. +- Overusing kbd hints in simple UIs, adding noise instead of clarity. + +## Useful particle references + +- input group: `p-input-group-11` diff --git a/apps/ui/skills/coss/primitives/label/SKILL.md b/apps/ui/skills/coss/primitives/label/SKILL.md new file mode 100644 index 000000000..57e4f61c5 --- /dev/null +++ b/apps/ui/skills/coss/primitives/label/SKILL.md @@ -0,0 +1,52 @@ +--- +name: coss-label +description: Use when implementing label patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Label + +## When to use + +- Visible accessible labels for inputs and controls. +- Simple `htmlFor`/`id` associations in forms and settings UIs. + +## Install + +```bash +npx shadcn@latest add @coss/label +``` + +Manual deps from docs: + +```bash +# No extra runtime dependency required for this primitive. +``` + +## Canonical imports + +```tsx +import { Label } from "@/components/ui/label" +``` + +## Minimal pattern + +```tsx + +``` + +## Patterns from coss particles + +- **Checkbox**: use the pattern shown in `checkbox-demo` when this variation is required. +- **Field integration**: prefer `FieldLabel` within `Field` for validation-aware forms. +- **Standalone controls**: use `Label htmlFor` + matching input `id` for isolated control-label pairs. +## Common pitfalls + +- Using `aria-label` when visible `Label` text exists and can be associated. +- Mismatching `htmlFor`/`id` between label and control. +- Using label component as generic typography instead of form labeling. + +## Useful particle references + +- with checkbox: `checkbox-demo` +- label-specific particles: no dedicated `p-label-*` family; use form references `p-field-1`, `p-input-1`, `p-checkbox-1`. diff --git a/apps/ui/skills/coss/primitives/meter/SKILL.md b/apps/ui/skills/coss/primitives/meter/SKILL.md new file mode 100644 index 000000000..52c706770 --- /dev/null +++ b/apps/ui/skills/coss/primitives/meter/SKILL.md @@ -0,0 +1,57 @@ +--- +name: coss-meter +description: Use when implementing meter patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Meter + +## When to use + +- Bounded scalar measurement display (not task progress). +- Quality/capacity indicators with min/max semantics. + +## Install + +```bash +npx shadcn@latest add @coss/meter +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { Meter, MeterLabel, MeterValue } from "@/components/ui/meter" +``` + +## Minimal pattern + +```tsx + + Progress + + +``` + +## Patterns from coss particles + +- **Without Label and Value**: use the pattern shown in `p-meter-2` when this variation is required. +- **Formatted Value**: use the pattern shown in `p-meter-3` when this variation is required. +- **Range**: use the pattern shown in `p-meter-4` when this variation is required. + +## Common pitfalls + +- Using meter to represent completion tasks better suited for `Progress`. +- Missing min/max context when values are not obvious to the user. +- Treating meter as interactive control rather than read-only indicator. + +## Useful particle references + +- without label and value: `p-meter-2` +- with formatted value: `p-meter-3` +- with range: `p-meter-4` diff --git a/apps/ui/skills/coss/primitives/number-field/SKILL.md b/apps/ui/skills/coss/primitives/number-field/SKILL.md new file mode 100644 index 000000000..ecff31384 --- /dev/null +++ b/apps/ui/skills/coss/primitives/number-field/SKILL.md @@ -0,0 +1,79 @@ +--- +name: coss-number-field +description: Use when implementing number field patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Number Field + +## When to use + +- Numeric entry with increment/decrement controls. +- Bounded stepper-style quantity/amount inputs. + +## Install + +```bash +npx shadcn@latest add @coss/number-field +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { + NumberField, + NumberFieldDecrement, + NumberFieldGroup, + NumberFieldIncrement, + NumberFieldInput, + NumberFieldScrubArea, +} from "@/components/ui/number-field" +``` + +## Minimal pattern + +```tsx + + + + + + + + +``` + +For form-bound numeric inputs, prefer wrapping `NumberField` with `Field` + `FieldLabel` + `FieldError` instead of standalone usage. + +## Patterns from coss particles + +- **Field composition**: use `Field` wrappers for form-bound numeric controls and error messaging. +- **Small Size**: use `p-number-field-2` as the baseline implementation for this variation. +- **Large Size**: use `p-number-field-3` as the baseline implementation for this variation. +- **Disabled**: use `p-number-field-4` as the baseline implementation for this variation. +- **External Label**: use `p-number-field-5` as the baseline implementation for this variation. +- **Scrub**: use `p-number-field-6` as the baseline implementation for this variation. +- **Range**: use `p-number-field-7` as the baseline implementation for this variation. + +## Common pitfalls + +- Treating number field value as free-form text without numeric bounds/steps. +- Missing increment/decrement controls in stepper-style UIs where expected. +- Not validating min/max constraints and resulting clamped behavior. + +## Useful particle references + +- small size: `p-number-field-2` +- large size: `p-number-field-3` +- disabled: `p-number-field-4` +- with external label: `p-number-field-5` +- with scrub: `p-number-field-6` +- with range: `p-number-field-7` +- with formatted value: `p-number-field-8` +- with step: `p-number-field-9` diff --git a/apps/ui/skills/coss/primitives/pagination/SKILL.md b/apps/ui/skills/coss/primitives/pagination/SKILL.md new file mode 100644 index 000000000..24f320ade --- /dev/null +++ b/apps/ui/skills/coss/primitives/pagination/SKILL.md @@ -0,0 +1,75 @@ +--- +name: coss-pagination +description: Use when implementing pagination patterns with coss primitives and particle-backed conventions. +user-invocable: false +--- + +# coss Pagination + +## When to use + +- Paged navigation over long result sets. +- Prev/next and index controls paired with data tables/lists. + +## Install + +```bash +npx shadcn@latest add @coss/pagination +``` + +Manual deps from docs: + +```bash +# No extra runtime dependency required for this primitive. +``` + +## Canonical imports + +```tsx +import { + Pagination, + PaginationContent, + PaginationEllipsis, + PaginationItem, + PaginationLink, + PaginationNext, + PaginationPrevious, +} from "@/components/ui/pagination" +``` + +## Minimal pattern + +```tsx + + + + + + + 1 + + + + + + + + + +``` + +## Patterns from coss particles + +- **Baseline structure**: start from `p-pagination-1` and preserve part hierarchy. +- **Responsive behavior**: verify behavior across compact and wide layouts. +- **Accessibility**: ensure labels, roles, and keyboard behavior are preserved. + +## Common pitfalls + +- Using pagination controls without synchronizing data/page state. +- Mixing pagination with infinite-scroll UX in the same surface. +- Missing disabled-state handling on prev/next boundaries. + +## Useful particle references + +- core patterns: `p-pagination-1`, `p-pagination-2`, `p-pagination-3` diff --git a/apps/ui/skills/coss/primitives/popover/SKILL.md b/apps/ui/skills/coss/primitives/popover/SKILL.md new file mode 100644 index 000000000..5f102f30b --- /dev/null +++ b/apps/ui/skills/coss/primitives/popover/SKILL.md @@ -0,0 +1,74 @@ +--- +name: coss-popover +description: Use when implementing anchored, non-modal floating UI with coss Popover (standard, tooltip-style, and detached-trigger patterns). +user-invocable: false +--- + +# coss Popover + +## When to use + +- Contextual floating content near a trigger. +- Inline editing/help panels without full modal lock. + +## Install + +```bash +npx shadcn@latest add @coss/popover +``` + +Manual deps from docs: + +```bash +npm install @base-ui/react +``` + +## Canonical imports + +```tsx +import { + Popover, + PopoverClose, + PopoverCreateHandle, + PopoverDescription, + PopoverPopup, + PopoverTitle, + PopoverTrigger, +} from "@/components/ui/popover" +``` + +## Minimal pattern + +```tsx + + }>Open Popover + + Popover Title + Popover Description + }>Close + + +``` + +## Patterns from coss particles + +- **Form-in-popover**: use `PopoverPopup` as a lightweight form container (for example feedback forms with `Form` + `Field` + `Textarea`). +- **Dismiss controls**: use `PopoverClose` both for footer actions and icon close buttons (`aria-label` + `render={