darkmatter-design-system

Darkmatter デザインシステム

これは darkmatter のデザインシステムです。Tailwind CSS v4、React 19、Radix UI を基盤にした、ダーク優先のターミナル／コンソール風のデザインです。アプリに既存のデザインシステムがない場合は、外観、トークン、コンポーネント API にこのシステムを使用してください。再利用可能な UI は引き続きリポジトリ独自の UI パッケージに配置します（ADR-0013）。@native/ui やその他のエイリアスを必須にしないでください。

セットアップ — スターターをベースに構築する

スターターはレイアウトの例であり、必須のインポートパスではありません。

• app/globals.css は tailwindcss をインポートした後、ベンダー提供の theme.css（native-tokens.css をインポートします）をインポートします。これにより、OKLCH の --n-* ランプ、shadcn のセマンティックブリッジ、Tailwind パレットのオーバーライドが設定されます。Tailwind のテーマを追加したり、トークンを再定義したりしないでください。
• ルートレイアウトでは ThemeProvider（ダークを強制）をマウントし、フォント（Inter／Space Grotesk／等幅数字）を読み込み、<html> に className="dark" を設定します。
• コンポーネントはこのリポジトリの UI パッケージからインポートしてください。スターターでは、そのパッケージは @native/ui/* としてベンダー提供されています。他のリポジトリでは異なるエイリアスを使います。workspaces／packages/*／vendor ツリーから確認してください。

画面を構築するには、アプリの下にルート／コンポーネントを追加し、UI パッケージからインポートして、システムのレイアウトプリミティブと組み合わせてください。スキャフォールドの再作成、プロバイダーの再配線、グローバルスタイルの再インポートは不要です。

インポートのルール

• UI パッケージがコンポーネントをエクスポートする方法に従ってインポートしてください（ファイルごとのパスまたはバレル。リポジトリの方式に従います）。
• cn やその他のヘルパーは、そのパッケージ内のコンポーネントの近くにあります。
• インタラクティブなコンポーネントの大半はクライアントコンポーネント（"use client"）です。フレームワークで可能な場合、ページはサーバーコンポーネントのままにしてください。
• モジュールの一覧と、各タスク領域のファイルで説明されている内容については、references/components/index.md を参照してください。

信頼できる情報源

• リポジトリ内の UI パッケージが、コンポーネント API、props、バリアントに関する唯一の権威ある情報源です。このスキルのリファレンスファイルでは、packages/ui/src/button.tsx のようなパスを例として挙げています。
• トークンは theme.css と native-tokens.css（またはリポジトリ内のそれらのファイルのコピー）からのみ取得します。16 進数／OKLCH 値をハードコードしたり、マッピングされていない標準の Tailwind シェードを使用したりしないでください。references/foundations/colors.md を参照してください。

ルーティングのルール — 構築前に読むこと

• 色とトークン → references/foundations/colors.md
• タイポグラフィとフォント → references/foundations/typography.md
• スペーシング、角丸、レイアウト → references/foundations/spacing-layout.md
• レスポンシブ対応とブレークポイント → references/foundations/responsiveness.md（レイアウト構築前に必ず確認してください）
• モーション → references/foundations/motion.md
• コンポーネントカタログとタスク領域のドキュメント → references/components/index.md
• 実例 → references/examples/

厳守事項

• ダーク優先です。このシステムが定義するのは単一のダークテーマであり、ライトモードはありません。
• デザイントークンとマッピング済みのユーティリティ（bg-n-bg-2、text-n-mute、border-n-hl、text-primary、bg-card）を使用してください。生の 16 進数／OKLCH 値や、マッピングされていない Tailwind の色は使用しないでください。
• Tailwind のブレークポイントとシステムのレイアウトプリミティブ（PageLayout、Grid）を使ってレスポンシブに構築してください。ページ構造の幅をピクセル単位で固定しないでください。
• 数値／財務データには tabular-nums（--font-num フェイス）を使い、列を揃えてください。タイポグラフィを参照してください。
• 事前の承認なしに、コンポーネント、props、バリアント、トークン名を独自に作らないでください。

最終確認

Darkmatter UI を仕上げる前に、次の点を確認してください。

• 再利用可能な UI はすべてリポジトリの UI パッケージから取得し、別のコンポーネントライブラリを混在させていないこと。
• 色が --n-* トークンまたはマッピング済みユーティリティに解決され、生の値を使っていないこと。
• レイアウトに PageLayout／Grid を使い、ブレークポイント全体でレスポンシブに対応していること。
• 数値データに tabular-nums を使っていること。
• 画面がダークで、情報密度が高く、ターミナルのような印象になっていること。Darkmatter らしさが感じられない場合は、場当たり的なスタイルではなく、基礎の指針に沿って構成を修正してください。