From f9b00e42a7014ffb4a70fb465a45a5b37772c3ed Mon Sep 17 00:00:00 2001 From: pasqualevitiello Date: Mon, 23 Mar 2026 10:10:31 +0100 Subject: [PATCH 1/2] mc --- .../coss/references/primitives/button.md | 23 ++++++++++++++++++- .../coss/references/primitives/drawer.md | 2 +- .../coss/references/primitives/sheet.md | 2 +- .../skills/coss/references/rules/styling.md | 1 + 4 files changed, 25 insertions(+), 3 deletions(-) diff --git a/apps/ui/skills/coss/references/primitives/button.md b/apps/ui/skills/coss/references/primitives/button.md index 4c0b5e0d4..825fd1e10 100644 --- a/apps/ui/skills/coss/references/primitives/button.md +++ b/apps/ui/skills/coss/references/primitives/button.md @@ -65,6 +65,25 @@ Button with icon and text (no opacity on the icon): Sizes: `xs`, `sm`, `default`, `lg`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`. +### Loading state + +Built-in `loading` prop (disables and shows spinner automatically): + +```tsx + +``` + +Composite approach (manual `Spinner` + `disabled`): + +```tsx + +``` + +Prefer the `loading` prop for typical async actions. Use the composite approach when you need custom spinner placement or label. + ### More examples - default: `p-button-1` @@ -85,4 +104,6 @@ Sizes: `xs`, `sm`, `default`, `lg`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`. ## Useful particle references -See particles `p-button-1` through `p-button-8` for all variant/size combinations. +- variants/sizes: `p-button-1` through `p-button-8` +- composite loading (Spinner + disabled): `p-button-18` +- built-in loading prop: `p-button-41` diff --git a/apps/ui/skills/coss/references/primitives/drawer.md b/apps/ui/skills/coss/references/primitives/drawer.md index e5026634d..8a238736e 100644 --- a/apps/ui/skills/coss/references/primitives/drawer.md +++ b/apps/ui/skills/coss/references/primitives/drawer.md @@ -88,7 +88,7 @@ Drawer with handle: - }>Cancel + }>Cancel diff --git a/apps/ui/skills/coss/references/primitives/sheet.md b/apps/ui/skills/coss/references/primitives/sheet.md index 10fdec3e9..27899b2b9 100644 --- a/apps/ui/skills/coss/references/primitives/sheet.md +++ b/apps/ui/skills/coss/references/primitives/sheet.md @@ -81,7 +81,7 @@ Sheet from the right side with form: - }>Cancel + }>Cancel diff --git a/apps/ui/skills/coss/references/rules/styling.md b/apps/ui/skills/coss/references/rules/styling.md index 781242c8d..e65d8f4c1 100644 --- a/apps/ui/skills/coss/references/rules/styling.md +++ b/apps/ui/skills/coss/references/rules/styling.md @@ -21,6 +21,7 @@ Use this guide when writing or updating coss primitives, particles, and docs exa - 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. +- Cancel/close buttons in Dialog, AlertDialog, Sheet, and Drawer footers use `variant="ghost"`. Reserve `variant="outline"` for triggers that open overlays, not for dismissing them. ## Global Styling Setup (when relevant) From 979427d69ddc998cc1d6f789585f0cfdfb36ff47 Mon Sep 17 00:00:00 2001 From: pasqualevitiello Date: Mon, 23 Mar 2026 10:53:47 +0100 Subject: [PATCH 2/2] mc --- apps/ui/content/docs/(root)/get-started.mdx | 1 + apps/ui/content/docs/(root)/meta.json | 9 +++- apps/ui/content/docs/(root)/roadmap.mdx | 2 +- apps/ui/content/docs/(root)/skills.mdx | 58 +++++++++++++++++++++ apps/ui/lib/docs.ts | 1 + 5 files changed, 69 insertions(+), 2 deletions(-) create mode 100644 apps/ui/content/docs/(root)/skills.mdx diff --git a/apps/ui/content/docs/(root)/get-started.mdx b/apps/ui/content/docs/(root)/get-started.mdx index 74cc0342b..a50e2afd5 100644 --- a/apps/ui/content/docs/(root)/get-started.mdx +++ b/apps/ui/content/docs/(root)/get-started.mdx @@ -124,5 +124,6 @@ For developers migrating from **Radix UI**, many of our **UI primitives** includ We structure the documentation to make the components **AI-friendly**, so language models can understand, reason about, and modify them. To support this, we include: +- **[Agent Skills](/ui/docs/skills)** — Install coss knowledge directly into your AI assistant with `npx skills add cosscom/coss`. Covers all 53 primitives, styling conventions, migration patterns, and particle examples. - A [llms.txt](/ui/llms.txt) file that provides a map of the documentation and component structure for your AI agent. - A **Copy Markdown** button on every page, so you can easily share content or feed it to your AI workflows. diff --git a/apps/ui/content/docs/(root)/meta.json b/apps/ui/content/docs/(root)/meta.json index 87e7ba596..b0cbf2ea6 100644 --- a/apps/ui/content/docs/(root)/meta.json +++ b/apps/ui/content/docs/(root)/meta.json @@ -1,4 +1,11 @@ { - "pages": ["index", "get-started", "styling", "radix-migration", "roadmap"], + "pages": [ + "index", + "get-started", + "styling", + "radix-migration", + "skills", + "roadmap" + ], "title": "Overview" } diff --git a/apps/ui/content/docs/(root)/roadmap.mdx b/apps/ui/content/docs/(root)/roadmap.mdx index 656f3b26d..3bed6bbd6 100644 --- a/apps/ui/content/docs/(root)/roadmap.mdx +++ b/apps/ui/content/docs/(root)/roadmap.mdx @@ -16,7 +16,7 @@ Origin UI offered a large collection of 600+ ready-to-use UI components. With th ## Current Status -- **40+ UI primitives** already available, with more on the way. +- **50+ UI primitives** already available, with more on the way. - A **growing set of particles**, progressively expanding to match and surpass the current Origin UI collection. ## What’s Next diff --git a/apps/ui/content/docs/(root)/skills.mdx b/apps/ui/content/docs/(root)/skills.mdx new file mode 100644 index 000000000..c56ba2aca --- /dev/null +++ b/apps/ui/content/docs/(root)/skills.mdx @@ -0,0 +1,58 @@ +--- +title: Skills +description: Give your AI assistant deep knowledge of coss ui components, patterns, and best practices. +--- + +Skills provide AI coding assistants with structured knowledge about **coss ui** — component APIs, composition patterns, styling conventions, migration rules, and common pitfalls. When installed, your assistant knows how to use coss primitives correctly without guessing. + +For example, you can ask your assistant to: + +- _"Add a settings dialog with a form and save/cancel buttons."_ +- _"Add a select with grouped options and a search filter."_ +- _"Migrate this shadcn dropdown menu to coss."_ +- _"Build a toast notification for form submission errors."_ + +## Install + +```bash +npx skills add cosscom/coss +``` + +This installs the coss skill into your project. Once installed, your AI assistant automatically loads it when working with coss ui components. + +Learn more about the skills ecosystem at [skills.sh](https://skills.sh). + +## What's Included + +The skill covers the full coss ui surface: + +### Component Knowledge + +Reference guides for all primitives — imports, minimal patterns, inline code examples, composition rules, and common pitfalls. The assistant knows when to use Dialog vs Sheet vs Drawer, how to compose trigger-based overlays, and how to structure forms with Field. + +### Styling Conventions + +Tailwind v4 token usage, semantic color system, icon sizing rules, `data-slot` selectors, `--alpha()` syntax, and the font variable contract (`--font-sans`, `--font-mono`, `--font-heading`). + +### Migration Patterns + +Rules for migrating from shadcn/Radix to coss/Base UI — `asChild` to `render`, `onSelect` to `onClick`, Select items-first pattern, ToggleGroup `type` to `multiple`, and Slider scalar values. + +### CLI and Registry + +Full reference for installing components via the shadcn CLI, discovery fallbacks, and manual install paths. + +### Particle Examples + +The skill references the particle catalog — real-world composition examples for every primitive — so the assistant can produce production-realistic code, not just minimal stubs. + +## How It Works + +1. **Skill activation** — Your AI agent detects the installed skill files in your project. +2. **Progressive loading** — The root `SKILL.md` provides core rules and a component registry index. Detailed per-component guides and rule references are loaded on demand when the task requires them. +3. **Pattern enforcement** — The assistant follows coss composition rules: `render` prop for trigger composition, `DialogHeader`/`DialogPanel`/`DialogFooter` section structure, `variant="ghost"` for cancel buttons, and correct Base UI APIs. +4. **Example-driven output** — Before generating code, the assistant consults particle examples to match real coss patterns. + +## Supported Agents + +Skills work with any agent that supports the Agent Skills specification, including Claude Code, Cursor, Codex, Cline, Windsurf, GitHub Copilot, and many more. diff --git a/apps/ui/lib/docs.ts b/apps/ui/lib/docs.ts index 0da2ce5b6..0ee260c86 100644 --- a/apps/ui/lib/docs.ts +++ b/apps/ui/lib/docs.ts @@ -1,5 +1,6 @@ export const PAGES_NEW = [ // "/docs/components/{component-name}", + "/docs/skills", "/docs/components/drawer", "/docs/components/input-otp", ];