starwind-ui

Starwind UI v3

Starwind UI は、Astro を優先し、Astro と React で利用できるフレームワーク対応のシステムです。通常の製品形態は、アプリケーションにインストールする、編集可能なスタイル付きソースです。プリミティブアダプターとフレームワークに依存しない Runtime は、より細かな制御が必要なプロジェクト向けの下位レイヤーです。

starwind@latest を使用してください。現在の要件は、Node 22.12 以降、Tailwind CSS 4、Astro 5 以降、または React と React DOM 18 以降です。上流リポジトリにある Vue と Svelte のコードは、非公開の検証用出力であり、公開パッケージや CLI の対象ではありません。

CLI コマンドは、プロジェクトのルートでプロジェクトのランナーを使って実行してください。例では npx starwind@latest を使用しています。ローカルファイルからパッケージマネージャーが確認できる場合は、 pnpm dlx、pnpx、または yarn dlx に置き換えてください。

プロジェクトのコンテキストを把握する

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

• package.json、packageManager、ロックファイル：フレームワーク、パッケージランナー、バージョン、スクリプト。
• starwind.config.json：設定の生成、主要なフレームワーク、レジストリ、コンポーネント／Primitive の配置先、インストール済みの記録、Tailwind CSS、Pro の設定。
• フレームワークの設定ファイル：astro.config.*、Vite、Next.js、TanStack Start、または React Router のファイル。
• 設定で指定されている Starwind の CSS ファイル：トークン、@theme inline、:root、.dark。
• 設定済みのコンポーネントディレクトリとローカルの index.ts／index.tsx のエクスポート：インストール済みのソースと正確な公開パーツ。
• 近くにあるインポートとテスト：エイリアス、アイコンシステム、構文、状態、イベントの規約。

Starwind UI v3 でも、スキーマ config-schema.v2.json と version: 2 を指定した設定が生成されます。製品のメジャーバージョンと設定形式のバージョンは異なるため、設定の番号を手動で「アップグレード」しないでください。

適切なレイヤーを選ぶ

1. まずスタイル付きコンポーネントを使用します。 starwind add を使用すると、Starwind のバリアントとコンポジションを備えた、すぐにレンダリングできる編集可能なソースを利用できます。
2. 構造を自分で管理する必要がある場合は、プリミティブアダプターを使用します。 @starwind-ui/astro/<name> または @starwind-ui/react/<name> をインポートするか、プロジェクト側でアダプター自体を編集する必要がある場合は、starwind primitives add でコンパイル可能なアダプターソースをプロジェクトに取り込んでください。
3. 生の DOM やアダプターを扱う場合は、Runtime を使用します。 @starwind-ui/runtime/<name> または initStarwind は、プレーンな HTML、カスタムアダプター、またはコントローラーとの直接的な統合にのみ使用してください。

パッケージの Primitive、プロジェクトに取り込んだ Primitive のソース、Runtime コントローラー、生の HTML、または Runtime ベースのコンポーネント内の編集を扱う場合は、layers.md を読んでください。

基本ルール

• UI を新たに考案する前に、インストール済みのソース、最新のドキュメント、MCP、またはレジストリのメタデータを確認してください。
• 似たマークアップを書く前に、既存のコンポーネントとドキュメントに記載されたパーツを組み合わせてください。
• カスタムの内部実装よりも、組み込みのバリアント、セマンティックトークン、ドキュメントに記載された状態セレクターを優先してください。
• インストール済みのコンポーネントソースを編集する場合は、公開パーツの識別子としての data-slot と、Runtime の検出フックとしての data-sw-* を保持してください。
• ファイルのフレームワークに合わせてください。Astro では class、for、初期状態を指定する静的プロパティ、ブラウザースクリプトを使用します。React では適切に className、htmlFor、React のハンドラー、制御プロパティを使用します。
• パーツ、プロパティ、イベント、asChild を前提とする前に、ローカルのエクスポートと最新のコンポーネントドキュメントを確認してください。
• スタイル付きソースはアプリケーション側が所有するものとして扱い、カスタマイズ済みファイルを置き換える前に差分を確認してください。

重要なルール

ルートのスキルだけが確実に読み込まれるファイルであるため、これらのガードレールをここに繰り返し記載しています。

• スタイリング： 生のパレットユーティリティや長い外観の上書きよりも、組み込みのバリアントとセマンティックトークンを優先してください。gap-*、size-*、truncateを使用し、グローバルなライト／ダークカラーは、アクティブなStarwind CSS変数で変更してください。
• フォーム： ネイティブのname、送信、リセット、必須、無効、検証の動作を維持してください。Astroではfor、ReactではhtmlForを使用します。無効な状態には、対応するエラーテキストを組み合わせてください。
• コンポジション： アイテムはドキュメントに記載されたグループ内に配置し、Dialog／Sheet／Alert Dialogにはタイトルを付けてください。TabsTriggerはTabsList内に配置し、AvatarImageにはAvatarFallbackを組み合わせてください。
• ローディング： Buttonには、想定されたisLoadingやisPendingプロパティはありません。インストール済みのAPIを確認したうえで、Spinner、disabled、aria-busyを組み合わせてください。
• アイコン： プロジェクトのアイコンシステムを再利用し、アイコンのみのコントロールにはすべて名前を付けてください。ローカルのStarwindソースに記載がない限り、shadcnのdata-icon規約を持ち込まないでください。
• 更新： カスタマイズしたスタイル付きソースやベンダー提供のソースを置き換える前に、--dry-run、--diff、--viewでプレビューしてください。

主要な形状：

<Field name="email">
  <FieldLabel>Email</FieldLabel>
  <FieldControl type="email" required />
  <FieldError match="valueMissing">Enter an email address.</FieldError>
</Field>

<Button disabled aria-busy="true"><Spinner /> Saving...</Button>

<DialogContent>
  <DialogHeader><DialogTitle class="sr-only">Edit profile</DialogTitle></DialogHeader>
  
</DialogContent>

用途別のルール

• rules/composition.md：コンポーネントのネスト、オーバーレイ、Toast、単独のCombobox、Card、Tabs、Avatar、ローディングのコンポジション。
• rules/forms.md：ネイティブフォームへの参加、Field／Form、ラベル、デフォルト値、検証、Input Group。
• rules/styling.md：セマンティックトークン、バリアント、間隔、状態セレクター、Runtimeフックの境界。
• rules/icons.md：フレームワークに適したアイコンのインポートと、アクセシブルなアイコンボタン。
• customization.md：テーマ設定、ダークモードの初期化、変数、安全なコンポーネントのカスタマイズ。

現在のタスクに合った参照だけを読み込んでください。

コンポーネントの選択

必要なもの	まず確認するもの
アクション	button；関連するアクションにはbutton-group
フォーム構造	form、field、fieldset、label
テキストと選択入力	input、textarea、input-group、checkbox、checkbox-group、radio-group、switch、slider、input-otp
固定選択リスト	selectまたはnative-select
検索可能な選択肢	単独のcombobox；V3にはSelectSearchはありません
ナビゲーション	navigation-menu、sidebar、breadcrumb、tabs、pagination
オーバーレイ	dialog、sheet、alert-dialog、popover、dropdown、context-menu、hover-card、tooltip
フィードバック	toast、alert、progress、skeleton、spinner
データとコンテンツ	table、card、badge、avatar、item、kbd、prose
リッチ入力／メディア	color-picker、dropzone、image、video、carousel
開閉と切り替え	accordion、collapsible、toggle、toggle-group

インストールする前に、設定済みのフレームワークで利用できることを確認してください。スタイル付きのimageコンポーネントはAstro専用です。

現在のドキュメントとコマンド

正確な API については、現在のドキュメントまたはインストール済みのソースを確認してください。

npx starwind@latest docs button dialog combobox --json
npx starwind@latest search combobox --json

利用可能な場合は Starwind MCP を優先し、次にページごとの Markdown、llms.txt、llms-full.txt、ai-manifest.json の順で確認してください。ソースの優先順位と代替手段については、mcp.md を参照してください。

一般的な V3 コマンド：

npx starwind@latest init --framework astro
npx starwind@latest init --framework react
npx starwind@latest add button dialog combobox
npx starwind@latest update button --dry-run
npx starwind@latest update button --diff
npx starwind@latest primitives add button --framework react
npx starwind@latest primitives list --framework all
npx starwind@latest migrate

cli.md に記載されたフラグのみを使用してください。

作業手順

1. フレームワーク、パッケージランナー、現在の設定形式、配置先、インストール済みの項目、ローカル検証コマンドを確認します。
2. レイヤー構成に従って、styled、Primitive、Runtime のいずれかを選択します。
3. インストール済みのソースと現在のドキュメントを確認し、コンポーネントと API を特定します。
4. 設定で指定された正確なフレームワークと配置先に合わせて、不足しているソースをインストールします。
5. アプリケーションに組み込む前に、追加または置換したファイルをすべて読みます。
6. ローカルのエクスポートとフレームワークの構文を使って構成し、Runtime のフックとネイティブのセマンティクスを保持します。
7. 関連する範囲で最小限のフォーマット、型チェック、ビルド、テスト、ブラウザーチェックを実行します。

意図したフレームワークと配置先からすべてのインポートを解決でき、生成または編集したソースが現在のドキュメントに記載された契約に合致し、関連する検証に合格するか、残っている失敗がそれぞれ報告されれば、タスクは完了です。

更新と移行

update は、ローカルで編集した styled ソースまたはベンダー提供の Primitive ソースを置き換える場合があります。まずプレビューしてください。

npx starwind@latest update button --dry-run
npx starwind@latest update button --diff
npx starwind@latest update button --view

依頼された範囲が明確で、ローカルの変更を復元できる場合に限り、--all または --overwrite を使用してください。

Runtime 導入前の Astro プロジェクトでは、starwind migrate を実行する前に v3-migration.md を読んでください。移行が成功したと判断するには、レポート、残っているレガシー項目、アプリケーションの API 変更、動作確認のすべてを把握する必要があります。コマンドが終了しただけでは不十分です。

参考資料

• cli.md：V3 CLI の全機能と所有権に関する注意事項
• layers.md：styled、Primitive、ベンダー提供ソース、Runtime の境界
• v3-migration.md：V2 Astro から V3 Runtime への移行手順
• customization.md：トークン、ダークモード、安全なカスタマイズ
• shadcn-migration.md：shadcn スタイルのテーマトークンのマッピングのみ
• mcp.md：ライブ Starwind ツールと AI が読み取れるドキュメント