shadcn-component-boundaries

# Placement examples

Paths assume `components.json` resolves `components` to `src/components` and `ui` to `src/components/ui`; substitute the project's resolved aliases.

| Component | Ownership | Path |
| --- | --- | --- |
| `Button` added with `shadcn add button` | registry primitive | `src/components/ui/button.tsx` |
| `ConfirmButton` wrapping `Button` + `AlertDialog`, used app-wide | reusable product | `src/components/common/confirm-button.tsx` |
| `InvoiceTable` used only by the billing feature | feature | `src/components/billing/invoice-table.tsx` |
| Dashboard page composing cards and tables | route composition | framework route directory |
| Brand accent color | theme token | global stylesheet variable |

Edge cases:

- A registry primitive needs a new look used in several places → add a variant to the primitive; do not create a styled copy in `common/`.
- A feature component becomes reused by a second feature → move it to `common/` and remove feature-specific behavior first.
- Re-running `shadcn add` overwrites a primitive → keep product behavior outside `ui` so the overwrite loses nothing.

---
name: shadcn-component-boundaries
description: "Trigger: components/ui, shadcn, component placement, common components, feature components, atomic design. Enforce registry and product component boundaries."
license: Apache-2.0
metadata:
  author: purrfold
  version: "1.0"
---

# shadcn Component Boundaries

## Activation Contract

Load this skill when creating, moving, wrapping, or reviewing UI components in a project that uses shadcn.

## Hard Rules

1. Resolve paths from `components.json` (its `aliases` for `components` and `ui`) or the installed shadcn skill's project-context command. Never assume `components/` versus `src/components/`.
2. Reserve the resolved `ui` directory for registry-managed primitives installed from shadcn or compatible registries.
3. Never place product-owned wrappers, composites, sections, domain components, or feature behavior in the `ui` directory.
4. Put reusable product-owned components under `common/` in the resolved components directory.
5. Put feature-owned components in a named feature folder or colocate them with that feature.
6. Compose: wrap a registry primitive from `common/` or a feature folder instead of adding product behavior to the primitive.
7. Keep dependencies one-way: feature → common → ui. The `ui` directory never imports from `common` or feature folders.
8. Use semantic tokens from the global stylesheet. Treat tokens as quarks and registry primitives as atoms; do not force molecule or organism names into paths.
9. When `@shadcn/lint` is configured, `shadcn/no-restyle` enforces the `ui` boundary: call sites may pass layout classes through `className`, but look comes from variants and sizes. Add a variant to the primitive instead of restyling at the call site.

## Decision Gates

| Component ownership | Destination |
| --- | --- |
| shadcn or compatible registry primitive | resolved `ui` directory |
| reusable product-owned component | `<components>/common/` |
| feature-specific component | `<components>/<feature>/` or feature colocation |
| route or page composition | framework route/page directory |
| theme token | global stylesheet variables |

## Execution Steps

1. Read `components.json` and resolve the `components` and `ui` aliases to directories.
2. Search installed primitives before creating custom markup.
3. Classify ownership and reuse scope with the table above.
4. Place the component; see [references/placement-examples.md](references/placement-examples.md) for edge cases.
5. Verify no product-owned file entered `ui` and no reverse import was introduced.

## Output Contract

State the ownership classification and final path for every component created or moved, and confirm the dependency direction holds.

## References

- [references/placement-examples.md](references/placement-examples.md) — worked placement decisions.