zard

zard/ui

Angular コンポーネントライブラリです。CLI を使ってコンポーネントをソースコードとしてユーザーのプロジェクトにインストールします。インポート元となるランタイムパッケージはなく、npm install するコンポーネントもありません。

IMPORTANT: すべての CLI コマンドは、プロジェクト独自のパッケージランナーで実行してください：npx zard-cli、pnpm dlx zard-cli、yarn zard-cli、または bunx zard-cli。components.json の packageManager に合ったものを選んでください。以下の例では npx zard-cli を使用しています。適切なランナーに置き換えてください。

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

何かをする前に、プロジェクトのルートにある components.json を読んでください。 このファイルは zard-cli init によって作成される設定ファイルです。呼び出すべき zard-cli info コマンドはありません。

{
  "$schema": "https://zardui.com/schema.json",
  "style": "css",
  "icons": "lucide",
  "rtl": false,
  "projectType": "angular",
  "appConfigFile": "src/app/app.config.ts",
  "packageManager": "npm",
  "tailwind": { "css": "src/styles.css", "baseColor": "neutral" },
  "baseUrl": "src/app",
  "aliases": {
    "components": "@/shared/components",
    "utils": "@/shared/utils",
    "core": "@/shared/core",
    "services": "@/shared/services",
    "blocks": "@/shared/blocks"
  }
}

components.json がない場合、プロジェクトは初期化されていません。コンポーネントファイルを手作業で作成するのではなく、init を実行してください。

components.json が存在していても、インストール済みコンポーネントのソースが名前変更後のセレクターや古いファイル構成（core/css/zard.css ではなく core/css/tailwind.css、グローバル CSS にある単独の ::-webkit-scrollbar ブロック、button-group の「separator」ではなく「divider」、sonner ではなく toast フォルダー）を使用している場合、そのプロジェクトは現在のレジストリより前のものです。この場合は移行スキルを使用してください。移行スキルでは、名前が変更されたセレクターがすべて正確に記載されています。現在の構成を推測してはいけません。

このファイルで分からないこと（何があるのか、コンポーネントの API は何か、何に依存するのか）は、レジストリを読むか、MCP サーバーを使用してください。コンポーネント API を記憶から再構成してはいけません。

主なフィールド

• aliases.components → すべてのコンポーネントに使われるインポートプレフィックスです。実際の値を使用し、@/shared/components をハードコードしないでください。プレフィックスにはどのような値でも使用できます（@app/...、~/... など）。これは tsconfig.json、または Nx ワークスペースでは tsconfig.base.json でマッピングされています。
• aliases.blocks → ブロック（add dashboard-01、add login-01）が配置されるインポートプレフィックスです。ブロックをインストール可能になる前に作成された components.json には含まれていません。init を再実行すると追加されます。
• baseUrl → エイリアスの解決先となるソースルートです。コンポーネントはこの配下に作成されます。
• projectType → angular、angular-library、nx、nx-library、または analog です。エイリアスを含む tsconfig、Tailwind の設定場所、および app.config.ts が存在するかどうかを決定します。cli.md を参照してください。
• appConfigFile → provideZard() が登録される場所です。ライブラリでは空です。ライブラリの場合は、それを使用するアプリが登録します。
• tailwind.css → テーマトークンを格納するグローバル CSS ファイルです。必ずこのファイルを編集し、2 つ目のファイルを作成しないでください。
• tailwind.baseColor → テーマプリセットです：neutral、stone、zinc、gray、または slate。
• icons → コンポーネントで使用されるアイコンファミリーです（現在は lucide）。@ng-icons/* パッケージとシンボル名を決定します。rules/icons.md を参照してください。
• rtl → レイアウトの方向に関する意図を示します。インストールされるものは変わりません。
• packageManager → すべての依存関係のインストール（npm install date-fns ではなく pnpm add date-fns）に使用し、CLI ランナーの選択にも使用してください。
• registryUrl → 任意です。https://zardui.com/r 以外のレジストリからプロジェクトにインストールする場合に設定されています。registry.md を参照してください。

原則

1. インポートする前にインストールします。 コンポーネントが存在するのは、zard-cli add によって追加された後だけです。まずコンポーネントディレクトリを確認し、存在しないものをインポートしないでください。
2. 存在するものを組み合わせます。 設定ページは Card + Field + Input + Button です。ダッシュボードは Sidebar + Card + Chart + Table です。既存のもので対応できない場合に限り、カスタムのマークアップを使います。
3. クラスより先にバリアントを使います。 zType="outline"、zSize="sm" を使います。同じ見た目にするためにコンポーネントを再スタイルする class は使いません。
4. セマンティックトークンのみを使います。 bg-primary、text-muted-foreground を使います。bg-blue-500 は使わず、dark: による色の上書きもしません。
5. 作成するコードにも、このライブラリ独自の規約を適用します。 スタンドアロン、OnPush、input()、z プレフィックス付きの入力を使います。rules/angular.md を参照してください。

重要なルール

常に適用されます。それぞれのリンク先ファイルに、誤った例と正しい例が記載されています。

Angular API → rules/angular.md

• imports を使ったスタンドアロン構成、ChangeDetectionStrategy.OnPush、ViewEncapsulation.None を使います。 NgModules と Default の変更検知は使いません。
• シグナル入力には input()、model()、output() を使います。 新しいコードでは @Input()／@Output() デコレーターを使いません。
• セレクターは z-<name> および／または [z-<name>] です。 要素専用のコンポーネントもあれば、ネイティブタグの属性として使うコンポーネント（input[z-input]、button[z-button]）もあります。コンポーネントで宣言されているものを使います。
• 複合コンポーネントでは、個々のクラスを一つずつではなく、Zard<Name>Imports 配列をインポートします。
• 生成された出力は編集しないでください。 apps/web/src/generated/** と public/r/*.json はビルド成果物です。

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

• セマンティックトークンを使い、生の色は使いません。 bg-blue-600 ではなく bg-primary を使います。
• class はレイアウト用であり、再スタイリングには使いません。 class は最後にマージされ、優先されます。だからこそ、コンポーネント独自の色を上書きするために使うべきではありません。
• 文字列の連結ではなく、mergeClasses() を使います。 これは twMerge(clsx(...)) です。単純な補間では競合解決が失われます。
• space-x-*／space-y-* は使いません。 flex と gap-* を使います。
• 幅と高さが同じ場合は size-* を使います。 w-4 h-4 ではなく size-4 を使います。
• dark: による色の上書きは使いません。 トークンによってすでに切り替わります。
• Tailwind v4 のみを使います。 tailwind.config.js はありません。テーマは CSS に記述されています。
• scroll-fade にはオーバーフローコンテナが必要です。shimmer はテキスト専用です。 どちらも core 項目に含まれる純粋な CSS ユーティリティです。

コンポジション → rules/composition.md

• コンポジション全体を使います。 z-card では、すべてをコンテンツに詰め込むのではなく、z-card-header／z-card-title／z-card-content／z-card-footer を使います。
• 項目は対応するグループに配置します。 z-select-item は z-select-group の中に配置します。
• ダイアログ、シート、アラートダイアログ、ドロワーには、それぞれ2つの使い方があります。 テンプレートで [(zVisible)] とヘッダー／タイトル／説明／フッターの子要素を使って z-dialog／z-sheet／z-alert-dialog／z-drawer を組み立てるか、コードから ZardDialogService／ZardSheetService／ZardAlertDialogService／ZardDrawerService を通じて同じパネルを開きます。手書きの open フラグや @if で切り替えないでください。
• トーストには ZardSonnerService の show、success、error、promise を使います。
• スタイルを適用したマークアップではなく、コンポーネントを使います。 <hr> ではなく z-separator、animate-pulse を付けた div ではなく z-skeleton、スタイルを適用した span ではなく z-badge、手作りの空状態ではなく z-empty を使います。

フォーム → rules/forms.md

• Angular の3つのフォーム API すべてに対応しています。 Signal Forms、Reactive Forms、Template-driven のいずれも使えます。プロジェクトですでに使われている方式に従ってください。
• フォームのレイアウトには z-field-group と z-field を使い、space-y-* を使った div は使いません。
• 検証状態はフィールドに data-invalid、コントロールに aria-invalid を設定します。
• エラーは z-field-error に表示し、単独の段落には表示しません。

Typeset → rules/typeset.md

• レンダリングされる Markdown には typeset コンテナーを適用し、タグごとにクラスを指定しません。 zard-cli add typeset でスタイルシートをインストールします。
• 6 つの変数で制御し、そのうち 3 つがリズムを決めます。 --typeset-size、--typeset-leading、--typeset-flow。
• 文章に埋め込まれたコンポーネントには not-typeset を指定します。 コンポーネント自体がサイズを設定します。
• 幅の広いテーブルは手作りのオーバーフロー用ラッパーではなく、typeset-scroll で囲みます。
• !important を使わずにユーティリティで上書きできます。 すべての要素セレクターは :where() の中にあります。

Icons → rules/icons.md

• アイコンは @ng-icons/<family> から取得し、viewProviders の provideIcons で登録します。 登録されていない名前は何も表示されず、エラーも出ません。
• ファミリーは components.json の icons で指定します。 lucide と決めつけないでください。
• コンポーネント内のアイコンにはサイズ指定クラスを付けません。 コンポーネント側でサイズを設定します。

Key Patterns

// Host classes: computed + mergeClasses. Never assembled in the template.
protected readonly classes = computed(() => mergeClasses(cardVariants(), this.class()));

// Variants, not classes.
<button z-button zType="outline" zSize="sm">Save</button>   // correct
<button z-button class="border bg-transparent px-2.5">Save</button>  // wrong

// Spacing: gap-*, not space-y-*.
<div class="flex flex-col gap-4">   // correct
<div class="space-y-4">             // wrong

// Field: data-invalid on the field, aria-invalid on the control.
<div z-field [attr.data-invalid]="invalid || null">
  <label z-field-label for="email">Email</label>
  <input z-input id="email" [attr.aria-invalid]="invalid || null" />
  <z-field-error>Enter a valid email.</z-field-error>
</div>

// Loading button: the zLoading input, not a hand-rolled spinner.
<button z-button [zLoading]="saving()" [zDisabled]="saving()">Save</button>

コンポーネントの選択

ニーズ	使用するもの
アクション	z-button（zType: default、destructive、outline、secondary、ghost、link）
グループ化されたアクション	z-button-group、z-toggle、z-toggle-group
テキスト入力	input[z-input]、textarea[z-textarea]、z-input-group、z-input-otp
選択	z-select、z-combobox、z-radio-group、z-checkbox、z-switch、z-slider
日付	z-calendar、z-date-picker
フォーム構造	z-field-group、z-field、z-field-label、z-field-description、z-field-error
データ表示	z-table、z-card、z-item、z-badge、z-avatar、z-chart
ナビゲーション	z-navigation-menu、z-breadcrumb、z-tab-group、z-pagination
入れ子／ツリーリスト	z-collapsible、入れ子構造 — フォルダツリーには専用のツリーコンポーネントではなく、z-collapsible-content内にz-collapsibleを配置します。合成ルールを参照してください。
レイアウト	z-sidebar（z-sidebar-providerおよびz-sidebar-insetと併用）、z-separator、z-resizable、z-accordion、z-carousel
オーバーレイ	z-dialog（モーダル）、z-drawer（下部／側面シート）、z-sheet（サイドパネル）、z-alert-dialog（確認） — それぞれサービス経由でコードからも使用できます —、z-popover、z-tooltip、z-dropdown
コマンドパレット	z-command
フィードバック	ZardSonnerService（トースト）、z-alert、z-progress、z-skeleton、z-spinner
空の状態	z-empty
チャット／メッセージ	z-bubble、z-bubble-group、z-bubble-content、z-bubble-reactions
キーボードのヒント	z-kbd
レンダリングされた文章	typeset + プリセットクラス（コンポーネントではなくスタイルシート） — rules/typeset.mdを参照してください。

名前はレジストリ名です。zard-cli addに渡す文字列と同じです。以前のレジストリにあったtreeとlayoutの2つの名前は、現在は存在しません。layoutのヘッダー／コンテンツ／サイドバーの構造は、上記のsidebarコンポーネントに置き換えられました。treeに置き換えられるコンポーネントはありません。上記の行に従って、代わりにz-collapsibleを入れ子にしてください。削除前にインストールされたプロジェクトでは、引き続きこれらを使用できる場合があります。移行スキルを参照してください。

コンポーネント以外の項目

レジストリ内の名前がすべて、UI の要件に合わせて選ぶコンポーネントとは限りません。次の 5 つはインフラストラクチャをインストールします。

項目	内容	インストール方法
core	共通ディレクティブ、オーバーレイスタック、provideZard()、テーマ CSS	自動 — init でインストールされます。コンポーネントが依存関係として宣言することはありません
utils	mergeClasses()（twMerge(clsx(...))）	自動 — core と同じです
utilities	scroll-fade / shimmer CSS ユーティリティ — rules/styling.md を参照してください	zard-cli add utilities、または使用するコンポーネントとともにインストールされます
dark-mode	ダークモードサービスと、index.html に挿入される切り替えスクリプト	オプトイン — zard-cli add dark-mode（対話形式。index.html のパスが必要です）
typeset	レンダリングされた Markdown 用の文章スタイルシート	オプトイン — zard-cli add typeset — rules/typeset.md を参照してください

ワークフロー

1. components.json を読みます。 ファイルがなければ init を実行します。aliases、baseUrl、icons、packageManager、projectType を確認してください。
2. インストール済みの項目を確認します。 aliases.components から解決されるコンポーネントディレクトリの内容を一覧表示します。すでにあるものを再追加したり、ないものをインポートしたりしないでください。
3. 利用可能な項目を確認します。 <registryUrl>/registry.json にあるレジストリインデックスにすべての項目が掲載されています。MCP サーバーでは、同じ内容を list-components と search-components で確認できます。
4. コードを書く前に、実際の API を読みます。 MCP の get-component-docs、または https://zardui.com/docs/components/<name>.md を使います。すべてのコンポーネントページは Markdown で公開されています。入力を推測することが、最もよくある失敗の原因です。
5. インストールします。 npx zard-cli add <name> を実行すると、そのコンポーネントの依存関係（npm パッケージとほかのレジストリ項目）が解決され、インストールされます。
6. 書き込まれた内容を確認します。 追加されたファイルを読みます。インポートがプロジェクトの実際のエイリアスで解決されること、アイコンの種類が icons と一致することを確認してください。
7. GitHub からコンポーネントのソースを手動で取得しないでください。 CLI またはレジストリを使います。プロジェクトが実際にインストールするのはレジストリの内容です。

クイックリファレンス

# Initialise a project (full-screen wizard).
npx zard-cli init
npx zard-cli init --type nx --project web        # answer the wizard up front
npx zard-cli init --yes                          # accept the defaults; required without a TTY

# Add components.
npx zard-cli add button card dialog
npx zard-cli add                                 # pick from the list
npx zard-cli add --all
npx zard-cli add button --overwrite              # replace local changes — ask first
npx zard-cli add button --path src/app/ui        # a directory other than the configured one

# Diagnose.
npx zard-cli add button --debug
npx zard-cli --version

search、view、diff、info、build コマンドはありません。これらは shadcn のコマンドです。すべてのフラグについては cli.md を参照してください。

詳細なリファレンス

• cli.md — init と add、すべてのフラグ、5 つのプロジェクトタイプ、ヘッドレス動作
• registry.md — インデックス、アイテム形式とアイコンカタログ形式、JSON Schema、独自のレジストリの参照方法
• mcp.md — 9 つの MCP ツール、接続方法、ZARD_REGISTRY_URL / ZARD_DOCS_URL
• customization.md — テーマトークン、CVA バリアント、mergeClasses、コンポーネントの拡張
• rules/angular.md — スタンドアロン、input()、OnPush、ViewEncapsulation.None、セレクター
• rules/styling.md — Tailwind v4、セマンティックトークン、mergeClasses、生のクラスより先にバリアントを指定する方法、scroll-fade / shimmer ユーティリティ
• rules/composition.md — マークアップを新たに作る前に、既存のものを組み合わせる方法
• rules/forms.md — Signal Forms、Reactive Forms、Template-driven
• rules/icons.md — ng-icons、provideIcons、カタログ、設定可能なファミリー
• rules/typeset.md — タグごとにクラスを指定せず、1 つのコンテナクラスでレンダリングされた Markdown のスタイルを設定する方法
• ../zard-migration/SKILL.md — インストール済みコンポーネントのソースが現在のレジストリより古いプロジェクト向けの、別個のスキル（セレクターの名前変更、--overwrite、core/utils/utilities の分割）