デザインシステム基礎講座にHTML/CSS実例を追加した記録

自分が書いた記事をそのまま流し込んだだけの「デザインシステム基礎講座」に、朝から晩まで手を入れ続けた一日だった。スキルとして成立しているのか自分で疑い、Codexに率直な評価を求め、方針を転換してから、Workflowにページ構成・レイアウト・26種のビジュアルスタイルを並列で組ませては表示を確認する、という往復を何度も繰り返した。夕方にはCloudflare Workerのバンドル余裕を測って公開し、7つに分けてコミットするところまで進んだ。

この日の流れ

07:30〜スキル化への疑問 → Codexレビュー → 独立講座へピボット
09:35〜外部のデザインシステム集と突き合わせて既存チャプターの記述を修正
09:49〜計画書に沿ってStep 0〜6を実装（バグ修正・ページ構成・レイアウト・26スタイル・拡張候補）
12:51〜バンドルサイズ確認 → デプロイ事故の切り分け → 公開 → 7コミット＋学習ゲート

スキル化を疑って、独立講座に舵を切った

前日から進めていた「デザインシステム基礎講座」は、最初はスキル（design-system）として仕立てる計画だった。SKILL.mdとreferences 6本をWorkflowで生成させ、原典記事との突き合わせ検証まで一度完了させていた。26スタイル全種・組み合わせ8例が漏れなく収録されているところまで確認できていたが、ふと「これは自分が渡した文章をそのままスキル化しただけで、モデルが元々持っている一般知識と重複しているだけではないか」という疑問がわいた。

Codexにこの疑いをそのまま投げてレビューさせたところ、指摘は的中していた。既存の「Claude Codeスキル実践」シリーズは実在するダウンロード可能なスキルの設計思想を解説するという建て付けなので、中身が薄いスキルをそこに乗せると看板に偽りありになる。一方でExcel基礎講座という、特定スキルに紐付かない独立した知識講座の前例があったので、そちらのパターンに乗り換えることにした。

ピボットの手順はこうだった。まずスキルファイル一式を削除し、計画書を独立講座向けに書き直す。次にExcel基礎講座の実装を参考資料として読み込み、独立講座としての配置パターンを把握する。最後にCodexへもう一度レビューを依頼する。この2回目のレビューで、TheaterViewer.vueのモバイル分岐がstageHtmlを一切参照していないという、既存講座全体に及ぶ実在のバグを見つけてもらえた。指摘を鵜呑みにせず自分でコードを開いて確認したところ、確かにモバイル分岐だけがexercise/videoモードと違う実装になっていた。

実装に入る前には、既存の型定義（TOCItem・MillerChapter・MillerSection）とページの雛形、NG/OK対比に使う.cmp共通スタイル、空いているmajorId帯も一通り確認した。生成されるVue/TypeScriptが既存の規約から外れないよう、正確性が要るところは自分の目で先に読んでおく方針にした。

外部のデザインシステム集と突き合わせて中身を整えた

実例を作り込む前に、公開済みの「レスポンシブ・アクセシビリティ」チャプターの記述が薄くないか確認したいと思い、GitHub上の外部リポジトリ（73ブランド分のデザイン方針集、各ファイルが9セクション固定フォーマット）と突き合わせてレビューした。10ページ全てをブラウザで通しで確認したが表示崩れはゼロで、問題は表示ではなく「考えること7点」という表記と実際の項目数がずれている中身の話だと分かった。

念のため機械的にも検証した。リポジトリのツリー構造を取得し直し、ブランドごとにファイル欠落がないかを目視ではなく突き合わせで確認している。該当する「7点」表記の出現箇所をすべて洗い出して計画書に落とし、表記を直したうえで、レスポンシブ設計チャプターの「考えること6点」リストからアクセシビリティチャプターへの相互参照も追加した。編集後はcontent JSONを再生成し、ブラウザで新しい注記の行が実際にコードブロック内に出ていることまで確認している。

Workflowで生成させては表示を確認する、を繰り返した

独立講座としての本番は、まずStep 0のバグ修正から。TheaterViewer.vueのモバイル分岐を既存のexercise/videoモードと同じパターンに直し、既存3講座でモバイル表示に影響が出ていないか回帰確認してから次に進んだ。

ここから先は同じ形の往復になった。

ページ構成の実例（Header/Hero/Problem/Solution/Feature/Step等）とレイアウトの型（1〜3カラム・グリッド）の2本をWorkflowに並列生成させる
待っている間に次の判断事項をユーザーに確認する
出てきた原稿をファイルに挿入し、型チェックを通す
content JSONを再生成し、ブラウザでPC幅・モバイル幅（375×812）の両方を確認する

実際に生成させたページ構成の実例では、パンくず・左サイドバーの目次・フック文の強調表示まで含めて描画に崩れがないかを確認し、レイアウトの型の実例ではPC幅で完璧に組めていることを確認したあとモバイル幅でも崩れがないか見た。ここまでで「ページ構成」「レイアウトの型」の2セクションが計画どおり完了した。

この一周が終わったところで、ビジュアルスタイル26種のギャラリーも同じ形でWorkflowに並列生成させた。フラットデザインからBento UIまで、共通のマークアップ構造をあらかじめ設計してから並列で書かせている。JSONをPythonでパースして各スタイルをファイルに分離する段でheredocのエスケープが崩れ、スクリプトをファイルに書いてから実行し直す一幕もあった。挿入後の型チェックで1行だけ引っかかったのでピンポイントで直し、26種すべてがPC幅・モバイル幅で正しく並んでいることを自分の目で確認した。実際のセクション数を数え直して、目次のスライド数（A/Bのチャプターが18→20、Cのチャプターが12→13）も正確な値に補正している。

拡張候補として残していたコンポーネント状態（hover/loading）とカラースウォッチも追加した。ボタンをクリックすると「処理中...」の表示に切り替わり、1.8秒後に元へ戻る挙動まで実際にクリックして確認している。角丸・影は既に実物プレビュー付きで実装済みだったので、この項目はスキップした。

「コーポレートもBentoも全部入れてほしい」で、もう一周

一連の実装が完了したあと、追加で気になっていた箇所の画像が壊れているという指摘が来た。確認すると、参照先の画像ファイルそのものが存在せず、alt文字列がそのままテキスト表示されて崩れていた。既存アイコンのパターンに合わせて作り直し、ブラウザで直っていることを確認した。

続けてフラットデザインなど4スタイルの深掘りページとトーン12種のギャラリーを16件まとめてWorkflowに並列生成させた。完了を待つ間にもう1件の依頼を計画書へ積み残しとして先に記録しておき、完了後にmillerDsVisualStyles.tsとmillerDsToneAndColor.tsへ統合、型チェックとPC幅・モバイル幅のブラウザ確認まで済ませて報告した。すると「コーポレートもベントも全部入れてほしいんですよ」と、追加要望が飛んできた。当初は絞り込むつもりだった範囲を全部含める方針に切り替え、同じ並列生成→統合→型チェック→ブラウザ確認のループをもう一周させ、既存2セクションの末尾にコーポレートデザインとBento UIの実例を追加した。ボタン・カード・バッジ等のUI実装は、この日の範囲を超えると判断して計画書に積み残しとして記録した。

バンドルの余裕を測ってからデプロイした

夕方、Cloudflare Workerバンドルの余裕が273.6 KiBまで減っていることに気づいた。SVG図解や既存のスキル実践講座がバンドルを圧迫しているのではと疑い、デプロイはしないビルドだけを走らせて実測した。クライアントビルド→サーバービルド（Nitro）→Cloudflare Pagesプリセットの最終バンドリング、という段階を一つずつ追いながら数分単位で待つことになったが、結果としてSVGや講座データはほぼバンドルを消費していないと分かった。

ここで検証用に自分がバックグラウンドで走らせていたビルドと、並行して走らせていた本番デプロイが、同じキャッシュディレクトリ（node_modules/.cache/nuxt/.nuxt）を取り合って壊れる事故が起きた。原因を自分のバックグラウンドビルドだと特定し、デプロイ履歴を見て失敗ビルドは記録に残らず本番には実害が出ていないことを確認してから、キャッシュを消して単独で再デプロイした。デザインシステム基礎講座とlearn-gate講座のdraftも解除し、公開に切り替えて、拡張機能が使えなかったのでWebFetchで本番URLを直接取得し、両講座が実際に公開されていることまで確認した。

7つのコミットと7回の学習ゲート

最後にコミットを頼んだところ、未コミット変更にはsvg-diagram講座への追加・design-system講座の新規追加・両講座のdraft解除公開という3つの独立した作業とゴミファイルが混ざっていた。意味の通る単位に切り分け、コミットのたびに学習ゲートの/learnを走らせた。

クイズは2回誤答した。1回目は共有CSSクラスの理解、2回目は「draft:trueは開発環境限定で本番では無視される」という誤った理解だった。どちらも教え直しを受けて再挑戦し、正解して受領証を発行してもらっている。「/learnが何回も出てくるのはなぜか」と聞いたら、コミット1回につき1回発火する仕組みだからと説明を受けた。最後にworker-bundle-history.csvも、過去の運用慣習に倣ってコミットに含めた。合計7つのコミットで、この日の作業を締めくくった。

学びメモ

スキルを作る前に「これは既に一般知識では」と自分の手を止めて疑い直したら、Codexのレビューがその疑いを裏付けてくれた
Workflowに並列生成させたあとは、自己申告（allPassed: true）を鵜呑みにせず、ディスク上のファイルとブラウザの表示を自分の目で確認するところまでがワンセットになっている
バックグラウンドビルドと本番デプロイを同時に走らせるとキャッシュが壊れると分かったので、次回はデプロイ前に他のビルドが動いていないか確認する一手間を先に入れる

次にやること

依頼③として積み残したボタン・カード・バッジ等のコンポーネントUI実装
計画書に残る「ページごとの本文⇔図解レビュー」を講座を見ながら進める