Codexで既存CSSだけを
使って説明ブロックを
追加した実践ログ

今回やった作業

公開中サイトで説明ブロックや静的guideを追加する際に、新規CSSを増やさず、既存のCSS classを使って表示した作業を一般化して書きます。この作業では、見た目を新しく作るのではなく、すでにサイト内で使われている白ボックス、guide系のブロック、チップ、カードグリッド、チェックリストなどの見た目を優先して使いました。

目的は、説明ブロックを追加しながらも、既存デザインとの統一感を保ち、CSS変更による表示崩れリスクを下げることです。説明文そのものは有用でも、ページごとに見た目が違いすぎると、サイト全体の印象が散らばります。そこで、新しいデザインを作る前に、既存classで対応できるかを確認しました。

作業前の状態

作業前は、ページに説明ブロックを追加したい状態でした。すでにサイト内には似た見た目の白ボックスやguideブロックがあり、新規CSSを追加することもできましたが、表示崩れやデザインのばらつきが心配でした。

PC表示とスマホ表示の両方で崩れないようにする必要があり、既存カード表示や一覧表示には影響を出したくありませんでした。説明ブロックの追加は小さな作業に見えますが、CSSを触ると影響範囲が広がることがあります。だからこそ、まず既存classの確認から始める方が安全です。

作業前に問題だったこと

説明ブロックを追加するたびに新しいCSSを作ると、ページ単位で独自スタイルが増えてしまいます。独自スタイルが増えると、あとから修正しづらくなります。同じような説明ブロックなのに、ページごとに余白、枠線、背景、文字サイズが変わると、サイト全体の統一感も落ちます。

また、CSSはPCでは自然に見えても、スマホで横幅や余白が崩れることがあります。説明ブロックだけを直したつもりでも、既存カードの余白や幅、ボタンの配置に影響する場合があります。Codexに「いい感じにデザインして」とだけ頼むと、必要以上にCSSが増えることもあります。

新規CSSを増やしすぎない理由

新規CSSを増やしすぎると、CSSファイルが肥大化します。どのclassがどのページで使われているか分かりにくくなり、既存classと競合する可能性もあります。似た見た目のclassが増えると、次に修正する時にどれを使えばよいか迷います。

スマホ表示で想定外の崩れが起きることもあります。PCでは整って見えても、スマホでは横スクロールが出たり、ボックスの余白が広すぎたり、文字が詰まったりします。Codexが次回以降の修正で迷いやすくなる点も見逃せません。そのため、まず既存CSSを確認し、使えるものがあればそれを優先します。

既存classを優先する理由

既存classを使うと、サイト内の見た目を揃えやすくなります。すでにPCとスマホで使われているclassなら、表示崩れリスクも比較的低くなります。もちろん確認は必要ですが、ゼロから新しい見た目を作るより、影響範囲を抑えやすいのが利点です。

既存classを使うことで、Codex作業の影響範囲も小さくできます。説明ブロックは新しいデザインを作るよりも、既存のUIに自然に馴染ませる方が安全な場合が多いです。特に実践ログやguideページを増やしているサイトでは、同じ役割のブロックは同じ見た目に寄せた方が、読者も迷いにくくなります。

Codexに任せたこと

Codexには、いきなり新規CSSを作らせず、まず既存classの確認を任せました。確認させた内容は、既存CSSファイル、既存の白ボックスclass、guide系class、チップやカードグリッド系class、説明ブロックに流用できるclass、新規CSSなしで実装できるかです。

作業後は、公開HTMLでclassが出ているか、PC表示で崩れていないか、スマホ表示で横スクロールが出ていないか、既存カード表示が壊れていないかを確認します。Codexには「CSS大改造は禁止」「新規CSSが必要な場合は最小追加案として報告」と明示します。これにより、作業がデザイン改修へ広がりすぎるのを防ぎます。

人間が判断したこと

人間が判断したのは、見た目の新規開発ではなく既存デザインに合わせることです。CSS大改造を避け、新規CSSを増やさない方針にしました。既存classで対応できるなら、それを使います。

PCとスマホ表示の確認を必ず入れること、既存カードや共通部品を触らないこと、表示改善よりも保守性を優先することも判断しました。見た目を少し派手にするより、サイト全体の見た目が揃っている方が、長く運用しやすい場合があります。Codexには、よい見た目だけでなく、壊さないこと、増やしすぎないこと、確認することを任せます。

既存CSSで説明ブロックを作る時の考え方

既存CSSで説明ブロックを作る時は、まず追加したいブロックの役割を整理します。ページの概要を伝えるguideなのか、注意点を伝える注意ボックスなのか、関連ページを並べるカードなのか、キーワードや分類を見せるチップなのか、確認項目を並べるチェックリストなのかを分けます。

役割が決まれば、似た用途のclassを探しやすくなります。新しい見た目を作る前に、すでにあるclassで実現できるかを見るのが基本です。たとえば、注意文ならnotice系、関連ページならlink-cardやlink-grid、確認項目ならcheck-list系、短い分類ならチップ系が使える場合があります。既存の見た目を活かすことで、ページ追加のたびにCSSを増やさずに済みます。

PC表示とスマホ表示で確認したこと

既存classを使っても、確認は必要です。PCでは余白や幅が崩れていないか、説明ブロックが本文の流れに自然に入っているか、既存カード一覧に影響していないかを見ます。横幅が広い画面では、ボックスの幅や行長が長くなりすぎないかも確認します。

スマホでは、横スクロールが出ていないか、文字が小さすぎないか、ボタンやリンクが押しやすいか、説明ブロックの余白が詰まりすぎていないかを確認します。既存classだから安全と決めつけず、公開HTMLと実画面の両方で確認します。特にカード一覧の上へ説明ブロックを置く場合、スマホでカード本体が遠くなりすぎないかも見ます。

うまくいった点

うまくいった点は、新規CSSなしで説明ブロックを追加できたことです。サイト全体の見た目に馴染み、PCとスマホの崩れリスクも抑えられました。既存カード表示を壊さずに済み、CSSの肥大化も避けられました。

次回以降も同じclassで横展開しやすくなったことも収穫です。guide、注意ボックス、関連カード、チェックリストのように役割ごとに使うclassを決めておくと、Codexへの指示も短くなります。新しいデザインを毎回作るより、既存の部品を使い回す方が、実務では安定します。

詰まった点・危なかった点

既存classの用途を確認せずに使うと、意図と違う見た目になることがあります。似た名前のclassでも、実際には別のページ専用だったり、スマホで特殊な動きをしたりする場合があります。既存classが似ていても、必ず公開HTMLと実画面で確認します。

新規CSSを追加したくなる場面もありますが、増やしすぎると保守性が下がります。説明ブロックだけのつもりが、既存カードに影響することもあります。CSS大改造は影響範囲が広がりやすいため、今回のような説明ブロック追加では避ける方針にしました。必要な場合でも、最小追加案として切り出して判断します。

作業後に確認したこと

作業後は、既存classを使ったこと、新規CSSを増やしていないこと、PC表示で崩れていないこと、スマホ表示で崩れていないこと、既存カード表示が壊れていないことを確認します。公開HTMLに説明ブロックが出ているか、CSS読み込みが維持されているかも見ます。

title、description、H1を変更していないこと、canonicalとrobotsが維持されていることも確認します。説明ブロック追加は本文改善であり、SEOタグや共通設定を変える作業ではありません。DB、cron、.htaccessも触りません。報告書では、既存CSS使用状況、新規CSS追加有無、既存カード表示への影響、共通header/footer変更有無を明記します。

次回使えるCodex指示文テンプレート

同じように説明ブロックを追加する時は、次のように依頼します。最初に「新規CSSを増やさない」と書くことで、作業範囲を抑えやすくなります。

説明ブロックを追加する際は、新規CSSを増やさず、既存のwhite-box、guide系class、chips、card-grid、checklist、notice系classなど、サイト内で既に使われているclassを優先してください。

まず既存CSSと既存HTMLを確認し、流用できるclassを探してください。

CSS大改造は禁止です。

新規CSSが必要な場合は、勝手に追加せず、最小追加案として報告してください。

作業後は、公開HTMLに説明ブロックが出ていること、PC表示で崩れていないこと、スマホ表示で横スクロールが出ていないこと、既存カード表示が壊れていないことを確認してください。

title、description、H1、canonical、robots、DB、cron、.htaccess、robots.txt、ads.txt、広告タグ、Search Console確認タグは変更しないでください。

確認チェックリスト

既存CSSだけで説明ブロックを追加する時は、次の項目を確認します。CSSを増やさない作業でも、公開HTMLとPC/スマホ表示は必ず見ます。

• 既存classを確認した
• 既存classを使った
• 新規CSSを増やしていない
• CSS大改造をしていない
• 公開HTMLに説明ブロックが出ている
• PC表示で崩れていない
• スマホ表示で崩れていない
• 横スクロールが出ていない
• 既存カード表示が壊れていない
• titleを変更していない
• descriptionを変更していない
• H1を変更していない
• canonicalが維持されている
• robotsが維持されている
• DB / cron / .htaccessを触っていない

注意書き

この記事は、実際の作業を一般化してまとめた実践ログ型ガイドです。具体的な案件名、内部情報、秘密情報は掲載していません。

特定のCSS設計や公式手順ではなく、公開中サイトで説明ブロックを安全に追加するための実務上の考え方として整理しています。実際の実装では、サイトの既存class、表示幅、ページ構成に合わせて確認してください。