bklit-ui

Bklit UI

@bklit shadcn レジストリで配布される、合成可能な React チャートコンポーネント（visx + motion）です。shadcn add はソースコードをユーザーのプロジェクトにコピーします。コードの所有者はユーザーであり、props の正確な定義はこのソースコードを参照してください。

プロジェクトのパッケージランナーを使って shadcn CLI を実行してください。npx shadcn@latest、pnpm dlx shadcn@latest、bunx --bun shadcn@latest、または yarn dlx shadcn@latest を使用します。

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

!`npx shadcn@latest info --json`

上のブロックが空、またはコマンドのまま表示されている場合（! インジェクションを展開しないエージェントなど）は、コードを書く前に npx shadcn@latest info --json を自分で実行してください。フレームワーク、エイリアス（@/…）、Tailwind のバージョン、インストール済みコンポーネントの確認に使用します。

• components.json がありませんか？ まず npx shadcn@latest init を実行してください。
• registries に @bklit がありませんか？ "@bklit": "https://ui.bklit.com/r/{name}.json" を追加してください（installation.md を参照）。または、URL でインストールします。npx shadcn@latest add https://ui.bklit.com/r/line-chart.json

基本方針

1. 独自に作る前にインストールします。 npx shadcn@latest add @bklit/<item> を実行し、SVG チャートを手作業で作成したり、レジストリのコンポーネントを再実装したりしないでください。
2. インストール済みのファイルからインポートし、@bklitui/ui/charts からはインポートしないでください。 これは非公開のモノレポパッケージです。コンポーネントは components/charts/<file>.tsx（プロジェクトで src/ を使用している場合はその下）にインストールされます。ユーザーのエイリアスを使って、たとえば @/components/charts/line-chart のようにインポートしてください。インポートを参照してください。
3. インストール済みのソースを確認します。 add の後、components/charts/ 内のファイルを開き、使用前に prop 名とデフォルト値を確認してください。
4. 組み合わせて使い、平坦化しないでください。 ルートチャート → Grid/Background → 系列 → 軸 → オーバーレイ → ChartTooltip の順に構成します。composition.mdを参照してください。
5. トークンでテーマを設定します。 個別の 16 進数値ではなく、--chart-* 変数と chartCssVars を使用してください。theming.mdを参照してください。

インポート

コンポーネント項目をまとめてエクスポートする barrel はありません。各エクスポートは、それを定義しているファイルからインポートしてください（パスは components/charts/ エイリアスからの相対パスです）。

インポート元	エクスポート
line-chart	LineChart、Line
area-chart	AreaChart、Area
bar-chart / bar / bar-x-axis / bar-y-axis	BarChart / Bar / BarXAxis / BarYAxis
sparkline	LineSparkline、AreaSparkline、BarSparkline、useSparklineHover
composed-chart / series-bar	ComposedChart / SeriesBar（各チャートの Line、Area も含む）
scatter-chart	ScatterChart、Scatter
candlestick-chart / candlestick	CandlestickChart / Candlestick
live-line-chart / live-line / live-x-axis / live-y-axis	LiveLineChart / LiveLine / LiveXAxis / LiveYAxis
pie-chart / pie-slice / pie-center	PieChart / PieSlice / PieCenter
ring-chart / ring / ring-center	RingChart / Ring / RingCenter
radar-chart、radar-grid、radar-axis、radar-labels、radar-area	各ファイルに 1 つのコンポーネント
gauge	Gauge（@bklit/gauge-chart によってインストール）
funnel-chart	FunnelChart
sunburst-chart、sunburst-segment、sunburst-center、sunburst（buildArcs）…	sunburst の各パーツ
heatmap · choropleth · sankey	フォルダーの index.ts がすべてのパーツを再エクスポート
grid · x-axis · y-axis · background · reference-area · projection-line · trend-line	Grid · XAxis · YAxis · Background · ReferenceArea · ProjectionLine · TrendLine
band · bollinger	Band · withBollingerBands（@bklit/line-chart、または @bklit/band によってインストール）
weekends · deadline	Weekends · Deadline（日付軸の網掛けと期限マーカー）
tooltip · legend · markers · patterns	フォルダーの index.ts（ChartTooltip、Legend*、ChartMarkers、Pattern*）
chart-context	chartCssVars、useChart、TooltipData

import { LineChart, Line } from "@/components/charts/line-chart";
import { Grid } from "@/components/charts/grid";
import { XAxis } from "@/components/charts/x-axis";
import { ChartTooltip } from "@/components/charts/tooltip";
import { chartCssVars } from "@/components/charts/chart-context";

重要なルール

構成 → composition.md

• 系列、軸、オーバーレイ、ChartTooltip は ルートチャートの子要素です。チャートコンテキストを読み取ります。
• チャートごとにルートは 1 つです。 日付を使った棒グラフと折れ線グラフの組み合わせには、Bar ではなく SeriesBar を使う ComposedChart を使用します。
• 系列がその上に描画されるよう、Grid（または Background）を最初に配置します。
• ライブチャートには Line / XAxis ではなく、LiveLine、LiveXAxis、LiveYAxis を使います。
• BarChart では、XAxis ではなく（バンドスケールの）BarXAxis / BarYAxis を使います。

テーマ設定 → theming.md

• 系列には --chart-1 … --chart-5 を、セマンティックな役割には chartCssVars.linePrimary などを使います。
• レジストリは、アプリに既存のトークンを上書きせず、不足している --chart-* トークンを追加します。
• トークンは :root / .dark で上書きします。チャートの SVG に dark: クラスは使わないでください。

ツールチップ → tooltips.md

• ChartTooltip の content には ({ point, index }) が渡されます。rows は { color, label, value }[] を返します。
• indicatorColor は文字列、または (point) => string です。
• カスタムのクロスヘアやインジケーターには useChart() を使います。グローバルなマウスリスナーは使わないでください。

スパークライン（@bklit/sparkline）

• LineSparkline / AreaSparkline / BarSparkline は単一の要素です。data と dataKey を指定し、子要素は使いません。軸を非表示にした LineChart でスパークラインを作らないでください。
• 親要素いっぱいに表示するには width を省略します。height のデフォルトは 32 です。color、curve（デフォルトは "monotone"）、strokeWidth、endDot が使えます。エリアでは fill="gradient" | "solid" と fillOpacity、棒では barGap と barRadius が使えます。
• 設計上、ツールチップはありません。 const hover = useSparklineHover<Row>() を使い、hover.sparklineProps を展開します（複数のスパークラインに設定するとクロスヘアを同期できます）。hover.datum ?? latest は自分で描画します。crosshair（デフォルトは "dashed"、"solid"、"gradient"、false）、dot、interactive={false} が使えます。ホバーすると系列がフェードし、メインチャートと同様にホバー中のセグメントが再度ストロークされます（showHighlight、inactiveOpacity は 0.5。棒グラフではフォーカスされていない棒が 0.4 にフェードします）。クロスヘアとドットは点間をスプリングアニメーションで移動します（スナップさせるには hoverTransition={false}、調整には springConfig を指定します）。新しい data は dataTransitionDuration の時間をかけて変化します（500ms。0 を指定するとスナップします）。動きを抑える設定では、どちらもスナップします。
• 表示時のアニメーションは有効です（animate、900ms）。動きを抑える設定ではフェードに切り替わります。

オーバーレイ → overlays.md

• ChartMarkers は ChartTooltip の兄弟要素です。マーカーのホバーコンテンツは ChartTooltip の子要素に配置します。
• ChartBrush にレジストリアイテムはありません。@bklit/brush を使えると案内しないでください。
• TrendLine（@bklit/trend-line）は既存の系列の dataKey に適合させます。その系列の後に配置してください（折れ線、エリア、棒（横棒を含む）、複合チャート）。

アニメーションと読み込み → animation.md、loading.md

• 表示時のデフォルトは 1100ms、イージングは cubic-bezier(0.85, 0, 0.15, 1) です。棒はその約 40% の時間にわたって順に表示されます。
• revealSignature または新しい key を使って再生します。
• LineChart / AreaChart / BarChart / HeatmapChart では status="loading" を使います。コンポーネントを切り替えず、インスタンスは 1 つのままにします。
• 動きを抑える設定への対応は、内部では部分的です。animation.md を参照してください。

インストール → installation.md

• npm の依存関係と @bklit/* レジストリ依存関係のインストールは shadcn add に任せます。@visx/* を手動でバージョン固定しないでください。
• 既存のアプリには *-example アイテムをインストールしないでください。app/page.tsx が書き換えられます。

カタログ

すべてのアイテムは npx shadcn@latest add @bklit/<item> でインストールできます。任意の <item> について：

• ドキュメント：https://bklit.com/docs/components/<item>（アドオンは https://bklit.com/docs/utility/… 以下にあります。例：/tooltip、/legend、/axis/y-axis）
• ギャラリー：https://bklit.com/charts/<item> · Studio（プロパティの調整、コードのコピー）：https://bklit.com/studio?chart=<item>
• レジストリ JSON：https://ui.bklit.com/r/<item>.json

チャート

項目	使用する場面
line-chart	時系列、複数ラインのトレンド、マーカー、破線の末尾
area-chart	塗りつぶし領域やグラデーション／パターン塗りつぶしを使ったトレンド
sparkline	テーブルセル、KPI、統計カード、密集したグリッドに表示する小さなインラインのライン／エリア／バーのトレンド。軸、グリッド、ツールチップはありません。ホバーした値は useSparklineHover で読み取ります
bar-chart	カテゴリの比較。グループ化、積み上げ、横向き、正方形の棒
composed-chart	1つの日付軸上のバー＋ライン／エリア、2つのY軸
live-line-chart	ストリーミング／リアルタイムの値（{ time: unixSeconds, value }）
scatter-chart	時間経過に伴う点群、複数の系列
candlestick-chart	OHLC 金融データ
profit-loss-line	符号に応じて色分けされ、ゼロを横切る単一系列（Studio のスラッグも同じ）
pie-chart	全体に対する部分を示すスライス。中央に統計値を表示することもできます
ring-chart	同心円の進捗リング／ドーナツ型 KPI
radar-chart	複数のエンティティにわたる複数指標の比較
gauge-chart	0～100の単一値。円弧または目盛り付きの線形トラック
heatmap-chart	カレンダー／コントリビューショングリッド、区分化された強度
funnel-chart	ステージ間のコンバージョン
sankey-chart	ノード間のフロー
sunburst-chart	ドリルダウン可能な階層構造の部分と全体
choropleth-chart	値に応じて色分けされた地理的領域（世界地図／国別地図）

アドオン（ほとんどは依存関係として自動インストールされます）

grid、x-axis、y-axis（line／area では自動的に追加されないため、値軸が必要な場合は追加します）、chart-tooltip、legend、markers、background、patterns、reference-area、projection-line、trend-line（line／area／bar／composed 用の最小二乗トレンドオーバーレイ）、band（LineChart の範囲／ボリンジャーバンド。line-chart に含まれています）、bar-depth（BarChart の3D／押し出しバー）、chart-stat-flow（pie／ring／gauge の中央や統計カードで使用するアニメーション付き統計値）。内部処理用の項目（chart-context、chart-animation、chart-series、chart-utils、chart-parent-size、utils、shimmering-text）は自動的に追加されます。

ブラシ： ChartBrush／ChartBrushLayout（ドキュメント：/docs/utility/brush）は、現在どのレジストリ項目にも含まれていません。ユーザーがブラシズームを必要としている場合は、その旨を伝え、インストールコマンドを作り出すのではなく、ドキュメント／ソースを案内してください。

ブロック（統計カード。https://bklit.com/blocks で参照できます）

項目	内容
stat-card-area-01	収益カード：AreaSparkline（グラデーション）、ホバーして値を表示、NumberFlow、トレンドバッジ
stat-card-line-01	セッションカード：値を重ねて表示する LineSparkline、ホバーして値を表示、トレンドバッジ
stat-card-choropleth-01	訪問者カード：コロプレスのミニマップ、トレンドバッジ

エリアカードとラインカードは @bklit/sparkline（依存関係としてインストール）を基盤としており、useSparklineHover を使って、見出しの数値をホバー中の値に切り替えます。テーブル行やカスタムカードにスパークラインを表示する場合は、ブロックをインストールするのではなく、@bklit/sparkline を直接組み合わせてください。

ブロックには shadcn の card と badge が必要です。また、サンプルデータを data/ に作成し、ブロックが作成する @/components/charts バレル（components/charts/index.ts）からインポートします。2つ目のブロックをインストールすると、そのバレルと共有ファイル（stat-card-chart.tsx、stat-card-sparkline-hover.ts、trend-badge.tsx）が上書きされるため、手動でマージしてください。

ワークフロー

1. プロジェクトのコンテキストを取得します（上記のインジェクション、または npx shadcn@latest info --json）。@bklit が設定されていることを確認します。
2. データが示す内容に基づいてカタログから項目を選びます。不明な場合は確認してください。
3. インストールします：npx shadcn@latest add @bklit/<item>（必要に応じて @bklit/y-axis、@bklit/legend なども追加します）。
4. components/charts/ にインストールされたソース（CLI が書き込んだファイル）を読み、エクスポート、プロパティ名、デフォルト値、データ形式を確認します。記憶やドキュメントと食い違う場合は、そちらよりインストールされたソースを優先してください。
5. ルート → グリッド → 系列 → 軸 → オーバーレイ → ツールチップの順に組み立てます。プロジェクトのエイリアスを使い、インストール先のパスからインポートしてください。
6. トークンでテーマを設定し、ライトモードとダークモードを確認します。
7. バリエーションについては、ギャラリー／Studio の URL を案内してください。

クイックリファレンス

npx shadcn@latest info --json
npx shadcn@latest add @bklit/line-chart @bklit/y-axis
npx shadcn@latest view @bklit/line-chart     # inspect files before installing

"use client";

import { ChartTooltip } from "@/components/charts/tooltip";
import { Grid } from "@/components/charts/grid";
import { Line, LineChart } from "@/components/charts/line-chart";
import { XAxis } from "@/components/charts/x-axis";

const data = [
  { date: new Date("2025-01-01"), users: 1200, sessions: 1800 },
  { date: new Date("2025-02-01"), users: 1350, sessions: 1950 },
];

export function UsersChart() {
  return (
    <LineChart data={data}>
      <Grid horizontal />
      <Line dataKey="users" stroke="var(--chart-1)" />
      <Line dataKey="sessions" stroke="var(--chart-2)" />
      <XAxis />
      <ChartTooltip />
    </LineChart>
  );
}

関連スキル

• bklit-ui-design — デザインの用語とレシピ：パターンとテクスチャ、スクアークル／角丸／3D バー、エッジフェード、グラデーション、ローディング時の見た目、アプリのテーマに合わせたチャート。チャートの 見た目 に関するリクエストで使用してください。
• bklit-ui-migrate — Recharts、shadcn の ChartContainer／ChartConfig、または TanStack Charts（@tanstack/charts）のチャートを Bklit の同等機能に移行します。小さなチャートからスパークラインへの移行も含みます。

npx skills add bklit/bklit-ui ですべてインストールできます。

リファレンス

• composition.md — 構成、データ形状、複数系列
• theming.md — トークン、chartCssVars、ダークモード
• tooltips.md — ChartTooltip のプロパティ、カスタムコンテンツ、useChart
• overlays.md — 凡例、マーカー、参照領域、予測、トレンドライン、背景、ブラシ
• animation.md — 表示タイミング、再生、ライブチャート、動きを減らす設定
• loading.md — status、スケルトン、ローディングラベル
• installation.md — レジストリの設定、ファイル構成、依存関係