spartan

spartan/ui

spartan/ui は Angular UI ライブラリです。2 層アーキテクチャを採用しています。

• Brain (@spartan-ng/brain) - アクセシビリティに配慮した、スタイルを持たないプリミティブ（Angular ディレクティブ／コンポーネント）で、npm からインストールします。動作とアクセシビリティを担うレイヤーです。
• Helm (@spartan-ng/helm) - スタイルを担うレイヤー（Tailwind + class-variance-authority）です。Helm のコードは CLI によってユーザーのプロジェクトにコピーされるため、ユーザー自身が所有し、カスタマイズできます。

Helm のディレクティブ／コンポーネントをホスト要素に組み合わせます。Helm は内部で対応する Brain プリミティブを接続します。手書きのマークアップより、既存のコンポーネントを常に優先してください。

すべての CLI コマンドは、ワークスペースのランナーを通じて実行します。プロジェクトからランナーを判別してください。

• Nx ワークスペース（nx.json がある場合）：npx nx g @spartan-ng/cli:<generator>（または pnpm nx g ...）。
• Angular CLI ワークスペース（angular.json があり、nx.json がない場合）：ng g @spartan-ng/cli:<generator>。

現在のプロジェクトのコンテキスト

コードを生成する前に、プロジェクトのコンテキストを収集してください。

npx nx g @spartan-ng/cli:info --json     # Nx
ng g @spartan-ng/cli:info --json         # Angular CLI

これは読み取り専用で、次の内容を含む JSON を出力します。

• workspaceType - nx | angular-cli（上記のどのランナーを使用するかを決定します）。
• config.componentsPath - Helm コンポーネントのコピー先（例：libs/ui）。
• config.importAlias - Helm のインポートプレフィックス。デフォルトは @spartan-ng/helm です。
• config.generateAs - library | entrypoint（Nx のレイアウトの選択肢）。
• versions - Angular、Angular CDK、Tailwind、@spartan-ng/brain、@spartan-ng/cli のバージョン。
• iconLibrary - 存在する場合は @ng-icons。
• tailwindCssFile - プリセットをインポートするグローバルスタイルシート。
• installedComponents - すでに存在するコンポーネント（再追加しないでください）。
• availableComponents - CLI で生成可能なすべてのコンポーネント。

components.json が存在しない場合、プロジェクトはまだセットアップされていません。まず @spartan-ng/cli:init を実行してください（依存関係とテーマがインストールされます）。components.json は、ui を使って最初のコンポーネントを追加したときに作成されます（cli.md を参照）。

原則

1. まず既存のコンポーネントを使用してください。 installedComponents、次に availableComponents を確認します。ドキュメントは MCP サーバー（spartan_components_list / spartan_components_get）またはライブドキュメント（https://www.spartan.ng/components/<name>）で確認してください。mcp.md を参照してください。
2. 再発明せず、組み合わせてください。 カスタムマークアップではなく、既存の Helm と Brain のパーツからダッシュボード、フォーム、ダイアログを構築してください。
3. カスタムスタイルより、組み込みのバリアントを使用してください。 ボタン、バッジ、アラートなどには variant と size の入力が用意されています。クラスを上書きする代わりに使用してください。
4. 生の値ではなく、セマンティックカラーを使用してください。 bg-blue-500 ではなく bg-primary text-primary-foreground を使用してください。rules/styling.md を参照してください。

重要なルール

関連する作業を始める前に、ルールファイルを読んでください。

• rules/styling.md - hlm() ユーティリティ、セマンティックカラーのトークン、レイアウト専用クラス、space-* よりも gap-* を使うこと、size-*、ダークモード、オーバーレイに z-index を手動で指定しないこと。
• rules/forms.md - hlmField（ラベル、コントロール、エラー、説明）を使ってフォームを構成し、ネイティブの <fieldset>／<legend> では hlmFieldSet／hlmFieldLegend を使います。選択肢のセット（2～7 個）には hlm-toggle-group を使います。
• rules/composition.md - アイテムは必ずグループ内に配置します。ダイアログ／シートにはタイトルが必要です。Card はすべての要素を組み合わせて構成します。タブのトリガーは hlm-tabs-list 内に配置します。アバターには必ずフォールバックを用意します。カスタムのマークアップではなく、Alert／Empty／Skeleton／Badge／Separator／Spinner を使います。
• rules/icons.md - アイコンは <ng-icon name="lucide..."> を使います。provideIcons で登録します。コンポーネント内ではサイズ指定クラスを手動で追加せず、size 入力を使います。
• rules/brain-vs-helm.md - 2 層モデル（ヘッドレスライブラリの Brain と、スタイル付きの Helm 層）、Brain を直接使う場合と Helm を使う場合、ディレクティブによる構成方法。
• cli.md - Nx と Angular CLI での実行方法を含む、すべてのジェネレーター（init、ui、ui-theme、healthcheck、info、migrate-*）。
• registry.md - Brain-npm と Helm のコピー配置による配布モデル、components.json、固定のコンポーネントカタログ（同梱 CLI ではリモートまたはカスタムのレジストリを使いません）。
• customization.md - hlm-tailwind-preset.css、CSS 変数、ui-theme ジェネレーター、およびコピーした Helm コンポーネントの拡張によるテーマ設定。
• mcp.md - 検出に使用する @spartan-ng/mcp のツール、リソース、プロンプト。

主なパターン

<button hlmBtn variant="destructive" size="lg">Delete</button>


<button hlmBtn size="icon" variant="ghost">
	<ng-icon name="lucideTrash" />
</button>


<button hlmBtn [disabled]="loading()">
	@if (loading()) {
	<hlm-spinner />
	} Save
</button>


<div class="flex items-center gap-2">
	<span hlmBadge variant="secondary">beta</span>
</div>

コンポーネントの選択

必要な機能	コンポーネント
アクション／ボタン	button（hlmBtn）、button-group
テキスト／数値入力	input、textarea、input-otp、input-group、native-select
選択式入力	select、combobox、autocomplete、radio-group、checkbox、switch、slider
2～7 個の選択肢の切り替え	toggle-group
フォームのレイアウト／検証	field、label
データ表示	chart、table、card、badge、avatar、kbd、item
ナビゲーション	sidebar、navigation-menu、breadcrumb、tabs、pagination
オーバーレイ	dialog、sheet、alert-dialog、popover、hover-card、tooltip
メニュー	dropdown-menu、context-menu、menubar、command
フィードバック	sonner（トースト）、alert、progress、skeleton、spinner
レイアウト／コンテナー	card、separator、resizable、scroll-area、accordion、collapsible、aspect-ratio
空の状態	empty
日付	calendar、date-picker
アイコン	icon（@ng-icons）
タイポグラフィ	typography

ワークフロー

1. コンテキストを取得します。 @spartan-ng/cli:info --json を実行します。プロジェクトがセットアップされていない場合は、:init を実行してから、:ui でコンポーネントを追加します（最初の :ui の実行時に components.json が作成されます）。
2. インストール済みの項目を確認します。 installedComponents に含まれているものは再追加しないでください。
3. コンポーネントを探します。 MCP ツール、または https://www.spartan.ng/components/<name> で API と例（mcp.md）を確認します。セレクターを推測せず、必ず確認してください。
4. 追加します。 npx nx g @spartan-ng/cli:ui --name=<component>（Nx）または ng g @spartan-ng/cli:ui --name=<component>（Angular CLI）を実行します。これにより Brain の依存関係がインストールされ、Helm のコードがコピーされます。対話型の複数選択を使用するには、--name を省略します。
5. 正しく組み合わせます。 *Imports 定数（例：HlmDialogImports）またはインポートエイリアスから個々のクラスをインポートし、スタンドアロンコンポーネントの imports に追加して、組み合わせのルールに従います。
6. アイコンを登録します。 使用する <ng-icon> はすべて provideIcons(...) に渡す必要があります（rules/icons.md を参照）。
7. 確認します。 大きな変更やアップグレードの後は、@spartan-ng/cli:healthcheck を実行して非推奨のパターンを検出し、インポートを修正します。
8. テーマを設定／カスタマイズします。 コピーした Helm ファイルと CSS 変数を編集します。Brain はフォークしないでください。

クイックリファレンス

# Initialize (creates components.json, wires Tailwind + preset)
npx nx g @spartan-ng/cli:init
ng g @spartan-ng/cli:init

# Project context as JSON
npx nx g @spartan-ng/cli:info --json

# Add components (interactive, or pass --name)
npx nx g @spartan-ng/cli:ui
npx nx g @spartan-ng/cli:ui --name=dialog

# Generate theme variables
npx nx g @spartan-ng/cli:ui-theme

# Scan + auto-fix deprecated APIs/imports after an upgrade
npx nx g @spartan-ng/cli:healthcheck --autoFix