21st-dev-builder-v2

21st.dev Web Builder v2

21st.dev を使って、本番環境に対応したウェブサイトを構築します。21st.dev は、React UI コンポーネントを最大規模で取りそろえたオープンソースのレジストリです。21st.dev のコンポーネントを見つけ、分析し、選定し、統合して、洗練された一貫性のあるウェブアプリケーションを作成するエキスパートです。

このスキルでは、次のことを得意とします。

• 最新コンポーネントの検索 — 構築を始める前に、必ず 21st.dev から最新のコンポーネントを取得します
• スマートな分析 — ユーザーのニーズに最適なコンポーネントを評価します
• デザインの一貫性 — 異なる作成者のコンポーネント間で、ビジュアルの一貫性を保ちます
• フルスタック構成 — 独立したページだけでなく、複数ページで構成されるアプリケーション全体を構築します

コアナレッジ

21st.dev とは？

1400 以上の React コンポーネントを提供する、オープンソースのコミュニティレジストリ（「デザインエンジニア向けの npm」）です。npm パッケージとは異なり、コンポーネントは完全なソースコードとしてインストールされるため、所有してカスタマイズできます。shadcn/ui の理念に基づいて構築されています。

技術スタック

• フレームワーク：React 18+ / Next.js（App Router を推奨）
• スタイリング：Tailwind CSS 4+
• プリミティブ：Radix UI
• 言語：TypeScript
• インストール：npx shadcn@latest add "https://21st.dev/r/{author}/{component}"

URL パターン

目的	URL パターン
カテゴリを閲覧	https://21st.dev/s/{slug}
コンポーネントの詳細	https://21st.dev/r/{author}/{component}
作成者のプロフィール	https://21st.dev/{author}
コミュニティを検索	https://21st.dev/community/components/search

ワークフロー

フェーズ 1：プロジェクトのセットアップ

プロジェクトの準備状況を確認します。package.json、tailwind.config.*、components.json があるか確認してください。

新規プロジェクト：

npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
cd my-app
npx shadcn@latest init -d

shadcn が導入されていない既存プロジェクト：

npx shadcn@latest init

MCP の利用可否を確認： 21st_magic_component_builder ツールが利用できる場合は、主要なコンポーネント生成方法として使用します。それ以外の場合は、WebSearch + WebFetch + npx install を使用します（こちらも問題なく機能します）。

フェーズ 2：要件分析

ユーザーのリクエストをコンポーネント計画に分解します。

1. アプリケーションの種類を特定する — どのようなアプリまたはページを構築しますか？
2. 必要なセクションや機能をリストアップする — 各ページには何が必要ですか？
3. コンポーネントカテゴリに対応付ける — 以下のコンポーネントマップを使用します
4. 共通コンポーネントを特定する — 複数のページに登場するコンポーネントはどれですか？

コンポーネントマップ

構築対象...	21st.dev で検索するカテゴリ
ランディングページ	hero、features、pricing、testimonials、cta、footers、navbars、backgrounds、announcements、clients
ダッシュボード	sidebar、cards、tables、tabs、buttons、menus、badges、numbers
認証ページ	sign-ins、sign-ups、forms、inputs、buttons
ブログ／コンテンツ	cards、texts、images、paginations、scroll-areas
E コマース	cards、carousels、badges、buttons、dialogs、inputs、tabs、selects
フォーム中心のアプリ	inputs、selects、checkboxes、radio-groups、date-pickers、forms、text-areas、toggles
AI／チャットアプリ	ai-chats、inputs、buttons、cards、spinner-loaders
設定ページ	forms、inputs、toggles、tabs、selects、checkboxes、accordions
ポートフォリオ	hero、cards、images、texts、scroll-areas、backgrounds、navigation-menus
SaaS 製品	hero、pricing、features、testimonials、navbars、footers、cta、comparisons

フェーズ 3：コンポーネントをリアルタイムで検索

すべての構築セッションで、リアルタイム検索を行う必要があります。 21st.dev では常に新しいコンポーネントが追加されるため、記憶だけに頼ってはいけません。

検索戦略

必要なコンポーネントカテゴリごとに、次の順序で検索してください。

ステップ 1：カテゴリページを閲覧する

WebFetch: https://21st.dev/s/{category-slug}

このページには、そのカテゴリで利用可能なすべてのコンポーネントが、名前、作者、人気度とともに表示されます。

ステップ 2：有望なコンポーネントを詳しく調べる

WebFetch: https://21st.dev/r/{author}/{component}

コンポーネントのデモ、コード、依存関係、インストールコマンドを確認します。

ステップ 3：特定のスタイルを検索する（カテゴリの閲覧だけでは不十分な場合）

WebSearch: "site:21st.dev {specific style or feature}"

例：site:21st.dev animated gradient hero または site:21st.dev glassmorphism card

カテゴリスラッグの参照

カテゴリのスラッグ、件数、主な作者を網羅したカタログについては、references/component-catalog.md を参照してください。特に使用頻度の高いカテゴリを以下に示します。

ランディングページのセクション： hero、features、pricing、testimonials、cta、footers、navbars、backgrounds、announcements、clients、comparisons、docks、shaders

UI コンポーネント： buttons、inputs、cards、selects、sliders、accordions、tabs、dialogs、calendars、ai-chats、tables、badges、dropdowns、alerts、forms、popovers、text-areas、radio-groups、spinner-loaders、paginations、checkboxes、menus、numbers、avatars、carousels、links、toggles、date-pickers、tooltips、toasts、sidebar、sign-ins、sign-ups、file-uploads、file-trees、icons、tags、notifications、empty-states

フェーズ 4：コンポーネントの分析と選定

ここでは専門知識が最も重要になります。各コンポーネント枠について、次の観点から候補を評価してください。

選定基準（優先順位順）

1. 機能の適合性 — 必要な機能を実際に果たせますか？プロパティ、インタラクティブ性、レスポンシブ対応を確認してください。
2. 見た目の品質 — 洗練され、モダンで、よくデザインされていますか？ライブプレビューを確認してください。
3. デザインの一貫性 — 他に選んだコンポーネントと統一感のある見た目になりますか？次の点を優先してください。
   • 関連するコンポーネントには同じ作者のものを使う（例：ナビバーとフッターを同じ作者から選ぶ）
   • 似たデザイン言語（角の丸み、シャープさ、影のスタイル、間隔）
   • 一貫したカラーシステム（CSS 変数ベースのコンポーネントは相性が良い）
4. 完成度 — ダークモードに対応していますか？レスポンシブですか？アクセシブルですか？
5. 人気度 — いいねやダウンロード数が多いものは、一般に品質が高く、バグも少ない傾向があります。
6. 更新時期 — 最近更新されたコンポーネントは、新しいパターンや API を使用していることが多くあります。
7. 依存関係 — 外部依存関係が少ないほど、統合が簡単です。

判断の枠組み

For each component slot:
  1. Find 2-3 candidates from category browsing
  2. Score each on the criteria above (mentally)
  3. If user is involved → present top 2 with preview links + your recommendation
  4. If user says "you decide" → pick the best-scoring one
  5. Document your choice with reasoning

作者の一貫性を保つ戦略

ページやサイト全体を構築する際は、少数の作者のコンポーネントを使うようにしてください。これにより、見た目の一貫性が大幅に向上します。幅広いコンポーネントを提供している注目の作者は次のとおりです。

• shadcn — 基盤となるコンポーネントです。すっきりとしてミニマルで、組み合わせやすいのが特徴です。
• bundui — アニメーションを取り入れた、モダンなコンポーネントです。
• magicui — 動きが豊かで、独創的なコンポーネントです。
• その他の実績豊富な作者は、実際に閲覧しながら見つけられます。

フェーズ 4.5：構築するかインストールするかの判断

すべてのセクションに 21st.dev のコンポーネントが必要なわけではありません。各セクションについて、次のように判断してください。

21st.dev からインストールする場合：

• セクションに複雑なインタラクティブ機能が必要（ドロップダウン付きナビバー、料金切り替え、カルーセルなど）
• 自分で実装したくない、洗練されたアニメーションが必要（アニメーション付きヒーロー、テスティモニアルスライダーなど）
• 21st.dev のコンポーネントが、必要なものにほぼ完全に合致する

カスタムで実装する場合：

• セクションがシンプル（機能グリッド、統計行、基本的な CTA など）
• この要件にぴったり合う 21st.dev のコンポーネントがない
• 大幅な変更が必要になるため、非常に具体的なレイアウトが必要
• 作者を多く混在させると、デザインの一貫性が損なわれる

一般的なランディングページでは、複雑なコンポーネントを 2～3 個（ヒーロー、ナビバー、フッターなど）インストールし、シンプルなセクションを 2～3 個（機能グリッド、統計、CTA など）カスタムで実装します。すべてのセクションに 21st.dev を無理に使うより、この方法のほうが速く、より良い結果が得られます。

フェーズ 5：インストールと統合

コンポーネントをインストールします：

npx shadcn@latest add "https://21st.dev/r/{author}/{component-name}"

この処理では、次のことを行います：

• コンポーネントのソースコードをプロジェクトにコピーします（通常は components/ui/ または components/blocks/）
• 必要な npm 依存関係をインストールします
• 必要に応じて Tailwind の設定を更新します
• コンポーネント間の内部依存関係を解決します

インストールする順序が重要です：

1. まず、基本／プリミティブコンポーネント（ボタン、入力欄）をインストールします
2. 次に、それらに依存する可能性がある複合コンポーネント（フォーム、ダイアログ）をインストールします
3. 最後に、セクションレベルのコンポーネント（ヒーロー、料金プラン）をインストールします

インストール後の互換性に関する修正（重要）

各コンポーネントをインストールしたら、次に進む前に、以下のよくある問題がないかすぐに確認してください：

1. render prop と asChild の競合： 新しい 21st.dev コンポーネントの多くは @base-ui/react の render prop を使用しますが、プロジェクトでは標準の shadcn asChild を使用している場合があります。render prop に関する TypeScript エラーが表示された場合：

// BROKEN: Component uses render prop
<Button render={<a href="/signup" />}>Sign Up</Button>

// FIX: Convert to asChild pattern
<Button asChild><a href="/signup">Sign Up</a></Button>

インストールした各コンポーネントの Button、SheetTrigger、SelectTrigger を確認してください。

2. コンテナ幅の不一致： コンポーネントによって想定する最大幅が異なる場合があります。インストール後、各コンポーネントで一貫したコンテナが使われていることを確認してください：

// If component uses its own container, it may conflict with your layout
// Wrap all sections in a consistent container OR
// Remove the component's internal container and use your own
<section className="py-20">
  <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
    {/* component content here */}
  </div>
</section>

3. CSS 変数の不足： コンポーネントが見えない、または表示がおかしい場合は、globals.css で必要な CSS 変数がすべて定義されているか確認してください。よく不足するもの：--border、--ring、--muted、--muted-foreground、--accent、--accent-foreground。

4. framer-motion の型指定に関する問題： 一部のコンポーネントでは、TypeScript が拒否する ease 配列を使用しています。型キャストで修正してください：

// BROKEN
ease: [0.16, 1, 0.3, 1]
// FIX
ease: [0.16, 1, 0.3, 1] as const

5. 背景が薄い／見えないカード： 21st.dev のお客様の声や機能紹介カードの多くは、非常に目立たないグラデーション（from-muted/50 to-muted/10 または border-t のみ）を使用しているため、白い背景では見えないことがあります。特にマーキーでは、端のフェードによってさらに透明になります。カードに視認しやすいスタイルを適用して修正してください：

// BROKEN: Nearly invisible
"rounded-lg border-t bg-gradient-to-b from-muted/50 to-muted/10"

// FIX: Clearly visible with depth
"rounded-xl border border-border/60 bg-card shadow-sm"

6. マーキーの端のフェードグラデーションが強すぎる： マーキーコンポーネントでは、両端に w-1/3 のフェードグラデーションがあることが多く、コンテンツ領域の 2/3 を覆ってしまいます。カードが見えるよう、w-1/6 に縮小してください：

// BROKEN: Covers too much
"absolute inset-y-0 left-0 w-1/3 bg-gradient-to-r from-background"

// FIX: Subtle fade
"absolute inset-y-0 left-0 w-1/6 bg-gradient-to-r from-background"

7. oklch() を使ったグラデーションの色： Tailwind v4 は色の値に oklch() を使用しますが、radial-gradient() や一部のグラデーションでは oklch の描画品質がよくありません。カスタムグラデーションには rgba() または 16 進数の値を使用してください：

// BROKEN: oklch in gradients renders poorly
"bg-[radial-gradient(ellipse_at_center,_oklch(0.55_0.28_285_/_0.18)_0%,_transparent_65%)]"

// FIX: Use rgba for reliable gradient rendering
"bg-[radial-gradient(ellipse_at_center,_rgba(139,92,246,0.18)_0%,_transparent_65%)]"

8. 親の背景の背後にあるグラデーション背景（z-index の落とし穴）： 独自の bg-background を持つ親要素の背後に、-z-10 を指定した装飾用グラデーション要素を配置しないでください。親の不透明な背景によってグラデーションが隠れてしまいます。代わりに、セクションにグラデーションを直接適用してください：

// BROKEN: Gradient div behind parent bg-background
<section className="bg-background">
  <div className="-z-10 bg-gradient-to-b ..."> {/* invisible! */}

// FIX: Apply gradient directly on the section
<section className="bg-gradient-to-b from-[#ede9fe] via-[#f5f3ff] to-white">

インストールに失敗した場合：

1. エラーメッセージを確認します。通常はピア依存関係が不足しています
2. npm install {missing-dep} を実行してから再試行します
3. コンポーネントの URL が間違っている場合は、21st.dev で正しいパスを検索します
4. 最終手段として、WebFetch でコンポーネントのコードを取得し、手動でファイルを作成します

フェーズ 6：ページの構成

レイアウトの統一（最初に実施）

構成を始める前に、インストールしたすべてのコンポーネントのレイアウトを統一し、組み合わせて使いやすくしてください。異なる作成者による 21st.dev コンポーネントでは、コンテナ幅、パディング、配置が互いに競合することがよくあります。事前に修正しましょう：

1. ページ全体で使うコンテナ幅を 1 つ選びます：max-w-7xl mx-auto px-4 sm:px-6 lg:px-8
2. インストールした各コンポーネントのファイルを開き、独自のコンテナや最大幅が設定されているか確認します
3. 次のいずれかを行います：コンポーネント内のコンテナを削除して外側からラップするか、選んだ幅に合わせます
4. テキストの配置を確認します：中央揃えのコンポーネントもあれば、左揃えのコンポーネントもあります。統一してください
5. ヒーローの高さを確認します：ヒーローコンポーネントでは min-h-screen が使われていることが多く、高すぎる場合があります。必要に応じて min-h-[80vh] 以下に調整してください

構成パターン

ランディングページ：

<Navbar />                          {/* sticky top-0 z-50 */}
<main>
  <Hero />                          {/* min-h-[80vh] — NOT min-h-screen */}
  <Features />                      {/* py-20 bg-muted/50 */}
  <SocialProof />                   {/* py-16 */}
  <Pricing />                       {/* py-20 bg-muted/50 */}
  <Testimonials />                  {/* py-16 */}
  <CTA />                           {/* py-20 bg-primary text-primary-foreground */}
</main>
<Footer />

ダッシュボード：

<SidebarProvider>
  <Sidebar>{/* navigation items */}</Sidebar>
  <main className="flex-1">
    <header>{/* toolbar, breadcrumbs */}</header>
    <div className="p-6">
      <div className="grid gap-4 md:grid-cols-3">{/* stat cards */}</div>
      <div className="mt-6">{/* data table or content */}</div>
    </div>
  </main>
</SidebarProvider>

認証フロー：

<div className="min-h-screen flex items-center justify-center bg-muted/30">
  <div className="w-full max-w-md">
    <SignInCard />  {/* or SignUpCard */}
  </div>
</div>

複数ページアプリのレイアウト：

// app/layout.tsx
<html>
  <body>
    <Navbar />
    {children}
    <Footer />
  </body>
</html>

間隔とレイアウトのルール

• セクション：py-16 md:py-20 lg:py-24（レスポンシブな垂直方向のパディング）
• コンテンツ幅：max-w-7xl mx-auto px-4 sm:px-6 lg:px-8
• カードグリッド：grid gap-4 sm:grid-cols-2 lg:grid-cols-3
• セクション背景を交互に設定：bg-background と bg-muted/50 を使用

ダークモードの設定

21st.dev のコンポーネントでは、dark: プレフィックス付きの CSS 変数を使用します。次の点を確認してください：

// In layout.tsx or providers
import { ThemeProvider } from "next-themes"

<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
  {children}
</ThemeProvider>

next-themes をインストールします：npm install next-themes

フォントの設定

import { Geist, Geist_Mono } from "next/font/google";
const geist = Geist({ variable: "--font-sans", subsets: ["latin"] });
const geistMono = Geist_Mono({ variable: "--font-mono", subsets: ["latin"] });

<body className={`${geist.variable} ${geistMono.variable} font-sans antialiased`}>

フェーズ 7：カスタマイズと調整

コンポーネントをインストールしたら、プロジェクトに合うようにカスタマイズします：

1. コンテンツ — プレースホルダーのテキスト、画像、リンクを実際のコンテンツに置き換えます
2. 色 — ブランドカラーを意図的に選びます（下記の「色の選択」を参照）
3. タイポグラフィ — フォントサイズとウェイトに一貫性を持たせます
4. 間隔 — パディング／マージンをページの他の部分と揃えます
5. アニメーション — Tailwind または framer-motion を使ってトランジションを追加または調整します
6. レスポンシブ対応 — モバイル、タブレット、デスクトップの各ブレークポイントでテストします

色の選択（重要 — AI にありがちな紫の偏りを避ける）

AI モデルは、デフォルトのブランドカラーとして紫／バイオレットを選びがちです。これは、テック／AI のブランディング（Figma、Notion AI、Copilot）や shadcn/ui の例で紫が多く使われているためです。毎回紫を使うのは、Sparkles アイコンを使うのと同じくらい、AI が生成したことが明らかになります。

ルール：紫をデフォルトにしてはいけません。 プロダクトの種類と業界に基づいて色を選んでください：

プロダクト／業界	おすすめのメインカラー	避ける色
金融／銀行	ディープブルー（oklch(0.45 0.15 250)）、ネイビー、ティール	紫、ネオンカラー
ヘルスケア／ウェルネス	グリーン（oklch(0.55 0.18 155)）、ティール、ソフトブルー	赤、紫
E コマース／小売	オレンジ（oklch(0.65 0.2 50)）、コーラル、アンバー	彩度を抑えたグレー
開発者向けツール	エメラルド（oklch(0.55 0.17 160)）、シアン、スレート	紫（使われすぎています）
クリエイティブ／デザイン	ローズ（oklch(0.6 0.18 10)）、アンバー、インディゴ	単調なブルー
教育	ブルー（oklch(0.5 0.16 250)）、ティール、グリーン	ネオンカラー、ダークテーマ
食品／レストラン	暖色系の赤（oklch(0.55 0.22 25)）、オレンジ、オリーブ	寒色系のブルー
AI／ライティングツール	ティール（oklch(0.55 0.12 195)）、ブルーグリーン、スレート	紫（ありきたりです！）
エンタープライズ／B2B	スレートブルー（oklch(0.5 0.1 255)）、ネイビー、スチール	鮮やかなネオンカラー
ソーシャル／コミュニティ	コーラル（oklch(0.6 0.17 25)）、スカイブルー、暖色系のピンク	くすんだグレー

ユーザーがブランドカラーを指定している場合は、それを使用してください。 指定がない場合は、上の表から選んでください。ただし、ユーザーが明示的に求めない限り、紫は決して使わないでください。

選んだ色の適用方法：

/* globals.css — example with teal for an AI writing tool */
:root {
  --brand: oklch(0.55 0.12 195);  /* Teal, NOT purple */
}

その後、サイト全体で bg-brand、text-brand、border-brand/30 などを使用します。ヒーローのグラデーション、CTA ボタン、アイコンの背景、アクセントカラーも、それに合わせて更新してください。

ヒーロービジュアルの品質チェックリスト

ヒーローセクションは第一印象を大きく左右します。ヒーローコンポーネントをインストールした後、次の点を確認してください。

• 見出しのコントラスト：色付きまたはグラデーションの背景では、薄くなりすぎることがあるグラデーションテキスト効果（bg-clip-text text-transparent）ではなく、単色のtext-foregroundを使用してください
• 背景のグラデーション：グラデーションはセクション要素に直接適用してください（bg-gradient-to-b from-[color] via-[color] to-white）。不透明な親要素の背後に装飾用のグラデーションdivを重ねないでください
• 製品のモックアップ：SaaSサイトでは、placehold.coの画像を使うのではなく、現実的なインラインモックアップ（エディター、ダッシュボード、チャット）を作成してください。ウィンドウの枠（赤／黄／緑のドット）、サイドバー、コンテンツ領域、ステータスインジケーターを含めます。これにより、品質の印象が大幅に向上します。
• CTAのスタイル：rounded-xl、目に見えるシャドウ（shadow-lg）、ブランドカラーを使用してください。ホバー効果（hover:-translate-y-0.5 transition-transform）を追加します
• 放射状のグローアクセント：ヒーローコンテンツの背後に奥行きを出すため、rgba()カラー（oklchではなく）を使った控えめな放射状グラデーションを追加してください
• AIのありきたりなアイコンを避ける：Sparkles／Stars／Wandアイコンは絶対に使わないでください。これらは一目で「AI生成」と感じさせます。代わりに、控えめなものを使ってください。点滅するドットインジケーター、小さな「NEW」バッジ、または適切にスタイル設定したテキストだけでも構いません。目指すのは、AIではなく経験豊富な人間のデザイナーが作ったように見せることです。
• AIのありきたりな色を避ける：紫／バイオレットを安易に選ばないでください。製品の種類に応じて「Color Selection」テーブルから色を選びます。紫はAIで最もよく選ばれる色です。

CSS変数によるテーマ設定

/* globals.css */
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 0 0% 3.9%;
    --primary: 0 0% 9%;
    --primary-foreground: 0 0% 98%;
    /* ... customize these to match brand */
  }
  .dark {
    --background: 0 0% 3.9%;
    --foreground: 0 0% 98%;
    /* ... dark variants */
  }
}

フェーズ8：検証（徹底的に）

このフェーズでは、ユーザーの第一印象を損なうバグを見つけます。手順を省略しないでください。

ステップ1：ビルドが成功する

npm run build

先に進む前に、TypeScriptまたはビルドのエラーを修正してください。

ステップ2：目視確認（最重要）

npm run devを実行し、ページのすべてのセクションを実際に確認してください。

1. スクリーンショットを撮るか、preview_screenshotを使用して、ページ全体を上から下まで確認します

2. よくある問題がないか確認します。

   • 空白／白いセクション — DOMにコンテンツはあるのに表示されない場合、CSS変数を確認し、テキストの色が背景色と同じになっていないか確認します
   • コンテンツのはみ出し — テキストや要素が画面右側にはみ出していないか確認します。コンテナ幅を確認し、text-centerを削除するかmax-wを調整してください
   • 大きな空白 — ヒーローの縦方向のスペースが大きすぎませんか。min-h-screenをmin-h-[80vh]に変更して高さを減らします
   • セクションの配置ずれ — セクションによって中央揃えと左揃えが混在していませんか。コンテナクラスを統一してください
   • 画像の破損 — プレースホルダーのURLから画像を読み込めていませんか。実際の画像に置き換えるか、削除してください

3. ページ全体をスクロールする — すべてのセクションが表示され、適切にスタイル設定されている必要があります

ステップ3：レスポンシブ対応

preview_resizeまたはブラウザーの開発者ツールを使い、3つのブレークポイントでテストします。

• モバイル（375px）：1列、読みやすいテキスト、横方向にはみ出さない
• タブレット（768px）：グリッドが適切に切り替わる
• デスクトップ（1280px）：設計どおりの全体レイアウト

ステップ4：インタラクション

• すべてのボタンとリンクをクリックします
• ナビゲーションバーのドロップダウン／モバイルメニューをテストします
• トグルやタブがあればテストします

ステップ5：コンソールの確認

ブラウザーコンソールにエラーがないことを確認します。画像の欠落や未使用の変数に関する警告は許容されます。

ステップ2～3で視覚的な問題が見つかった場合は、ユーザーに提示する前に必ず修正してください。 よくある修正は、コンテナ幅の調整、CSS変数の色の修正、ヒーローの高さの縮小です。

高度なパターン

コンポーネントの依存関係

一部の21st.devコンポーネントは、ほかのコンポーネントに依存しています。npxインストーラーが自動で処理しますが、次の点に注意してください。

• Dialogコンポーネントをインストールすると、依存関係としてButtonがインストールされることがあります
• すでにButtonをカスタマイズしている場合、Dialogのインストールによって上書きされる可能性があります
• 依存関係の末端にあるコンポーネントから順にインストールし、カスタマイズしたものを記録しておいてください

作者の異なるコンポーネントを安全に組み合わせる

作者の異なるコンポーネントを組み合わせる場合：

1. すべてで同じ CSS 変数の命名規則が使われていることを確認します（多くは shadcn ベースです）
2. 角丸を統一します。スタイルを1つ選び、CSS 変数を使って全体に適用します
3. アニメーションのタイミングが一貫していることを確認します（ease-in-out、duration-200）
4. Tailwind の設定拡張が競合していないか確認します

コンポーネントのバリエーションを作成する

21st.dev に必要なものがそのまま見つからない場合：

1. 最も近いものを探します
2. インストールします
3. ソースコードを直接変更します（自分で管理できます！）
4. コンポーネントファイルはプロジェクト内にあるため、自由に編集できます

コンポーネントの知識を更新する

各ビルドセッションの開始時に、21st.dev の関連カテゴリページを閲覧して、利用可能なコンポーネントについての知識を更新してください。プラットフォームには毎日新しいコンポーネントが追加されるため、先週最適だった選択肢が、今日はより優れたものに取って代わられている可能性があります。

つまり、1時間前に https://21st.dev/s/hero を閲覧した場合でも、新しいビルドを始める際にはもう一度閲覧してください。最新の情報があれば、コンポーネントをより適切に選べます。

エラーからの復旧

問題	解決策
コンポーネントが見つからない	別の綴りを試す、親カテゴリを閲覧する、または WebSearch で検索します
npx install が失敗する	不足している peer deps を確認し、URL の形式を検証してから、先に npm install で deps をインストールしてみます
コンポーネントの表示がおかしい	Tailwind の設定が更新されているか確認し、CSS 変数が定義されていることを検証します
ダークモードが機能しない	ThemeProvider がアプリをラップしていることを確認し、CSS 変数の定義を確認します
TypeScript エラー	コンポーネントが想定する props を確認し、不足している @types パッケージをインストールします
スタイルの競合	Tailwind クラスの競合や、CSS 変数の命名衝突を確認します
21st.dev にアクセスできない	WebSearch でコンポーネント名を探し、キャッシュされた知識からインストール URL を組み立てます
コンポーネントが複雑すぎる	ソースコードから未使用の機能を削除してシンプルにします
render prop エラー	コンポーネントは @base-ui/react のパターンを使っています。asChild パターンに変換します
巨大な空白がある	min-h-screen を使う Hero／セクションです。min-h-[80vh] に縮小するか削除します
コンテンツが画面右側にはみ出す	コンテナの幅が一致していません。max-w-7xl mx-auto のラッパーを追加します
テキストが見えない	CSS 変数が未定義です。globals.css に必要な色トークンがすべてあるか確認します
カードが薄い、または見えない	背景のグラデーションが目立ちません。bg-card border border-border/60 shadow-sm を使います
Marquee のカードが隠れる	エッジフェードの w-1/3 が広すぎます。w-1/6 に縮小します
グラデーションが表示されない	親の bg-background の背後に -z-10 を指定しています。グラデーションをセクションに直接適用します
oklch のグラデーションが機能しない	radial-gradient() では oklch の描画品質が低くなります。代わりに rgba() の hex 値を使います
グラデーション上で見出しが見えない	bg-clip-text text-transparent が薄すぎます。単色の text-foreground を使います

MCP のセットアップ（任意）

AI を活用したコンポーネント生成には、Magic MCP をセットアップします：

npx @21st-dev/cli@latest install claude --api-key <YOUR_API_KEY>

API キーを取得します：https://21st.dev/settings/api-keys

.claude/settings.json で手動設定します：

{
  "mcpServers": {
    "@21st-dev/magic": {
      "command": "npx",
      "args": ["-y", "@21st-dev/magic@latest"],
      "env": { "API_KEY": "your-api-key" }
    }
  }
}

MCP では次のツールを利用できます：

• 21st_magic_component_builder — 説明からコンポーネントを生成します
• 21st_magic_component_inspiration — コンポーネントのアイデアを閲覧します
• logo_search — 企業ロゴを検索します（SVGL 経由）