【テクニカル・上級編】Notionのカスタムアイコン・カバー画像をSVGとCSSで最適化する：社内Wikiのブランド統一とロード高速化ハック – プロジェクト・ナレッジ管理活用バイブル

Notionを「超高速・高精度」なエンタープライズWikiへ昇華させる：SVGとCSS最適化によるブランド統制の極意

開発チームのベロシティを鈍らせる最大の隠れた負債は、コードベースの美しさではない。「情報の断片化と、それを探す認知負荷」である。

多くの組織がNotionを社内Wikiとして導入したものの、数ヶ月後には「どのページがどの文脈に属するのか判別がつかない雑多な情報の墓場」と化す。絵文字（Emoji）の乱用、文脈を無視した巨大なUnsplashカバー画像、そしてロードのたびにガタつくUI。これらは単なる美観の問題ではなく、エンジニアのコンテキストスイッチコストを確実に増大させ、組織全体の認知レイテンシを悪化させる致命的なアンチパターンだ。

本稿では、NotionのビジュアルアセットをSVGとCSSの最適化レイヤーで完全に掌握し、ダークモード/ライトモード完全対応かつ極限までロードを高速化した、世界最高峰のエンタープライズWiki運用アーキテクチャを解説する。

—

1. 現場の病理：なぜNotion標準のビジュアル運用は破綻するのか？

標準のNotion UIは柔軟性が高いゆえに、ガバナンスが効かない。チームメンバーが思い思いの絵文字や外部画像を設定した瞬間、以下の技術的・運用的なペインが発生する。

• DOMの肥大化とネットワークレイテンシ:

Unsplash経由の高解像度JPEG/PNGカバー画像は、1枚あたり2MB〜5MBに達する。数百ページのWikiを巡回する際、CDNからのフェッチとデコード処理がブラウザのメインスレッドを圧迫し、DOMのインタラクティブ化（TTI）を遅延させる。

• テーマ適応性の欠如:

固定カラーのPNGアイコンは、システムやユーザーがダークモードに切り替えた途端に視認性を失う。白背景に黒のベクターは、ダークテーマでは視覚的ノイズ（光の塊）と化す。

• ブランドアイデンティティの欠落:

「誰が書いても同じフォーマット、同じ文脈の美しさ」を担保できないドキュメントは、構造化データとしての信頼性を失う。

これを解決するには、UIアセットを「プログラム可能なベクター（SVG）」として定義し、Notion APIとCI/CDパイプラインを用いて完全に自動同期するシステムを構築する必要がある。

—

2. 軽量SVGとCSS制御による「ゼロ・レイテンシ」ビジュアルハック

Notionのカスタムアイコンやカバー画像には、外部URLを指定できる。この仕様をハックし、自社CDN（あるいはGitHub Pages / AWS S3 + CloudFront）上に最適化されたSVGをホストすることで、パフォーマンスと美観を両立させる。

2.1 CSS変数（Variables）を埋め込んだ「カメレオンSVG」の設計

ダークモードとライトモードの両方で完璧な視認性を保つためには、SVGの内部にCSSを埋め込み、Notion側のテーマ変化（あるいはCSSカスタムプロパティ）に追従させる。

以下は、システムカラーに合わせて動的に色が反転・変化する、プロダクト仕様書用カスタムアイコンのSVG実例だ。

2.2 パフォーマンス上の優位性

• ファイルサイズ: 上記のSVGはわずか `680 bytes`。PNGと比較して99.9%以上の軽量化。
• スケーラビリティ: ベクターデータであるため、Retinaディスプレイや超高解像度モニターであっても一切のピクセル化（ぼやけ）が発生しない。
• メモリ消費の最小化: ブラウザのペイントフェーズにおけるラスター画像のデコード負荷がゼロになり、NotionのSPA（Single Page Application）としてのスクロールパフォーマンスが劇的に向上する。

—

3. 自動化パイプライン：Notion APIとCLIによるアセットの完全同期

手動でSVGのURLをNotionにペーストする運用など、エンジニアリングの観点から論外である。リポジトリにコミットされたアセットを、Notion APIを叩いて全ページのアイコン・カバーに自動反映するCLIツールチェーンを構築する。

以下は、Node.js（TypeScript）を用いて、指定した親ページ下位の全サブページに対して、定義された命名規則に基づいてカスタムアイコンを自動アタッチするスクリプトの実装例だ。

3.1 自動同期スクリプト (`sync-notion-assets.ts`)

import { Client } from “@notionhq/client”;
import as dotenv from “dotenv”;

dotenv.config();

const notion = new Client({ auth: process.env.NOTION_TOKEN });
const ROOT_PAGE_ID = process.env.NOTION_ROOT_PAGE_ID as string;
const CDN_BASE_URL = “https://cdn.internal.example.com/notion-assets”;

interface PageMeta {
id: string;
title: string;
category: string;
}

/

• 再帰的にNotionのページツリーを走査し、メタデータを取得する

/
async function fetchPageTree(blockId: string): Promise {
const results: PageMeta[] = [];
const response = await notion.blocks.children.list({ block_id: blockId });

for (const block of response.results) {
if (‘type’ in block && block.type === ‘child_page’) {
const pageId = block.id;
const pageDetails = await notion.pages.retrieve({ page_id: pageId });

let title = “Untitled”;
if (‘properties’ in pageDetails) {
const titleProp = pageDetails.properties[‘title’] || pageDetails.properties[‘Name’];
if (titleProp && titleProp.type === ‘title’ && titleProp.title.length > 0) {
title = titleProp.title[0].plain_text;
}
}

// ページのカテゴリ判定ロジック（タグや命名規則に基づく）
const category = determineCategory(title);

results.push({ id: pageId, title, category });

// 子ページを再帰的に取得
const subPages = await fetchPageTree(pageId);
results.push(…subPages);
}
}
return results;
}

function determineCategory(title: string): string {
if (title.includes(“API”) || title.includes(“Backend”)) return “backend”;
if (title.includes(“Frontend”) || title.includes(“UI”)) return “frontend”;
if (title.includes(“DevOps”) || title.includes(“Infrastructure”)) return “devops”;
return “default”;
}

/

• ページのアイコンをSVGの外部URLに更新する

/
async function updatePageIcon(pageId: string, category: string) {
const iconUrl = `${CDN_BASE_URL}/icons/${category}.svg`;

try {
await notion.pages.update({
page_id: pageId,
icon: {
type: “external”,
external: {
url: iconUrl,
},
},
});
console.log(`[SUCCESS] Updated icon for page: ${pageId} with ${category}`);
} catch (error) {
console.error(`[ERROR] Failed to update page ${pageId}:`, error);
}
}

async function main() {
console.log(“Starting Notion asset synchronization pipeline…”);
const pages = await fetchPageTree(ROOT_PAGE_ID);

console.log(`Found ${pages.length} pages. Applying SVG assets…`);

for (const page of pages) {
await updatePageIcon(page.id, page.category);
// Rate Limit（Notion APIは平均3回/秒）を考慮したスロットリング
await new Promise((resolve) => setTimeout(resolve, 350));
}

console.log(“Synchronization completed successfully.”);
}

main().catch((err) => {
console.error(“Fatal error in sync pipeline:”, err);
process.exit(1);
});

3.2 パイプラインの統合（GitHub Actions）

このスクリプトを、Gitリポジトリの `main` ブランチへのマージ、または夜間バッチとしてGitHub Actionsに組み込む。

name: Sync Notion Enterprise Assets

on:
push:
branches:

• main

paths:

• ‘assets/’

jobs:
sync:
runs-on: ubuntu-latest
steps:

• name: Checkout Repository

uses: actions/checkout@v4

• name: Setup Node.js

uses: actions/setup-node@v4
with:
node-version: ’20’
cache: ‘npm’

• name: Install Dependencies

run: npm ci

• name: Run Asset Synchronization

env:
NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
NOTION_ROOT_PAGE_ID: ${{ secrets.NOTION_ROOT_PAGE_ID }}
run: npx ts-node scripts/sync-notion-assets.ts

これで、デザインチームがCDN上のSVGアセットをアップデートするか、開発者がリポジトリ内のアイコン定義を更新すれば、組織全体のNotion Wikiのビジュアルが一瞬にして同期され、ブランド統制が完全に自動化される。

—

4. チーム全体での素材共有・ガバナンスフロー

システムを構築しただけでは、現場のエンジニアが勝手に絵文字を使い始めてエコシステムが崩壊する。これを防ぐための「運用レイヤーのガバナンス」をコードとルールで強制する。

1. デザインシステム・リポジトリの分離:
Notion用のアセットは、プロダクトのコードベースとは別に専用のGitリポジトリ（例: `company/notion-design-system`）として切り出す。
2. PRレビューの義務化:
新しいアイコンを追加・変更する場合、デザインチームによるSVGの最適化チェック（SVGO等を通した不要なメタデータの削除）と、エンジニアによるレビューを必須とする。
3. Lintツールの導入:
Notion APIを定期的にクロールし、許可されていない外部画像URLやデフォルトの絵文字が使用されているページを検知してSlackにアラートを飛ばす「Notion Lint Bot」を社内インフラとして常駐させる。

—

結び：ドキュメントを「プロダクト」として扱え

ドキュメントは、コードの単なる副産物ではない。それ自体がチームの思考スピードを最大化するための「ファーストクラスのプロダクト」である。

SVGとCSSによるビジュアル最適化、そしてAPI駆動の自動同期パイプライン。これらを導入した瞬間から、あなたの会社のNotion Wikiは、ただの「メモ帳の集まり」から、洗練されたデザインシステムを持つ最高峰のナレッジエンジニアリング・プラットフォームへと生まれ変わる。

妥協のないアーキテクチャで、チームのベロシティを次の次元へ押し上げろ。