spartan-ng-developer

Spartan/ng 開発ガイドライン

angular-developer と併用してください - このスキルでは Angular の基礎（シグナル、DI、ルーティング、フォーム、SSR、アクセシビリティ）を扱います。このスキルでは Spartan/ng 固有の内容に焦点を当てています。最適な環境を得るには、両方をインストールしてください。

互換性

• 対象バージョン： @spartan-ng/brain v1.8.0（2026-10-16 リリース）。Spartan は 2026 年 6 月に 1.0 安定版に到達しました。1.x 系では API サーフェスのバージョン管理と各更新時の再検証を維持しながら、コンポーネントを迅速に追加しています。
• 1.1 → 1.8 の主な変更点： 1.1 では Calendar / Date Picker に年月ピッカーと日付入力の完全なサポートが追加され、brn-radio / brn-checkbox / brn-switch のホストスタイルのオーバーライド、CLI のスキャフォールド整合性ヘルスチェック、厳格な CSP に対応するインラインスタイルの修正も追加されました。1.2 ではメッセージ、バブル、添付ファイル、マーカーの各コンポーネントに加え、Date Picker と Input OTP の Signal Forms 互換性が追加されました。1.3 / 1.3.1 では autocomplete / combobox / command のアクセシビリティ修正と、Sidebar の defaultOpen オプションが追加されました。1.4 ではQuestionnaire（Brain + Helm、Signal Forms 対応）、Chart の TanStack Charts 統合（アルファ版）、Slider の maxStepsBetweenThumbs / preventStepOverThumb、Calendar のフォーカス日付 API が追加されました。1.5 ではチャットの会話履歴向けのMessage Scroller、ディレクティブとしての brn-switch-thumb、Switch の forceInvalid、Sonner のテンプレート用 action / cancelAction、Tooltip の既定の showDelay / hideDelay として 0 が追加されました。1.6 では Accordion に遅延コンテンツ（hlmAccordionContentLazy）が追加されました。1.7 では Pagination のラベルを設定できるようになりました。1.8 ではTrace と Code Block の各コンポーネント、ディレクティブの exportAs、すべてのコンポーネントを非対話形式で追加する CLI（ui all）が追加されました。各パッチリリースでは、アクセシビリティ（select、autocomplete、combobox、dialog、sidebar sheet）や popover / overlay のスクロールストラテジーに関する問題が修正されました。1.x 系を通じて、API に破壊的変更はありません。
• Angular： v21 または v22。@spartan-ng/[email protected] のピア依存関係は @angular/* >=21.0.0 <23.0.0 のため、Angular 21 と 22 の両方が公式にサポートされています。スタンドアロンコンポーネント、制御フロー（@if / @for）、シグナル API（input() / output()）を前提としており、NgModule ベースまたはデコレーターベースのコードは生成しません。
• Tailwind： v4 が必須です。 Spartan 1.x のピア依存関係は tailwindcss >=4.0.0 で、v3 はサポートされなくなりました。また、ピア依存関係として luxon >=3.0.0（日付プリミティブ）、clsx >=2.0.0、tw-animate-css >=1.0.0 も必要です。これらがインストールされていることを確認してください。setup.md を参照してください。
• サポート対象外： 古いアルファ版（v0.0.1-alpha.*。1.0 より前の API との差異があります）、Angular v20 以下、Tailwind v3、@spartan-ng/ui-* パッケージを使用するプロジェクト（非推奨で、@spartan-ng/helm に置き換えられています）。

プロジェクトにインストールされているバージョンが対象バージョンと大きく異なる場合は、コードを生成する前にユーザーに警告してください。API サーフェスが変更されている可能性があります。

1. ガイダンスを提供する前に、必ずプロジェクトの Spartan/ng バージョンを確認してください。Spartan は 1.0 安定版になりましたが、現在も進化を続けています。正確な情報源は package.json です。

2. まずプロジェクトの構成を確認します。

   • nx.json がある場合 → Nx ワークスペースです。npx nx g @spartan-ng/cli:ui <name> コマンドを使用します。
   • ない場合 → Angular CLI です。ng g @spartan-ng/cli:ui <name> コマンドを使用します。

   生成される Helm ソースの出力先は components.json の componentsPath で設定します。出力先を決めつけないでください。init の後に tsconfig.json の paths を確認して、実際の場所を特定してください。setup.md を参照してください。

3. プロジェクトがTailwind v4（package.json の tailwindcss 依存関係）を使用していることを確認してください。Spartan 1.x には Tailwind v4（ピア依存関係 >=4.0.0）が必須で、v3 はサポートされなくなりました。また、luxon、clsx、tw-animate-css の各ピア依存関係も揃っていることを確認してください。setup.md を参照してください。

4. Spartan コンポーネントを使用するコードを生成した後、ng build を実行してコンパイルエラーがないことを確認してください。コンポーネントがスタイルなしで表示される場合、ほとんどの場合は Tailwind の設定に問題があります。setup.md のトラブルシューティングのセクションを参照してください。

Spartan のアーキテクチャ：Helm と Brain（重要）

Spartan には、独自の関係を持つ 2 つのパッケージがあります。

• @spartan-ng/helm - node_modules ではなく、ユーザーのプロジェクト内に配置されるスタイル付きコンポーネントです。CLI（ng g @spartan-ng/cli:ui button）は、components.json（componentsPath）で設定されたパスにコンポーネントのソースをコピーします。@spartan-ng/helm/<name> のインポートは、生成されたソースを指す tsconfig のパスエイリアスです。Helm コンポーネントをカスタマイズするには、ユーザーのリポジトリ内のファイルを編集してください。node_modules 内を探さないでください。

• @spartan-ng/brain - npm から通常どおりインストールする、ヘッドレスでアクセシブルなプリミティブです。Helm コンポーネントは、Angular の hostDirectives を介して Brain のプリミティブを組み合わせます。

まず Helm を使ってください。 次の場合に限り Brain を使用します。（1）必要なプリミティブが Helm で公開されていない場合、（2）複数の Helm コンポーネントをラップする再利用可能なコンポジションを構築する場合、（3）Helm が隠しているアクセシビリティ属性を制御する必要がある場合。

インストールとテーマ設定

• セットアップ：CLI をインストールして Spartan を追加し、Tailwind v4（必須。luxon／clsx／tw-animate-css のピア依存関係も含む）を設定します。CLI と Nx の判定についても確認してください。setup.md をお読みください。
• テーマ設定：CSS 変数、ダークモード、カスタムテーマ。theming.md をお読みください。

コンポーネント

Spartan/ng には、カテゴリ別にまとめられた 66 個の安定版 Helm コンポーネントがあります。共通の規約ファイルはすべてのコンポーネントに適用され、カテゴリ別ファイルでは各コンポーネント固有の API と注意点を説明します。

• Helm の規約：hlm* ディレクティブのパターン、シグナル入力、hostDirectives によるコンポジション、cn() ヘルパー、HlmXImports バレルパターン、よくある問題。helm-conventions.md をお読みください。
• フォームコントロール：オートコンプリート、ボタン、ボタングループ、チェックボックス、コンボボックス、日付ピッカー、フィールド、入力、入力グループ、入力 OTP、ラベル、ネイティブセレクト、ラジオグループ、セレクト、スライダー、スイッチ、テキストエリア、トグル、トグルグループ。form-controls.md をお読みください。
• オーバーレイ：アラートダイアログ、コマンド、コンテキストメニュー、ダイアログ、ドロワー、ドロップダウンメニュー、ホバーカード、メニューバー、ナビゲーションメニュー、ポップオーバー、シート、Sonner（トースト）、ツールチップ。overlays.md をお読みください。
• レイアウト：アコーディオン、アスペクト比、カード、折りたたみ、サイズ変更可能、スクロール領域、区切り線、サイドバー、タブ。layout.md をお読みください。
• 表示：アラート、アバター、バッジ、空の状態、アイコン、項目、Kbd、進行状況、スケルトン、スピナー。display.md をお読みください。
• データ表示：パンくずリスト、カレンダー、カルーセル、チャート、データテーブル、ページネーション、テーブル。data-display.md をお読みください。
• チャットとエージェント UI：メッセージ、バブル、添付ファイル、マーカー、メッセージスクローラー、トレース、コードブロック、質問票。chat.md をお読みください。

レシピ

複数の Helm コンポーネントを組み合わせて、目的に特化した UI を構築するクックブック形式のパターンです。ここで提供するのはレシピであり、Helm コンポーネントとして提供されるものはありません。コードレビュー用ツールを構築する場合は、差分ビューアー（シンタックスハイライト、行ごとのガター、ファイルツリー、インライン行コメント）から始めてください。recipes.md をお読みください。

Brain のプリミティブ

• Brain：ヘッドレスプリミティブ、Helm から Brain に切り替える場面、カスタムコンポジションの構築。brain.md をお読みください。

フォーム連携

• フォーム：Helm のフォームコンポーネントと ReactiveForms または Signal Forms の接続、ControlValueAccessor のパターン、バリデーション表示。forms.md をお読みください。

アクセシビリティ

• アクセシビリティ：Helm と Brain が標準で提供するアクセシビリティ規約、知っておくべき ARIA パターン、注意点。accessibility.md をお読みください。