Communitygithub.com

フロントエンド

キーボード、スクリーンリーダー、低速なスマートフォン、プリンターなど、実際のユーザーが使用するブラウザUIの構築、レビュー、修正時。ネイティブアプリやビジュアルデザインの方向性は対象外。

フロントエンド とは?

このスキルは、実際のユーザーが様々な環境(キーボード、スクリーンリーダー、低速端末、プリンター)で使用するブラウザUIの構築とレビューのための包括的なルールと基準を提供します。アクセシビリティ、パフォーマンス、状態管理、印刷対応など、UIが「見た目が完成した」だけでは見落とされがちな重要な側面に焦点を当てています。Claude CodeやCursor、Codexなどのエージェントで使用でき、適切なHTML要素の使用、非同期ビューの4状態(ローディング、エラー、空、データ)の実装、色だけに頼らない情報伝達、共有可能な状態のURL管理、パフォーマンスの優先順位付けといった具体的なガイドラインを提供します。また、チャート、印刷表示、簡略化ビュー、パフォーマンス最適化に関する個別のリファレンスファイルを参照することで、より深い知識にアクセスできます。このスキルは、視覚的なデザイン方向性(designerスキル)やネイティブモバイルアプリ開発(mobileスキル)とは明確に区別されています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/heliacon/claude-skills/tree/HEAD/skills/frontend

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

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

ドキュメント

フロントエンド は何をしますか?

キーボード、スクリーンリーダー、低速なスマートフォン、プリンターを実際に使う人々のためのブラウザUIの基準。 以下のルールは、UIが「見た目は完成」したときに見逃されがちなものです。

最も重要なルール

  1. その意味を持つ要素を使う。 操作には<button>、ナビゲーションには<a href>、すべてのフィールドには<label>、表形式データには<table>を使用する。クリックハンドラを持つ<div>はフォーカス不可、ロールを持たず、支援技術からは見えない。ARIAはネイティブ要素で埋められないギャップを埋めるためだけに使用する。
  2. すべての非同期ビューには4つの状態がある: ローディング、エラー、空、データ。ビューを完了と呼ぶ前にこれら4つすべてを書く。空白の領域はバグである。
  3. データをでっち上げてはいけない。 欠損期間はギャップまたは「データなし」ラベルで表現し、ゼロや補間線にしてはいけない。予測値は常に実測値と視覚的に区別できるようにする。
  4. 色だけで伝えてはいけない。 色分けされたすべてのステータスには、テキストまたはアクセシブルな名前を持つアイコンも併記する。グレースケール印刷や色覚障害のある読者は、そうしなければ何も得られない。
  5. 共有可能な状態はURLに保存する。 フィルター、タブ、検索語、選択ID。戻る、更新、共有で状態が維持されなければならない。一時的な状態(ホバー、開いたツールチップ)はURLに入れない。
  6. 複数の状態から導き出される値は、そのいずれかが変更されるたびに呼び出される1つの関数で処理する。 決してそのうちの1つに属するコールバック内で計算してはいけない。例:カットオフとグループフィルターから構築されたダウンロードリンクが、カットオフのフェッチコールバック内でのみ再構築されたため、フィルター変更後にエクスポートが黙って全リストを指していた。
  7. 320 CSS pxからリフローに対応する。 水平方向のページスクロールなし、クリップされるコンテンツなし、テキストは200%に拡大可能。設計したデスクトップ幅だけでなく、電話の幅でもテストすること。
  8. ツールはニーズに合わせる。 既存のリポジトリでは、すでにあるフレームワークとビルドに従う。小さな新しいページや内部ツールでは、ビルドパイプラインを追加する前にプレーンなHTML、CSS、少しのJavaScriptを検討する。状態が本当にそれを要求する場合にのみフレームワークに手を伸ばす。

使用しない場合

  • ビジュアルの方向性、タイポグラフィ、パレットの選択:designerおよびvisual-designスキル。
  • ネイティブiOS、Android、React Native:mobileスキル(およびSwiftコードにはswift)。
  • APIの形状とサーバーエンドポイント:api-designおよびbackend-patternsスキル。
  • 詳細なテスト技法:tddおよびtesting-strategyスキル。

状態の居場所

コンポーネント状態を書く前に決定する。ローカルから始め、明確な理由がある場合のみスケールアップする。

状態所在例
ローカルUIコンポーネント状態モーダル開閉、入力ドラフト、ホバー
兄弟間で共有最も近い共通の親2つのパネルで読み取られるアクティブタブ
サーバーデータサーバーキャッシュライブラリ(TanStack Query、SWR)またはフレームワークのローダーAPI応答、ページネーション、再フェッチ
アプリ全体のクライアント状態必要な場合のみ、小さなストアログインユーザー、通知キュー
共有可能なビュー状態URLクエリまたはルートフィルター、検索、選択ID
リロード後も持続、デバイスごとlocalStorage設定、未送信のドラフト

以下の場合のみスケールアップする:無関係な2つのコンポーネントが同じ状態を必要とする場合(リフトするか、サーバーキャッシュを使用)、状態がリロード後も持続する必要がある場合(URLまたはストレージ)、データがサーバーから来る場合(サーバーキャッシュを使用し、グローバルストアは使わない)。グローバルストアにコピーされたサーバーデータは古くなり、ローディングとエラーのロジックが重複する。

チャート、印刷、簡略化ビュー

  • チャート:フロントエンドとバックエンドで共有する1つのカラーマップ、明示的な空の状態、正直なギャップ、HTML凡例。チャートを構築または変更する前にreferences/charts.mdを読む。
  • 印刷またはPDF:印刷可能なビューを構築する前にreferences/print.mdを読む。キャンバスは、そこに記述されているキャプチャ手順なしでは確実に印刷できない。
  • 非技術読者向けの簡略化または読み取り専用ビュー:編集コントロールなし、余裕のあるテキストとターゲットサイズ、色と単語によるステータス、データから計算された平易な要約、少ない画面数、生のテーブルではなく短い文章と主要な数値。

パフォーマンス

影響の大きい順に修正する:まずリクエストウォーターフォール、次に配信されるJavaScript、次にサーバー応答時間、その次にインタラクション中のメインスレッド作業、最後にマイクロ最適化。目標:実際の訪問の75パーセンタイルでLCP 2.5秒以下、INP 200ミリ秒以下、CLS 0.1以下。ページが遅い場合、重い依存関係を追加する前、またはパフォーマンス目標のあるリリース前にreferences/performance.mdを読む。

ハマりどころ

  • レンダーパスはホットループである。 コンポーネント本体や算出ゲッターは、ホバーや無関係な状態変更のたびに実行される。そこでの重い導出はメインスレッドを枯渇させ、最初の症状は別の場所での不安定なテストかもしれない。重複を排除し、上流の入力でメモ化する。
  • 宣言されていないCSSカスタムプロパティは静かに失敗する。 トークンが--font-monoのときにvar(--mono)と書くと、宣言は計算値時点で無効になる:プロパティは継承され、エラーは発生しない。ショートハンド(font: 400 10px/1 var(--mono))では、サイズと行の高さも失われる。var()にフォールバックを与えるか、ビルドされたスタイルシート上で宣言されたトークンと参照されたトークンを確認する。
  • チャートの高さはラッパーに指定する。 canvasに高さを指定すると、ライブラリのリサイズロジックと競合し、リサイズのたびにチャートが成長する。
  • カスタムウィジェットでのフォーカス管理はあなたの仕事である。 ダイアログを開くときはフォーカスをその中に移動し、閉じるときはトリガーに戻す。Escapeで閉じる。ネイティブの<dialog>要素を優先する。innerHTMLでマークアップを再構築するとフォーカスが失われる。
  • outline: noneを代替なしで使うと、キーボードユーザーが頼りにする唯一の手がかりを削除する。代わりに:focus-visibleを使用してスタイルを設定する。
  • アイコンのみのボタンには名前が必要(aria-labelまたは視覚的に隠されたテキスト)。
  • クライアントフェッチ後にのみ存在するコンテンツは、弱いデバイスでは遅く、JavaScriptが失敗すると空白になり、クローラーにとっては弱い。スタックが許せば、意味のあるコンテンツをサーバーでレンダリングする。
  • サイズ指定のないメディアはレイアウトをシフトさせる。 画像、動画、埋め込みにはwidthとheight(またはaspect-ratio)を設定する。ファーストビューで最大の要素となる画像を遅延ロードしてはいけない。
  • 手作りのドロップダウン、タブ、スライダーには、WAI-ARIAオーサリングプラクティスに基づく完全なキーボードモデルが必要である。ネイティブ要素の方がほとんどの場合、コストが低い。
  • 手書きのフェイクDOMはテストを無力にする可能性がある。 フェイクが参照のたびに新しいオブジェクトを返す場合、それに書き込まれたすべてのプロパティ(href、disabled、value)は失われ、それに対するアサーションは失敗できない。機能を元に戻し、テストが失敗することを確認してから信頼する。
  • 固定バージョンのCDN、固定しないバージョンは使ってはいけない。 固定しないスクリプトはコミットなしで変更される。

検証

新しいツールを追加する前に、プロジェクトにすでにあるもの(テストランナー、リンター、型チェッカー、アクセシビリティツール)で証明する。

  • テスト、リント、型チェックが通る。新しいテストは、機能を元に戻した状態で失敗することを確認した。
  • ページをレンダリングし、電話幅とデスクトップ幅で目視確認した。可能な場合は、レビュアーにスクリーンショットだけでなく実行中のプレビューも提供する。
  • キーボードのみ:すべてのコントロールが到達可能、操作可能、視覚的にフォーカスされている。順序は視覚的な順序と一致する。トラップがない。
  • 自動アクセシビリティ監査(axe、Lighthouse、またはプロジェクトのツール)で新しい違反がない。ツールでコントラストを確認:本文テキスト4.5:1、大きなテキストとUIコンポーネントの境界線3:1(WCAG AA)。
  • ローディング、エラー、空、データの各状態を、それぞれ強制して表示した。
  • 共有可能な状態は更新と戻るで維持される。
  • コンソールにエラーと警告がロード時および使用中にゼロである。
  • 依存関係を追加する場合や重いビューに触れる場合、パフォーマンスバジェットを確認した(バンドルアナライザー、スロットルプロファイル)。
  • ページが印刷可能な場合、印刷プレビューを確認した。

レビューの場合、ファイルごとに、破られたルールと修正を重大度順に報告する。

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

関連スキル