ui-design-system

Files (1)

• SKILL.md

SKILL.md (first lines)

# UI Design System — Component Generation & Quality Skill

**Agent:** Designer
**Phase:** Discovery (mockups) and Implementation (component specs)
**Priority:** Load when UI work is involved

---

## IRON LAW

**Every component MUST be accessible, responsive, and token-based. No exceptions.**

If you can't make it accessible, use a headless primitive (Radix UI, React Aria, Reka UI).

---

## Decision Framework: Before Creating Any Component

```
1. Does it already exist in the project's components/ui/?
   → YES: Use it. Compose it. Don't rebuild.
   → NO: Continue.

2. Can existing atoms be composed to achieve this?
   → YES: Compose. Don't abstract.
   → NO: Continue.

3. Will it be used ≥ 3 times?
   → NO: Build inline. Don't abstract prematurely.
   → YES: Continue.

4. Can you define clear variant/size props?
   → NO: It's too complex. Break it down.
   → YES: Create the component.
```

---

## Component Architecture Standard

### The Canonical Component Skeleton (CVA + forwardRef)

This is the **de facto standard** across shadcn/ui, v0.dev, and modern React design systems:

```tsx
import { forwardRef, type ComponentPropsWithoutRef } from "react";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

const componentVariants = cva(
  // Base classes — always applied
  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
      },
      size: {
        sm: "h-8 px-3 text-xs",
        md: "h-10 px-4 py-2",
        lg: "h-12 px-6 text-base",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: { variant: "default", size: "md" },
  }
);

interface ComponentProps
  extends ComponentPropsWithoutRef<"button">,
    VariantProps<typeof componentVariants> {
  isLoading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ComponentProps>(
  ({ className, variant, size, isLoading, children, ...props }, ref) => (
    <button
      ref={ref}
      className={cn(componentVariants({ variant, size }), className)}
      disabled={isLoading || props.disabled}
      {...props}
    >
      {isLoading ? <Spinner className="mr-2 h-4 w-4 animate-spin" /> : null}
      {children}
    </button>
  )
);
Button.displayName = "Button";
```

### Key Rules
- **Always** `forwardRef` — parents need DOM access
- **Always** extend native HTML props (`ComponentPropsWithoutRef<"element">`)
- **Always** use `cn()` to merge classNames — never override
- **Always** set `displayName` for DevTools
- **Composition over configuration** — use `children` and sub-components, not config props

### Compound Component Pattern (Preferred for Complex Components)

```tsx
// GOOD: Composition
<Card>
  <Card.Header><Card.Title>Title</Card.Title></Card.Header>
  <Card.Body>Content</Card.Body>
  <Card.Footer>Actions</Card.Footer>
</Card>

// BAD: Prop explosion
<Card title="Title" content="Content" footerContent="Actions" />
```

---

## Design Tokens Architecture (Three-Tier)

From lshtram/nso, MIT.

More from lshtram/nso