ak-ui

ak-ui

ak-ui のインダストリアルな幾何学、戦術的な情報階層、ターミナルのようなフィードバックを活用して、オリジナルのインターフェースを構築します。ak-ui はデザイン上の契約および CSS の基盤として扱い、特定の Arknights の画面を再現する依頼として扱わないでください。

関連するリファレンスを読む

• ビジュアルに関する判断を行う前に、必ず references/design-language.md と references/tokens.md を読んでください。
• Arknights 公式サイト、そのナビゲーションやニュースのレイアウト、抽出内容の監査については、references/official-site.md を読んでください。観察したソースの値、ak-ui による調整、未実装のパターンを区別してください。
• 登場、スタッガー、カウントアップ、メディア、パララックスのエフェクトについては、references/motion.md を読んでください。
• コンポーネントの実際の構成とコントローラーのセットアップについては、references/examples.md を読んでください。
• ak-ui >=1.1.0 で、全ページのナビゲーション、モバイルメニュー、アーカイブ／メディアのセレクター、実際のリソース進捗、またはパーティクルフィールドを扱う場合は、references/site.md を読んでください。公開されている /site コントローラーまたは Registry site を使用してください。公式シェーダーを創作したり、CSS だけでインタラクションが追加されると想定したりしないでください。
• ネイティブコントロールやスタイルのないライブラリ、またはヘッドレスライブラリを調整する場合は、references/headless-components.md を読んでください。
• プロジェクトで Reka UI を使用している場合、または Vue のヘッドレスプリミティブが必要な場合は、references/reka-ui.md も読んでください。
• 作業の完了を宣言する前に、references/quality-checklist.md を読んでください。

変更する前に調査する

可能な限りユーザーに質問せず、プロジェクトから次の情報を特定してください。

1. フレームワーク、パッケージマネージャー、スタイリングシステム、既存のデザイントークン。
2. 既存のアクセシブルなプリミティブ、ヘッドレスライブラリ、ak-ui のインストール状況。
3. 対象範囲のコンポーネントやページと、そのインタラクション状態。
4. 維持する価値のある既存のブランドカラー、フォント、間隔、コンテンツ階層。

不足しているプロダクト上の選択によって結果が大きく変わる場合に限り、質問してください。ドキュメント化された例を使うためだけに、既存のヘッドレスライブラリを置き換えないでください。

スタイルの強度を選択する

明示的に指定されたモードに従ってください。

• accent：現在のブランドとレイアウトを維持し、ak-ui のタイポグラフィ、シグナル、フォーカス、控えめな幾何学的要素を追加します。
• system：サーフェス、階層、密度、幾何学的要素、状態にデザイン言語全体を適用します。デフォルトではこのモードを使用してください。
• terminal：没入感のある構成、非対称なコマンドプレーン、テレメトリー、奥行き、より強い動きを追加します。ページ構成が変わる可能性があるため、要求された場合、または明確に示唆されている場合に限り使用してください。

選択したモードを実装の概要に記録してください。モードをカラーテーマとして解釈しないでください。

最小限の統合方法を選ぶ

次の順序で進めてください。

1. 適合する場合は、既存の ak-ui CSS クラスとコンポーネントを再利用します。
2. カスタムのサーフェス、またはヘッドレスのみのサーフェスには、@yunyoujun/ak-ui/tokens.css をインポートし、セマンティックトークンで既存の動作をスタイリングします。
3. ak-ui Registry にすでに存在する Vue コンポーネントには、編集可能な Registry アダプターを優先して使用します。
4. 必要な動作が不足している場合は、まずプロジェクト既存のヘッドレスプリミティブを使用し、次にブラウザー標準のセマンティクスを使用します。
5. Reka UI は、アクセシビリティと状態管理の仕組みが必要な Vue のインタラクションに限り追加します。プレゼンテーションのみの要素には追加しないでください。

プロジェクトのパッケージマネージャーを使用してください。すべてのスタイリングは .ak-*、プロジェクト所有のコンポーネントクラス、または data-ak-ui を通じてオプトイン方式にし、グローバルリセットを追加したり、無関係な要素を上書きしたりしないでください。

デザイン契約を守る

• 既存のブランドカラーを新しいパレットに置き換えるのではなく、既存のブランド値をセマンティックな --ak-* トークンに割り当てて、ユーザーのブランドを維持します。
• 繰り返し使うデザイン判断には、公開されている ak-ui トークンを使用します。色、間隔、タイミング、カットサイズをハードコードして散在させないでください。
• 挙動、フォーカス管理、キーボード操作、ARIA、状態は、ネイティブまたはヘッドレスのプリミティブに委ねます。描画されるパーツと状態属性を ak-ui のスタイルに割り当ててください。
• あらゆるエッジを装飾するのではなく、力強い幾何学的なアクセントを一つ設け、明確な情報階層を構築します。
• ステータスカラーは機能的で、見分けやすいものにします。状態を示す手段を色だけにしてはいけません。
• オリジナルまたはユーザー提供の画像を使用します。ゲームのアセット、ロゴ、キャラクターアート、特定の画面構成を入手、コピー、模倣してはいけません。
• ユーザーが破壊的な再設計を明示的に依頼していない限り、既存の公開 API を維持します。

指定されたワークフローを適用する

統合

CSS パッケージまたは Registry アダプターをインストールし、必要最小限のインポートを追加して、代表的なコンポーネントを一つ描画し、実際のビルドでインポートを検証します。

構築

まず情報階層とレスポンシブレイアウトを確立します。既存のプリミティブを組み合わせ、プロジェクトのコンテンツを追加してから、選択したスタイルの強度を適用します。実際の製品情報を伝えない限り、デモのようなプレースホルダーのテレメトリーは避けてください。

拡張

スタイルを適用する前に、コンポーネントの契約を定義します。パーツ、状態、キーボード操作、フォーカスの所有者、レスポンシブ対応の制約を記述してください。既存のプリミティブを再利用またはラップし、表示と挙動を分離します。

レビュー

デザイン契約への具体的な違反を、可能であればファイルの場所も含めて報告します。ユーザーが実装を依頼した場合にのみ問題を修正します。見た目の違いよりも、セマンティクス、インタラクションの喪失、トークンの逸脱、読みにくい情報階層、モバイルでのはみ出しを優先します。

検証

プロジェクトで関連する lint、型チェック、ビルド、テストを実行します。ブラウザーのツールを利用できる場合は、デスクトップとモバイルのレイアウトに加え、該当するキーボードフォーカス、開閉、選択済み、無効、無効な入力、読み込み中、動きを抑えた表示の各状態を確認します。

コンパイルだけを根拠に、ビジュアル面の完成を主張してはいけません。ブラウザーで検査できない場合は、その制約を明記し、品質チェックリストに沿って残りの確認項目を提示します。