Communitygithub.com

better-ui

表面、アイコン、モーションの視覚的な磨き込みを、ボーダー半径、光学的配置、シャドウ、アイコンの状態、アニメーションの正確な値で行います。

better-ui とは?

better-ui は、UI の視覚的な磨き込み(ポリッシュ)に特化した AI エージェントスキルです。このスキルは、ボタンの押下状態、アイコンの切り替え、テーマ切り替え時のアニメーション抑制など、細部のインタラクションに具体的かつ正確な数値(例:押下スケール0.96、トランジション150ms)を提供します。主に Claude Code、Cursor、Codex などの AI コーディングエージェント向けに設計されており、基礎的なインタラクションが確立された後に適用されます。CSS、Tailwind CSS、Framer Motion などの主要なフロントエンド技術をサポートし、アクセシビリティ(prefers-reduced-motion 対応)やパフォーマンス(will-change の適切な使用、transition-all の禁止)にも配慮しています。また、検出と修正のための包括的なチェックリストと、バグ報告のための明確な重大度基準(HIGH/MEDIUM/LOW)を提供します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Atou4/skillsmith/tree/HEAD/skills/ui-ux/better-ui

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

UI ポリッシュ(磨き込み)

このスキルは、表面、アイコン、モーションの視覚的な磨き込みを、各詳細が取る正確な値とともに保持します。基礎となるインタラクションが確実になった後に適用され、ポリッシュの指摘事項が壊れたインタラクションよりも優先されることはありません。

正確な値、オプションのポリッシュ

以下の値は正確であり、近似する範囲ではありません。cubic-bezier(0.2, 0, 0, 1) は cubic-bezier(0.4, 0, 0.2, 1) ではなく、0.96 は 0.95 ではありません。光学的な微調整と同心パディングのカットオフは例外であり、これらは目視で判断するための開始点です。

プロジェクトのコンポーネントライブラリ、トークン、密度を維持し、ここで値が指定されていない動きのルールには、そのプロジェクトの動きの言語に合わせてください。意図的で一貫したプロジェクトの規約(例:シャドウのないスタイル)は、好みであり指摘事項ではありません。プロジェクト内で同じ詳細が2つの方法で行われている場合は、それが指摘事項となります。

テキストの折り返し、フォントレンダリング、タブラー数字、テキスト間隔は better-typography に属します。ヒットエリア、キーボードサポート、ARIA、および動きの縮小要件は better-accessibility に属します。グループ化、セクション間隔、ブレークポイント、および空間的な RTL(方向性アイコンのミラーリングを除く)は better-layout に属します。カラートークンとコントラスト測定は better-colors に属します。

外側の半径 = 内側の半径 + パディング

ネストされたサーフェスが可視的で均一なインセットを共有する場合、外側の半径は内側の半径にパディングとボーダー幅を加えたものになります。パディングが 24px を超える場合、またはパディングが意図的に非対称である場合は、レイヤーを個別のサーフェスとして扱い、それぞれの半径トークンを保持します。レシピは surfaces.md にあります。

幾何学的な配置が不自然に見える場合は光学的に調整する

幾何学的な中央揃えが不自然に見える場合は、目視で微調整します。ボタンのアイコン側のパディングを 2px 減らし、再生トライアングルをその頂点方向にシフトし、SVG自体で非対称なグリフを修正します。レシピは surfaces.md にあります。

高低差にはシャドウ、構造にはボーダー

ボーダーが高低差を作り出すためだけに存在する場合は、それをレイヤー化された透明な box-shadow 値に置き換えます。区切り線、セパレーター、テーブルセル、選択状態にはボーダーを維持します。また、better-accessibility の下で3:1の非テキストコントラストが必要なフォーム入力にもボーダーを維持します。フォーカスリングも better-accessibility に属します。

強制カラーモードはすべての box-shadow を削除します。シャドウリングの下に border: 1px solid transparent を維持し、そのモードでもエッジが描画されるようにします。レシピは surfaces.md にあります。

画像の輪郭を純粋な黒または白で描画する

コンテンツ画像に 1px インセットの 1px 輪郭線を与えます。ライトモードでは oklch(0 0 0 / 0.1)、ダークモードでは oklch(1 0 0 / 0.1) を使用します。パレットの黒に近い色、着色されたニュートラル、アクセントカラーは決して使用しないでください。これらの色合いは画像の端に色付きのフリンジとして現れるためです。ロゴやイラストなどの透明なアートワークはスキップします。レシピは surfaces.md にあります。

インタラクティブな状態にはキーフレームではなくトランジションを使用する

インタラクティブな状態変化は、CSS トランジションまたはモーションライブラリのスプリングで駆動します。これらは、ユーザーが途中で操作を元に戻した場合に再ターゲットできます。キーフレームは固定のタイムラインで実行され、逆方向に戻せないため、1回だけ実行されるシーケンスのために予約します。animations.md を参照してください。

押下状態は 0.96 にスケール

押下されたボタンは、150ms で ease-out を使用して 0.96 にスケールし、無効なボタンはスケールしません。モーションが気を散らす可能性がある場合に備えて、コンポーネントの既存のバリアント API または static プロパティを介して、ボタンにオプトアウトを提供します。CSS、Tailwind、Motion のレシピ を参照してください。

高頻度のインタラクションは即座に応答する

キーストローク、行ホバー、タブ切り替えは、即座のフィードバック、または opacity や background-color に対する 150ms 以下のトランジションを得ます。表現力豊かなモーションは、ビューの最初の読み込み、成功状態、空の状態など、頻度の低い瞬間のために予約します。

アニメーション化されたすべての状態変化は、色、アイコン、ラベルの形で静的な手がかりも残します。モーションが唯一のフィードバックチャネルになることは決してありません。

モーションを動きの縮小設定の背後にゲートする

better-accessibility が要件を所有し、ここにあるレシピはそれなしでは出荷されません。prefers-reduced-motion: no-preference の下でのみ、移動、スケール、ぼかしを実行します。動きの縮小が設定されている場合は、要素を即座に削除するのではなく、不透明度のクロスフェードに置き換えます。CSS、Tailwind、Motion のレシピは animations.md にあります。

頻度の低いエントランスを 100ms 間隔でずらす

段階的なエントランスでシーケンスが階層を伝える場合、コンテンツをタイトル、説明、アクションなどの意味的なチャンクに分割します。それらを 100ms 間隔でずらし、それぞれが不透明度、4px のぼかし、12px の translateY を 300ms の ease-out で伴って入場します。ルーチンのインタラクションをずらすことは決してありません。enter-exit.md を参照してください。

退出は入場よりも短く、小さい

退出は、不透明度、4px のぼかし、固定の -12px の translateY を 150ms の ease-out で伴い、コンテナの高さ全体では決して行いません。ドロワーが閉じるなど、目的地が意味を持つ場合にのみ、完全にスライドアウトします。モーションが情報を追加しない場合は、要素を即座に削除します。enter-exit.md を参照してください。

最初のレンダリングでは状態アニメーションをスキップする

状態の切り替えをラップする AnimatePresence に initial={false} を設定し、デフォルトの状態がマウント時にアニメーションしないようにします。段階的なヒーローのような意図的なエントランスの周りにこれを設定しないでください。animations.md を参照してください。

コンテキストアイコンを正確な値でクロスフェードする

アイコンが再生から一時停止、コピーからコピー済みなど、頻度の低い状態変化で切り替わる場合、クロスフェードします。スケールは 0.25 から 1、不透明度は 0 から 1、ぼかしは 4px から 0px に実行されます。モーションライブラリを使用する場合は、{ type: "spring", duration: 0.3, bounce: 0 } を使用し、バウンスは常に 0 です。モーションライブラリがない場合は、両方のアイコンを DOM に保持し、300ms で cubic-bezier(0.2, 0, 0, 1) を使用してクロスフェードします。

タブのアイコン切り替えと、行をホバーしたときに明らかになるアクションは、高頻度のインタラクションは即座に応答する に該当します。両方のレシピは icon-transitions.md にあります。

テーマ切り替え時にトランジションを抑制する

テーマの切り替えのためにすべてのトランジションを無効にし、スタイルのフラッシュを強制し、次のフレームの後にトランジションを復元します。そうしないと、すべてのカラートランジションが一度に発火し、切り替えがスメアになります。レシピ を参照してください。

変化するものだけをトランジションする

transition-property: scale, opacity のように正確なプロパティを指定し、決して all を使用しないでください。performance.md を参照してください。

will-change でアニメーションプロパティを指定する

will-change は、最初のフレームでのカクつきを確認した後にのみ追加し、アニメーション化するプロパティを指定します: scale には scale、transform には transform。transform プロパティ、opacity、filter に限定し、決して all を使用しないでください。performance.md を参照してください。

ホバーエフェクトはホバー対応のポインターにのみ適用する

ホバーのみのスタイルは @media (hover: hover) の背後に配置します。タッチでは、:hover はタップ後にラッチされ、スタックした選択状態のように見えます。Tailwind 4 の hover: バリアントは既にそのクエリの下にコンパイルされますが、Tailwind 3 のものはそうではありません。コントロールが独自の押下状態を描画する場合は、-webkit-tap-highlight-color: transparent を設定して、デフォルトのグレーのフラッシュがそれを二重にしないようにします。

オーバーレイ内のスクロールをコンテインする

スクロール可能なダイアログ、ドロワー、メニュー、サイドパネルには overscroll-behavior: contain を指定し、それらの端を過ぎてスクロールしても背後にあるページがスクロールしないようにします。

アイコンのストロークをテキストの太さに合わせる

アイコンのレンダリングされたストロークは、隣接するテキストのウェイトに追従し、400 で 1.5px、700 で 2.5px になります。サーフェスごとに1つのアイコンライブラリを使用します。テーブル、サイジング、グリッドのルールは icons.md にあります。

1つのSVGを状態ごとに色を変えて使用する

アイコンは currentColor を使用し、ホバー、選択、無効の状態を別々のアセットからではなく、CSS の色と不透明度から取得します。アウトラインがデフォルトのバリアントであり、塗りつぶしがアクティブ状態を示します。dir="rtl" の下では、読む方向に従うアイコンのみをミラーリングします。icons.md を参照してください。

終了前の確認

検出修正
同じ rounded-* または border-radius を持つパディングされた親と子外側の半径にパディングを追加する
隣に border がない box-shadow: 0 0 0 1px リングborder: 1px solid transparent
img に対する outline-slate-*、outline-zinc-* または16進数の輪郭色outline-black/10 および dark:outline-white/10
transition-all または transition: all変化するプロパティを指定する
:hover、.open またはその他のトグルされるクラスに設定された animation:同じプロパティに対するトランジション
active:scale-95、scale-90 または 0.96 未満の whileTap0.96
:disabled の除外がない :active スケールenabled:active: または :not(:disabled):active
0 以外に設定された bounce:bounce: 0
animation のみが表示する基本ルール内の opacity: 0from キーフレーム内の非表示状態、animation-fill-mode: both
prefers-reduced-motion、motion-safe: または MotionConfig ガードのない translate、scale、filter または motion.* アニメーションゲートし、動きの縮小設定の下で不透明度をクロスフェードする
disableTransitionOnChange またはオーバーライドのないカラートランジションとテーマトグルテーマ切り替え抑制レシピ
will-change: all、またはアニメーションしない要素に対する will-changeアニメーションプロパティを指定するか、削除する
アイコン SVG 内の fill="#..." または stroke="#..."currentColor
@media (hover: hover) 外のプレーンCSS :hover または Tailwind 3 hover:クエリ内にラップする
overscroll-behavior のないダイアログ、ドロワー、メニューに対する overflow: auto または overflow-y-autooverscroll-behavior: contain

報告

重大度。 HIGH はインタラクションを破壊します。例えば、元に戻せないキーフレームトグルや、タッチでスタックするホバー状態などです。better-interface のエスカレーショントリガーのうち2つがここに該当し、発見され次第 HIGH とみなされます。1つは prefers-reduced-motion を無視するモーションで、もう1つはモーションのみによって伝えられる状態変化です。MEDIUM は、サーフェス、アイコン、モーションにおける目に見える不整合です。LOW は、孤立したポリッシュの問題です。

検証。 ブラウザなしでは、コンポーネントが定義するすべての状態(ホバー、押下、選択、ローディング、空など)を、その持続時間とイージングとともにコードから読み取ります。ブラウザを使用する場合は、各状態をウォークスルーし、ブラウザのアニメーションパネルでモーションを10%の速度で再生します。実行できなかったすべてのチェックを Not verified として報告します。

フォーマット。 指摘事項を、それぞれが違反する原則の下にグループ化し、重大度順に並べ、根本原因ごとに1行で、それが現れるすべての場所をリストします:

重大度場所修正前修正後理由

場所 は path/to/file:line です。理由 は原則とユーザーへの影響を示します。

HIGH が残っている場合は Block で終了し、そうでない場合は Approve で終了します。残りの作業はテーブルに残します。調査しなかった範囲を Approve しないでください。報告することが何もない場合は、「アクション可能な UI ポリッシュの指摘事項はありません」と述べ、検証を報告します。

関連スキル