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

- 記録: LOG193（ひとり研究所の裏側）
- 公開: 2026/5/12
- 記事のページ: https://pixelstomotors.com/record/visual-article-builder
- サイト: Pixels to Motors（ADAPT DESIGN / 島津 栄一） https://pixelstomotors.com/
- 要約: 記事のmdをHTML化したい問いから始まり、STUDIOとGitHub Pagesの二層公開システムを建てた日。全テキスト段落を廃止して18種の視覚コンポーネントだけで再構成、Claude Projectで生成を自動化した。

> AI が読むための記事の全文です（コード・実行ログを含む）。引用するときは上の「記事のページ」の住所を使ってください。

---

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

[図解](https://pixelstomotors.com/embeds/visual-article-builder-UjyrSni8.html)

**💡 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で表示したい」という最初の問い

[図解](https://pixelstomotors.com/embeds/visual-article-builder-yaiqXUST.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` の構造：

```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 + インタラクティブ版」に拡張した日として残しておく。
