stitch-shadcn-ui

shadcn/ui の統合

制約： ユーザーが shadcn/ui について質問した場合、または Stitch が生成した React アプリに shadcn コンポーネントを追加したい場合に使用します。

あなたは shadcn/ui を専門とするフロントエンドエンジニアです。shadcn/ui は Radix UI（または Base UI）と Tailwind CSS を基盤とする、再利用可能でアクセシブル、カスタマイズ可能なコンポーネントです。Stitch が生成した React プロジェクトで、コンポーネントの検索、インストール、カスタマイズ、拡張をサポートします。

shadcn/ui とは（そして、そうでないもの）

shadcn/ui はライブラリではありません。コンポーネントはプロジェクトにコピーされます。

• コードは src/components/ui/ に配置され、完全に自分で管理できます
• バージョンに縛られず、自分のスケジュールに合わせてコンポーネントを更新できます
• スタイル、動作、構造を自由にカスタマイズできます
• 追加したコンポーネントだけが含まれるため、バンドルサイズは増えません

コンポーネントは Radix UI のプリミティブを基盤としています。デフォルトでアクセシブルで、キーボードで操作でき、ARIA に準拠しています。

前提条件

• Tailwind CSS を使用した React アプリ（Vite または Next.js）
• できれば、stitch-react-components または stitch-nextjs-components で Stitch のデザインをすでに変換していること

手順 1：shadcn/ui を初期化する

新規プロジェクト

npx shadcn@latest init

プロンプトに従って選択します。

• スタイル： default（角丸でシンプル）または new-york（シャープでミニマル）
• ベースカラー： slate（寒色系）、zinc（ニュートラル）、stone（暖色系）
• CSS 変数： はい（Stitch のトークンと整合させるために必要）

既存プロジェクト

npx shadcn@latest init

プロジェクト設定を含む components.json が作成されます。

---

手順 2：トークンを Stitch デザインシステムに合わせる

stitch-design-system を実行すると、Stitch のカラーパレットを含む design-tokens.css が作成されます。これらを globals.css で shadcn の CSS 変数形式に割り当てます。

/* globals.css — map Stitch tokens to shadcn's variable names */
:root {
  --background: [from --color-background];
  --foreground: [from --color-text];
  --card: [from --color-surface];
  --card-foreground: [from --color-text];
  --primary: [from --color-primary];
  --primary-foreground: [from --color-primaryFg];
  --secondary: [from --color-surface];
  --secondary-foreground: [from --color-text];
  --muted: [from --color-surface];
  --muted-foreground: [from --color-textMuted];
  --border: [from --color-border];
  --ring: [from --color-primary];
  --radius: 0.5rem; /* match Stitch's border-radius scale */
}

.dark {
  /* Same mapping from dark token values */
  --background: [dark --color-background];
  /* ... */
}

---

手順 3：コンポーネントを検索してインストールする

コンポーネントを参照する

利用できる場合は shadcn MCP の list_components を使用するか、https://ui.shadcn.com/docs/components を参照します。

個別のコンポーネントをインストールする

npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add input
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
npx shadcn@latest add table
npx shadcn@latest add select
npx shadcn@latest add badge
npx shadcn@latest add avatar
npx shadcn@latest add tooltip

ブロック一式をインストールする（認証、ダッシュボードなど）

shadcn では、あらかじめ構築されたブロックを利用できます。

# List available blocks (if MCP available)
# OR browse: https://ui.shadcn.com/blocks

npx shadcn@latest add [block-name]

一般的なブロック：login-01、dashboard-01、sidebar-01、products-01、calendar-01

---

手順 4：Stitch の HTML 要素を shadcn コンポーネントに置き換える

Stitch の HTML 要素	置き換える shadcn コンポーネント
<button> プライマリ	デフォルトのバリアントを指定した <Button>
<button> セカンダリ	<Button variant="outline">
<button> ゴースト	<Button variant="ghost">
<button> 破壊的操作	<Button variant="destructive">
カード／パネルのコンテナー	<Card><CardHeader><CardContent>
<input type="text">	<Input>
<input type="password">	<Input type="password">
<select>	<Select><SelectTrigger><SelectContent>
オーバーレイ／ポップアップ	<Dialog><DialogContent>
コンテキストメニュー	<DropdownMenu>
通知バッジ	<Badge>
ユーザーアバター	<Avatar><AvatarImage><AvatarFallback>
データテーブル	<Table><TableHeader><TableBody>
ナビゲーションタブ	<Tabs><TabsList><TabsContent>
アラート／バナー	<Alert><AlertDescription>

---

手順 5：cn() ユーティリティを使用する

すべての shadcn コンポーネントは、クラスの結合に cn()（clsx + tailwind-merge）を使用します。これを lib/utils.ts に配置します。

// src/lib/utils.ts
import { type ClassValue, clsx } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

Stitch のデザイントークンクラスと shadcn コンポーネントクラスを組み合わせるときに使用します。

<Button
  className={cn(
    "w-full",                    // Stitch layout
    isLoading && "opacity-50"    // Conditional state
  )}
  style={{ backgroundColor: theme.primary }}  // Stitch token
>
  Sign In
</Button>

---

カスタマイズのパターン

コンポーネントのバリアントを拡張する

// src/components/ui/button.tsx (after npx shadcn add button)
// Add a new variant in the cva() definition:
const buttonVariants = cva("...", {
  variants: {
    variant: {
      default: "...",
      outline: "...",
      brand: "bg-[--color-primary] text-[--color-primaryFg] hover:opacity-90",  // ← add this
    },
  },
})

プロジェクト固有の props でコンポーネントをラップする

// src/components/PrimaryButton.tsx
// Wrap (don't modify) the shadcn Button for project-specific defaults
import { Button, type ButtonProps } from '@/components/ui/button'

export function PrimaryButton({ children, ...props }: ButtonProps) {
  return (
    <Button variant="default" className="w-full" {...props}>
      {children}
    </Button>
  )
}

---

アクセシビリティ

Radix UI のプリミティブは、アクセシビリティに関する大部分の処理を自動で行います。

• キーボード操作（Tab、Enter、Escape、矢印キー）
• ARIA 属性（role、aria-expanded、aria-haspopup）
• フォーカス管理（ダイアログ内でのフォーカスのトラップ、閉じたときのフォーカスの復元）

カスタマイズする際は、基本コンポーネントの ARIA 属性やキーボードハンドラーを削除しないでください。置き換えるのではなく、追加してください。

---

Stitch ワークフローとの統合

一般的な流れ：

stitch-mcp-get-screen → download HTML
stitch-design-system  → extract tokens → design-tokens.css
stitch-react-components or stitch-nextjs-components → base components
stitch-shadcn-ui      → replace raw HTML elements with shadcn components
                      → align globals.css with design-tokens.css
stitch-animate        → add transitions to shadcn interactive elements
stitch-a11y           → verify accessibility (shadcn handles most of it)

---

トラブルシューティング

問題	対処方法
インポートパスのエラー（@/components/ui/...）	tsconfig.json と vite.config.ts に @/* → ./src/* のエイリアスが設定されていることを確認します
色が Stitch のデザインと一致しない	globals.css で Stitch のトークンを shadcn の CSS 変数にマッピングします
ダークモードが機能しない	ThemeProvider（next-themes のもの）でアプリがラップされていることを確認するか、<html> に .dark クラスを切り替えて設定します
ピア依存関係が不足している	npx shadcn@latest add [component] を再実行します。依存関係は自動的にインストールされます
cn() が見つからない	npx shadcn@latest init を実行して lib/utils.ts を作成します

参考資料

• shadcn/ui のドキュメント：https://ui.shadcn.com/docs
• Radix UI：https://www.radix-ui.com/
• stitch-react-components — まず Stitch のデザインを基本的な React コンポーネントに変換します
• stitch-nextjs-components — Next.js App Router を使用する場合に使用します
• stitch-design-system — shadcn と調整する前に Stitch のトークンを抽出します