normalize

normalizeスキルの概要

normalizeでできること

normalize スキルは、UI機能を監査し、既存のデザインシステムに再び沿う状態へ整えるためのスキルです。ページ、ルート、コンポーネントが、余白、タイポグラフィ、トークン、状態表現、インタラクション設計といった既存パターンから徐々にズレてきたケースに向いています。

normalizeを導入すべき人

この normalize スキルは、すでに何らかのデザイン言語を持つチームに最適です。たとえば、コンポーネントライブラリ、スタイルガイド、トークンセット、あるいは繰り返し使われるプロダクトパターンがある場合です。特に、フロントエンドエンジニア、デザインエンジニア、そしてプロダクト全体を作り直さずに不整合なUIを整理したいAI活用メンテナーに向いています。

実際に解決したい仕事

多くのユーザーが求めているのは、単に「もっと見た目を良くして」ではありません。実際には次のようなことをしたいはずです。

• どこで機能がシステム上の規約を外れているか特定する
• 表面的な見た目の不一致と、構造的なUIの問題を切り分ける
• そのプロダクトに元からあったように感じられる変更を出す
• 既存パターンを再利用すべき場面で、新しいパターンを勝手に作らない

normalizeが汎用プロンプトと違う理由

最大の違いは、normalize が自由なUIリデザイン用プロンプトではなく、デザインシステム整合 のためのワークフローとして設計されている点です。まずシステムの文脈を集め、そのうえでズレを分析し、設計原則が曖昧なときは推測しないようエージェントを促します。また、このスキルは /frontend-design に依存しており、まだ十分なデザイン文脈がない場合は先に /teach-impeccable の実行が必要になることがあります。

向いているケース・向いていないケース

向いているケース:

• アプリ全体と比べて特定の機能だけ「何かおかしい」と感じる
• トークン、余白、タイポグラフィ、コンポーネント利用に一貫性がない
• 大規模なプロダクト再設計なしで整合性を高めたい
• Design Systems の運用はあるが、適用にムラがある

向いていないケース:

• 基準にできるシステムがまだない新規プロダクト設計
• ブランド探索やビジュアルディレクションの検討
• UI整理の前にUX戦略が必要なフロー
• リポジトリの文脈を渡さず、自動修正だけを期待するチーム

normalizeスキルの使い方

normalizeの導入コンテキスト

上流の SKILL.md には、パッケージのようなインストールコマンドは公開されていません。そのため、GitHubベースのスキルを扱えるホスト側のスキルシステム経由で利用します。環境が一般的なCLIパターンを採用しているなら、基本の導入例は次のとおりです。

npx skills add https://github.com/pbakaus/impeccable --skill normalize

ただし、導入そのもの以上に重要なのが依存関係の準備です。normalize は /frontend-design によるコンテキスト収集を前提 としており、その文脈がまだ整っていない場合は、先に /teach-impeccable を実行するよう案内されます。

初回利用前に必要な前提条件

normalize を呼び出す前に、次を確認してください。

• 対象リポジトリ、または関連するUIファイルにアクセスできる
• デザインシステムの痕跡がある: トークン、ドキュメント、共有コンポーネント、スタイルガイド、スクリーンショット、運用ルールなど
• 近接する機能を比較対象として調査できる
• 同じスキル環境で /frontend-design が利用可能である

この文脈がないと normalize は推測に頼ることになり、元のガイダンスでも「原則が不明なときは推測しない」ことが明示されています。

normalizeが想定している入力

引数のヒントは次のとおりです。

[feature (page, route, component...)]

実運用では、対象のUI面と参照先を具体的に指定した入力ほど結果が安定します。例:

• normalize settings billing page
• normalize /dashboard/reports route
• normalize AccountMenu component and related dropdown states

このスキルは「アプリ全体」より、境界が明確な1機能に対して使うほうがうまく働きます。

normalize依頼を強くする書き方

弱い依頼:

• “Normalize the UI.”

より強い依頼:

• “Normalize the /checkout flow to match our existing design system. Focus on spacing, form field hierarchy, button treatments, error states, and component reuse. Compare against our account settings pages and shared form components before changing anything.”

これが有効な理由:

• 対象範囲が明確になる
• 比較対象のUI面を示せる
• 品質基準を伝えられる
• 不要なリデザインに流れるリスクを下げられる

normalize利用時の推奨ワークフロー

実践的な流れは次のとおりです。

1. /frontend-design を実行し、そのコンテキスト収集プロトコルに従う
2. まだ使えるデザイン文脈がない場合は /teach-impeccable を実行する
3. normalize に1つの機能を分析させる
4. コード変更の前にプランをレビューする
5. 合意した正規化作業だけをエージェントに実装させる
6. 修正がハッピーパスだけで終わらないよう、周辺の状態やバリアントも再確認する

この順序が重要なのは、normalize が「まずシステムを理解し、その後で編集する」前提で作られているためです。

normalizeが最初に確認すべきもの

このスキル自体のリポジトリ側サポートは最小限なので、実際にはあなたのリポジトリ文脈が最重要です。エージェントにはまず次を確認させてください。

• 共有UIコンポーネント
• トークン定義
• デザインシステムやスタイルガイドのドキュメント
• プロダクト内で似ていて成熟しているページ
• フォーム、テーブル、モーダル、カード、ナビゲーションのパターン
• 現在の機能が持つ各状態: empty、loading、error、disabled、success

対象コンポーネントだけしか渡さない場合、出力は見た目の微修正止まりになりやすいです。

最初に読むべきリポジトリファイル

上流のスキル自体については、まず次を確認してください。

• SKILL.md

このファイルに、利用可能なガイダンスのほぼすべてが入っています。必須の事前準備ステップや、変更前にデザインシステムを発見・把握することを重視する normalize のワークフローもここに含まれています。

Design Systems向けにnormalizeを使う実践プロンプト

Design Systems の作業で normalize を使うなら、比較対象セットを必ず渡してください。例:

“Use normalize on the TeamMembers page. First study our design system tokens, the shared table component, and the settings pages. Identify where this page diverges in spacing, typography, action placement, row density, empty states, and status badges. Propose a concise plan, then update the implementation to reuse existing patterns instead of introducing new ones.”

単に「一貫性を出して」と頼むより良いのは、観察可能な評価軸が明示されているためです。

想定しておくべき制約とトレードオフ

normalize は魔法の「完璧にするボタン」ではありません。想定すべきトレードオフには次があります。

• システム自体に一貫性がない場合、きれいに解決するより先に曖昧さを露出させることがある
• 見た目の正規化を強く進めると、本来このスキルが勝手に解くべきでない深いUX課題が見えてくることがある
• 一部のズレは実装の粗さではなく、プロダクト要件から来ている
• 厳密な一貫性が、ローカルな機能要件と衝突することがある

normalize が最も信頼できるのは、システムを推測ではなく参照できる程度に成熟している場合です。

normalize利用時によくあるミス

導入時のつまずきを避けるには、次をしないでください。

• /frontend-design を飛ばす
• アプリ全体の広範な整理を一度に依頼する
• 参照すべきコンポーネントや成熟したページを何も渡さない
• エージェントにトークンやパターンを新規発明させる
• ビジュアルの正規化を、プロダクトレビューやアクセシビリティレビューの代替とみなす

成功した状態の見え方

良い normalize の結果には、次の特徴があります。

• 既存のコンポーネントとトークンを再利用している
• その場しのぎのスタイル指定が減っている
• 機能がそのプロダクト本来のUIの一部に感じられる
• 機能の意図を保ったまま一貫性を改善している
• 各変更が既存パターンにどう整合するか説明できている

もし出力が色や余白を少し変えるだけで、パターン上の根拠が薄いなら、文脈の渡し方が足りていない可能性が高いです。

normalizeスキルのFAQ

normalizeは初心者でも使いやすい？

はい、ただしガードレール付きです。対象機能と、良い比較対象になりそうなUI面をいくつか示せるなら、初心者でも normalize を使えます。逆に、コードベースに明確なデザインシステムが見当たらない場合や、プロダクトパターンが文書化されていない場合は、初心者向きとは言いにくくなります。

normalizeには既存のデザインシステムが必要？

必ずしも正式なデザインシステムサイトまでは必要ありません。ただし、繰り返し現れる基準の証拠は必要です。共有コンポーネント、トークン、安定したページ、視覚的な慣例があれば、通常は十分です。そうしたものが何もないなら、normalize との相性は弱くなります。

normalizeは、AIに「UIをきれいにして」と頼むのと何が違う？

通常のプロンプトは、いきなり編集に入ってしまいがちです。normalize は、まず既存の基準を見つけて適用することを明確に重視しています。そのため、特に大きなプロダクトで、局所的な改善がかえってシステムの分断を進めてしまうリスクを避けたいとき、一貫性のための作業に向いています。

normalizeを使わないほうがいいのはどんなとき？

次のような場合は normalize を使わないでください。

• まったく新しいビジュアル方向性が必要
• 初期段階のプロダクトデザイン探索をしたい
• 大きなUXフローの発明が必要
• 主目的が包括的なアクセシビリティ検証である
• コンポーネントライブラリ戦略をゼロから作りたい

こうしたケースでは、normalize は役割が狭すぎます。

normalizeは単一コンポーネントにも使える？

はい。むしろ、そこから始めるのが最適なことも多いです。ページの一部、1つのルート、1つのコンポーネントといった単位であれば、スキルが十分に文脈を捉えつつ、変更のレビューもしやすくなります。

normalizeは見た目の磨き込み専用？

いいえ。元の説明では、標準、トークン、パターンに触れており、これは単なる表層スタイルではなく、コンポーネントの使い方、階層、状態処理まで含むのが普通です。ただし、深いUXリサーチの代わりにはなりません。

normalizeスキルを改善する方法

normalizeに比較対象を渡す

normalize の出力を最も手早く改善する方法は、あなたのアプリで「良い状態」が何かを明示することです。参照ページやコンポーネントを2〜3個挙げてください。これがスキルの判断軸になり、設計判断を勝手に作ってしまうリスクを減らせます。

壊れている機能だけでなく、システムの証拠も渡す

質の高い入力には次のようなものが含まれます。

• token files
• shared component paths
• design documentation
• screenshots of mature interfaces
• notes on audience or brand tone

これは、コードを変える前に設計原則を発見するという、このスキルの前提要件を直接支えます。

実装前にプランを出させる

normalize は整合性重視のスキルなので、先にプランを出させると信頼性が上がります。次の内容を含めるよう依頼してください。

• 検出したズレ
• 根本原因
• 既存コンポーネントをどう再利用するか
• システムが不明確な箇所に関する未解決事項

これにより、見た目だけ整えた出力がそのままコードに入るのを防げます。

広い整理は機能単位のパスに分ける

大きなプロダクト全体で normalize を回したい場合は、段階的に進めてください。

1. まず1つのルートを normalize する
2. 次に1つの共有コンポーネント群を normalize する
3. その隣接フローを normalize する
4. 前のパスで見えてきたパターンを統合する

一度に広く依頼するより、この進め方のほうが整合性は高くなります。

こうした失敗パターンに注意する

よくある失敗パターンには次があります。

• エージェントがデザイン言語を推測してしまう
• 1つの参照ページに過剰適合してしまう
• 既存のものを再利用せず、新しいバリアントを増やしてしまう
• ハッピーパスの見た目だけ直して、状態を無視する
• パターン整合の説明なしにスタイル変更だけ行う

こうした症状が見えたら、原因は実行の弱さだけでなく、たいてい文脈不足です。

normalizeのフォローアッププロンプトを強化する

最初の出力の後は、次のようなプロンプトで normalize の結果を改善できます。

• “Revise this to use only existing button and form patterns.”
• “Re-check empty, loading, and validation states against our settings pages.”
• “List any new patterns you introduced and replace them with existing system equivalents.”
• “Separate must-fix inconsistencies from optional polish.”

こうした追いプロンプトにより、作業をシステム整合にしっかり結びつけられます。

normalizeをデザイン負債の削減ツールとして使う

normalize スキルが最も価値を発揮するのは、ズレが蓄積しやすい領域に繰り返し使うときです。古いルート、最近出荷した機能、多くのコントリビューターが触るUI面などが典型です。単発の見た目改善ツールではなく、狙いを絞ったデザイン負債削減ツールとして扱ってください。

譲れない条件を明確にして出力を改善する

何を絶対に変えてはいけないかを normalize に伝えてください。

• layout constraints
• business logic
• component APIs
• accessibility requirements
• release-risk limits

これにより、normalize は無関係な全面書き換えに踏み込みすぎず、システム整合に集中しやすくなります。