shadcn/ui

What it is

shadcn/ui is a collection of composable component primitives that you add directly into your codebase.

Best practices

Why we use it

• Fast UI delivery with accessible primitives.
• Full ownership because components live in the repository.
• Strong compatibility with Tailwind utility workflows.

Setup in this repo

• Install and generate only required components.
• Keep shared styles, design tokens, and variants centralized.
• Reuse base UI wrappers for repeated business-specific patterns.

Team conventions

• Prefer composition over heavy one-off custom components.
• Keep design tokens consistent across variants.
• Avoid direct edits in many places for the same pattern; create wrappers when repeated.
• Keep semantic HTML and accessibility attributes explicit.

Error handling and reliability

• Treat accessibility regressions as defects.
• Keep interaction states (disabled, loading, error) explicit in components.
• Use consistent focus and keyboard behavior across interactive elements.

Testing and validation

• Test critical interaction flows (dialogs, forms, menus).
• Validate keyboard and focus behavior for accessibility.
• Visual-check variant consistency in key reusable components.

Abstractions and anti-patterns

• Avoid over-customizing generated primitives without a shared abstraction.
• Avoid duplicating variant logic across multiple components.
• Avoid ad hoc class strings when a reusable variant pattern is warranted.

Example

import { Button } from "@/components/ui/button";

export function SaveButton() {
  return <Button>Save Changes</Button>;
}

Common pitfalls

• Generating many unused components.
• Inconsistent local styling that diverges from shared design tokens.
• Accessibility drift when wrappers hide semantic behavior.

References

Internal

• Frontend Stack
• React

External

• shadcn/ui Documentation
• Radix UI Primitives
• Tailwind CSS Documentation