LOG193ロボティクスデザイン2026/5/12

記事をビジュアルウィジェットで作り直す日 | STUDIOとGitHub Pagesの二層公開システムを建てた

記事のmdをそのままHTMLで表示したい、という素朴な問いから始まったセッションが、最後はClaude Projectで「ビジュアル記事ビルダー」を組み、STUDIOとGitHub Pagesの二層構造で記事を公開する運用フローを建てるところまで進んだ。テキスト段落を全廃して18種類の視覚コンポーネントだけで記事を再構成する、という振り切りが起点になった。

💡 Key Takeaway

毎日のDAYログをSTUDIOにmdで投稿する運用は変えない。その横に「インタラクティブ版」というもう一つの公開層を建てた。インタラクティブ版はテキスト段落を完全に廃止し、全ての情報をカード・タグ・数値・アイコン・グリッド・対比のいずれかの視覚要素に変換する。Claude Projectに記事mdを渡すだけで自動生成され、GitHub Pagesで公開され、STUDIOの記事上部に置いたバナーから1クリックで往復できる構造になった。

起きたこと	現場判断	結果
「mdをそのままHTML化したい」という当初の問いに対してmarkdown-it + highlight.js + 自前CSSのClaude Code変換システムを提案したが、意図がズレていた	添付済みの `DAY192_two_cameras_role.html`（記事に埋め込むインタラクティブ図解ウィジェット）のフォーマットを記事全体に拡張したい、という意図と判明	テンプレ方式は廃案、「記事内容に合わせた図解生成」へ方針転換
図解とテキストを混ぜた49KB・9セクションのHTMLを生成したが、テキスト段落と図解が並列する状態だった	「なんかメリット感じないね。全部図解で作ってみて」という指示で全テキスト段落を視覚要素に変換	value-card / keyphrase-block / spec-block / concern-card / before-after / tag-set など18種類の視覚コンポーネントが定義された
STUDIO（adaptdesign.jp）はインタラクティブHTMLが動かない（Embed経由のiframe表示のみ）ため、生成したビジュアル記事をどこで公開するか問題が発生	STUDIO（通常版）とGitHub Pages（インタラクティブ版）の二層構造を採用。両者をバナーとロゴで相互リンク	`pixelstomotors.github.io/interactive-articles/{slug}/` というURL構造で公開、STUDIO記事上部にP2M_Interactive_Bannerを埋め込み
記事が増えるたびに `index.html` を手で書き換えるのは持たない	`articles.json` を別ファイルに切り出してJSが動的にカード描画する設計に変更	新記事追加時は「フォルダ + index.html + articles.jsonの1ブロック追記」の3操作で完結する状態になった

「mdをそのままHTMLで表示したい」という最初の問い

最初の問いはシンプルだった。毎日のDAYログはmdで書いている。SVG図解はHTMLで別添してSTUDIOにiframe埋め込みしている。ではmd本文そのものを「もっと記事のHPに近い見た目」でHTML化するには何がいいか。

最初の回答は、Claude Codeでmarkdown-itベースの変換システムを組む案だった。

~/PixelsToMotors/article-html/
├── template.html      # 共通レイアウト
├── styles.css         # ブランド統一CSS
├── convert.js         # MD→HTML変換
└── articles/
    └── DAY192_article.md

node convert.js articles/DAY192.md のような構造で、tables・fenced_code・toc・attr_list を効かせて、h2見出しから自動目次、Key Takeawayはコールアウト、Pixels to Motorsブランドに合わせたCSS、という方向で提示した。

技術的には正しい提案だった。ただ意図とズレていた。

意図していたこと:
  添付の DAY192_two_cameras_role.html のような
  記事内に埋め込むインタラクティブ図解ウィジェットを
  記事全体に対して量産したい

提案していたこと:
  記事mdを綺麗なHTMLページに変換するシステム

この食い違いに気づくのに、最初のやりとり1回分を使った。

テンプレ方式の廃案

意図を取り違えていたことが分かった後、最初に提示したのは「タブ切替型・二項対比型・フロー型」の3種類のテンプレを作ってパーツ化する案だった。記事の論点ごとに、どのテンプレに当てはまるかを判定して使い回す、という構造化思考の発想だ。

~/PixelsToMotors/figure-widgets/
├── figure-style.css       # 共通スタイル
├── pattern-A-tabs.html    # タブ切替テンプレ（2〜4タブ可変）
├── pattern-B-compare.html # 二項対比テンプレ
├── pattern-C-flow.html    # フロー型テンプレ
└── articles/
    ├── DAY192_two_cameras_role.html    # 既存
    ├── DAY192_yokocam_position.html    # 新規
    └── DAY192_grip_orientation.html

前の記事の論点を9つにマッピングして、そのうち8つがパターンAタブ切替型で表現できる、という分析まで進めた。

ここで返ってきた答えはこうだった。

記事に合わせて図解作るから（いつも記事の内容から図解を自動生成している）テンプレ方式の必要はないね。

テンプレを作ってそこに記事の論点をはめ込むのではなく、記事の論点を見てから図解の形を作る。順序が逆だった。テンプレを固定すると論点が痩せる、というデザインシステムの古典的なトレードオフが、この場では「テンプレ廃止」という選択になった。

設計の意思決定として、これは大きい。固定テンプレを持つとブランドは揃うが、毎回の記事内容が痩せる。毎回ユニークに作るとブランドが揺れる可能性があるが、論点は活きる。どちらを取るか。ここでは後者を取った。

代わりに、ブランドの一貫性は「色は3色のみ・ボーダー1.5px・強調は白黒反転・フォントはIBM Plex MonoとNoto Sans JP」という最小限のルールだけで担保する方針にした。構造は自由、原則は固定。

「全部図解で作って」への振り切り

最初のビジュアル化版は、テキスト段落と図解ウィジェットを混ぜた49KBのHTMLだった。9セクション、図解ウィジェット9本、タブUI12個、フロー13ステップ、対比カラム12個入り。記事として「読む」流れに、要所で図解が挿入される構造。

これを見て返ってきた答えはこうだった。

なんかメリット感じないね。全部図解で作ってみて。

STUDIOの通常版でも読める内容を、HTMLでもう一度同じように読ませる意味がない、ということだ。インタラクティブ版を別公開層として作るなら、STUDIO版とは別の体験価値を持たせる必要がある。

全テキスト段落を視覚要素に変換する作業に振り切った。各セクションの導入文（section-lead）は完全廃止、図解の補足文（widget-note）はキーワードのタグ集合や数値カードに変換、引用ブロックは「キーフレーズ・ブロック」、決定カードのスペック列挙はアイコン+キー+値の4分割グリッド、警告文は「concern-card」、フローステップの説明文はタグ集合、締めの一文は「世界の対比」（before-after）として視覚化。

廃止したテキスト要素と変換先を整理すると、以下のようになった。

元のテキスト要素	変換先の視覚要素
section-lead（各セクションの導入文）	完全廃止
widget-note（図解下の補足）	tag-set または value-row
Z係数 4.786 の説明文	取り消し線付き value-card 3枚並び
quote-card の引用文	keyphrase-block（大フレーズ + ソース）
decision-card のスペック列挙	spec-block（アイコン + キー + 値の4分割グリッド）
warning-card の警告文	concern-card（アイコン + statsグリッド + actionタグ）
flow-step-detail の説明文	flow-step-tags（キーワードのタグ集合）
closing-statement のフレーズ	before-after（左右対比 + チェック項目）
takeaway-summary の段落	完全廃止（3カードのみに）

これで「読む文章」はゼロになり、全情報が「カード・タグ・数値・アイコン・グリッド・対比」のいずれかの視覚要素に変換されたHTMLが完成した。インタラクティブ版の輪郭がここで初めて見えた。

公開先の選択：STUDIOとGitHub Pages

ビジュアル記事ができても、どこに置くかが次の問題になった。STUDIO（adaptdesign.jp）とGitHub Pagesの差を整理した。

項目	STUDIO	GitHub Pages
HTML/CSS/JSの自由度	制限的	完全自由
インタラクティブ図解	Embed経由のiframeのみ	そのまま動く
サイト統合	adaptdesign.jp内	別URL
SEO/OGP	STUDIO側で管理	自前で設定
編集の手軽さ	Cmd+Vで貼るだけ	git push必要
コスト	有料プラン込み	無料

タブ切替・SVG・アコーディオン展開が動くインタラクティブ版は、Markdownでは再現できないし、STUDIOでもネイティブには動かない。だから普段通りSTUDIOにCmd+Vでペーストするmd記事の運用には収まらない。

選択肢は3つあった。

A. 全部GitHub Pagesに置く
   → adaptdesign.jp の記事側からリンクで誘導
   → 別URLになるが、見た目もインタラクションもそのまま反映される

B. STUDIO記事内に iframeでGitHub Pages版を埋め込む
   → URLはadaptdesign.jpのまま、中身だけGitHub Pagesから配信
   → 高さ調整やレスポンシブで若干工夫が必要

C. 図解ウィジェットだけ部分埋め込み
   → 普段の運用に近い、これまでと同じ
   → 記事全体の図解化はできない

ここで採用したのは案Aの拡張形だ。STUDIO側は通常のmd記事をそのまま運用、別途GitHub Pagesに「インタラクティブ版」を公開し、両者を相互リンクで往復させる。

Pixels to Motors の「インタラクティブ版」として GitHub Pages に置き、adaptdesign.jp の通常記事末尾に「→インタラクティブ版を見る」リンクを置く。役割が違うコンテンツとして共存させる形。

役割を分けるという選択だ。STUDIO版は「読む」、インタラクティブ版は「触る」。同じ情報を別の体験として2回提供する。

Claude Projectで生成システム化

二層構造を決めた後、毎回手作業で全図解化したHTMLを書くわけにはいかない。生成パイプラインをClaude Projectで組んだ。

Project: Pixels to Motors Visual Article Builder

カスタム指示:
  PROJECT_INSTRUCTIONS.md（プロジェクト指示文として貼り付け）

ナレッジ:
  TEMPLATE.html  (34KB) — CSS/JS完備の骨組み
  COMPONENTS.md  (16KB) — 18コンポーネントのカタログ

PROJECT_INSTRUCTIONS.md には、白黒ミニマル、段落完全廃止、18コンポーネントの選び方、ブランドURL定義、HTMLサンプル、仕上げチェックリスト、タイトル構造ルールが入っている。プロジェクト内で新しいチャットを開いて、記事のmd（例：DAY{N}_article.md）を添付して送るだけで、毎回同じ品質で DAY{N}_visual_article.html が生成される、という運用になる。

TEMPLATE.html はCSS・JS・Google Fontsのpreconnectまで全部入った骨組みで、body部分はガイドコメント付きの空欄。COMPONENTS.md は18種類のコンポーネント（value-card, keyphrase-block, spec-block, concern-card, before-after, tag-set, flow-step-tags, value-row, tabs, compare-cols, flow-steps, matrix, timeline, annotated-svg, cards, header, tabs-multi, list-stack）について、HTMLサンプル付きで使い分けを定義したもの。

注意点として、PROJECT_INSTRUCTIONS.md には「読む文章はゼロ、全部図解」という原則を明記している。これがStep 2のコピペで漏れると、毎回の出力で散文段落が混ざりやすくなる。試行錯誤で固まったルールを、ここに集約してある。

STUDIOとGitHub Pagesをバナーで往復させる

二層をどう接続するか。STUDIO記事の上部に、インタラクティブ版へのCTAバナーを置く設計にした。

┌────────────────────────────────────────────────┐
│ [■] ▶ INTERACTIVE EDITION                       │
│ [■]   この記事をインタラクティブ版で読む    [View →] │
│ [■]   全要素図解化 / タブ切替 / SVG動的表示       │
└────────────────────────────────────────────────┘
   ↑          ↑                       ↑
 ミニ図解   テキスト2行              CTAボタン

仕様：

項目	内容
サイズ	720×160px (max-width)、レスポンシブで自動縮小
カラー	ブラックベース (#0d0d0d) + 白文字 (#f5f5f0)
構成	ミニ図解アイコン + 2行テキスト + CTAボタン
インタラクション	ホバーで背景がスッとグレーに変化（動きはなし）
設定箇所	`href="https://YOUR-USERNAME.github.io/YOUR-REPO/"` の1か所を実URLに書き換え
STUDIOへの設置	「埋め込み」ブロックにHTML全体をコピペ

最初の版ではホバー時に2px浮き上がる・CTAボタンが白黒反転・矢印が右にスライド、という動きを入れていたが、「マウスオーバーでグレーになるよう修正（動きはなし）」という指示で全廃した。上下paddingはコンテンツに合わせて自動で詰まる構造にした（aspect-ratio: 720/160を削除、padding 20pxに統一）。

ブラックベース+白文字+太めボーダー+ミニ図解アイコンで、明らかに「外部リンク・別バージョン」とわかる作りにしている。

リポジトリ構造とURL設計

GitHub Pagesで公開するために、PixelsToMotors/interactive-articles というPublicリポジトリを新設した。PixelsToMotors/r2r2r-content はPrivateで、Free planではPagesが使えない。Public用に新リポジトリを切り出すのが最もシンプルで、記事資産（Private）と公開コンテンツ（Public）を分離できるメリットもある。

リポジトリ構造：

interactive-articles/  ← Public
├── README.md
├── index.html         ← 記事一覧（JSで動的描画）
├── articles.json      ← 記事メタデータ
└── setting-up-the-side-camera/
    └── index.html     ← DAY192のインタラクティブ版

URLは https://pixelstomotors.github.io/interactive-articles/setting-up-the-side-camera/ という形になる。setting-up-the-side-camera はSTUDIO側の記事スラッグと揃えてあり、対応関係が一目で分かる。

新しい記事を追加する時は、新フォルダを切って中に index.html を置く。例えば次の記事（横カメラのキャリブレーション）なら parallel-slide-kinematics/index.html のような構造になる。

GitHub Pages有効化の手順は以下の通り。

1. リポジトリの Settings → Pages
2. Source: Deploy from a branch を選択
3. Branch: main / (root) を選択
4. Save
5. 1〜2分待つと https://pixelstomotors.github.io/interactive-articles/ で公開

一覧ページとarticles.json

最初の index.html は記事カードをHTMLに直書きする形だった。これだと記事が増えるたびに index.html を毎回書き換えなければならない。3記事目で疲れる構造だ。

そこで articles.json に記事メタデータを切り出して、index.html はJSで動的に描画する設計に変更した。

articles.json の構造：

{
  "articles": [
    {
      "day": 193,
      "slug": "calibrate-side-camera",
      "date": "2026-05-10",
      "category": "デジタルツイン学習",
      "series": "mechArm 270 Pi 動的追従の限界を探る ─ Log #11",
      "title": "横カメラのキャリブレーション完了 ─ アームをキャリブ装置として使う"
    },
    {
      "day": 192,
      "slug": "setting-up-the-side-camera",
      "date": "2026-05-07",
      "category": "デジタルツイン学習",
      "series": "mechArm 270 Pi 動的追従の限界を探る ─ Log #10",
      "title": "視点を増やす日 ─ 設計判断と iPhone 2台体制の物理構築"
    }
  ]
}

index.html 側はfetchで articles.json を読み、day番号の降順で自動ソートしてカードを描画する。一覧上には件数カウンタも入っていて、「01 / 全1件」のように自動更新される。

これで、新記事を追加する時の作業は以下の3操作だけになる。

1. interactive-articles リポジトリのトップで Add file → Upload files
   → 新フォルダ(slug)/index.html をアップロード

2. articles.json を開いて鉛筆アイコンで編集
   → 配列の先頭に新記事のメタデータブロックを1つ追加

3. STUDIO通常記事に P2M_Interactive_Banner を埋め込み
   → href を新URLに書き換えるだけ

index.html 自体は最初に作った後は一切触らない。記事が増えても触らない。

一覧ページの情報設計

一覧ページは最初、記事カードだけを並べた最小構成だった。これに対して「Pixels to Motorsのページとわかるように最低限の情報は追加してください」という指示で、以下を補強した。

1. Heroセクションに小見出しタグ
   ┌──────────────────────────────────────┐
   │ Pixels to Motors — デジタルツインが生み出す次世代ロボティクスUX │
   └──────────────────────────────────────┘
   
   ▶ INTERACTIVE EDITION   ▶ 全要素図解版
   
   INTERACTIVE ARTICLES   ← 巨大に（40〜72px）
   記事の判断・設計・データを...

2. Aboutセクション（記事リストの下）
   About / 事業所
   ─────────────
   29年の UI/UX デザイン経験を     |  Designer    島津 栄一
   ロボティクスへ。R2R2R プロセスで、 |  Office      ADAPT DESIGN
   iPhone での 3D スキャンから物理   |  Location    秋田県男鹿市
   シミュレーション、実機制御までを   |  Founded     2021年10月
   1人で担う実験記録。               |

これで一覧ページ単体で訪問されても「Pixels to Motors プロジェクトの公式インタラクティブアーカイブ」として完結する。ハコブくんチャットやプロトタイプセクションは含めず、必要な3要素（プロジェクト名 / 記事一覧 / 制作者情報）に絞っている。

トップバーには Pixels to Motors ロゴ（→ adaptdesign.jp/pixelstomotors）と「← 通常記事一覧」（→ adaptdesign.jp/pixelstomotors）を配置。各記事の右上には DAY 192 タグ（→ adaptdesign.jp/pixelstomotors/record/{slug}）を置いた。これで以下の往復が成立する。

STUDIO通常記事 (adaptdesign.jp/pixelstomotors/record/setting-up-the-side-camera)
    ↓
    │ [この記事をインタラクティブ版で読む →] ← バナークリック
    ↓
GitHub Pages インタラクティブ版 (pixelstomotors.github.io/interactive-articles/setting-up-the-side-camera/)
    ↓
    │ 右上「DAY 192」クリック → STUDIO記事に戻る
    ↓
STUDIO記事ページ

完成した構成

最終的に整った構成はこうなった。

[STUDIO通常記事]  ⇄  [GitHub Pages インタラクティブ版]
       ↑ バナーで誘導         ↑ DAY番号タグでSTUDIOに戻る
                              ↑ ブランドロゴで一覧に戻る

[インタラクティブ版一覧]
  └ articles.json を編集するだけで自動更新

プロジェクトに登録する3点：

PROJECT_INSTRUCTIONS.md（カスタム指示）
TEMPLATE.html（ナレッジ）
COMPONENTS.md（ナレッジ）

GitHub interactive-articles リポジトリ：

index.html（動的描画、編集不要）
articles.json（記事追加時に編集）
各記事フォルダ + index.html

このセッションが示したこと

最初の問いは「mdをHTML化したい」というシンプルなものだった。そこから最終的に建てたのは、生成パイプライン（Claude Project）と公開インフラ（GitHub Pages + STUDIO）と運用フロー（3ステップ）を含む、独立した一つの公開システムだった。

転換点は2回ある。

1回目は「テンプレ方式の廃止」。固定テンプレに記事の論点を流し込むのではなく、記事の論点を見てから視覚要素を組み立てる、という順序の選択。デザインシステムとしては「部品は最小限・原則は固定・構造は自由」という非典型な設計になった。

2回目は「全テキスト段落の廃止」。「全部図解で」という指示が、インタラクティブ版とSTUDIO版の役割分担を初めて明確にした。同じ情報を別の体験として2回提供する、という二層構造の輪郭が、ここで決まった。

公開インフラとして見ると、STUDIO（編集ラク・有料・JS不可）とGitHub Pages（無料・JS可・git push必要）はトレードオフが完全に逆向きで、どちらかを選ぶというより、両方をそれぞれの役割で使う方が合理的だった。バナーとロゴで相互リンクすると、訪問者から見れば「同じプロジェクトの2つの読み方」になる。

articles.json を分離した判断も後から効いてくる。index.html を毎回書き換える運用は3記事目で破綻するが、JSON1ブロック追加なら100記事目でも持つ。Build-in-publicの長期プロジェクトでは、初期の運用設計が10ヶ月後の負債になりやすい。早めに動的化しておくと、未来の自分が助かる。

今後の新記事は、DAY{N}_article.md をプロジェクトに添付するだけで DAY{N}_visual_article.html と articles.json 追記ブロックが揃う。後はGitHub Web UIで2操作、STUDIO記事にバナー1枚埋め込み、で完結する。記事を書く側の工数は、STUDIOにmdを貼ってから3〜5分で公開まで進む計算になる。

このセッションは、Build-in-publicの公開層を「STUDIOだけ」から「STUDIO + インタラクティブ版」に拡張した日として残しておく。