antfu-design

@antfu/design で優れたデザインを実現する

@antfu/design は、開発ツール風の Vue アプリ向けに共有されるデザインレイヤーです。コンポーザブルな UnoCSS プリセット（presetAnthonyDesign）、トークン駆動の Vue プリミティブ群、そして色コントラストのアクセシビリティチェックで構成されています。このスキルでは、語彙、デフォルト設定、そしてデザインの勘所を含め、これをうまく使う方法を説明します。

最も重要な3つのルール

1. 色ではなく、トークンを使いましょう。 アプリの UI では、16進カラーコードや Tailwind の生の色をハードコードしないでください。まずはセマンティックレイヤーを使いましょう。bg-base、color-base、color-muted、border-base、op-fade、btn-action、badge などです。これらは（プリセット内で）一度定義され、ライトモードとダークモードに自動的に適応します。references/core-tokens.md を参照してください。

2. ライトモードとダークモードの両立は必須です。 すべてのサーフェスおよびテキスト用トークンには、ダークモード用のバリエーションが組み込まれています。独自の色をひとつ書けば、ダークモードの不具合を作ったことになります。常時実行されるコントラストスキャン（@antfu/design/a11y）で重大な問題は検出できますが、トークンを使う代わりとして頼らないでください。

3. 雑に仕上げないでください。 技術的な値には font-mono tabular-nums を使います。UI の文言には、ダッシュを多用しないでください（ダッシュ禁止）。競合する選択肢を3つ並べるより、明確なアフォーダンスをひとつ選びましょう。references/best-practices.md を参照してください。

4. 作る前に再利用しましょう。 UI を作成したりコンポーネントを使用したりするときは、新しいコンポーネントを作ったり、インライン DOM 要素を作成したりする前に、@antfu/design のコンポーネントを再利用できるか必ず確認してください。まずカタログに目を通しましょう（references/core-components.md）。

再利用ルールを AGENTS.md に記録する

利用プロジェクトの今後のエージェントにもルール4を適用するため、プロジェクトの AGENTS.md にまだ記載されていない場合は、次の指示を追記してください。

When making UI or using components, always check if components from
`@antfu/design` can be reused, before making new components or creating
inline DOM elements.

用途に応じた選び方

• 件数、サイズ、期間、日付を表示する → 生のテキストではなく、表示コンポーネント（DisplayNumber、DisplayBytes、DisplayDuration、DisplayDate）。
• ステータス、種類、タグ → DisplayBadge（ハッシュまたはパレットで色付け）または DisplayLabel。
• ファイルやモジュールのパス → DisplayFilePath（省略表示し、ディレクトリを薄く表示し、リンクを付けます）。
• オーバーレイ → OverlayModal / OverlayDrawer（reka-ui）、ポップオーバー → OverlayTooltip / OverlayDropdown。
• 重要度（新鮮→古い、高速→低速、小→大） → colorize プロパティを使って表示コンポーネントから color-scale-* のカラースケールを使用し、場当たり的に赤や緑を使わないでください。

コンポーネントはカテゴリ別に分類され、カテゴリ名を接頭辞に持ちます（Display*、Form*、Overlay*、Layout*、Action*、Feedback*）。ダークモードの管理はアプリ側で行います。このパッケージには isDark / toggleDark（ダークモード切り替えコンポーネントも含む）はありません。カラースキームによって表示が変わるコンポーネントには、colorScheme: 'light' | 'dark' プロパティを渡します。切り替えボタンを作る場合は、ActionIconButton と VueUse の useDark を組み合わせてください。

全カタログ：references/core-components.md。

セットアップ

これは単一のプリセットであり、それだけで完結するものではありません。ベースプリセット、アイコン、フォント、リセット CSS は含まれていないため、別途追加してください。プリセットの設定、スタイルのインポート、コンポーネントのクラスが生成されるように UnoCSS でパッケージを指定する方法については、references/core-setup.md を参照してください。

参考資料

• core-setup.md — プリセットのインストールと接続、スタイルのインポート。
• core-tokens.md — プリセットから生成される、正式なトークン一覧。
• core-components.md — インポートパスを含むコンポーネントカタログ。
• recipes.md — パッケージに含まれない小規模な構成（例：ダークモード切り替え）。
• best-practices.md — attributify よりクラスを優先する方法、パリティ、単一値、ダッシュ禁止、「3つのダイヤル」。
• features-data-presentation.md — 数値、サイズ、期間、パスの表示。
• advanced-patterns.md — 構成パターンと再設計プロトコル。
• storybook.md — Storybook のセットアップ：テーマと同期する manager+preview、自動ドキュメント、生成される Overview。