Webツール
概要
ブラウザで使うWebツールを docs/web/ 配下に作成・編集し、ツール集に追加するための作業手順を整理する。
重要ファイル
- •
docs/web/*.html - •
docs/index.html - •
docs/theme.css - •
docs/image/ - •
docs/firebase.js
手順
- •ツールの目的と配置場所を決め、
docs/web/<name>.htmlまたはdocs/web/<name>/index.htmlを作成・編集する。 - •HTMLで
../theme.cssを読み込み、ツール集と同じテーマを適用する。 - •
.cssや.jsを別ファイルから読み込む場合、対象ファイルに実際の更新があったときのみ?v1のようなクエリ末尾をインクリメントして更新を明示する。 - •手順3は新規作成時だけでなく、既存ページの修正・リファクタリング時にも必ず適用する。
- •共有機能が必要なら
docs/firebase.jsをES moduleとして読み込む。 - •UIは既存のスタイルに合わせ、ページ破壊を避ける配置と
z-indexを意識する。 - •
docs/index.htmlにツールへのリンクカードを追加・更新する。 - •必要に応じて
docs/image/にスクリーンショットを追加する。 - •対象ページで手動確認する。
- •作業完了前に、変更した外部ファイル参照（
theme.css/*.js/*.css）のクエリバージョンを対象HTML全体で再確認する。
バージョン確認チェック（必須）
- •変更した外部ファイルがある場合は、公開対象HTML（
docs/web/**/*.html）で当該参照を検索し、古い?vが残っていないことを確認する。 - •共通ファイル（例:
docs/theme.css,docs/web/tool-common.js）を更新した場合は、そのファイルを読み込む全ページで?vを揃える。 - •
?vを上げた場合はハードリロードでキャッシュ影響を除外して確認する。
実装コメント方針
- •関数を新規追加・修正・移動した場合は、原則として関数定義の直前に「目的」と「概要」が分かる短いコメントを入れる。
- •コメントは手順説明ではなく、その関数が何を受け取り、何を返し、どの責務を持つかに限定して書く。
- •1行で意図が伝わる関数は1行コメント、複数責務を含む関数は2〜3行コメントで簡潔に説明する。
- •既存関数を大きくリファクタリングした場合は、同時にコメントも更新し、実装との差分を残さない。
注意点
- •Firebaseのローカル設定は
docs/firebase.config.local.jsに置き、公開対象に入れない。 - •
docs/配下はすべて公開対象なので、機密情報やローカル専用の設定は置かない。
UI方針
- •操作や機能の説明は原則として本文テキストで増やさず、UIの形状・配置・アイコン・ラベルで読み取れる設計を優先する。
- •補足説明が必要な場合でも、計算式や検証メモのような内容説明に限定し、操作手順の説明文は最小限にする。
- •一般的なUI要素（カード、区切り線、ボタン、共通レイアウト）は基本的に
docs/theme.cssの既存クラスを使う。 - •共通化できる新しいUI要素を追加する場合は、ページ固有CSSではなく
docs/theme.cssに定義して再利用する。 - •計算ツール（入力と出力を持つページ）は、出力エリアをページ上部に配置し、
position: stickyで固定する。 - •計算ツールの出力エリアはページごとに個別実装せず、共通クラス（
docs/theme.css側の出力用クラス）で同じ見た目を使う。 - •計算ツールの結果表示マークアップと描画処理は、
skills/web-tool/resources/calc-output-snippet.htmlとskills/web-tool/resources/calc-output-snippet.jsを雛形として流用し、ラベル左/値右の同一レイアウトに統一する。 - •計算ツールの詳細表示は「カード内カード」を禁止し、
result-detail-entryを使ったシンプルな行リストで表現する（過剰な余白を作らない）。 - •計算ツールの詳細表示は、
result-detail-title/result-detail-list/result-detail-entry/result-detail-meta/result-detail-valueの表記を共通化して使う。