`, ``, etc.)
- Provide proper ARIA roles, states, and properties
- Support keyboard navigation for all interactive elements
- Ensure focus management in modals, dropdowns, and overlays
Components should be easy to restyle or adapt to different design requirements.
**Correct: design tokens and className override**
```tsx
export function Button({ className, ...props }: ButtonProps) {
return
{children}
);
}
```
**Incorrect: obfuscated or overly complex**
```tsx
export const Button = compose(withHOC1, withHOC2, withHOC3)(BaseButton);
```
Components should come with clear documentation and examples.
**Correct: comprehensive JSDoc**
```tsx
/**
* Button component for primary actions.
*
* @example
* Click me
*
* @remarks
* - Supports keyboard navigation (Enter/Space)
* - Accessible by default with proper ARIA attributes
*/
export function Button({ ... }: ButtonProps) { }
```
A well-designed component applies all six principles together: **Composes** with other components, **works for everyone** with proper accessibility, **adapts** to different designs via theming, **performs** efficiently, **can be inspected** and modified, and **is easy to learn** through documentation.
---
## 3. Definitions
**Impact: MEDIUM**
Common terminology and component type definitions including
primitive, compound, headless, and styled components.
### 3.1 Component Artifact Definitions
**Impact: MEDIUM (Essential for correct component classification)**
Precise terminology for classifying and naming UI artifacts.
The **lowest-level building block** providing behavior and accessibility without styling. Completely headless.
**Examples:** Radix UI Primitives, React Aria Components, Headless UI
A **styled, reusable UI unit** that adds visual design to primitives or composes multiple elements.
**Examples:** shadcn/ui components, Material UI, Ant Design
A **specific composition** solving a UI/UX problem. Documentation-focused, not a reusable component.
**Examples:** Form validation with inline errors, confirming destructive actions, typeahead search
An **opinionated, production-ready composition** solving a concrete interface use case.
**Examples:** Pricing table, auth screens, onboarding stepper, AI chat panel
A **complete, single-route view** composed of multiple blocks.
A **multi-page collection** or full-site scaffold bundling pages, routing, layouts, and providers.
**Examples:** SaaS starter, e-commerce template, dashboard starter
A **helper** for developer ergonomics or composition; not rendered UI.
**Examples:** React hooks, class utilities, keybinding helpers, focus scopes
1. **Behavior/a11y only, no styling?** → **Primitive**
2. **Styled, reusable UI element?** → **Component**
3. **Concrete product use case with opinionated composition?** → **Block**
4. **Multi-page scaffold with routing/providers?** → **Template**
5. **Documentation of recurring solution?** → **Pattern**
6. **Non-visual logic?** → **Utility**
**Incorrect: mislabeling a styled component as a primitive**
```tsx
// Wrong: This is styled, so it's a Component, not a Primitive
function DialogPrimitive({ open, onOpenChange, children }) {
return (
{children}
);
}
```
**Correct: proper classification based on styling presence**
```tsx
// Primitive - behavior only, no styling
function DialogPrimitive({ open, onOpenChange, children }) {
return (
{children}
);
}
// Component - styled wrapper around primitive
function Dialog({ open, onOpenChange, children }) {
return (
{children}
);
}
```
- **Props API** - Public configuration surface, typed and documented
- **Children/Slots** - Placeholders for caller-provided structure
- **Render Prop** - Function child delegating rendering
- **Controlled** - Value driven by props (parent is source of truth)
- **Uncontrolled** - Internal state with optional `defaultValue`
- **Provider/Context** - Supplies shared state to subtree
- **Portal** - Rendering outside DOM hierarchy for layering
- **Headless** - Behavior without styling
- **Styled** - Ships with default visual design
- **Variants** - Style/behavior permutations via props
- **Design Tokens** - Named values for theming
---
## 4. Composition
**Impact: HIGH**
Compose existing shared parts without duplicating state or behavior.
### 4.1 Component Composition
**Impact: HIGH (Compose existing shared parts without duplicating state or behavior)**
Compose the existing Core parts before building a new primitive. Shared Base UI components already own state coordination, keyboard navigation, ARIA and focus behavior; do not recreate them with a parallel Context or an inert `asChild` prop.
#### Compose the Shared Parts
```tsx
import {
Accordion,
AccordionContent,
AccordionItem,
AccordionTrigger,
} from "@asym/ui/components/shadcn/accordion";
Project details
Compose the content for this feature.
;
```
Import the existing flat exports shown above. Do not invent an `Accordion.Root` namespace or replace `value`/`defaultValue`/`onValueChange` with a custom `open`/`setOpen` state API.
#### Compose a Trigger Host
```tsx
import { Button } from "@asym/ui/components/shadcn/button";
import { DialogTrigger } from "@asym/ui/components/shadcn/dialog";
Click me
```
**Correct: semantic element**
```tsx
// Polite announcement
{savedMessage && "Saved"}
// Assertive announcement
{errorMessage}
```
Every interactive element must be keyboard accessible:
Use ARIA attributes when necessary:
Support users with visual impairments:
1. **Don't use ARIA if you can use semantic HTML**
2. **Don't change native semantics unless necessary**
3. **All interactive elements must be keyboard accessible**
4. **Don't hide focusable elements** - Never use `aria-hidden="true"` on focusable elements
5. **All interactive elements must have accessible names**
**Placeholder as labels:**
```tsx
// ❌ Placeholder disappears
Email address
```
**Empty buttons:**
```tsx
// ❌ No accessible name
Details
Project details
;
```
For controlled expansion, pass `value={expandedItems}` and `onValueChange={setExpandedItems}` with parent state typed to the shared Accordion's value contract. Do not replace that API with a boolean `open`/`setOpen` pair.
#### Preserve the Primitive Contract
| Existing primitive | Controlled prop | Initial default | Change callback |
| ------------------ | --------------- | ---------------- | ----------------- |
| Switch / Checkbox | `checked` | `defaultChecked` | `onCheckedChange` |
| Accordion / Tabs | `value` | `defaultValue` | `onValueChange` |
| Dialog / Popover | `open` | `defaultOpen` | `onOpenChange` |
- Inspect the existing component's exported props; value types and callback details vary by primitive.
- Forward the existing state props, callback arguments and ref when a wrapper is required.
- Preserve `false`, `0` and empty values; do not use truthiness to decide whether a prop is controlled.
- Do not combine controlled and default props to create competing state owners, or mirror a controlled prop into another local state variable.
- Let the shared primitive own keyboard, ARIA, disabled and focus behavior.
References: `packages/ui/components/shadcn/switch.tsx`, `packages/ui/components/shadcn/accordion.tsx`, and [Base UI composition](https://base-ui.com/react/handbook/composition).
---
## 7. Types
**Impact: HIGH**
TypeScript patterns for component props including extending HTML
attributes, exporting types, and single element wrapping.
### 7.1 Component Types
**Impact: HIGH (Type-safe, flexible component interfaces)**
Proper typing is essential for creating flexible, customizable, and type-safe component interfaces.
Each exported component should wrap a single HTML or JSX element:
**Incorrect: hard to customize**
```tsx
const Card = ({ title, description, footer, ...props }) => (
);
```
**Correct: composable, each layer customizable**
```tsx
export type CardRootProps = React.ComponentProps<"div"> & {
variant?: "default" | "outlined";
};
export const CardRoot = ({ variant = "default", ...props }: CardRootProps) => (
);
```
Every component should extend native HTML attributes:
**Common HTML Attribute Types:**
```tsx
// Enables type extraction
import type { CardRootProps } from "@/components/ui/card";
type Variant = CardRootProps["variant"];
// Enables extending
export type ExtendedCardProps = CardRootProps & { isLoading?: boolean };
// Enables wrapper components
const MyCard = (props: CardRootProps) => (
Props`.
**1. Always Spread Props Last:**
```tsx
// ✅ User props override defaults
// ❌ Defaults override user props
```
**2. Avoid Prop Name Conflicts:**
```tsx
// ❌ Conflicts with HTML title attribute
type CardProps = React.ComponentProps<"div"> & { title: string };
// ✅ Use a different name
type CardProps = React.ComponentProps<"div"> & { heading: string };
```
**3. Document Custom Props:**
```tsx
type PolymorphicProps = {
as?: E;
} & React.ComponentPropsWithoutRef;
function Component({
as,
...props
}: PolymorphicProps) {
const Element = as || "div";
return ` |
| Type extraction | Get specific prop type | `CardProps['variant']` |
| Type extension | Extend existing component props | `CardProps & { isLoading?: boolean }` |
---
## 8. Polymorphism
**Impact: MEDIUM**
Implementing the `as` prop pattern to change rendered HTML
elements while preserving component functionality.
### 8.1 Polymorphism Patterns
**Impact: MEDIUM (Flexible element rendering)**
Build flexible components that can render as different HTML elements or components while maintaining consistent styling and behavior.
The `as` prop allows components to change their rendered element type:
**Typography Components:**
```tsx
function Text({ as: Element = 'span', variant = 'body', ...props }) {
const className = cn(
'text-base',
variant === 'heading' && 'text-2xl font-bold',
variant === 'body' && 'text-base',
props.className
);
return Title
Paragraph
```
**Layout Components:**
```tsx
function Flex({ as: Element = 'div', ...props }) {
return Nested Invalid Valid
;
return
;
function Parent() {
return
Details
Review the details before continuing.
;
```
`render` merges the trigger behavior onto the custom host. Do not put a second button inside a trigger. Keep the shared primitive responsible for keyboard behavior, disabled state, ARIA and focus restoration.
#### Forward Props and Ref
A custom render component must spread the received props and forward its ref to the same DOM node. React 19 components can receive `ref` as a prop:
```tsx
import * as React from "react";
import { DialogTrigger } from "@asym/ui/components/shadcn/dialog";
function ActionButton({
ref,
type = "button",
...props
}: React.ComponentPropsWithRef<"button">) {
return
Settings
;
);
};
```
**Consumer styles from outside:**
```tsx
```
Give components stable identifiers for parent targeting:
**Incorrect:**
```tsx
data-slot="input" // Too generic
data-slot="blueButton" // Includes styling
data-slot="div-wrapper" // Implementation detail
```
**Correct:**
```tsx
const Button = ({
variant = "primary",
size = "md",
loading,
disabled,
className,
...props
}: ButtonProps) => {
return (
;
export const Button = ({ className, variant, size, ...props }: ButtonProps) => {
return (
` for TypeScript types
- Always merge with `className` prop using `cn`
**1. Extract Repeated Patterns:**
```tsx
export const focusRing = 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500';
export const disabled = 'disabled:pointer-events-none disabled:opacity-50';
className={cn(focusRing, disabled, className)}
```
**2. Use CSS Variables for Dynamic Values:**
**Incorrect:**
```tsx
// Dynamic class generation (not detected by Tailwind)
```
**Correct:**
```tsx
// CSS variables
```
**3. Document Variants:**
```tsx
type ButtonProps = {
/** The visual style @default "default" */
variant?: "default" | "destructive" | "outline" | "ghost";
/** The size @default "default" */
size?: "sm" | "default" | "lg" | "icon";
};
```
**State-Based Styling:**
```tsx
```
**CVA with Additional Conditionals:**
```tsx
```
---
## 12. Design Tokens
**Impact: MEDIUM**
CSS variables for theming, color schemes, and consistent design
system values across components.
### 12.1 Design Tokens
**Impact: MEDIUM (Flexible theming and consistency)**
Use semantic design tokens instead of hardcoded colors. Design tokens separate what something is from how it looks.
**Base Tokens:**
- `--background` - Main page background
- `--foreground` - Primary text color
- `--muted` - Subtle backgrounds
- `--muted-foreground` - Text on muted
- `--border` - Border colors
- `--ring` - Focus ring
**Semantic Tokens:**
- `--primary` / `--primary-foreground`
- `--secondary` / `--secondary-foreground`
- `--destructive` / `--destructive-foreground`
- `--accent` / `--accent-foreground`
**Correct: semantic tokens**
```tsx
Click me
```
**Incorrect: hardcoded colors**
```tsx
// Before
Content
// After
Content
```
Override tokens in `.dark` class:
Components automatically adapt because they reference tokens.
Use `oklch()` for better color manipulation:
1. **Never hardcode colors** - Always use design tokens
2. **Use semantic names** - `--primary`, not `--blue-600`
3. **Keep tokens minimal** - Start with base set, add when needed
4. **Document token purpose** - Add comments
5. **Test theme switching** - Ensure all components work in light/dark
6. **Maintain contrast** - Ensure WCAG contrast ratios
---
## 13. Documentation
**Impact: MEDIUM**
Documenting components with JSDoc, usage examples, accessibility
notes, and prop descriptions.
### 13.1 Component Documentation
**Impact: MEDIUM (Adoption and developer experience)**
Create documentation that makes components accessible and easy to use.
Brief introduction explaining what the component does:
Include live demos with code:
Clear, copy-paste ready instructions:
List key capabilities:
Show variants, states, and advanced usage:
Document all props:
Document a11y features:
Track versions:
**Use Real-World Examples:**
```tsx
// ✅ Real-world
function UserProfile({ user }) {
return (
{user.name}
editUser(user.id)}>Edit Profile
);
}
// ❌ Too abstract
Button ;
```
**Include Troubleshooting:**
```markdown
## Troubleshooting
**Button not responding:**
- Ensure `onClick` handler is provided
- Check if `disabled` is set
- Verify no parent is capturing events
```
**Link Related Components:**
```markdown
## Related
- [`IconButton`](/components/icon-button)
- [`ButtonGroup`](/components/button-group)
```
**Make Examples Runnable:**
```tsx
// ✅ Complete, runnable
import { Button } from "@/components/ui/button";
import { useState } from "react";
export function CounterButton() {
const [count, setCount] = useState(0);
return setCount(count + 1)}>Count: {count} ;
}
```
- [ ] Clear overview
- [ ] Live demo
- [ ] Installation instructions
- [ ] Feature list
- [ ] Multiple examples
- [ ] Complete API reference
- [ ] Accessibility docs
- [ ] Changelog
- [ ] Troubleshooting
- [ ] Related components
- [ ] All examples runnable
---
## 14. Registry
**Impact: LOW**
Component registry structure and schema for distributing
components via registries like shadcn/ui.
### 14.1 Component Registries
**Impact: LOW (Source code distribution)**
Registries distribute **source code**, not compiled packages. This enables true component ownership and customization.
**Bad:**
```typescript
// Traditional npm - compiled dependency
import { Button } from "some-ui-library";
```
**Good:**
```typescript
// Registry-based - source code in your project
import { Button } from "@/components/ui/button";
```
**Bad:**
```json
{
"name": "announcement",
"type": "registry:component",
"description": "A compound badge component"
// Missing dependencies, registryDependencies, files, and category
}
```
**Good:**
```json
{
"name": "announcement",
"type": "registry:component",
"description": "A compound badge component",
"dependencies": ["class-variance-authority", "lucide-react"],
"registryDependencies": ["badge"],
"files": [
{
"type": "registry:component",
"path": "announcement.tsx",
"content": "..."
}
],
"category": "ui"
}
```
**1. Create structure:**
```typescript
my-component/
├── public/
│ └── metric-card.json
└── vercel.json
```
**2. Configure headers (`vercel.json`):**
**Example:**
```json
{
"headers": [
{
"source": "/(.*).json",
"headers": [
{ "key": "Access-Control-Allow-Origin", "value": "*" },
{ "key": "Content-Type", "value": "application/json" }
]
}
]
}
```
**3. Deploy:**
**Example:**
```bash
vercel --prod
```
**4. Users install via:**
**Example:**
```bash
npx shadcn@latest add https://your-project.vercel.app/metric-card.json
```
**Example:**
```json
{
"name": "metric-card",
"type": "registry:component",
"description": "Display metrics with icon and trend",
"dependencies": ["lucide-react"],
"registryDependencies": ["card"],
"files": [
{
"type": "registry:component",
"path": "metric-card.tsx",
"content": "import { Card } from '@/components/ui/card'\n\nexport function MetricCard({ title, value }) {\n return {title} {value}