Refactoring UIの原則をClaude Codeに守らせるスキル｜実測すると発火しない条件がある

AIコーディング支援が吐くUIが「どれも同じ顔で、どこか素人っぽい」と言われる原因の多くは、センスではなく値の決め方にある。17px と 18px、#3B82F6 と lighten(5%) を毎回その場で選んでいると、全体の統一が崩れる。これを潰すのが書籍『Refactoring UI』（Adam Wathan & Steve Schoger）の考え方で、その原則をClaude Codeに実行させるスキルが s0xDk/refactoring-ui-skill（★140・MIT・2026-08-26 公開）である。実際に導入して測ったところ、入れただけでは効かないという結果になった。

デザイントークンやスケールという考え方そのものを整理したい場合は、デザインシステムとは？仕組み・構成要素・有名事例をエンジニア向けに整理する【2026年版】を先に読むと、以下の「尺度を1つに決める」という話が早く飲み込める。

Refactoring UI スキルは何を強制するのか——4つの尺度

このスキルの主張は SKILL.md の冒頭1文に集約されている。視覚デザインは才能ではなく、一度だけ行うシステム上の決定と、階層を作るための少数の技法である、と。したがってスキルの中身は「センスの教え方」ではなく、選んでよい値のリストになっている。

配布される尺度は4つ。

・余白・寸法 — 4 8 12 16 24 32 48 64 96 128 192 256 384 512 640 768。16pxを基準に、隣り合う値の差が常に25%以上あく。margin・padding・幅・高さ・アイコン寸法・線幅まで全部これで賄う
・文字サイズ — 12 14 16 18 20 24 30 36 48 60 72。比率から生成する modular scale ではなく手で選んだ値。単位は px か rem のみで、em は禁止（.875em が 1.25em の内側に入ると 17.5px という尺度外の値が生まれ、尺度が黙って消えるため）
・太さ — 2種類だけ。本文が 400 か 500、強調が 600 か 700。400未満は使わない。弱く見せたいときは太さではなく色を薄くするか字を小さくする
・影 — 光源を1つに固定し、下方向だけに落とす。段階も固定

「隣り合う値の差が25%以上」という条件が効いているのは、選択を機械的に一意にするためだ。4の倍数を並べただけの線形スケールは、120pxと124pxのどちらを選ぶかを助けてくれない。

リポジトリは全部で900行と小さい。内訳は SKILL.md 267行、references/systems.md 144行、references/techniques.md 216行、references/diagnose.md 44行、assets/tokens.css 149行、README.md 80行。references/ はスキル本体から必要に応じて読み込まれる追加資料で、後述の実測でも発火時にだけ読まれていた。

assets/tokens.css はそのままプロジェクトにコピーして使う想定のCSS変数集で、灰色のランプはHSLで組まれ、明度が50%から離れるほど彩度を上げるという書籍のルールに従っている。灰色に色味（既定は寒色系、暖色にしたければ色相を約39へ）を入れる指示もそのまま入っている。

実測：Refactoring UI スキルは読み込まれていたが、発火しなかった

ここが本題である。Claude Code 2.1.241 で、スキルを置いたディレクトリと置いていないディレクトリを用意し、同じ依頼を投げた（2026-08-27・macOS）。

最初の依頼はごく普通の言い方にした。

統計ダッシュボードのカードコンポーネントを1つ、HTMLとCSSで作ってください。コードだけ返してください。

結果は次のとおり。

スキルを置いた側で refactoring-ui はまったく呼ばれていない。「入れたつもりで効いていない」状態がそのまま再現した。

読み込まれていないのか、選ばれていないのか

原因の切り分けが要る。同じディレクトリで、スキルの一覧を出させた。

claude -p "利用可能なスキルを列挙してください。名前だけでいい。" \
  --allowedTools "Skill,Read,Glob" < /dev/null

返ってきた一覧の中に refactoring-ui は含まれていた。読み込みは成功していて、呼ばれていないだけである。つまり設定の問題ではなく、依頼文とスキルの description が結びつかなかったという経路の問題だ。

そこで description に書かれている語をそのまま依頼に入れた。この description には「a UI が looks off / looks amateur / feels cluttered と言われたとき」「make this look better と頼まれたとき」に使う、と列挙されている。

このダッシュボードのUI、なんか素人っぽく見えます。よくしてください。HTML/CSSで書き直して。

今度は発火した。実行ログには次の行が出た。

"name":"Skill","input":{"skill":"refactoring-ui"}
"content":"Launching skill: refactoring-ui"

さらに references/ 配下のファイルを Read で読みに行く挙動も観測できた。スキルの description は「何をするか」の説明文ではなく、呼び出しの経路そのものとして働いている。

色は「9段のランプ」と、コントラスト比の注記で配られる

4尺度のうち色だけは扱いが厚い。references/systems.md は色を作る手順を9節に分けて説明していて、要点はHSLで組み、明度が50%から離れるほど彩度を上げることにある。RGBやHEXで明度だけを機械的に上下させると、端に行くほど色が灰色に沈んで死ぬ。だから基準色（500）を先に決め、両端（900と100）を決め、あいだを埋める、という順序を取る。

assets/tokens.css が面白いのは、各段にコントラスト比が実測値としてコメントで書き込まれている点だ。

・--grey-400（2.7:1）— 無効状態のテキスト専用。WCAGは非活性コンポーネントを免除するが、プレースホルダは活性コンテンツなので免除されない、という注記つき
・--grey-500（3.9:1）— 大きい文字専用（24px以上、太字なら18.66px以上）。12pxの小見出しには使えないと明記
・--grey-600（5.6:1）— 脚注・著作権表記などの三次テキスト
・--grey-700（8.0:1）— 二次テキスト
・--grey-900（13.4:1）— 本文

「薄いグレーを使ったらアクセシビリティで落ちた」という事故は、どの段が何に使えるかが数字で書かれていないことから起きる。このトークン集はそこを潰しにいっている。アクセントカラー（赤・黄・緑）を100/500/800の3段だけに絞っているのも意図的で、100を背景・500を塗り・800をその背景の上の文字という三点セットが、色でコントラストを稼ぐ「flip the contrast」という技法に必要な最小構成だからだ。淡い黄色の帯に濃い黄土色の文字を載せる、というあのパターンである。

影も同じ発想で、--shadow-1 から --shadow-5 までを見た目ではなくz軸上の位置で選ぶと決めている（1がボタン、2がドロップダウン、5がモーダル）。角丸は --radius: 4px の1つだけを持ち、0なら硬い印象、12px以上なら砕けた印象という「性格の選択」として扱う。

階層の付け方は「大きさ」ではなく「重さと色」

references/techniques.md（216行）は、尺度ではなく技法を集めた側の資料だ。ここで繰り返されるのは、要素を目立たせたいときにサイズを上げるなという指示である。サイズを上げると場所を取り、レイアウトが崩れる。代わりに太さ（600/700）と色（--grey-900）で持ち上げ、弱めたいものは薄い色（--grey-600）へ落とす。

そのほか収録されている技法は次のようなものになる。

・光源を1つに固定して影を作る — 上から光が当たっている前提を全体で共有する
・2段構えの影 — 拡散する大きな影と、輪郭を締める小さな影を重ねる
・影に頼らない奥行き — 背景色の差や重なりだけで手前・奥を表現する
・中央揃えではなくベースライン揃え — 大きさの違う文字を横に並べるときは下端で揃える
・字間は大きい文字だけ詰める — 小さい文字はむしろ空ける
・グリッドは過大評価されている — 12カラムに全部を合わせず、要素ごとに必要な幅を取る

references/diagnose.md（44行）は逆方向の資料で、すでにあるUIのどこが悪いかを見立てるための手順が入っている。スキルが「作る」だけでなく「直す」側の依頼で発火する設計になっているのは、この資料があるからだ。実測で発火のトリガーになった「素人っぽく見える」という言い回しは、まさにこの診断側の入口にあたる。

発火しても尺度どおりにはならない——適合率を数えた

「発火した＝原則が守られた」とは限らない。出力されたCSSの数値を、スキル自身が配布する尺度と突き合わせて数えた。判定は単純で、font-size の px 値が11段の型に載っているか、padding / margin / gap の px 値が余白スケールに載っているかを機械的に照合しただけである。

改善はしている。型どおりの割合は 0% → 50% → 71% と上がり、CSS変数の数は11個から45個へ4倍になった（HSL指定は33箇所）。尺度を持ち込むという目的自体は達成されている。

一方で見落とせない逸脱も残る。font-size: 32px は余白スケールには載っているが文字スケールには無い値で、28px はどちらにも無い。さらに font-weight が 500・600・700・800 の4種類使われていて、これはスキル自身が定めた「2種類だけ」というルールを外している。800 に至っては「強調は600か700」という明記に反する。

理由ははっきりしている。このスキルには検査の仕組みが無い。 900行はすべて散文の指示で、生成後に値を照合するスクリプトもテストも同梱されていない。前述の照合は筆者が書いた使い捨てのスクリプトで測ったもので、スキルの機能ではない。守られたかどうかを確かめたければ、Stylelint などで尺度を許可リスト化して自分で縛る必要がある。

なお、この発火実行では同梱の別スキル（artifact-design）も併せて呼ばれていた。検証機に他のスキルが入っているため、出力差の全部を refactoring-ui の効果とは言い切れない。適合率の数字はこの交絡を含んだ値として読んでほしい。

ライセンスと、書籍との関係

GitHub のAPIはこのリポジトリのライセンスを NOASSERTION（判定不能）として返すが、LICENSE の実体は MIT である。判定不能になるのは、MIT本文の末尾に次の一段落が追記されているためだ。

この許諾は本リポジトリの記述物（SKILL.md・references/・assets/）にのみ及び、Adam Wathan と Steve Schoger による書籍『Refactoring UI』——参照はされているが同梱はされていない別個の著作物——には及ばない。

つまりスキルが配っているのは、書籍から抽出した数値の尺度と手順であって、書籍の本文・図版ではない。リポジトリ側もその線引きを明示し、書籍の購入リンクを併記している。書籍そのものは有料（公式サイト）なので、スキルを使うことと書籍を読むことは代替関係ではなく、原則の根拠を確かめたければ書籍が要る、という関係になる。

SKILL.md の name フィールドは refactoring-ui（リポジトリ名の -skill は付かない）である点にも注意したい。設置先ディレクトリ名を refactoring-ui-skill にしても動くが、発火時のログには refactoring-ui と出る。

似たスキルとの使い分け

デザイン系のAgent Skillは増えているが、担当範囲が違う。

尺度を新規に決めたいなら本スキル、既存プロダクトの見た目に揃えたいなら designlang で抽出したトークンを先に用意する、という順序が実務的だ。

尺度を守らせる3つの方法と、その強さの差

実測で分かったのは「スキルは指示であって強制ではない」ということだった。では尺度を本当に守らせたいとき、選択肢は何があるか。強い順に3つある。

3つは排他ではなく、下から順に積む関係にある。スキルは「何を選ぶべきか」の知識を持ち込み、tokens.css は選択肢そのものを絞り、linter は違反を止める。スキルだけで運用すると、発火しなかった回だけ静かに尺度が壊れる——これが本記事の実測がいちばん強く示した点である。

stylelint で縛るなら、文字サイズと余白をそれぞれ許可リストにするのが最短だ。

{
  "rules": {
    "declaration-property-value-allowed-list": {
      "font-size": ["/^(12|14|16|18|20|24|30|36|48|60|72)px$/", "/^var\\(--text-/"],
      "font-weight": ["400", "500", "600", "700", "/^var\\(--weight-/"]
    },
    "unit-disallowed-list": ["em"]
  }
}

em を単位ごと禁止しているのは、スキルが最も強い調子で警告している項目だからだ。em は現在の文字サイズに対する相対値なので、1.25em の親の内側に .875em を置くと 17.5px という尺度に存在しない値が生まれる。しかもCSSを読んだだけでは気づけない。ネストが深いほど実際の値が推測できなくなり、スケールは「書いてあるのに機能していない」状態になる。rem ならルート基準なので入れ子で崩れない。

このスキルが向いている場面・向いていない場面

星140、公開から1日というリポジトリなので、大規模導入の実績があるわけではない。向き不向きははっきりしている。

向いているのは、デザイナーが常駐していないチームが、新規の管理画面や社内ツールをAIに書かせるような場面だ。値の選択が毎回ばらつくのを、900行の指示と149行のトークンで一気に均せる。逆に向いていないのは、既にデザインシステムを持っているプロダクトである。既存の尺度と本スキルの尺度が競合し、AIがどちらに寄せるかが不安定になる。その場合は本スキルではなく、既存プロダクトからトークンを機械的に抽出する道具を先に使ったほうが早い。

もう1点、SKILL.md の description が長めに書かれていることは覚えておく価値がある。「UIを作る／整えるとき」「フォントサイズ・余白・色・影・角丸を選ぶとき」「パレットやデザイントークンを設計するとき」「looks off / looks amateur / feels cluttered と言われたとき」と、発火してほしい状況が列挙されている。それでも「カードを作って」では呼ばれなかった。description に書いてあることと、実際に呼ばれることは別——スキルを自作するときにも効いてくる教訓である。

導入手順

設置は1ディレクトリのコピーで終わる。references/ と assets/ も一緒に置かないと、発火時に読みに行くファイルが無くなる。

git clone --depth 1 https://github.com/s0xDk/refactoring-ui-skill.git /tmp/rus
mkdir -p .claude/skills/refactoring-ui
cp -r /tmp/rus/SKILL.md /tmp/rus/references /tmp/rus/assets .claude/skills/refactoring-ui/

# 発火するか確認（何も出なければ呼ばれていない）
claude -p "このUIが素人っぽい。整えて" --output-format stream-json --verbose \
  --allowedTools "Skill,Read" < /dev/null | grep -o 'Launching skill: [a-z-]*'

実測を踏まえた運用上の注意は3つ。

・依頼に「素人っぽい」「整えて」「見た目を直して」を入れる。 「作って」だけでは呼ばれないことがある
・トークンを先に置く。 assets/tokens.css をプロジェクトへコピーして読み込ませておくと、生成側が値を発明する余地が減る
・出力を検査する。 尺度外の値が残るので、Stylelint の許可リストか簡単な照合スクリプトを併用する

実測の再現手順も残しておく。同じ結論が出るかは環境（導入済みの他スキル・モデル）に依存するため、断定ではなく手順として読んでほしい。

# 1) 対照を2つ作る（片方にだけスキルを置く）
mkdir -p with/.claude/skills/refactoring-ui without/.claude
cp -r /tmp/rus/{SKILL.md,references,assets} with/.claude/skills/refactoring-ui/

# 2) 同じ依頼を両方に投げ、Skill 呼び出しの有無を数える
for d in with without; do
  (cd $d && claude -p "統計ダッシュボードのカードを作って" \
     --output-format stream-json --verbose --allowedTools "Skill,Read" < /dev/null \
     | grep -c '"name":"Skill"')
done

この対照を取らないと、出力が良く見えたときにスキルのおかげなのか、モデルが元々そう書くのかを区別できない。実測1で「導入したが未発火」の側が font-size 2/4 と、未導入の 0/3 よりわずかに良かったのも、統計的な差というより1回の揺らぎの範囲で読むべき数字である。n=1の比較で効果を語らないための最低限の作りが、この2ディレクトリ構成になる。

まとめ

・Refactoring UI の原則を、余白16基準・文字11段・太さ2種・影は光源1つという4尺度に落として持ち込むスキル。900行・MIT・★140（2026-08-26 公開の新しいリポジトリ）
・設置しただけでは効かない。 実測では「カードを作って」で発火せず、一覧には表示されていたので読み込みの失敗ではなく経路の問題だった
・description の語を依頼に入れると発火する。 確認は --output-format stream-json で Launching skill: を見る
・発火しても完全ではない。 font-size 5/7、太さは自ルールの2種を超えて4種。検査の仕組みが同梱されていないため、守らせたいなら別途linterで縛る
・ライセンスはMITだが書籍には及ばない。 LICENSE 末尾にその旨が明記されている

星140という規模のとおり、これは大きなフレームワークではなく尺度の配布である。価値の大半は assets/tokens.css と references/systems.md に書かれた数字にあり、スキルとして起動しなくてもその数字を自分のプロジェクトに貼るだけで効果は取れる。発火の当たり外れに悩むより、トークンを先に固定してしまうほうが確実というのが、実測を通した率直な結論である。

書籍そのものを読むかどうかも、ここで一度整理しておきたい。スキルが持っているのは結論としての数値と手順であって、その数値がなぜそうなのかという根拠の記述ではない。「隣り合う値の差を25%以上あける」「太さは2種類まで」といったルールは、SKILL.md では1〜2行の断定として書かれている。運用するぶんにはそれで足りるが、例外を判断したくなったとき——たとえば既存プロダクトの都合で3種類目の太さが要るとき——根拠が無いと決められない。そこが書籍の担当範囲になる。スキルは書籍の代替ではなく、書籍の結論を機械に渡すための翻訳層だと考えるのが実態に近い。

最後に規模の話をしておく。★140・公開から1日というリポジトリは、当サイトの実測基準では「需要が立つ前の題材」に属する。それでも取り上げる価値があるのは、中身が900行しかなく全部読めるからだ。大きなフレームワークだと「入れたのに効かない」が起きたとき原因の特定に時間がかかるが、このスキルは SKILL.md 267行と description 1つを読めば、なぜ呼ばれなかったかまで追える。スキル機構そのものの挙動を学ぶ教材として、小ささが利点になっているという読み方ができる。

実測をもう一段進めるなら、発火した実行と発火しなかった実行を10回ずつ回して適合率の分布を取るのが筋になる。本記事の数字は各条件1回ずつで、差の向きは見えるが幅は分からない。それでも「発火0件」という観測は1回でも十分に意味がある——呼ばれていないなら効きようがないからだ。まず発火させること、それから品質を測ること、という順序は動かない。

参照ソース

・s0xDk/refactoring-ui-skill — 公式リポジトリ。★140・fork 12・MIT（2026-08-27 時点／2026-08-26 作成）
・assets/tokens.css — 配布されるデザイントークン149行
・Refactoring UI 公式サイト — 書籍本体（Adam Wathan & Steve Schoger）
・本記事の実測は 2026-08-27 に macOS・Claude Code 2.1.241 で実行した結果です。適合率の照合は筆者が書いた使い捨てスクリプトによるもので、スキルの機能ではありません