atai-design-system

Archetype AI デザインシステム — 一から作らず、スキャフォールドを使う

npm で公開されている、MIT ライセンスの実際のデザインシステムがあります。フロントエンドは、トークンを書き起こしたり、コンポーネントのマークアップをコピー＆ペーストしたりするのではなく、インストールして組み立てます。ds CLI は SvelteKit + Tailwind v4 プロジェクトをスキャフォールドし、パッケージをインストールして、順序が重要な CSS を適切に設定し、デザインシステム独自のエージェント設定（CLAUDE.md/AGENTS.md + ds-manifest.json）をリポジトリに配置します。その後は、同梱された設定を優先してください。コンポーネント、フォント、フォールバックの動作、スタイリングはその設定が管理します。このファイルの役割は、スキャフォールドまでを案内することだけです。

パッケージ化されたコンポーネントは現在、Svelte 5 向けに提供されています。Svelte 5 + SvelteKit + Tailwind v4 + DS パッケージという、ds create がスキャフォールドする構成そのものです。React への移植は進行中です。Newton のデモ用フロントエンドには、このスタックを推奨します。それ以外のスタック（React、Flask、プレーン HTML）では、@archetypeai/ds-lib-tokens は純粋な CSS なので、どのフレームワークからでも使用できます。トークンとベーススタイルのみで、コンポーネントは含まれません。

適用する場合

• 新しい Newton のデモ用フロントエンド／ダッシュボード／モニタリング UI を始めたい場合
• 既存の SvelteKit アプリに Archetype AI のブランディングとトークンを追加したい場合
• ブランドに沿ったコンポーネント（メニューバー、ロゴ、カード、バッジ、テーブル、ダイアログ、センサー／散布図／エリアチャート、ビデオプレーヤー、コードブロック、トースト）が必要な場合

次の場合は、このスキルを使用しないでください。

• Newton API／モデルの作業（テキスト・画像・動画の推論、埋め込み、KNN、データ準備）の場合。atai-newton-fusion-model、atai-newton-omega-model、または atai-newton-omega-model-data-prep スキルを使用してください（ソース）。

システム（MIT）

@archetypeai/ スコープの 4 つのパッケージ：

パッケージ	役割	内容
@archetypeai/ds-lib-tokens	Tailwind v4 テーマ	OKLCH のセマンティックトークン（background、foreground、card、primary、muted、destructive、border、ring、chart-1..5、sidebar、atai-{neutral,good,warning,critical}）+ ブランドカラー（brand-{babyblue,yellow,black,white}）+ フルシェードパレット（Tailwind のスケールに、カスタムの mauve／olive／mist／taupe を加えたもの、50–950）+ 間隔／角丸／アイコン線幅のスケール + .dark バリアント + システムフォールバックを含むフォントファミリースタック + 裸の h1～h6／p／code をブランドに沿ってスタイリングするセマンティック HTML ベースレイヤー。純粋な CSS で、JS は不要です。
@archetypeai/ds-ui-svelte-console	安定版プリミティブ	約 24 個の Svelte 5 コンポーネント：alert、badge、button、card、checkbox、codeblock、collapsible、dialog、dropdown-menu、dropzone、empty-state、input、input-group、item、label、progress、select、separator、sonner、spinner、table、tabs、textarea、tooltip。さらに、theme ヘルパーと utils（cn）も含まれます。
@archetypeai/ds-ui-svelte-labs	実験的なプリミティブ（console を組み合わせて構成）	aspect-ratio、chart、kbd、logo、menubar、scatter-chart、sensor-chart、slider、switch、toggle、video-player。チャートは layerchart（特定のプレリリース版に固定）を基盤としています。
@archetypeai/ds-cli（ds）	スキャフォールド + エージェント設定	create／init／add。パッケージと依存パッケージをインストールし、順序が重要な layout.css を書き込み、shadcn-svelte を設定して、デザインシステム独自のエージェント設定をインストールします。

コンポーネントごとにサブパスからインポートします。例：import { Button } from "@archetypeai/ds-ui-svelte-console/primitives/button"、import { Menubar } from "@archetypeai/ds-ui-svelte-labs/primitives/menubar"。すべてのコンポーネントについて、インポートパス、説明、usage レシピ、デフォルト値付きのバリアント軸をまとめた正式なカタログは、CLI がインストールする ds-manifest.json です。推測せず、そちらを参照してください。

Assembly Path — ds CLI

フロントエンドはこの方法で組み立てます。手動インストールよりこちらを優先してください。

CLI は必ず @latest タグを付けて実行してください（npx @archetypeai/ds-cli@latest …）。付けない場合、npx はキャッシュ済みの ds-cli のバージョンを黙って再利用するため、古いパッケージ、旧バージョンの ds-manifest.json、または置き換えられた layerchart のピン留めを使ってスキャフォールドする可能性があります。@latest を付けると、実行のたびに npx が公開済みの最新 CLI を解決します。

create を実行する前に、スキャフォールドの配置先を確認してください。 ds create <name> は、現在の作業ディレクトリに <name> という名前の新しいフォルダーを作成します。配置場所を尋ねることはありません。実行前に cwd を確認し、親ディレクトリとプロジェクト名をユーザーに確認してください。アプリが予期しない場所（たとえば、skills ディレクトリ内や別のリポジトリ内）に作成されるのを防げます。既存のプロジェクトにシステムを追加する場合は、まずそのプロジェクトに cd してから、create ではなく init を使用してください。

スキャフォールドする前に、ブランドフォントについて確認してください。 ブランド書体（PP Neue Montreal + PP Neue Montreal Mono）はライセンスが必要で、npm には含まれていません。CLI は --fonts <path-to-font-files> を渡した場合にのみインストールします（static/fonts/ にコピーされます。トークンの fonts.css はこの場所を参照します）。ファイルがない場合、アプリはシステムフォントのフォールバックで黙って描画され、ブランドの印象が明らかに損なわれます。ライセンス済みフォントファイルを所有しているかユーザーに尋ね、所有している場合はそのフォルダーを --fonts で渡してください。所有していない場合に限り --no-fonts を使用し、その場合の見た目への影響も伝えてください。フォントを自分でダウンロードしたり、代替フォントに置き換えたりしてはいけません。フォントは商用ライセンスのため、フォントファイルを公開リポジトリにコミットしてはいけません。--fonts を使用し、プロジェクトが公開されている（または今後公開される）場合は、.gitignore に static/fonts/ を追加してください。

# New project: SvelteKit (TS) + Tailwind v4 + tokens + console + labs + a demo page
npx @archetypeai/ds-cli@latest create my-app --codeagent claude

# Existing SvelteKit project: add the system in place (no demo page)
cd my-existing-app && npx @archetypeai/ds-cli@latest init --codeagent claude

# Granular adds
npx @archetypeai/ds-cli@latest add ds-ui-svelte          # editable component SOURCE (modify workflow)
npx @archetypeai/ds-cli@latest add ds-lib-tokens         # tokens + CSS imports only
npx @archetypeai/ds-cli@latest add ds-config-codeagent --claude   # (re)install agent config only

create は必要な作業をすべて行います。SvelteKit アプリをスキャフォールドし、サードパーティパッケージ内で Svelte 5 の runes が動作するように svelte.config.js を修正し、3 つすべての DS パッケージと peer 依存関係をインストールします（labs のチャートに必要な正確なプレリリース版に layerchart をピン留めします）。また、components.json と src/lib/utils.ts（ツリー内に cn は 1 つだけ）を初期化し、順序が重要な src/routes/layout.css を書き込み、エージェント設定をインストールして、デモ用の +page.svelte を作成します。

CLI はエージェントを考慮して設計されています。TTY がない場合、または --defaults を指定した場合は、まだ必要なオプション（--pm、--fonts／--no-fonts、--codeagent）を一覧表示して終了します。そのため、推測で進めず、事前にユーザーへ確認してください。配置先のディレクトリ／プロジェクト名も、同じ確認に含めてください。

2 つのインストール方式

• npm パッケージから構成する（デフォルト）。 create／init はインストール済みパッケージからコンポーネントをインポートします。アップグレードは npm update で行います。コンポーネントの内部を編集する必要がない限り、この方法を使用してください。
• ソースをインストールする／「変更」ワークフロー。 ds add ds-ui-svelte は、2 つのレジストリ（labs: https://design-system-labs.archetypeai.workers.dev、console: https://design-system-console.archetypeai.workers.dev）から shadcn-svelte 経由で編集可能なコンポーネントソースをプロジェクトに取り込みます。個別のコンポーネントを追加する場合：npx shadcn-svelte@latest add <registry>/r/<name>.json。

スキャフォールディング後は、同梱された設定を優先してください

--codeagent claude は、プロジェクトのルートにファイルを正確に2つ書き込みます（--codeagent cursor の場合は、CLAUDE.md の代わりに AGENTS.md を書き込みます）。

• ds-manifest.json — すべてのコンポーネントを1つのフラットなリストにまとめた、機械可読なカタログです。インポートサブパス、レジストリのソースURL、1行の説明、実際のプロダクトでの使用方法からまとめた usage レシピ、デフォルト値付きのバリアント軸が記載されています。コンポーネントの信頼できる唯一の情報源です。 UI を構築する際は、プロパティ名やバリアント名を独自に考えず、コンポーネントのエントリーを参照してください。
• CLAUDE.md — システムの使用方法を説明しています。スタック、順序が重要な CSS の設定、セマンティック／ステータス／ブランドのトークン、タイポグラフィのルール（システムですでに使用されている場合に限り等幅フォントを使い、ID と桁ずれしやすい数値にも適用）、ダークモード、ページシェルのパターン、API キーの取り扱い、チャートのガイダンス、カスタムコンポーネントの規約、アクセシビリティに関する必須事項、そして厳守すべきルール（node_modules は編集しない、コンソール製品限定のバリアント名は使用しない、layerchart は固定する）が記載されています。

単独のプリミティブではない複合デモ要素（再生／スクラバーのバー、サブシステムごとのステージパネル、ログ行の項目、ステータスバッジのグリッドなど）は、マニフェストのコンポーネントごとの usage レシピと CLAUDE.md のパターンに従い、プリミティブ（slider + button + card + badge）を基に構築します。これらをインポートできるとは考えないでください。生のマークアップではなく、プリミティブのレイヤーを再利用してください。

スタック

パッケージ化されたコンポーネントは現在、Svelte 5 + SvelteKit + Tailwind v4 + bits-ui（ds create がスキャフォールディングするスタック）向けに提供されています。React への移植も進行中です。Newton のデモ用フロントエンドにはこのスタックを優先し、生のトークンを使って手作業で構築したり、アセットをリポジトリにコピーしたりせず、公開済みのプリミティブを使用してください。デモに必要なもの（ロゴ、チャート、メニューバーなど）はすべてプリミティブとして提供されています。Svelte 以外のスタックでも、@archetypeai/ds-lib-tokens は引き続き利用できます。純粋な CSS なので、どのフレームワークでも動作します。

よくある落とし穴

• トークン、フォント、コンポーネントのスタイルを手作業で転記しないでください。 これらはパッケージと ds-manifest.json に含まれています。手作業でコピーした別の情報源は、気づかないうちに乖離します。マニフェストを確認し、パッケージをインストールしてください。
• 手動インストールより CLI を優先してください。 CLI は svelte.config.js の runes パッチを適用し、layerchart を正確なプレリリース版に固定し、ツリー内の cn を 1 つに保ちます。手動でインストールする場合は、この 3 つすべてを再現してください。そうしないと、パッケージのコンポーネントがコンパイルできないか、チャートが壊れます。
• Svelte スタックを優先してください。 プリミティブは現在 Svelte 5 向けに提供されています（React への移植は進行中です）。マークアップを手作業で作るのではなく、SvelteKit で ds-ui-svelte-* プリミティブを使って構築してください。ほかのスタックでは、トークンを転記する代わりに ds-lib-tokens（純粋な CSS で、フレームワークに依存しません）を使ってください。
• CLI では必ず @latest を指定してください。 npx @archetypeai/ds-cli@latest … を実行し、npx @archetypeai/ds-cli のようにバージョンを省略しないでください。バージョンを省略した npx はキャッシュ済みの CLI を再利用するため、古いパッケージやマニフェスト、または誤った layerchart のバージョン固定でスキャフォールディングすることがあります。
• スキャフォールディング先を確認してください。 ds create <name> は確認なしで、現在の作業ディレクトリに新しい <name>/ フォルダーを作成します。まず cwd を確認し、親ディレクトリとプロジェクト名をユーザーに確認してください。既存のプロジェクトにシステムを追加する場合は、プロジェクト内に cd してから init を使ってください。
• インライン要素は、何もしなければフォントサイズを継承しません。 ds-lib-tokens/theme.css は、ブロックプリミティブと合わせて、@layer base 内で span、strong、em、a、code（すべて text-sm）に明示的なサイズを設定します。明示的な値は継承より優先され、クラスのルールでも解決しません。.badge { color; border } はより具体的ですが、font-size を宣言していないため、ベースルールが引き続き優先され、10px の行内の <span> が 14px で表示されます。この問題は、各要素にサイズを設定する提供済みのプリミティブではなく、独自の文字サイズ体系でトークンを単独使用する場合に発生します。要素自体にサイズを設定するか、継承を一度だけ復元してください。その際、@layer base より優先されるようレイヤー外に置き、詳細度を持たずほかのすべてのルールが引き続き優先されるよう :where() 内に記述します。 :where(span, strong, em, b, i, code, a) { font-size: inherit; }。
• フォントを黙って省略しないでください。 --no-fonts を指定してスキャフォールディングすると、ライセンスされたブランド書体が読み込まれず（fonts.css は static/fonts/ から /fonts/PPNeueMontreal-* を要求します）、UI はシステムフォントにフォールバックします。スキャフォールディングしたアプリの見た目がブランドに合わない場合は、まず static/fonts/ を確認し、フォールバックフォントモードになっていることを必ずユーザーに伝えてください。

ファイル構成

skills/atai-design-system/
└── SKILL.md   ← this file (delegates to the published packages + the CLI-installed CLAUDE.md/ds-manifest.json)

ここにリファレンス用スクリプトがないのは意図的です。デザインシステムは公開済みの npm パッケージと ds CLI で構成され、コンポーネントの使い方、フォント、スタイルは、CLI がプロジェクトにインストールする CLAUDE.md と ds-manifest.json が管理します。このスキルは、それらを重複させずに参照します。