Communitygithub.com

Xipher-Labs/walter-os

フロントエンド品質基準を適用します。アクセシビリティ(WCAG 2.2 AA)、パフォーマンス(Core Web Vitals: LCP/INP/CLS)、セマンティックHTML、画像最適化、バンドルサイズ、モバイルファースト、ローディング/空/エラー状態をチェックします。React、Next.js、Astro、Svelte、Vueのコンポーネント、CSS/Tailwind、レイアウトファイル、または `app/`、`components/`、`pages/`、`src/` 内のファイルに変更があるPRに対してこのスキルを使用してください。

walter-os とは?

このスキルは、フロントエンドUIの品質基準をコードレビューに強制するものです。アクセシビリティ(WCAG 2.2 AA)、パフォーマンス(Core Web Vitals)、セマンティックHTML、画像最適化、バンドルサイズ、モバイルファースト、そしてローディング・空・エラー・部分/古い・成功の5つの状態をすべてのデータ駆動コンポーネントで処理することを必須とします。特に、アルゼンチンのモバイルユーザーが遅い3G/4G回線で利用するプロジェクトや、開発者向けドキュメントサイトなど、実際のユーザー体験に直結する問題を検出するために重要です。このスキルは、`*.tsx`、`*.jsx`、`*.svelte`、`*.vue`、`*.astro`、`*.css` ファイルの差分に対して自動的にトリガーされます。レビュー結果は、[BLOCKING|WARN|NIT] の重要度とともに、影響範囲と具体的な修正案、確認方法を含む標準化された形式で出力されます。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Xipher-Labs/walter-os/tree/HEAD/skills/frontend-quality

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

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

ドキュメント

フロントエンド品質基準

あらゆるユーザー向け Web UI の品質基準。ハード要件(アクセシビリティ、パフォーマンス、モバイルファースト)であり、スタイル上の好みではありません。レビューは、実際のユーザーにとって重要なバグ(遅いページ、壊れたキーボードナビゲーション、読み込み中にレイアウトがずれるなど)をキャッチします。

モデルルーティング

モデルがUI、UX、視覚階層、アクセシビリティコピー、またはインタラクションの詳細を批評または書き換える必要がある場合は、オペレーターのフロントエンド設定を使用します。

source "$WALTER_OS_HOME/scripts/walter/lib/model-router.sh"
frontend_model=""
walter_model_resolve frontend frontend_model

デフォルトの設定は Claude です。オペレーターは ~/.config/walter-os/overlay/personal.env でエイリアスを別の LiteLLM ルートに変更できます。

このスキルは、フロントエンドに影響する差分に対して自動的にトリガーされます。ゼロからランディングページを構築する場合は、landing-page-fast(このルールを含み、さらにスキャフォールディングを提供します)を使用してください。

このオペレーターにとってこれが重要な理由

  • [プロジェクトA] のユーザーはアルゼンチンの中小企業のサプライヤーであり、多くがスマートフォンで、3G/4Gの不安定な接続環境にあります。サイトが遅いとユーザーは離脱します。WCAG が重要なのは、一部のユーザーがデジタルリテラシーが低く、視覚障害を持っているためです。
  • [プロジェクトB] のユーザーには障害のある患者が含まれます。WCAG は「あると良い」機能ではなく、ユーザビリティ上の要件です。
  • [会社] ドキュメント は、洗練された開発者によって読まれており、サイトが遅かったりキーボード操作が壊れているとすぐに離脱します。

アクセシビリティ(WCAG 2.2 AA — 必須)

キーボード

  • すべてのインタラクティブ要素は Tab キーで到達可能であること。ボタン、リンク、フォームフィールド、カスタムコントロール。手動で Tab キーによる操作を確認し、スキップされたコントロールがあれば BLOCKER。
  • フォーカスが可視であること。:focus-visible のアウトラインは明確である必要があります。代替手段なしに outline: none を設定しないでください。
  • 論理的なタブ順序。読み取り順序が DOM 順序と一致していること。tabindex の値が 0 より大きいものは避けてください(自然な流れを壊します)。
  • スキップリンク。すべてのページの最初のフォーカス可能要素は「メインコンテンツにスキップ」であること。
  • Escape キーでモーダルを閉じる。モーダルが閉じられるまで、フォーカスをモーダル内に閉じ込めます。

セマンティックHTML

  • アクションには <button>、ナビゲーションには <a>。どちらにも <div onClick> を使用しないでください。
  • 見出しは階層構造に:ページに1つの <h1>。<h2> ... <h6> はレベルをスキップしない。
  • ランドマーク:<header>、<nav>、<main>、<footer>。ARIA ロールは、適切なセマンティック要素がない場合のみ使用します。
  • リストは <ul> / <ol>。<div> でリストを偽装しないでください。
  • フォームコントロールには <label> を。for 属性が id と一致していること。

色とコントラスト

  • WCAG AA コントラスト最小値:本文テキスト 4.5:1、大きいテキスト(18pt以上、または14pt以上の太字)3:1、UIコンポーネントとグラフィック 3:1。
  • 色だけが唯一のインジケーターではない:エラー状態は、赤い枠線だけでなく、アイコン + テキスト + 色で示します。
  • シミュレートされた色覚異常でテスト。Stark、axe DevTools、またはブラウザ開発ツールの色覚シミュレーターを使用します。

フォーム

  • すべての入力には可視ラベルがあること。プレースホルダーはラベルではありません。
  • エラーメッセージはプログラム的に関連付けられている(aria-describedby を使用)。
  • 必須フィールドはマークされていること。視覚的(* または「必須」)およびプログラム的(aria-required="true" または required)の両方。
  • バリデーションエラーはフォーカス時に消えない。修正されるか、却下されるまで永続する。
  • 成功状態が確認されている。送信後、スクリーンリーダーユーザーがそれが機能したことを認識できる。

画像とメディア

  • すべての <img> に alt 属性。装飾用は空(alt="")、コンテンツ用は説明的に。生成AI画像:プロンプトではなく、画像に実際に何が写っているかを説明する。
  • ビデオ/オーディオにはキャプション/トランスクリプト。
  • 音声付きの自動再生は禁止。
  • アニメーションは prefers-reduced-motion を尊重する:
    @media (prefers-reduced-motion: reduce) {
      *, *::before, *::after {
        animation-duration: 0.01ms !important;
        transition-duration: 0.01ms !important;
      }
    }
    

ツール

  • 開発モードで @axe-core/react — アクセシビリティ問題をコンソールに記録。
  • eslint-plugin-jsx-a11y — ビルド時にキャッチ。
  • ローンチ前に 手動スクリーンリーダーテスト:VoiceOver(Mac)、NVDA(Windows)、TalkBack(Android)。
  • CI で Lighthouse アクセシビリティスコア ≥ 95。

パフォーマンス — Core Web Vitals

Google がランキングに使用する3つの指標。すべてに合格して「良好」と評価されること。

LCP(Largest Contentful Paint)— 読み込み速度

目標:3G で 2.5 秒未満。[プロジェクトA] の実際の環境では、アルゼンチンのモバイルネットワークは中央値よりも遅いため、より厳格です。

方法:

  • LCP 画像をプリロード:<link rel="preload" as="image" href="...">
  • レンダリングブロックするリソースなし:重要でないJSは defer、クリティカルなCSSはインライン化。
  • フォントはセルフホストし、font-display: swap を使用するか、システムフォントスタックを使用します。
  • 静的アセットには CDN:Vercel、Cloudflare R2、Bunny.net。
  • HTTP/2 または HTTP/3:Vercel/Cloudflare のデフォルト。
  • 画像を圧縮:WebP/AVIF、ビューポートに合わせたサイズ。
  • 特にヒーロー画像を最適化:ほとんどの場合、これが LCP になります。

INP(Interaction to Next Paint)— 応答性

目標:p75 で 200ms 未満。2024年にFIDから置き換えられました。

方法:

  • インタラクション中にメインスレッドで 50ms を超える長時間タスクを禁止。
  • ハイドレーションを遅延(Astro アイランド、Next.js ストリーミング、qwik)。
  • 重い計算には Web Workers。
  • 入力ハンドラーを デバウンス/スロットル。
  • 大きな文字列での dangerouslySetInnerHTML を避ける — 解析がブロックされる。
  • useMemo / memo は測定した場合のみ、先制的に使用しない。

CLS(Cumulative Layout Shift)— 視覚的安定性

目標:0.1 未満。

方法:

  • 画像と動画のタグに width + height を指定(ブラウザがスペースを予約する)。
  • 広告/埋め込み用にスペースを予約(min-height を使用)。
  • 既存のコンテンツの上にコンテンツを挿入しない:通知バナーはフォールドの下に配置するか、DOM の上に挿入するのではなく、transform で押し下げます。
  • Webフォント:メトリクスを一致させるために font-display: swap + size-adjust を使用するか、可能であれば font-display: optional を使用します。
  • スケルトン画面のサイズは実際のコンテンツに合わせる。

バンドルサイズ

  • 初期 JS の予算:ランディングページは 150KB gzip 未満、アプリシェルは 250KB 未満。
  • ルートごとにコード分割(Next.js、Astro、SvelteKit はデフォルトでこれを行う)。
  • 重要でない重い依存関係は動的インポート(チャート、エディター)。
  • 依存関係を監査:bundle-analyzer または next-bundle-analyzer。1つのコンポーネントだけインポートするために 10MB のUIライブラリを削除する。
  • ツリーシェイキングが機能していること:必要なものだけをインポートする(import { thing } from 'lib' であって import lib from 'lib' ではない)。

読み込みパターン

  • 必要なオリジンにプリコネクト:<link rel="preconnect" href="...">
  • 次に遷移しそうなページをホバー/フォーカス時にプリフェッチ(Next.js はこれを行う)。
  • フォールドより下の画像は遅延読み込み:loading="lazy"
  • iframe は遅延読み込み:loading="lazy"
  • オフラインファーストのための Service Worker(適切な場合 — [プロジェクトA] は恩恵を受けるが、マーケティングページは受けない)。

状態 — すべてのコンポーネントが5つすべてを処理する

データ駆動型の UI の場合、どの状態も処理されていないと BLOCKER。

  1. ローディング — スケルトンまたはスピナー。空白画面は不可。レイアウトシフトも不可。
  2. 空 — 初回、データがない状態。データを投入するための CTA を表示。
  3. エラー — 明確なメッセージ、再試行ボタン、ユーザーにスタックトレースを表示しない。Sentry にログ出力する。
  4. 部分 / 古い — データがキャッシュまたは部分的なフェッチからのものである場合。
  5. 成功 — ハッピーパス。

リストの例:

if (isLoading) return <ListSkeleton />
if (error)     return <ErrorState onRetry={refetch} />
if (data.length === 0) return <EmptyState cta={...} />
return <List items={data} />

コンポーネントに diff で示された成功状態のみしかない場合、他の4つの状態はどこにあるのかを尋ねてください。

モバイルファースト

  • まず 360px 幅でデザインし、スケールアップする。
  • タッチターゲットは 44×44px 以上(Apple HIG)または 48×48px(Material)。
  • ホバー専用のインタラクションは禁止:ホバーで利用可能なものはすべて、フォーカス/タッチのパスもあること。
  • 実機または Chrome デベロッパーツールのスロットリングでテスト:3G ネットワーク、4倍 CPU 低下。
  • フォームはズームなしで動作:入力の font-size: 16px+(そうしないと iOS はフォーカス時にズームする)。

ツールリファレンス

CI / マージ前:

  • Lighthouse CI(指標ごとの予算あり)。
  • @axe-core/cli または Lighthouse アクセシビリティサブセット。
  • bundlewatch — バンドルが予算を超えた場合にPRを失敗させる。
  • ビジュアルリグレッション:Chromatic(Storybook)、Percy、または Playwright のスクリーンショットをチェック。

ローカル:

  • Chrome DevTools の Performance + Lighthouse パネル。
  • unlighthouse — サイト全体の監査用。
  • @unjs/check-vitals — ワンショットの Web Vitals チェック用。

出力形式

**[BLOCKING|WARN|NIT] [FE-N] <一行の説明>**

場所:`path/to/Component.tsx:42-58`
カテゴリ: <a11y | perf | states | mobile | semantic>
影響: <どのユーザー / シナリオ / 指標>
修正: <具体的な変更、コードが適切ならそれも>
確認: <確認方法 — Lighthouse 実行 / 手動テスト / など>

重要度:

  • BLOCKING:WCAG AA 違反、コアフローの破損、「Poor」範囲の Web Vitals 違反。修正必須。
  • WARN:ベストプラクティスのギャップ、まだユーザーに顕在化していないパフォーマンス低下。
  • NIT:改善の機会(より小さいバンドル、より良いスケルトン)。

ハードルール

  • ボタンに <div onClick> は使用禁止。常に。
  • alt なしの画像は禁止。常に。
  • 実際のコンテンツによるレイアウトシフトは禁止。常にスペースを予約する。
  • 音声付きの自動再生は禁止。常に。
  • prefers-reduced-motion を尊重する。常に。

このスキルがカバーしないもの

  • バックエンド(web-security-baseline を使用)。
  • DB スキーマ / クエリ(data-migration-safety を使用)。
  • ブランドアイデンティティ / ビジュアルデザイン(brand-creation を使用)。
  • 新しいランディングページの構築(スキャフォールディングを提供する landing-page-fast を使用)。

参考資料

  • WCAG 2.2 クイックリファレンス
  • web.dev Core Web Vitals ドキュメント
  • web.dev パフォーマンス学習パス
  • Heydon Pickering 著「Inclusive Components」
  • The A11y Project チェックリスト

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

関連スキル