shark-ui

Shark UI

Shark UI は、Ark UI を基盤とするコンポーネントレジストリで、shadcn のような開発者体験（npx shadcn@latest add @shark/<component>）を提供します。

CLI の例は、プロジェクトのパッケージランナー（npx shadcn@latest、pnpm dlx shadcn@latest、または bunx shadcn@latest）で実行してください。packageManager またはチームの規約に合わせます。

このスキルの用途

このスキルは、次の用途に使用します。

• UI タスクに適した Shark のプリミティブを選ぶ
• Shark がラップする Ark UI のパターンに沿って、正しい使用コード（インポート、構成、プロパティ）を記述する
• Shark のドキュメントや例を確認せずに、Radix／shadcn の API を想定することを避ける
• レジストリの例を、コンポーネントの組み合わせ方を知るための主要な参考資料として使用する

原則

1. 既存のコンポーネントを優先します。 カスタム UI を作る前に、Shark のプリミティブと registry/react/examples/ を優先してください。references/component-registry.md を参照してください。
2. 作り直さずに組み合わせます。 設定画面のようなフローでは、ドキュメントにあるパーツ（例：Tabs + Card + Field）を組み合わせます。ダッシュボードでは Sidebar、Table、チャートを使い、リポジトリ内の例に従ってください。
3. カスタムクラスより組み込みのバリアントを優先します。 プリミティブを再スタイリングする前に、variant、size、セマンティックトークンを使用してください（references/rules/styling.md を参照）。
4. セマンティックカラーを使用します。 プロダクト UI では、パレットのユーティリティを直接使うのではなく、bg-primary、text-muted-foreground、border-input を使用してください。

信頼できる情報源

• コンポーネントのドキュメント：content/docs/components/*.mdx
• レジストリの例：registry/react/examples/<component>/example-*.tsx
• 実装：registry/react/components/<component>.tsx
• 公開済みレジストリアイテム：public/r/<name>.json（registry/manifest/<name>.ts からビルド）
• LLM 向けルート：app/(llms)/ と lib/llms.ts
• リポジトリの規約：AGENTS.md

対象外

• ユーザーが明示的に求めない限り、Next.js アプリのルーティング、マーケティングページ、レジストリ以外のアプリコード。
• 明示的な依頼がない限り、生成済みの public/r/*.json を手動で編集すること。

重要なルール

これらのルールは、Shark の出力に常に適用されます。各セクションには、該当する場合、誤った例／正しい例を含む詳細なガイダンスへのリンクがあります。

スタイリングと Tailwind → references/rules/styling.md

• レイアウトには className を使用し、場当たり的な再スタイリングには使わないでください — プリミティブではバリアントとセマンティックトークンを優先します。
• space-x-*／space-y-* は使用しないでください。 flex／grid と gap-* を使用します。
• 幅と高さが同じ場合は size-* を使用します — アイコンや正方形のコントロールには、w-*／h-* の組み合わせよりも優先します。
• truncate の短縮形を使用します — overflow-hidden text-ellipsis whitespace-nowrap は使用しません。
• セマンティックトークンで対応できる場合、手動で dark: のパレットを組み合わせないでください。
• 条件付きクラスや結合したクラスには @/lib/utils の cn() を使用します。
• オーバーレイに z-index を手動で設定しないでください — Dialog、Sheet、Drawer、AlertDialog、Menu、ContextMenu、Popover、Tooltip、HoverCard などが重なり順を管理します。

フォームと入力 → references/rules/forms.md

• フォームのレイアウトには FieldGroup + Field を使用します — div + space-y-* は使用しません。
• グループ内では InputGroup + InputGroupInput／InputGroupTextarea を使用します — Input／Textarea を直接使用しません。
• アドオン — 入力欄の横にアクションを置く場合は、ドキュメントにある InputGroup + InputGroupAddon のパターンを使用します。
• 少数の選択肢（2～7 個） — Button をループしてアクティブ状態を手動でスタイリングするより、ToggleGroup + ToggleGroupItem を優先します。
• チェックボックス／ラジオボタンのグループには FieldSet + FieldLegend を使用します — Field のドキュメントを参照してください。
• バリデーション — Field に invalid を設定すると、コントロールに自動的に渡されます。無効化のパターンについてはフォームガイドを参照してください。

フォームとバリデーション → references/rules/forms.md

コンポーネントの構成と合成 → references/rules/composition.md

• 正しい親の中に項目を配置する — 各プリミティブの構造に従います（例：ドキュメントに記載されているとおり、コレクション／リストのパーツ内にリスト行を配置します）。
• トリガー — Shark のパターンに従い、単一の子要素（Button、a）とともに asChild を使用します。トリガーには render={...} を使用しないでください（references/rules/migration.md を参照）。
• オーバーレイにはタイトルが必要です — アクセシビリティのために DialogTitle、SheetTitle などを使用します。視覚的に非表示にする場合は className="sr-only" を使用します。
• 複合コンポーネント — MDX と同様に、エクスポートされたパーツ（CardHeader、TabsList + TabsTrigger など）を使用します。プリミティブが意図的に最小限の構成でない限り、単一のスロットにまとめないでください。
• TabsList 内の TabsTrigger — Tabs のルート直下にトリガーを配置しないでください。
• Avatar + AvatarFallback — 画像の読み込みに失敗した場合に備えて、必ずフォールバックを指定します。

個別のマークアップではなく、コンポーネントを使用する

• ユースケースがドキュメントに合致する場合は、独自にスタイルを設定した div よりも Alert、Separator、Skeleton、Badge（およびその他のプリミティブ）を優先します。
• トースト — Shark の toast／ドキュメントのパターンに従います。必要な場合を除き、通知 DOM を独自に実装しないでください。

アイコン

• 装飾用アイコンについては、AGENTS.md と references/rules/styling.md に従います（aria-hidden、例に示されたサイズ設定）。
• プロダクトの UI では、同じコンポーネントのレジストリ例と MDX で採用されているアイコンの扱いに合わせます。

Shark 固有のルール（必須）

• Shark または Ark の API を推測で作らないでください。MDX と registry/react/components/<name>.tsx で確認します。
• Combobox（および類似のコンポーネント）：useFilter + useListCollection、collection プロパティ、onInputValueChange からの filter(inputValue)、リスト内の collection.items.map(...) を使用します（AGENTS.md）。
• Select／listbox でコレクションを使用する場合：例と同様に createListCollection／useListCollection を使用します。
• チャート：content={(props) => <ChartTooltipContent {...props} />} を指定した ChartTooltip を使用します。ツールチップのプロパティをスタブ化しないでください。静的プレビューでは、必要に応じて accessibilityLayer={false} を指定できます（AGENTS.md）。
• Sidebar のドキュメントプレビュー：absolute inset-0 overflow-hidden、className="absolute" を指定した Sidebar、SidebarProvider の h-full、ScrollArea がレイアウトを崩す場合はネイティブの overflow-y-auto を使用します（AGENTS.md）。

コンポーネントの確認

一覧と ./references/primitives/<name>.md へのリンクについては、references/component-registry.md を参照してください。

使用ワークフロー

1. 意図を特定します（オーバーレイ、フォーム、コレクションコントロール、チャートなど）。
2. references/component-registry.md と、存在する場合は対象の ./references/primitives/<name>.md を開きます。
3. インストール方法、構造、API、Ark ドキュメントへのリンクについて、content/docs/components/<name>.mdx を読みます。
4. registry/react/examples/<component>/example-*.tsx を少なくとも1つ開きます。
5. 動作が不明な場合は、Ark のインポートとプロパティの受け渡しについて registry/react/components/<component>.tsx を読みます。
6. 利用側のアプリでは、resolvedPaths にすでにあるコンポーネントを再追加しないでください。
7. アクセシビリティ、制御あり／制御なしの状態、SSR／遅延マウントのデフォルト、および上記の 重要なルール をセルフチェックします。

インストールの更新／差分確認

上流の CLI 出力をローカルの編集内容とマージする場合、上書きする前に、ファイルごとに npx shadcn@latest add @shark/<component> --dry-run と --diff を使用します。明示的なユーザーの承認なしに --overwrite を使用しないでください。references/cli.md を参照してください。

インストールのリファレンス

references/cli.md を参照してください。

npx shadcn@latest add @shark/<component>

合成度の高いプリミティブ

オーバーレイ、コレクション、アプリの外枠に関する作業を始める前に、以下のガイドを読んでください。

• ./references/primitives/dialog.md
• ./references/primitives/sheet.md
• ./references/primitives/menu.md
• ./references/primitives/context-menu.md
• ./references/primitives/popover.md
• ./references/primitives/select.md
• ./references/primitives/combobox.md
• ./references/primitives/field.md
• ./references/primitives/sidebar.md

詳細なリファレンス

• references/rules/styling.md — セマンティックカラー、バリアント、className、間隔、size-*、truncate、ダークモード、cn()、z-index
• references/rules/forms.md — FieldGroup、Field、InputGroup、ToggleGroup、FieldSet、バリデーション
• references/rules/composition.md — トリガー／コンテンツの階層、asChild、複合パーツ
• references/rules/migration.md — Radix／shadcn の慣習と Shark／Ark（render → asChild など）
• references/cli.md — CLI コマンド、@shark/*、ドライラン／差分
• テーマ設定／CSS 変数 — content/docs/(root)/styling.mdx および content/docs/(root)/ 内のインストール資料

出力チェックリスト

コードを返す前に、以下を確認してください。

• インポートと props が Shark のドキュメントやソースに一致している
• Shark で使われている Ark のパターンに沿った構成になっている（トリガー、コレクションオブジェクト）
• フォーム内のボタンに明示的な type が指定され、コントロールにラベルが関連付けられている
• 該当する場合、コンボボックス／セレクトの例でコレクション＋フィルターパターンを使用している
• 重要なルール（スタイリング、フォーム、構成、CLI）を満たしている