normalize

normalizeスキルの概要

normalizeがすること

normalize スキルは、UI機能を監査し、既存のデザインシステムに沿うよう実装を整え直すためのものです。承認済みのパターン、余白、トークン、情報階層、インタラクション規約から、ページ・ルート・コンポーネントがずれてしまったケースに向いています。

normalizeを使うべき人

すでにある程度のデザイン方針があり、実装をその基準へ戻したい場合に normalize を使います。特に、UIを新しく考えることより不整合の解消コストのほうが大きい成熟したアプリで、フロントエンドチーム、デザインシステム担当者、プロダクトエンジニアに適しています。

normalizeの本当の役割

多くのユーザーが求めているのは、単に「見た目をよくすること」ではありません。必要なのは、余計な場当たり的スタイルを増やさずに、機能の見た目と振る舞いをプロダクト全体に揃えることです。normalize skill は、発想を広げる用途ではなく、一貫性を回復したいときに最も力を発揮します。

このスキルが他と違う理由

汎用的な「このUIを改善して」というプロンプトと違い、normalize は既存の標準に明確に基づいて動きます。リポジトリから読み取れる重要な点はひとつで、このスキルは推測してはいけない、ということです。まずデザイン文脈を集め、次に逸脱箇所を特定し、そのうえで編集前に計画を立てる前提になっています。

normalizeのベストな利用シーン

• 機能ごとに余白、タイポグラフィ、カラートークンの使い方が揃っていない
• コンポーネント自体は動くが、見た目がシステムと一致していない
• レガシーUIを大きくリファクタリングする前に整理したい
• 急いで出した新規ページを、あとからデザインシステムに合わせ直したい
• プロダクトの意図は変えずに標準化だけ進めたい

normalizeが向かないケース

チームに文書化されたパターンがなく、再利用可能なコンポーネントもなく、プロダクトやUXの方向性も固まっていない場合、normalize for Design Systems は最初の一手としては適しません。足りない部分を可視化する助けにはなっても、信頼できる標準そのものを安全に作り出すことはできません。

normalizeスキルの使い方

skills環境にnormalizeを導入する

このリポジトリでは SKILL.md 内にインストールコマンドは公開されていないため、通常は自分が使っているスキル実行環境の方法に合わせて、ソースリポジトリのパスから追加します。もし利用中の環境が GitHub からの直接インストールに対応しているなら、pbakaus/impeccable リポジトリを指定し、normalize スキルを選んでください。

たとえば次のようなコマンド体系を使っている場合は、
npx skills add pbakaus/impeccable --skill normalize

そのまま使う前に、必ず自分のランナーで有効か確認してください。重要なのは、このスキルの配置先が .agents/skills/normalize である点です。

初回利用前に読むべきファイル

まず確認するのは次のファイルです。

• SKILL.md

このスキルのフォルダには追加のヘルパーファイル、スクリプト、参考資料がないため、実際に使えるガイダンスのほぼすべてがこの1ファイルに集約されています。手早く把握できる反面、不足しているプロジェクト文脈は自分で補う必要があります。

frontend-designへの依存を理解する

導入時に見落としやすい最大のポイントは、normalize が先に /frontend-design を実行することを前提としている点です。この上流スキルには、このワークフローが依存するデザイン原則、アンチパターン、文脈収集の進め方が含まれています。

さらに、まだ十分なデザイン文脈が存在しない場合は、先に /teach-impeccable を実行しなければならないと書かれています。実務上の normalize usage は、単発のワンショットではなく、前段を含む連鎖型ワークフローです。

normalizeが期待する入力を把握する

定義されている引数ヒントは次のとおりです。
[feature (page, route, component...)]

相性のよい入力例:

• checkout page
• settings/billing route
• pricing card component
• mobile nav menu

弱い入力例:

• the whole app
• make the UI better
• fix styling everywhere

曖昧な依頼を強いnormalizeプロンプトに変える

弱い依頼:
Normalize the dashboard

より強い依頼:
Use normalize on the analytics dashboard route. Align it to our design system by checking token usage, spacing scale, typography hierarchy, component variants, and empty-state patterns. Preserve current functionality. Flag any places where the design system is unclear instead of guessing.

この形が有効な理由:

• 対象機能の境界が明確
• 何を基準に整えるかが具体的
• 既存機能を守る条件が入っている
• 基準が曖昧なときの振る舞いまで指定している

normalize実行前に最低限集めたい文脈

高品質な出力にするなら、次を用意してください。

• 対象機能のパスまたはルート
• コンポーネントライブラリやデザインシステムの所在
• テーマファイルや CSS 変数などのトークン定義元
• 関連するUIガイドラインやスクリーンショット
• 「変更してはいけない」業務上の制約
• 計画だけ欲しいのか、実装変更まで含めるのか

この文脈がないと、スキルはズレを検出できても、何に置き換えるのが正しいかまでは安定して判断できません。

normalizeが前提とするワークフローに従う

リポジトリの記述からは、次の流れが推奨されます。

1. /frontend-design を実行する
2. デザイン文脈が不足しているなら /teach-impeccable を実行する
3. デザインシステムのドキュメント、コンポーネントパターン、トークンを見つける
4. 現在の機能にどんな逸脱があるか分析する
5. 正規化の計画を作る
6. 変更は保守的に実行する
7. 場当たり的なスタイルや不整合を掃除する

この順序は重要です。というのも、このスキルは「標準を推測しない」ことを強く前提にしているからです。

normalizeがコードベース内で確認すべきポイント

ソース抜粋で強調されているのは次の点です。

• デザイン原則と美的方向性
• ターゲットユーザーやペルソナ
• コンポーネントのパターンと規約
• 色・文字・余白に関するデザイントークン
• 不整合が見た目だけの問題か、機能面にも及ぶか
• 場当たり実装やトークン不足といった根本原因

つまり、normalize install は判断材料の半分にすぎません。本当に重要なのは、エージェントがこれらの手がかりを追えるだけの情報が、あなたのリポジトリに揃っているかどうかです。

normalizeの出力を良くするプロンプトパターン

診断とアクションの両方を求める:
Normalize the account settings page. First identify where it deviates from our system and categorize issues as token misuse, layout inconsistency, component misuse, or interaction mismatch. Then propose the minimal set of edits to align it.

不確実性への対応を明示する:
If a pattern is not documented, stop and ask rather than inventing a new one.

出力形式を指定する:
Return a brief audit, a change plan, then the implementation.

実プロダクトでnormalizeを使う際の実践的ガードレール

normalize guide を安全に使うには、次を守ると有効です。

• プロダクト要件と文言の意図を維持する
• 既存パターンに明確に反していない限り、フローは変えない
• カスタムスタイルは既存プリミティブへの置き換えを優先する
• 見た目の微修正だけでなく、場当たりコードを減らす差分を求める
• システム側に不整合がある箇所も、エージェントに明記させる

うまくいった正規化の実行は、UIの一貫性だけでなく保守性の改善にもつながります。

normalizeスキル FAQ

normalizeは普通のUIクリーンアップ用プロンプトより優れている？

すでにデザインシステムがあるなら、多くの場合ははいです。normalize の価値は、気の利いた言い回しそのものではなく、先に標準を集め、その標準と照らしてズレを確認し、勝手なデザイン判断を避けるという流れを強制してくれる点にあります。

normalizeは初心者向き？

中程度です。スキル自体は単純ですが、初心者は前提条件を満たせないことが多いです。たとえばデザインドキュメント、トークン定義元、何を正とみなすかの判断材料などです。初めてなら、1つのルートや1つのコンポーネントのように小さい単位から始めるのが安全です。

正式なデザインシステムがなくてもnormalizeは使える？

部分的には使えます。不整合の洗い出し自体は可能ですが、明確な source of truth がないと出力品質は下がります。このスキルは推測を避けるよう明示しているため、標準の欠落は見えない前提にはならず、むしろ作業上の障害として表面化します。

normalizeが得意ではないことは？

主目的は次のような用途ではありません。

• 新規画面のビジュアル探索
• 大きなUX戦略変更
• ブランドの新規設計
• アプリ全体を一度で大規模リファクタリングすること

使いどころは、全面的な再設計ではなく、既存システムへの整合です。

normalizeはフロントエンドスタックにどう適合する？

normalize skill は、トークン・パターン・規約を中心に扱うため、考え方としてはスタック非依存です。特に、再利用可能なコンポーネント、テーマプリミティブ、正しいUI判断を追跡できるだけの構造がコードベースにある環境で効果を発揮します。

どんなときにnormalize for Design Systemsを避けるべき？

本当の問題が見た目の不整合ではなく、未整理のプロダクトスコープにあるなら避けるべきです。また、チーム内でデザインシステム自体への合意が取れていない場合も不向きです。そうした状況では、スキルが「動いている標的」に向けて正規化しようとして、労力だけがかかる可能性があります。

normalizeスキルを改善する方法

normalizeの対象をもっと狭くする

最も速く効く改善はスコープ設定です。normalize には、一度に1つのルート、1つの機能、または1つのコンポーネント群だけを担当させてください。対象が小さいほど、監査結果は明確になり、意図しないリグレッションは減り、整合判断の精度も上がります。

実際のsource of truthを渡す

単に「うちのデザインシステムに従って」と言うだけでは不十分です。次のような具体物を示してください。

• component folders
• Storybook やドキュメントの URL
• token files
• 正としたい画面のスクリーンショット
• 承認済みパターンの実例

これによって最大の失敗パターン、つまり「もっともらしいが間違っている整合」が起きにくくなります。

見た目のズレとパターンのズレを分ける

強い依頼は、何を求めるのかを明確に分けています。

• トークン整理だけしたい
• ビジュアル階層を揃えたい
• 承認済みバリアントへコンポーネントを置き換えたい
• インタラクションまで正規化したい

この違いで計画は大きく変わりますし、過剰な編集の防止にも役立ちます。

変えてはいけないものをnormalizeに伝える

より良い normalize usage プロンプトには、次のような制約を含めます。

• 現在のデータフローは維持する
• バリデーションロジックは変更しない
• アクセシビリティの挙動は維持する
• analytics selectors は安定させる
• 新しいコンポーネントは導入しない

こうした条件があると、正規化の焦点がシステム適合に保たれ、意図しないリファクタリングに流れにくくなります。

コード変更の前に計画を求める

リポジトリが計画重視であることを、そのまま活かしてください。次の順で返すよう求めるのが有効です。

1. デザインシステム上の発見事項
2. 逸脱監査
3. 提案する正規化ステップ
4. その後に実装

誤った前提を早い段階で見つける、最も簡単な方法です。

欠けている標準への対処を明示する

余白、タイポグラフィ、コンポーネント選定のルールが見つからない場合は、エージェントに次の対応を指示してください。

• いったん止まって確認する
• トレードオフ付きで選択肢を提示する
• その欠落をデザインシステム上の課題として明記する

この振る舞いのほうが、無理に推測させるよりも、スキルの意図に合っています。

スクリーンショットではなく保守性まで確認する

理想的な normalize guide の成果は、単に見た目が揃うことではありません。次の点まで確認してください。

• ハードコード値がトークンに置き換えられているか
• カスタムの場当たりラッパーが減っているか
• 承認済みプリミティブを再利用しているか
• 将来のシステム更新を簡単にしているか

デザインシステムに対して長期的な価値を生みやすいのは、まさにこの部分です。

最初のnormalize後にもう一度回す

1回目の実行後は、絞ったフォローアップを入れると効果的です。
Re-check the implementation and list any remaining deviations from the design system, especially token usage, component variants, and spacing rhythm.

微妙な不整合は、2回目の確認で見つかることが少なくありません。

比較対象の実例でnormalizeの出力品質を上げる

手本になる画面があるなら、明示してください。
Normalize the billing page to match the visual and structural patterns used in the account overview page.

比較参照の提示は、normalize for Design Systems において最も効果の高い入力のひとつです。

主な失敗パターンを把握しておく

特に注意したいのは次の点です。

• ドキュメントが薄いまま、パターンを発明してしまう
• 過剰修正でUXの意図まで変えてしまう
• 見た目だけ揃えて、トークン整理ができていない
• 共有コンポーネントを無視して局所修正に終わる
• デザインシステム上の根拠なしに広範な「磨き込み」をしてしまう

こうした兆候が出たら、スコープを狭め、参照情報を増やし、必ずシステムに結びついた明示的な根拠を出させてください。