shadcn

Shadcn UI 開発者ガイド

このスキルでは、このプロジェクトで shadcn/ui コンポーネントを扱うためのガイドライン、パターン、ベストプラクティスを紹介します。

クイックスタート

1. コアパターン：スタイル設定、テーマ設定、コンポーネントのパターンを詳しく知るには、references/patterns.md を読んでください。
2. Tailwind の統合：Tailwind CSS のパターンについては、tailwindcss スキルを使用してください。

基本理念

• 所有権：Shadcn は依存関係ではなく、コピーして使うものです。コードは自分で所有します。
• カスタマイズ：コンポーネントはニーズに合わせて変更することを前提としています。
• アクセシビリティ：適切なアクセシビリティを実現するため、Radix UI のプリミティブを基盤としています。
• 柔軟性：カスタマイズしやすい Tailwind CSS でスタイルを設定します。

重要：デザイントークンの使用

テーマ切り替えとの互換性を確保するため、必ずデザインシステムのトークンを使用してください。

必須トークン：

• 背景：bg-background、bg-card、bg-muted、bg-popover
• テキスト：text-foreground、text-muted-foreground、text-card-foreground
• 境界線：border-border、border-input、border-ring
• アクション：bg-primary text-primary-foreground、bg-secondary text-secondary-foreground
• 状態：bg-destructive text-destructive-foreground、bg-accent text-accent-foreground

bg-white、text-black、border-gray-200 などの明示的な色は使用しないでください。 テーマ切り替えが機能しなくなります。

よくあるタスク

コンポーネントの追加

CLI を使ってコンポーネントを追加し、必要に応じてカスタマイズします。

npx shadcn@latest add button card dialog

コンポーネントの拡張

アクセシビリティを維持しながら、カスタムのプロパティやバリアントを追加します。

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  loading?: boolean
}

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, loading, children, ...props }, ref) => {
    return (
      <button
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        disabled={loading || props.disabled}
        {...props}
      >
        {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
        {children}
      </button>
    )
  }
)

複合コンポーネント

名前空間付きプロパティではなく、必ず個別にエクスポートしてください。

// CORRECT
export const CardTech = CardTechRoot;
export const CardTechHeader = CardHeader;
export const CardTechTitle = CardTitle;
export const CardTechContent = CardContent;

// WRONG - Do not use
export const CardTech = Object.assign(CardTechRoot, {
  Header: CardHeader,
  Content: CardContent,
});

アクセシビリティの維持

Radix UI のアクセシビリティ属性は削除しないでください。

<Dialog>
  <DialogTrigger asChild>
    <Button>Open Dialog</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Accessible Title</DialogTitle>
      <DialogDescription>
        This description helps screen readers understand the dialog's purpose
      </DialogDescription>
    </DialogHeader>
  </DialogContent>
</Dialog>

テーマ設定

globals.css のすべての色の値に CSS 変数を使用してください。

@layer base {
  :root {
    --success: 142 76% 36%;
    --success-foreground: 355 100% 100%;
  }

  .dark {
    --success: 142 76% 46%;
    --success-foreground: 142 76% 10%;
  }
}

検証チェックリスト

shadcn/ui に関するタスクを完了する前に、以下を確認してください。

• すべての色に明示的な値ではなく、デザイントークンが使われていることを確認します。
• Radix UI のアクセシビリティ属性が維持されていることを確認します。
• キーボード操作が正しく機能することをテストします。
• 複合コンポーネントには、名前空間付きではなく個別のエクスポートを使用します。
• 型チェック（pnpm run typecheck）とテスト（pnpm run test）を実行します。

包括的なパターン、コンポーネントの例、詳細なガイドラインについては、references/patterns.md を読んでください。