ng-blatui

ng-blatui

アクセシブルな Angular UI ライブラリ — BlatUI のビジュアルシステムを Angular に忠実に移植しました。公式の Angular ヘッドレススタック（Angular Aria + CDK）を基盤とし、Tailwind CSS v4 と oklch デザイントークンでスタイリングしています。

157 個のコンポーネント · 16 個のブロック · 70 個のチャート · 35 個のページテンプレート — すべてスタンドアロン、シグナルベース、ゾーンレス、SSR セーフです。

🔗 ドキュメントとライブデモ → · 📦 npm · 🤖 AI との使用方法 →

---

主な特長

• Angular 21 & 22 — スタンドアロンコンポーネント、シグナル（input()/model()/output()）、ゾーンレス変更検知、デフォルトで OnPush。
• SSR 対応 — すべてのコンポーネントがサーバーサイドレンダリングで正しく描画されます（ドキュメントサイトでは 280 以上の静的ルートを事前レンダリングしています）。
• アクセシブル — @angular/aria + @angular/cdk を基盤とする動作を実装し、AXE / WCAG AA に準拠しています。
• フォームネイティブ — すべてのフォームコントロールが ControlValueAccessor を実装しているため、同じコンポーネントをリアクティブフォーム、テンプレート駆動フォーム、シグナルフォームで使用できます。
• テーマ設定可能 — Tailwind v4 ユーティリティ + CSS 変数（oklch トークン）を使用し、ライト／ダークモードに標準対応しています。
• AI 対応 — MCP サーバー、llms.txt インデックス、機械可読なレジストリが付属します（以下を参照）。

インストール

npm i ng-blatui

ピア依存関係（Angular 21 または 22）：@angular/core、@angular/common、@angular/forms、@angular/cdk、@angular/aria。

Tailwind CSS のセットアップ

スタイリングには Tailwind CSS v4 を使用します。アプリのグローバルスタイルシート（例：src/styles.css）に 3 行追加します。

@import 'tailwindcss';
@import 'ng-blatui/foundations/blatui.css'; /* design tokens + dark theme */
@source '../node_modules/ng-blatui'; /* ← generate the utilities the lib's classes use */

見落としやすいのは @source の行です。これがないと Tailwind は ng-blatui のコンパイル済みテンプレートをスキャンしないため、コンポーネントはスタイルなしで描画されます。スタイルシートから見た ng-blatui の場所を指定してください（../ の階層を調整してください）。ダークモードは親要素の dark クラスで設定します（<html class="dark">）。:root / .dark 内の oklch トークンを上書きすると、テーマを変更できます。詳細なガイド： **https://ngblatui.remix-it.com/docs/installation**。

アイコン

ng-blatui にはアイコンセットが付属しないため、provideIcons(...) で独自のアイコン（例：@ng-icons）を接続し、使用する各アイコンを登録してください。アイコンを受け取るコンポーネントは SVG のパス d 文字列を受け付けるため、どのアイコンソースでも使用できます。

使い方

ng-blatui のバレルからコンポーネントクラスをインポートし、スタンドアロンコンポーネントの imports[] に追加します。NgModule は不要です。セレクターには bui の接頭辞が付いています。

import { Component } from '@angular/core';
import { BuiButton, BuiBadge, BuiInput } from 'ng-blatui';

@Component({
  selector: 'app-demo',
  imports: [BuiButton, BuiBadge, BuiInput],
  template: `
    <label>
      Email
      <input buiInput type="email" placeholder="[email protected]" />
    </label>
    <button buiButton>Save <span buiBadge tone="success">New</span></button>
  `,
})
export class Demo {}

• 要素セレクター：<bui-avatar>、<bui-rating>、…
• 属性／ディレクティブセレクター：<button buiButton>、<input buiInput>、<span buiBadge tone="success">、…
• シグナル：[checked] / (checkedChange) などをバインドします。追加の設定なしで、ゾーンレス CD と SSR で動作します。
• フォーム：formControlName、[(ngModel)]、[formControl] のいずれも動作します。すべてのコントロールが ControlValueAccessor です。

フォームフィールド：2 つのレベル

• 必要な機能がそろったコンポーネントが、ラベル + ヒント + エラー + ARIA をまとめて設定します：BuiInputField、 BuiMoneyInput（ローカライズされた通貨。symbol="DH" を指定すると ISO コードを上書きします）、BuiDateRangePicker （プリセット付きの開始→終了）、および BuiSelect、BuiCombobox、BuiAutocomplete、BuiPhoneInput。
• 構成用プリミティブは、カスタムレイアウト向けです：buiField + buiFieldLabel / buiFieldDescription / buiFieldError で、単独の buiInput / .blat-* コントロールを囲み、アクセシビリティの関連付けを管理します。

単独のコントロール（buiInput）を使う場合は、buiField の構成も自分で追加してください。ほかにも見落としやすい構成要素として、buiEmpty（空の状態）、bui-stat（統計カード）、 buiFieldSet / buiFieldLegend（フィールドのグループ化）があります。

テーマ設定

スタイリングには Tailwind v4 と CSS 変数を使用しています。oklch デザイントークン（--background、--foreground、--primary、--border、--muted、--radius、…）を上書きすると、すべてのスタイルをグローバルに変更できます。ダークモードにするには dark クラスを切り替えてください。https://ngblatui.remix-it.com/docs/theming をご覧ください。

ローカライズ

2 つのプロバイダーでライブラリ全体をカバーします。どちらもアプリの設定で一度だけ指定します。

import { provideBuiLabels, provideBuiLocale } from 'ng-blatui';

providers: [
  provideBuiLocale('fr-BE'), // dates, times, numbers, week start, weekend, week numbering
  provideBuiLabels({ fileUploadRemove: 'Supprimer le fichier' }), // built-in strings
];

どちらも設定しない場合、すべて en-US 形式になります。これは Angular 自身の LOCALE_ID のデフォルトであり、アプリがアメリカ式ではないのにピッカーがアメリカ式のままになる一般的な原因です。解決時には、最も具体的な設定が優先されます。コンポーネントの [locale] 入力 → provideBuiLocale() → アプリの LOCALE_ID → en-US の順です。ここで registerLocaleData() を呼び出す必要はありません。ng-blatui は Intl を通じてフォーマットします。

どちらのプロバイダーも シグナル、またはインジェクションコンテキストで実行されるファクトリーを受け取れます。これにより、ng-blatui が特定の翻訳ライブラリに依存したり、翻訳形式を把握したりすることなく、あらゆる翻訳ライブラリ（Transloco、ngx-translate、独自のシグナルストアなど）と連携できます。Transloco の例を含む詳しいガイドは https://ngblatui.remix-it.com/docs/localization をご覧ください。

内容

カテゴリ	数	閲覧
コンポーネント	157	https://ngblatui.remix-it.com/components
ブロック	16	https://ngblatui.remix-it.com/blocks
チャート	70	https://ngblatui.remix-it.com/charts
テンプレート	35	https://ngblatui.remix-it.com/templates

テンプレートは、本番環境を想定したページ一式です（ダッシュボード、料金プラン、認証、ストア、CRM、ブログ、ドキュメント、EC 商品、さらにアートディレクションを施したランディングページ 20 種類）。BlatUI のオリジナルを忠実に 1:1 で再現しています。

AI エージェントでの利用

ng-blatui は AI コーディングアシスタントがカタログを推測ではなく正しく見つけて使用できるよう、3 つのレイヤーを通じて利用されることを想定して構築されています。

レイヤー	内容	場所
MCP サーバー	カタログの一覧表示・検索と、完全なドキュメントおよびコードの取得に使うツール	npx ng-blatui-mcp
llms.txt	llms.txt 標準のインデックス	https://ngblatui.remix-it.com/llms.txt
registry.json	機械可読なカタログ	https://ngblatui.remix-it.com/registry.json

クイックスタート（Claude、Cursor、Windsurf、Cline、Zed、VS Code…で動作します）。

claude mcp add ng-blatui -- npx -y ng-blatui-mcp
# or add to any MCP client:
# { "mcpServers": { "ng-blatui": { "command": "npx", "args": ["-y", "ng-blatui-mcp"] } } }

MCP サーバーは list_components（category は任意）、list_blocks、list_charts、list_templates、search({ query })、get_docs({ name }) を提供します。クライアントごとの設定と、コピーして使えるエディター用ルールを含む詳しいガイドは USING-WITH-AI.md をご覧ください。

---

開発

これは、ライブラリ（projects/ng-blatui）とドキュメント／デモアプリ（projects/demo）の 2 つのプロジェクトで構成される Angular ワークスペースです。

git clone https://github.com/anousss007/ng-blatui.git
cd ng-blatui
npm install
npm start          # serve the docs/demo app at http://localhost:4200

スクリプト

コマンド	内容
npm start	デモアプリを起動します（ng serve demo）
npm run build:lib	公開可能なライブラリをビルドします（ng build ng-blatui）
npm run build	デモサイトをビルドします
npm test	ユニットテスト（Vitest）
npm run lint	ESLint（型を考慮した厳格な設定）＋テンプレートのアクセシビリティチェック
npm run format	Prettier（Tailwind クラスの並べ替え対応）
npm run build:registry	カタログから registry.json と llms.txt を再生成します
npm run capture:previews	テンプレートのプレビュー画像をキャプチャします（Playwright）
npm run deploy:site	ドキュメントサイトをビルドして VPS にデプロイします

プロジェクト構成

projects/
  ng-blatui/        # the published library (src/lib/* = 157 component dirs, public-api.ts)
  demo/             # docs + live demo site (components/blocks/charts/templates galleries)
    src/app/pages/templates/   # the 35 page templates
    public/         # static assets incl. generated llms.txt + registry.json
scripts/
  build-registry.mjs   # generates registry.json + llms.txt + mcp/registry.json
  capture-previews.mjs # template preview screenshots
  deploy-site.sh       # build + rsync to VPS
mcp/                # the ng-blatui-mcp MCP server package (published separately)
.claude/skills/     # angular-best-practices (contributing) + ng-blatui (consuming)
AGENTS.md           # guide for AI agents working IN this repo
USING-WITH-AI.md    # guide for consuming ng-blatui WITH an AI agent

規約

Angular v22、ゾーンレス、スタンドアロン（デフォルトで有効のため、明示的に設定しないでください）。あらゆる箇所でシグナルを使用し、ネイティブの制御フロー（@if／@for／@switch）を使います。*ngIf／ngClass は使用しません。ライブラリのセレクタープレフィックスは bui、デモのプレフィックスは app です。すべての規則については、AGENTS.md と CONTRIBUTING.md を参照してください。

リリース

• ライブラリ（ng-blatui） — GitHub Actions の Release ワークフロー（手動実行）で semantic-release を実行します。Conventional Commits を解析し、バージョンを更新してタグを付け、GitHub リリースを作成し、provenance 付きで npm に公開します。
• MCP サーバー（ng-blatui-mcp） — mcp/package.json のバージョンを更新してから、Release MCP ワークフロー（手動実行）を実行して公開します。

クレジット

BlatUI（Blade／Laravel ＋ Tailwind のコンポーネントシステム）の Angular 移植版です。動作は Angular Aria ＋ CDK に基づいています。

ライセンス

MIT