Shadcn Component Boundaries

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

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 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 — worked placement decisions.