ui-ux

ダッシュボードシステムの UI/UX

項目 0 を最後まで確認するまで、このターンではコードを一行も書かないでください。 デフォルトではデザイナーとして進めます（references/design-process.md、分岐 U）：ブリーフ、 各画面の主要タスク、2～3 個のワイヤーフレームを用意し、ユーザーが選んでから構築します。依頼がベトナム語でも英語でも同じです。 この分岐で確認を待つのは 2 つのゲート（ブリーフの承認、ワイヤーフレームの選択）だけです（デザインシステムのルートには専用ゲート D9 があり、ロゴ作成のルートにはロゴ選択のゲート components/logo.md があります）。それ以外では質問しません。依頼が不明確な箇所はデフォルトを採用し、納品時に選択内容を伝えます。 ほかの分岐に進むのは、依頼で明示された場合のみです（質問 1）：既存 UI のレビュー（references/review.md）ならそのままレビューし、修正する場合は確認します。ブランドを維持して作り直す、スキルの作風に沿って作り直す、リファクタリングする、ワイヤーフレームなしでそのまま構築する、先にデザインシステムを構築する、小さなコンポーネントを修正する、といった分岐があります。

このスキルは形容詞で「美しさとは何か」を教えるものではありません。行うのは 3 つです。構築前に正しい順序で進めること、AI が作ったとすぐ分かる UI になる習慣を禁止すること、残りの部分が自然に整うよう数値で制約することです。

対象範囲：アプリ内の画面です。ダッシュボード、一覧、テーブル、フォーム、設定、モーダルが該当します。販売ページは対象外ですが、料金表（references/layouts/pricing.md）は対象です。

依頼がこの UI スキルで扱われていない種類の場合は、最初に一行伝えてから作業してください。対象には、ランディングページ、紹介ページ、Web サイトのホームページ、購入者向けオンラインストア（ショップのホームページ、商品ページ、カート、決済）、ブログ（ブログのホームページ、記事ページ）、および類似のもの（ポートフォリオ、イベントページ）が含まれます。これらの管理側（注文、商品、記事の管理）はアプリ内の画面であり、この対象外グループには含まれません。通知は最初の回答の冒頭、監査の行より前に、依頼と同じ言語で記載します。

注意：このスキルはランディングページ／オンラインストア／ブログ向けには学習されていないため、作成はできますが、結果はアプリ内の画面ほど見栄えがよくない可能性があります。アプリ内の画面と共通する部分（料金表、選択用のスクロール一覧、フォーム）は、承認済みのパターンに従います。

これは通知であり、ゲートではありません。作業を続けるかどうかの確認で止まらず、ほかの依頼と同様に質問 1 に進みます。パターンがないページ部分は、「パターンのないものを構築する」フロー（references/principles.md の末尾）に従います。⚑

このスキルの対象はUIです。レイアウト、スタイル、および各状態の見た目（選択中、ロック中、空、読み込み中、エラー、1 ページ、行なし）を扱います。処理ロジックは作成しません。ページをクリックしたときに何を呼び出すか、行数を変更したらどこに戻るか、URL に保存するか、どの API を呼び出すか、といった内容です。該当箇所には空の prop またはハンドラー（onPageChange、onConfirm）を用意し、ユーザーが独自に接続できるようにします。複数の状態を確認する必要がある場合は、各状態の静的な例を横に並べて作成し、操作して確認する形式にはしません。

---

項目 0 の前に — 新しいバージョンを通知 ⚑

セッション内でこのスキルを初めて呼び出すときは、node <このスキルのディレクトリ>/scripts/check-update.mjs を実行します。これは項目 0 のステップではなく、ほかのコマンドと同時に実行してもかまいません。

• 何も出力されない場合：何も言わず、触れません。
• UPDATE <cũ> -> <mới> | <lệnh> と出力された場合：回答は、依頼の言語で次の形式の一行から始めます。「Skill ui-ux có bản mới <mới> (đang dùng <cũ>), cập nhật: <lệnh>」。この行は、未対応の UI 種類に関する通知よりも前に置きます。その後、同じターン内ですぐに本来の作業を続けます。
• **確認を求めたり、更新コマンドを自分で実行したりしません。**更新したい場合はユーザー自身が実行します。作業途中で更新すると、構築中にルールが変わってしまいます。
• Node がない、コマンドがエラーになる、または権限を拒否された場合：無視して、何も伝えません。

---

0. 4 つの質問を、必ずこの順番で

質問 1 — どのルートで進めますか？ デフォルトはデザイナーとしての進め方です

これは最初の質問で、何よりも先に確認します。ルートによってリスク、ステップの順序、承認が必要な人が異なります。

表を上から順に読み、最初に当てはまる行が見つかったらそこで止めます。プロジェクトオーナーの決定により、最後の行がデフォルトで、その上の9行は依頼で明示された場合（ベトナム語または英語）のみ適用します。

依頼内容	進め方
新しい版と元の版を比較する（「元の版と比較して」「元のページと比べて」「何が良くなったか」「良くなったか悪くなったか」「…と比べて問題ないか」「compare with the original」「is it better than before」）	references/review.md の V6：両方の版を同じ条件でキャプチャし、元／新しい版／優れている方を基準ごとに並べた表を作成します。劣っている行を必ず見つけ、劣っている行ごとに修正案を提示します。ユーザーが行を選ぶまでは修正しません。ここでセクション0を終了します ⚑
現在のUIの問題点を知りたい（「見てもらえますか」「レビュー」「問題点」「ごちゃごちゃしている」「check this UI」「what's wrong with」、自分のアプリのスクリーンショットやリンクを送って確認を依頼する）	references/review.md を開き、V の診断モードに進みます。変更前／変更後の表を作成し、ユーザーが行を選んでから修正します。ここでセクション0を終了します。引き渡し時は S15 ではなく V5 に従います ⚑
ブランド／外観を保って作り直す（「ブランドを保って」「色を保って」「現在の外観を保って」「整えるだけ」「keep the brand」「keep the current look」）	references/review.md のブランド維持の再構築モード：ページ構成を保ち、既存のコントロールをスキルのコンポーネントに置き換え、色の役割を維持します。古いスタイルを捨てるという依頼はこの行には該当しません。スキルのデザイン方針に沿った再構築の行を参照してください。ここでセクション0を終了します ⚑
見た目を変えずにリファクタリング／コードを整理する（「refactor」「Tailwindに移行」「CSSを整理」）	references/refactor.md を開き、L に進みます。ここでセクション0を終了します — このルートには独自のデフォルトがあり、「結論を出す前に測定する」ことから始めます
ロゴを作る（「ロゴを作る」「ロゴをデザインする」「ロゴを差し替える」「design a logo」）	references/components/logo.md を開きます。質問2の監査を行い、次にサイドバー、ログイン画面、ブラウザーのタブに配置した3案のロゴ選択ページを作成します。確認は1回のみ：ユーザーが案を選びます。依頼に「必ず」とあれば、推奨案をそのまま作成します。ここでセクション0を終了します ⚑
ワイヤーフレームなしですぐに作る（「すぐに作る」「ワイヤーフレームは不要」「just build it」「skip the wireframe」）	ワイヤーフレームを描かない U ルート：U1、U2 を実施し、推奨案を内部で選んで、その案に沿ってすぐに作成します（design-process.md のファイル先頭）。質問はしません。質問2の監査は引き続き U1 で実施します。ここでセクション0を終了します
先にデザインシステムを作る（「design system」「先にコンポーネントを作る」「UI kit」「先にトークン／スペーシング／タイポグラフィを決める」「build a design system」「component library first」）	references/system.md の D9 を開きます。トークン、D1 の7つの基本要素に加えて依頼で指定された要素、デザインシステムのプレビュー用ページを作成します。ワイヤーフレームは描きません。確認は1回のみ：そのページを承認します。以降の画面作成は通常ルートで進めます。質問2の監査を除き、ここでセクション0を終了します ⚑
画面1つ未満の小さな作業：コンポーネント1つの修正、ドロップダウン1つの追加、バグ1つの修正、色1つの変更	質問2に進み、デフォルトのレイアウト（質問4）で作成します。質問はしません
古いスタイルを捨てて、スキルのデザイン方針に沿って作り直す（「完全にスキルのデザイン方針に従って」「古いスタイルを捨てて」「スキルのデザイン方針に変更して」「古いスタイルを維持しなくてよい」）	references/review.md のスキルのデザイン方針に沿った再構築モード：ページ構成を保ちつつ、外観と色の役割の両方をスキルのデザイン方針に沿って変更します。ここでセクション0を終了します ⚑
画面1つ以上を作成または作り直すすべての依頼（「注文一覧画面を作成」「このページをきれいに作り直して」「スキルに沿って作り直す」「一からデザインする」「build a settings page」「redesign this screen」）、新製品でも既存画面でも	デフォルト。 references/design-process.md を開いて U ルートに進み、各画面の概要と主要な作業を整理してから、2～3案のワイヤーフレームを作成します。ユーザーが選んでから作成します。質問2の監査を除き、ここでセクション0を終了します。既存のUIがあるプロジェクトでも、監査は引き続き U1 で、概要を書く前に実施します ⚑

ユーザー自身のワイヤーフレーム画像が依頼に含まれている場合、それがすでにワイヤーフレームのステップです。U4 から U ルートに入り、画像に従って作成します（S13～S15）。コード整理と見た目の変更の両方が依頼されている場合は、先に U に進み、その後 L に従って整理します。診断またはブランド維持が依頼されている場合は U の代わりに V を使い、L はその後に進めます。

質問 2 — プロジェクトでは何を使っていますか？（自分で調べて、聞かないでください）

監査はゲートであり、参考手順ではありません。 以下のコマンドブロックを 実行し終えるまでは、レイアウトファイルを開いたり、レイアウトを提案したり、 コードを一行でも書いたりしてはいけません。「ドロップダウンを追加する」 といった小さな課題でも同じです。

このスキルはコードベースに沿って進めます。自分のツールセットを他人の プロジェクトに押し付けることはありません。監査は3層で行います。スタック （プロジェクトで何を使っているか）、コンポーネント（これから作ろうとする ものがすでにあるか）、スタイル（プロジェクトがフラット、グラス、 グラデーション、ダークのどれか）です。

# Tầng 1 — stack
ls package.json 2>/dev/null || echo "KHÔNG CÓ package.json — xem dòng cuối bảng"
cat package.json 2>/dev/null | grep -E '"(tailwindcss|@radix-ui|@mui|antd|@chakra|bootstrap)"'
ls components/ui src/components/ui 2>/dev/null          # dấu hiệu shadcn
# thư viện chuyên dụng: biểu đồ, lịch/ngày, bảng, danh sách ảo
cat package.json 2>/dev/null | grep -E '"(recharts|chart\.js|react-chartjs-2|echarts[a-z-]*|@tremor/react|@nivo/[a-z]+|victory|react-apexcharts|react-day-picker|react-datepicker|@mantine/dates|@fullcalendar/[a-z]+|react-big-calendar|date-fns|dayjs|@tanstack/react-table|@tanstack/react-virtual|react-window|react-virtuoso|ag-grid-react)"'
grep -rn "@import\|@theme\|--primary\|--brand\|font-family" \
  app/globals.css src/index.css tailwind.config.* 2>/dev/null | head   # không có `@import "tailwindcss"` = không preflight, W9

# Tầng 2 — thứ sắp dựng đã có chưa. Thay TÊN bằng thứ đang dựng:
# avatar, dropdown, menu, modal, dialog, button, input, badge, toast...
find . -path ./node_modules -prune -o -iname "*TÊN*" -print 2>/dev/null | head
grep -rliE "function TÊN|const TÊN|export.*TÊN" --include="*.tsx" --include="*.jsx" \
  --include="*.vue" --include="*.svelte" . 2>/dev/null | grep -v node_modules | head

第2層は見落とされがちです。 プロジェクトに Avatar があるのにもう一つ 作ると、アプリ内に異なるアバターが2種類でき、新しく作ったほうが他の箇所と ちぐはぐになります。すでにある場合はプロジェクトのものを使い、ルールに 反する場合に限りトークンを調整します。

次に進む前に、監査結果を一行で報告してください。何も見つからなかった 場合も同じです。

Audit: Next + Tailwind v4、shadcn あり。トークンは globals.css にあります。 components/ui/avatar.tsx に Avatar がすでにあります — これを使います。 ドロップダウンはまだありません — 新しく作成します。

この一行によって、監査を省略したことが見えるようになります。この一行が なければ、AI が確認したのか、推測したのかをユーザーは判断できません。

第3層 — スタイル。 行数ではなく、兆候が見られるファイル数を数えます。

count_files() {
  grep -rlE "$1" --include='*.tsx' --include='*.jsx' --include='*.vue' --include='*.svelte' \
    --include='*.html' --include='*.css' --include='*.scss' . 2>/dev/null \
    | grep -viE 'node_modules|dialog|modal|popover|dropdown|menu|select|toast|tooltip|sheet|drawer|command' \
    | wc -l | tr -d ' '
}
echo "glass:    $(count_files 'backdrop-blur|backdrop-filter')"
echo "gradient: $(count_files 'bg-gradient-|bg-linear-|bg-radial-|linear-gradient\(|radial-gradient\(')"
echo "nổi:      $(count_files 'shadow-(md|lg|xl|2xl)')"
# Màu: nền / viền / chữ có sắc dùng làm trang trí hay phân vai, không phải trạng thái
echo "màu:      $(count_files '(bg|border|ring)-(blue|sky|indigo|violet|purple|fuchsia|pink|cyan|teal)-(50|100|200)|bg-primary/(5|10|15|20)|bg-(accent|brand)')"
# Thang màu biểu đồ có sẵn (shadcn sinh --chart-1..5)
grep -rhoE -- '--(chart|categorical|category)-[a-z0-9-]*' --include='*.css' . 2>/dev/null | grep -v node_modules | sort -u | head
# Tối: chỉ cần MỘT file, là layout gốc
grep -rlE '<(body|html)[^>]*(bg-black|bg-(zinc|neutral|slate|gray|stone)-9[0-9]{2})|color-scheme: *dark' \
  --include='*.tsx' --include='*.jsx' --include='*.html' --include='*.css' . 2>/dev/null | grep -v node_modules | head -3
# Token phong cách: có là có chủ đích, dù đếm file ra ít
grep -rhoE -- '--(glass|gradient|shadow|blur)[a-z0-9-]*' --include='*.css' . 2>/dev/null | grep -v node_modules | sort -u | head

このコマンドでは、dialog、dropdown、toast などのファイルを意図的に除外 しています。M15 では浮遊レイヤーにシャドウとブラーを使うためです。除外 しないと、shadcn を使うフラットなプロジェクトがすべて「浮遊」として数え られてしまいます。

数値は references/styles.md の P4 に従って読み取ります。プロジェクトに 固有のスタイルがなければフラットです。固有のスタイルがある場合はプロジェクト のスタイルに合わせ、引き渡し時に報告します（P1）。

Audit: の一行にスタイルを追加します。

Audit: Next + Tailwind v4、shadcn あり。Avatar はすでにあります。 スタイル：7ファイルでグラス（card、sidebar、header）— この画面も 統一感が出るようグラスにします。

続いて、次の表に従います。

見つかったもの	対応
Tailwind（このスキルのデフォルト）	通常どおりutilityを使います。Tailwind v4の場合は、@theme に触れる前に references/tailwind-v4-traps.md を読みます
Tailwind がない	プロジェクトの規約に従います — CSS Module、styled-components、SCSS など、何でも構いません。このスキルが定めるのは トークン、リズム、レイアウト、範囲 であり、スタイルの書き方ではありません。スキル内のルールではTailwindのクラスを使っていますが、色は references/tokens.css の変数に置き換え、色コードを自分で選ばないでください。text-rose-700 → var(--danger)、badge bg-emerald-50 text-emerald-700 → --success-bg / --success。対応表は M7、M30 に、アバターの色は components/avatar.md にあります
shadcn / Radix / MUI / Ant / 社内ライブラリ	プロジェクトのコンポーネントを使います。 shadcn がすでにあるプロジェクトで Button を書き直すのは、一貫性を損なうことであり、見た目を良くすることではありません
専門ライブラリ（チャート、カレンダー、テーブル、仮想リスト）	あれば正しく使い、このスキルの見た目に調整します（最初から有効になっている機能をオフにし、色にはトークンを使います）。なければ自分でインストールしません。references/components/ の例に従って通常どおり作成し、自作するとコストがかかる場合（大量のデータ、ズーム、リアルタイム、多種類のチャート）に限り提案します。選定基準は、軽量であること、要件を適切に満たすこと、トークンで色を指定できること、保守が続いていること、既存のエコシステムに適合することです。理由を添えて一行で提案します。インストールするかどうかはユーザーが決めます（N10）。チャートの設定例は components/charts.md にあります
コンポーネントがない	references/components/ のコード例を提案します。どこに配置すればよいか明確に説明します
package.json がない	素のHTML/CSS、またはWordPress、PHP、Rails、Djangoです。references/components/ の例は .tsx で書かれています — HTMLタグとclassに置き換えてから渡し、ReactのないプロジェクトにJSXを貼り付けないでください。references/tokens.css は素のCSSなので、そのまま貼り付けられます

コピーの言語もこの段階で調べます — i18n と既存ラベルを grep し、ルール T24 に従います。最初のラベルを書く前に決めてください。推測を間違えると、 一行ではなくすべてのラベルを修正することになるためです。コピーがベトナム語 でない場合は、T28、T29 を開きます。

既存のトークンがあれば使い、質問はしません。 grep して何も見つからなかった 場合に限り、references/tokens.css を使ってそのまま設定します。依頼者が ブランドガイドをすでに持っている可能性があっても同じです。アクセントカラーと フォントを一か所にまとめ、引き渡し時にその場所を伝えれば（S15）、依頼者が 自分で差し替えられます。フォントの数は絶対に尋ねません。 スクロールバーは、プロジェクトにトークンが用意されていても必ずコピーします。「既存のトークンを使う」というのは、色とフォントに限ります。tokens.css のスクロールバー用ブロック（* { --scrollbar-thumb から .scrollbar-clean の末尾まで）と ScrollbarAutohide コンポーネント（I18）は見た目の形であり、ブランドではありません。元の CSS で ::-webkit-scrollbar を grep し、まだない場合や別のバージョンの場合はコピーします。このブロックがないと、ブラウザーはページ、サイドバー、横スクロールするテーブル、ドロップダウンなど、すべてのスクロール領域に大きくて粗いデフォルトのスクロールバーを表示します。純粋な HTML のページやワイヤーフレームにもコピーします。

相手のライブラリを使う場合、スキルを適用する方法はトークンを合わせて調整することに加え、ルールに反するデフォルトをいくつか修正することです。shadcn なら、通常は次の 3 か所です。

• Input のデフォルトは bg-transparent → surface の背景に変更します。ページの背景に溶け込む入力欄では、ユーザーは入力欄だと気づきません。
• Button にはデフォルトで複数の variant と size があります → ライブラリの選択肢は削除せず、I1 のルールにある 4 種類だけを自分で使うように制限します。
• 影を確認します。多くのセットではカードに shadow-sm がデフォルトで適用されていますが、M15 のルールでは影を浮き上がったレイヤーにのみ使用します。

質問 3 — UI をどのような見た目にしますか？

デフォルトのスタイルはフラットです。references/styles.md の P1 に従います。

• ユーザーがスタイルを指定した場合（「グラスモーフィズム風」「SaaS のランディングページ風のグラデーション」など）→ そのとおりにし、聞き返しません。references/styles.md を開き、そのスタイルのブロックを確認します。
• レベル 3 の監査で、プロジェクトがフラット以外のスタイルだと分かった場合 → プロジェクトのスタイルに合わせて、そのまま制作します。納品時に、どのスタイルに合わせたかと、それを確認した場所を一行で伝えます。フラットにしたい場合は言ってもらいます。例は P1 を参照してください。
• それ以外の場合 → フラットにします。スタイルについて質問しません。

どのスタイルを選んでも、references/styles.md で該当するブロックを確認します。そのブロックには、どのフラットスタイルのルールを上書きするかと、そのスタイル特有の落とし穴が書かれています。原則は、どのスタイルでも上書きできません（P2）。

参考画像、説明、似せたい製品がある場合は、それに合わせて制作し、この質問の残りの内容は無視します。

「まだ分からない」「おまかせ」「いい感じにして」と言われた場合 → A の方向で制作し、納品時に B と C の方向もあることを一行で伝えます。希望があれば言ってもらいます。事前に質問しません。

方向性	見た目	向いている場合
A. 細い線のフラット (このスキルのデフォルト)	薄いグレーの背景、白いカード、ごく薄い 1px の枠線、角丸約 12px、影なし。文字サイズと太さで階層を表現します	ほとんどのダッシュボード。小さなブロックが隣り合っていても境界が分かります。このスキルのすべてのルールはこの方向に沿って書かれています
B. 沈み込むブロック	枠線なし。背景の色の差と余白でブロックを分け、白いカードをグレーの背景から浮かせます。角丸は大きめです	ブロック数が少なく、各ブロックが大きい画面。A よりすっきりして柔らかな印象です。その代わり、小さなブロックが隣り合うと境界が曖昧になります
C. データ密度重視	テーブルが主役です。文字は小さく、行間は詰め、角丸は小さく、罫線は明確にし、一度に見られる行数を優先します	運用テーブル、取引記録、ログなど、一日中使う画面。その代わり「詰まった」印象になり、概要画面には向きません

B または C を選ぶ場合は、どのルールを上書きするかを明確に伝えます。B は M13（枠線で分ける）と M15 を上書きします。C は references/budgets.md のリズムに関する部分を上書きします。次の作業者が「ルールどおりに」直してしまわないよう、納品時に一行記載します。

選択したら、この質問にも答えます。ダークモードが必要かどうか。 デフォルトでは不要です。M20 を参照してください。

フォームがある場合、入力欄のデフォルトでは左側にアイコンを付けません。 質問せず、アイコンなしで制作し、納品時に一行で伝えます。「入力欄はシンプルな状態にしています。左側にアイコンを付けたい場合はお知らせください。」 希望があれば、references/components/input.md に従って制作し、アイコンは F15 から選びます。

認証画面のデフォルトセットも同様です。references/layouts/form.md を参照してください。デフォルトで制作し、一行で伝えます。質問一覧にはしません。

câu 4 — レイアウト：デフォルトのレイアウトを構築し、一言報告する

ユーザーがワイヤーフレーム画像を渡せば、AIはちゃんとしたものを作ります。ユーザーが 言葉で説明するだけだと、色パレット、文字サイズ、間隔のスケールがすべて そろっていても、AIはあれこれ適当に描いてしまいます。理由は、デザインシステムが 決めるのは色、サイズ、間隔であり、何をどこに配置するかではないからです。 ページの良し悪しを決めるのはレイアウトであり、どんな色のルールも でたらめなレイアウトを補うことはできません。

防止策：画面の種類ごとに、デフォルトのレイアウトを一つだけ用意し、 layout ファイルに記載します。勝手に作らず、選択肢も並べません。

1. 画面の種類を判別します。 これは何の画面なのか、アプリ内画面、フォーム、オーバーレイ、料金プランのどれなのかを明確にします。画面の種類によって、開く layout ファイルが決まります。
2. layout ファイルを開き、デフォルトのレイアウトを使います。 ファイルに条件（「フィールドが8つ以上ならB」など）が記載されている場合は、その条件に従います。これは好みではなく、依頼内容から導かれるものだからです。
3. そのまま構築し、引き渡すときに一言報告します。 どのレイアウトを構築したかを伝え、別のスタイルがよければ言ってもらいます。

横並びのカード3枚で料金プランを構築し、Proプランを目立たせています。ひとつにまとめたり、 ボタンを上に移動したりしたい場合はお知らせください。

スキルが対応するのは、最もシンプルで標準的なデフォルトです。バリエーションはユーザーが決めます。 希望を伝えられたらそれに合わせて変更し、聞き返しません。

質問4は、1画面未満の小さな作業（質問1）でのみ適用されます。デフォルトは U 分岐です。ここでのデフォルトのレイアウトは、ワイヤーフレーム案のひとつで、 通常は推奨案です。

⚠️ 古いルールは廃止済みです。復活させないでください。「レイアウト案を2～3個、言葉で 提示してから、選ばれるまで完全に停止する」。ユーザーが何も見る前に選択を迫られ、 あらゆる画面の種類について各 layout ファイルに複数案を用意しなければならないため、廃止されました。 デフォルトの U 分岐（プロジェクトのオーナーが確定）は、そのルールの復活ではありません。 ユーザーは、内容が実際に入っていて、probe 済みで、クリックして開けるワイヤーフレームを 見てから選択します。各 layout ファイルに用意するデフォルトのレイアウトは、引き続きひとつだけです。

画面の種類	開くファイル
ダッシュボード、開始手順（オンボーディングチェックリスト）、リスト、テーブル、空のリスト、設定、個人プロフィール、セキュリティ（二要素認証、ログインセッション）、API キー、メンバーと権限、カレンダーページ（月間カレンダー）、エラーページ（404、403、500、メンテナンス）、レポートページ（売上、期間別分析）、ページヘッダー（パンくずリスト＋タイトル＋ボタン）、レコード詳細ページ	references/layouts/app.md
ログイン、登録、パスワードを忘れた場合、複数フィールドのフォーム、複数ステップのフォーム（ステップバー）、エラー状態	references/layouts/form.md
モーダル、スライドパネル、ドロップダウン、コマンドパレット、通知パネル、トースト、すべてのオーバーレイの開閉アニメーション（select、date picker を含む）、ライブラリを指定せずにアニメーションを求める依頼（「ライブラリを指定せずにアニメーションを求める依頼」の項目）	references/layouts/overlay.md
料金表、プラン選択ページ	references/layouts/pricing.md
ひとつの依頼に複数画面が含まれる場合	他の構築依頼と同様に U 分岐へ進みます。references/system.md — 最初の画面より前に、U4 で基盤となる契約を確定します。デフォルトのレイアウトをそのまま使うのは、直接構築する場合か、小さな作業に限ります。

ワイヤーフレームがある場合は質問4をスキップし、項目1に進んで、 ルール S13、S14、S15 に従って画像を再現します。

---

1. 範囲 — Sルール

この部分は、あらゆるタスクに必要なため、SKILL.md に残します。形式に関するルールは references/ にあります。項目2を参照してください。

S1. セクションを勝手に追加しません。 依頼にあるブロックだけを構築します。 スケルトンにカードが3枚描かれているなら、カードは3枚で納品します。ヘッダー、比較表、よくある質問、フッターを勝手に追加しません。

S2. 「完成させる」は、内容を追加する許可ではありません。 依頼された部分を 完成させるという意味だけです。

S3. 画面タイトルは、追加コンテンツに数えません。 ユーザーが要素を列挙して タイトルを忘れていても、構造であってコンテンツではないため、タイトルを付けてかまいません。同じ種類のものとして、 入力欄のラベル、ボタンの文言、エラーメッセージがあります。それ以外は追加しません。 ロゴ、広告文、「ログイン状態を記憶する」チェックボックス、2つ目のログインプロバイダーなどは追加しません。 ⚠️ 認証画面には個別のデフォルト設定があります。references/layouts/form.md を参照してください。 製品ロゴ、「パスワードを忘れた場合」、Google ボタン、プレースホルダーはそのまま実装します。ログイン状態の保持はバックエンドが必要なため実装しません。引き渡し時にこの選択を一文で伝えてください。質問票にはしないでください。

S4. 内容を聞き直さないでください。 ユーザーが画面に含めるものを明確に列挙している場合は、その一覧をそのまま維持し、選択済みのワイヤーフレーム案（小規模な作業なら質問4のデフォルトレイアウト、またはそのまま実装する方法）に配置してください。

例：「ログインページにメールアドレス欄、パスワード欄、パスワードを忘れた場合のリンク、ログインボタン、Google でログインボタン」と指定されている場合、内容は確定しています。U1 の概要にはこの5つをそのまま記載し、どのワイヤーフレーム案でも5つすべてを含めます（そのまま実装する方法なら、画面中央に1列で配置します）。Google ボタンが必要かどうかを聞き直さないでください。

S5. 要件の範囲が曖昧なら、質問せずデフォルトの範囲を実装してください。

• 要件に列挙されている場合（「ログインページにはメールアドレス欄、パスワード欄、ボタン…を含める」）：範囲は確定済みです。そのまま実装してください。
• 要件の範囲が曖昧な場合（「ダッシュボードを作って」）：その画面タイプのレイアウトファイルにあるデフォルトのブロック一式を使用してください（ダッシュボードの場合は references/layouts/app.md のブロック表）。一式をすべて実装してください。S1 を「最低限だけ作る」と解釈し、3つのブロックしかない薄っぺらな画面にしないでください。
• 引き渡し時の最初の一文で、実装したブロックと、表にあるうち省略したブロックを列挙してください。追加や削除が必要なら、ユーザーから指示があります。

S6. モックアップには妥当なダミーデータを入力し、空欄にしないでください。 [要入力] だらけのページではデザインが分からず、ただのフォームになってしまいます。もっともらしい数値を入力し、引き渡し時に一文でこの版の数値はダミーだと伝えてください。 同じレコードの各ブロック間でデータを一致させてください。アクティビティタブにキャンセル済み注文が1件あるのに、数値カードに注文3件、1,230万ドンと表示してはいけません。2つのタブ間でダミーデータの数値が食い違うと、レビュー担当者は画面の計算が間違っていると思ってしまいます。作成日を前倒ししたり、履歴に注文を追加したりしてダミーデータを整合させるのは、ビルド側の作業です。質問せずに対応してください。ロジックにも実データにも影響しません。

**S7. [要入力] にするのは、実際のユーザーに公開するビルドの場合に限り、かつ法的または金銭的な影響があるものだけにしてください。販売価格、返金額、稼働率の保証、規約などが該当します。

S8. ダミーデータには、きれいなデータだけでなく境界ケースも含めてください。 2行に折り返される名前、9桁の数値、0、画像なし、説明なし、空の一覧。きれいなデータだけでは、実際の顧客を迎えるまでは問題なく見えてしまいます。

S9. プロジェクトに既存のコンポーネントライブラリがある場合は使用してください。 セクション0の質問2を参照してください。ユーザーが使用するライブラリを明確に指定した場合は、その指定に従い、異議を唱えないでください。

S10. 要件に曖昧な語がある場合は、デフォルトの意味を採用し、引き渡し時に明示してください。

語	デフォルトの意味	明示的な指定がある場合に限る別の意味
表	データテーブル	カンバン形式のボード（「ドラッグ＆ドロップ」、「ステータス列」、「ボード」）
カード	カード	タブ
リスト	縦方向のリスト	ドロップダウン
枠	レイアウト領域	モーダル（「ポップアップ」、「ポップアップウィンドウ」）
ページ	1つのルート	複数ステップのうちの1ページ（「ステップ2」）
カレンダー	月間カレンダー	タイムライン

引き渡し時の最初の一文で、解釈を明確に伝えてください。「表はデータテーブルという意味で理解しました。カンバンボードのことならお知らせください。変更します。」 解釈が違っていれば、ユーザーは最初の一文で気づけます。テストまで分からない、ということはありません。そもそもの教訓は、「プロジェクト管理の表」を誰も明示せずにカンバンと解釈し、テストサイクル全体を無駄にしたことです。問題は珍しい意味を黙って選んだことであり、質問しなかったことではありません。

S11. layouts/ のサンプルコードを開くのは、画面タイプを確定してからにしてください。 サンプルコードは「どう実装するか」に答えるものであり、「要件が何を求めているか」には答えません。カンバンのサンプルファイルがあると、曖昧なものを何でもカンバンと解釈しやすくなります。

S12. ユーザーが画像を提示したら、それが何の画像か自分で判断し、質問しないでください。

• デフォルトではデザインリファレンスです：レイアウト、配色、スタイルに沿ってください。
• ワイヤーフレームなのは、依頼でワイヤーフレーム／ラフ／骨組みと呼ばれている場合、または画像が白黒やグレーのみで、長方形のブロックやダミー文字で構成されている場合です。この場合はレイアウトだけを参考にし、色とスタイルはスキルに従ってください。
• 現状の画面なのは、ユーザー自身のアプリの画面を見てほしいと依頼されている場合です。依頼に「見てもらえますか」「レビュー」「どこがよくないか」「なぜ変に見えるのか」「ごちゃごちゃしている」といった言葉が含まれます。この画像は問題点を見つけるためのもので、手本として沿うものではありません。V の分岐（references/review.md）に進んでください。画像がリポジトリ内のルートに一致していて、依頼に問題点を指摘する言葉がなく、構築または作り直しだけを求められている場合は、U 分岐の**「変更前」の画像**です。U1 で読み込み、納品時に変更後の画像と並べてください。V には分類しません。⚑
• 納品時に一言伝えてください：「画像はデザインリファレンスとして使用しました（色も含めて踏襲しています）」「…ワイヤーフレームとして使用しました（レイアウトのみ参考にしています）」、または「…はアプリの現状の画面です（問題点を確認します）」。

S13. レイアウトには要素の一覧だけでなく、位置も含まれます。 バッジがカードの上辺中央にあるなら、中央に配置してください。アイコン枠が価格の横にあるなら、その位置を維持してください。ブロックの順番も変えないでください。色やスタイルは変更できますが、位置はずらさないでください。

S14. ワイヤーフレーム内のアイコンは、装飾用も含めてそのまま残してください。 項目ごとに異なるアイコンを一つずつ使用できるというルールは F17 を参照してください。

S15. 納品時には次の4点を伝えてください：ユーザーに代わって選んだデフォルト設定（曖昧な依頼の解釈 S10、ブロックのセット S5、画像の種類 S12、スタイル P1、質問4のレイアウト。それぞれ1行に分け、「別の希望があればお知らせください」と添えてください）、ブランドを変更する箇所（アクセントカラーを指定する行、フォントを指定する行）、どのデータがダミーか、ダークモードを実装したかどうか。デフォルト設定は最初に記載してください。推測を誤っている可能性があるのは、そこだけだからです。スキルや UI のラベルがベトナム語でも、ユーザーが使っている言語で伝えてください（T27）。

S16. 画像が必要なダミーデータには、グレーのブロックやイラストではなく、実際の写真を使ってください ⚑。実際の製品で画像が表示される項目（部屋、商品、記事、企業のカバー画像、人物のアバターなど）には、モックアップでもワイヤーフレームでも実際の写真を使用し、新しいページが稼働中の製品のように見えるようにしてください。

• 風景や物の画像：Unsplash を使い、次の形式にしてください。 https://images.unsplash.com/photo-<id>?w=800&q=80&auto=format&fit=crop。項目に合った題材を選んでください（賃貸の部屋なら室内、求人情報ならオフィス）。<id> を適当に作らないでください。Unsplash で検索し、リンクごとに curl -sI を実行してください。200 が返らないリンクは別のものに差し替えます。項目ごとに異なる画像を使ってください。
• 人物のアバター：人物の顔写真（https://randomuser.me/api/portraits/women/<0-99>.jpg、.../men/<0-99>.jpg）を使い、ダミーの名前の性別に合わせてください。画像の形状は components/avatar.md に従います。
• 架空の企業ロゴ：components/avatar.md に従い、角丸の正方形に文字を表示してください。架空の企業に実在ブランドのロゴを割り当てないでください。
• S8 の境界ケースも維持してください：画像のない項目を少なくとも1つ、アバターのない人物を少なくとも1人含め、文字や「画像がありません」の枠にフォールバックする様子がわかるようにしてください。
• Next.js の場合は、next.config の images.remotePatterns に2つのホストを追加してください。プロジェクトに独自の画像（public/ フォルダー、CDN など）がある場合は、まずそれを使ってください。
• 納品時には、S15 の「ダミーデータ」の説明に、Unsplash と randomuser の画像はサンプルであり、実際に運用する前に本物の画像へ差し替える必要があることも記載してください。

8つの項目に似たようなイラストを8つ使うと、レイアウトが正しくてもページは「つまらない」印象になります。

---

2. 必要なドキュメントを開くタイミング

SKILL.md には、常に必要な内容だけを残してください。必要なファイルだけを開いて作業し、すべて読み込まないでください。

単一の情報源の原則： 各ルールはただ1つのファイルに記載してください。SKILL.md にはルール番号への参照のみを記載し、ルールの内容をコピーしてはいけません。同じルールが2か所に書かれている場合は、どちらか一方が誤りです。

グループ	ファイル	用途
S	SKILL.md 項目 1	範囲：実行してよいこと、勝手に追加してはいけないこと
N	references/principles.md	ほかのすべてのルールの根底にある12の原則。それぞれにテストがあります。仕様がない箇所では、これに従います
M	references/rules-color.md	色、境界線、影、ダークモード、トークン
T	references/rules-type.md	テキスト、フォント、折り返し、切り詰め、コピー、回答言語、英語のコピー
F	references/rules-form.md	ブロック、グリッド、角丸、余白、アイコン、エフェクト
I	references/rules-state.md	ボタン、ホバー、フォーカス、リスト、モーダル
R	references/responsive.md	画面幅が狭い場合のすべてのルール、375pxの確認基準
D	references/system.md	複数画面の依頼：プリミティブの契約。まずデザインシステムを構築します（D9）
V	references/review.md	既存UIの確認：3段階のエラー、幅のスキャン、プロジェクトのダークモード、変更前後の表、新しい版と元の版の比較（V6）
L	references/refactor.md	既存コードベースのリファクタリング
U	references/design-process.md	ゼロからのデザイン：ブリーフ、各画面の主要タスク、ワイヤーフレーム案、構築
W	references/tailwind-v4-traps.md	古いCSSがある場合のTailwind v4の落とし穴
P	references/styles.md	ビジュアルスタイル：フラット、浮き上がり、ガラス、グラデーション、ダーク。上書きできるルール、固有の落とし穴、コントラスト

常に開くファイル（すべてのタスク）：

必要なもの	開くファイル
共通原則、見本のないUIのテスト	references/principles.md
予算、リズム、文字サイズのスケール	references/budgets.md
カラーパレット、フォント、ブランドの変更方法	references/brand-tokens.md + references/tokens.css
完了を報告する前の確認	references/checklist.md
プロジェクトオーナーが確定したルールと却下された理由：色やボタンの強さ（赤かニュートラルか、primary か枠線か）を選ぶ前に開く	references/locked-rules.md

該当するブロックを構築するときに開くファイル：

作成するもの	開くファイル
カード、ウィジェット、パネル	references/components/card.md
詳細ページのラベルと値のブロック	references/components/description-list.md
ボタン	references/components/button.md
入力欄、フォームフィールド	references/components/input.md
OTP 入力欄	references/components/otp-input.md
− + ボタン付き数量入力欄	references/components/quantity-input.md
ページ上部のインライン編集可能な名前（プロジェクト名、ドキュメント名）	references/components/inline-edit.md
ヘッダーバーまたはページ名の上にあるパンくずリスト	references/components/breadcrumb.md
クリックして並べ替えるテーブルの列見出し	references/components/sortable-header.md
チェックボックス、ラジオボタン、スイッチ、セレクト、時刻選択、日付選択、日付範囲、日時、カード形式の選択肢	references/components/choice-controls.md
リストの行	references/components/list-row.md
タイムライン、アクティビティ履歴	references/components/timeline.md
フォルダーツリー、開閉できるネストされたツリー	references/components/tree.md
アコーディオン、FAQ、その場で開閉する項目	references/components/accordion.md
コメント欄、ネストされた返信	references/components/comment-thread.md
AI アシスタントとのチャット画面：双方向のメッセージ、ツール使用の手順、追加の質問候補、メッセージ作成欄	references/components/chat.md
数値範囲、価格帯を選択するスライダー	references/components/range-slider.md
複数タグ入力欄（受信者のメールアドレス、ラベル）	references/components/tag-input.md
空のリスト、読み込みエラー	references/components/empty-state.md
読み込み中：スケルトン、再読み込み、画面上での即時変更、「保存中…／保存済み」、長時間実行される処理	references/components/loading.md
ページ内通知バー（情報、注意喚起、エラー）	references/components/banner.md
フィルターチップ、適用中のフィルターチップ（×付き）、アイコンのみのボタン、タブバー（4 種類）、ページネーション	references/components/small-controls.md
アバター、重ねて表示するアバターグループ	references/components/avatar.md
プロダクトロゴ（サイドバー上部、認証画面、独立したエラーページ）とファビコン。プロジェクトにロゴがない場合	references/components/logo.md
棒グラフ、折れ線グラフ、数値、進捗バー	references/components/charts.md
ファイルのドラッグ＆ドロップ領域、アップロード中のファイル一覧	references/components/file-upload.md

ページの作成は組み立てる作業であり、描き直す作業ではありません。 上の表にある要素がページに含まれる場合は、たとえ隅にある小さなボタンでも、該当するファイルを開いてそのパターンをそのまま使ってください。「このページに合うように」独自のバリエーションを作らないでください。同じバッジがテーブルとドロワーで異なるスタイルになると、2 つのアプリをつなぎ合わせたようになってしまいます（D1、D2）。ページにまだファイルのない要素が必要な場合は、references/principles.md の最後にある 「サンプルのないものを作る」 の手順に従ってください。最も近い型を借り、境界ケースも含めて作成し、自動修正プローブを実行し、5 つの項目を目視確認します。引き渡し時に 「X は承認済みのサンプルがないため、Y の型を借りました」 と一言伝えてください。

承認済みコードサンプル（画面の種類を確定した後にのみ開いてください。ルール S11）： references/layouts/app-kanban.html

3. 忘れてはいけない6つのこと

references/checklist.md を要約したものです。完了を報告する前に、チェックリスト全体を実行してください。

• 項目0の質問1に回答しましたか――（デフォルトの）デザイナーとして対応する、UIを分析する、ブランドを維持して再構築する、スキルのスタイルに合わせて再構築する、リファクタリングする、そのまま構築する、または先にデザインシステムを構築する。依頼で別の方法が明確に指定されているのに、ブリーフとワイヤーフレームを省いていきなり構築したなら、質問1への回答を誤っています。
• 独自のルールを適用する前に、コードベースで Tailwind／shadcn などが使われているか grep しましたか。
• 選択したワイヤーフレーム案（ブランチ U）どおりに構築しましたか。それとも独自に作り上げましたか。小規模な作業やそのまま構築する場合は、layout ファイルのデフォルトレイアウトに従い、納品時に「別のスタイルがよければお知らせください」と一言伝えてください。
• 依頼にないセクションを追加していませんか。
• scripts/probe.mjs で実際のページを開き、スクリーンショットを確認しましたか（ゲート3）。それとも、コードを読み返してチェックリストに回答しましたか。375px幅でページが横スクロールするなら、問題があります。
• 特に見本がないものについて、references/principles.md の12項目のテストを実行しましたか。

---

4. 新しいルールを追加するときは、この方針に従う

このスキルは、ルールを追加したことで悪化したことがあります。症状を治すために書いたルールが、次の構築で別の症状を生むことがあります。

• 1回に追加できる新しいルールは最大5つです。
• 新しいルールには、既存のどのルールを置き換えるのか、またはどのルールと矛盾するのかを明記してください。古いルールを覆す場合は、「古いルールは廃止。復活させない」とその理由を明記した⚠️ブロックを残してください。
• ルールには適用条件を付けてください。「アプリ内ではX、リファクタリング時はY」のように記述し、「常にX」とはしないでください。
• 3回のテストを経ても実際の問題を一度も防げなかったルールは削除してください。
• 1つのルールは1か所にだけ記述します。 ルールは該当するグループのファイルに追加してください。SKILL.md にはルール番号への参照だけを記載します。
• ルールを追加したら、layouts/ と components/ のサンプルファイルを見直し、追加したルールに違反していないか確認してください。サンプルコードはそのままコピーされるため、そこにある間違いは広く使われます。実際に2回起きています。
• スキルにはルールと理由を記載し、履歴は記載しません。 日付、ページ名、テスト用プロジェクト名、「2回目」といった記述、試したバージョンの説明は書かないでください。AIが誤った方法を再び使いそうな場合は、「Xをしないこと。影響：…」と一文で記載してください。日付と該当箇所はコミットメッセージに記載します。プロジェクトオーナーの決定では、元の動詞（「確定する」「廃止する」「選択する」など）をそのまま使い、日付は付けず、「確定する」に勝手に置き換えないでください。スキル内で日付を記載できるのは、locked-rules.md の「確定日」列だけです。
• グループ内で番号を連続させてください。 15b、15c、17d のような番号を途中に挿入しないでください。
• テストを一度も通過していないルールには⚑を付けてください。まだ誰も試していないものを使っていると、ユーザーにわかるようにします。