MENU

Microsoft developer platform documentation updateの変更点：Fluent UI Headless docsite対応ガイド

Microsoft

Microsoft developer platform documentation updateの今回のポイントは、アプリのAPIやSDKの破壊的変更ではなく、Fluent UIのheadless components向けドキュメントサイトとStorybook周辺の表示・開発体験を改善する更新です。

特に確認すべきなのは、「Show code」パネルがプレビュー画面の中で見やすくなったこと、StackBlitzサンドボックスで表示されるファイルが整理されたこと、CSS ModulesまわりのStorybook設定が整理されたことです。なお、元のPR #36073は2026年5月5日に#36088へ集約する形でクローズされ、実際の統合は#36088側で行われています。対応が必要なのは、Fluent UIのheadless componentsを参照している開発者、Storybookベースの社内ドキュメントを運用しているチーム、CSS Modules付きのサンプルコードを管理しているフロントエンド担当者です。(GitHub)

目次

今回の更新は何が変わったのか

このMicrosoft developer platform documentation updateは、Microsoft/fluentuiリポジトリ内のheadless components docsiteを磨き込む変更です。PR #36073の説明では、主な内容として「Show code」パネルをcanvas card内に埋め込むこと、アクセントカラーをマゼンタ系へ変更すること、StackBlitzサンドボックスとタブ表示を改善することが挙げられています。(GitHub)

重要なのは、これは一般ユーザーが利用しているMicrosoft 365やAzureの管理画面が変わる話ではないという点です。影響は主に、Fluent UIのドキュメント、Storybook、サンプルコード、CSS Modules、StackBlitz連携といった開発者向け領域にあります。

確認項目変更内容実務上の意味
Show codeパネルcanvas card内に表示されるよう改善プレビューとコードを同じ文脈で確認しやすくなる
テーマアクセントカラーをマゼンタ系に変更ドキュメントサイトの見た目や選択状態の印象が変わる
StackBlitzサンドボックスに渡すCSS Modulesやtokens.cssの扱いを整理サンプルを開いた時に必要なスタイルが揃いやすくなる
タブ表示表示中のStoryで参照されるファイルに絞る不要なタブが減り、コード確認の迷いが少なくなる
Storybook設定CSS Modules対応やソース注入の仕組みを整理Storybookを運用する側は設定差分の確認が必要

Show codeパネルがcanvas内に入り、コード確認の流れが自然になる

これまでドキュメントサイトでコンポーネントを確認する場合、プレビュー、コード、外部サンドボックスの位置関係が分かりにくいことがありました。今回の変更では、Storybookのネイティブな「Show code」トグルに連動するソースパネルが、同じ.sbdocs-previewのcanvas card内に表示される設計になっています。これにより、表示中のコンポーネントとコードの対応関係を把握しやすくなります。(GitHub)

実務では、次のような場面で効果があります。

利用シーン改善されること
UI部品の採用検討画面表示とTSX/CSSの関係をすぐ確認できる
新人・他チームへの共有「どのコードがこの表示を作っているのか」を説明しやすい
デザインシステムのレビュー見た目、状態、コードを同じ流れで確認できる
サンプルコードのコピーStackBlitzへ移動する前に必要なコードを確認できる

注意したいのは、Show codeの表示場所が変わっても、コンポーネント自体の利用方法が全面的に変わるわけではない点です。自社アプリでFluent UIを利用しているだけなら、まずはパッケージのリリースノートや実際の依存関係変更を確認するのが先です。今回の記事で扱う変更は、主にドキュメント体験とStorybook基盤の改善として捉えるのが正確です。

マゼンタテーマへの変更は、見た目だけでなく識別性にも関係する

PR #36073では、サイドバー、ツールバーのアクセント、タブインジケーター、選択中ナビゲーションにマゼンタ系の#9b1f5aを使う変更が説明されています。サイドバーのhover背景はニュートラルグレーへ変更されています。(GitHub)

一見すると単なる配色変更ですが、ドキュメントサイトを日常的に使う開発者にとっては、選択中のStory、現在のタブ、操作対象の見分けやすさに関わります。社内で同様のStorybookテーマを使っている場合は、次の観点で確認するとよいでしょう。

確認観点チェック内容
視認性選択中タブ、サイドバー選択状態、hover状態が判別しやすいか
アクセシビリティ背景色とのコントラストが不足していないか
ブランド整合性自社デザインシステムのアクセントカラーと衝突しないか
ダークモード暗い背景でマゼンタが強く見えすぎないか
スクリーンショット差分Visual Regression Testで意図しない差分として扱われないか

配色変更は「壊れていないから問題ない」と見落とされがちです。しかし、ドキュメントサイトは開発者が仕様を判断する場所です。選択状態やフォーカス状態が分かりにくいと、コードの誤読やレビュー漏れにつながります。

StackBlitzとタブ表示の改善で、サンプルコードの迷子を減らす

今回の更新で実務的に重要なのが、StackBlitzサンドボックスとコードタブの整理です。PR #36073では、StoryのTSXで実際に参照されているCSS Modulesに絞ってタブを表示しつつ、サンドボックス側には必要なCSSをバンドルできるようにする内容が説明されています。(GitHub)

これにより、読者は「このStoryを見るために本当に必要なファイルはどれか」を判断しやすくなります。特にheadless componentsのように、コンポーネント本体とスタイル実装が分かれているケースでは、不要なCSSファイルやhelperが多く表示されると、初心者ほど混乱します。

サンプルコード確認時のおすすめ手順

手順やること見るポイント
1ドキュメント上でStoryを表示する目的の状態やバリエーションが合っているか
2Show codeを開くTSXとCSS Modulesの対応を確認する
3タブに表示されるCSSを確認する表示中のStoryで参照されているスタイルか
4StackBlitzで開く必要なファイルがsrc/styles/配下に揃っているか
5自社コードへ移植するtokens.cssやCSS Modulesの依存を取りこぼしていないか

よくある失敗は、TSXだけをコピーしてCSS Modulesやtokens.cssを忘れることです。見た目が崩れた時に「コンポーネントが壊れている」と判断する前に、サンプルで参照されているCSSとトークンが移植先にも存在するかを確認してください。

#36073だけで判断せず、#36088への集約も確認する

この更新を追う時に最も注意すべき点は、PR #36073がそのままマージされたわけではないことです。#36073は2026年5月5日に「#36088を優先する」としてクローズされ、#36088は同日にmasterへマージされています。(GitHub)

36088では、#36073で扱われていたCSS ModulesのShow code対応を、よりプラグイン化された形に整理しています。具体的には、Story作者がCSS Moduleをimportするだけで動作するようにし、Babelプラグインが*.module.cssのimportを検出して、Storyごとにparameters.cssModuleSourcesを注入する流れが説明されています。(GitHub)

つまり、実装や移行の判断では次のように見るのが安全です。

見るべき情報目的
#36073変更の背景、当初の改善内容、UI上の意図を理解する
#36088実際に統合された構成、CSS Modules検出、設定方法を確認する
自社のStorybook設定同じ仕組みを取り込む必要があるか判断する
既存のStoryファイル手動の?raw importやhelperが残っていないか確認する

対応が必要な人、不要な人

今回のMicrosoft developer platform documentation updateは、すべてのMicrosoft利用者が対応すべき変更ではありません。影響範囲を誤ると、必要のない調査に時間を使ってしまいます。

対象者対応要否理由
Fluent UIのheadless componentsを評価している開発者必要サンプルコードの見方とCSS依存の確認方法が変わるため
Storybookで社内UIドキュメントを運用している担当者必要Show code、CSS Modules、sandbox連携の設計参考になるため
Fluent UIリポジトリに近い開発をしているコントリビューター必要#36088に集約された実装方針を確認する必要があるため
CSS Modules付きのサンプルを公開しているチーム推奨タブ表示やsandboxへのファイル注入設計を見直せるため
Microsoft 365の一般利用者原則不要管理画面や日常利用機能の変更ではないため
AzureやTeamsアプリを利用するだけの管理者原則不要今回の変更は主にFluent UI docsiteとStorybook基盤の話であるため

移行や設定確認で見るべきポイント

社内のStorybookやデザインシステムドキュメントに似た構成を持っている場合は、単に「見た目が変わった」と捉えず、ソース表示とサンドボックス生成の設計を確認しましょう。

CSS Modulesは手動登録から自動検出へ寄せられている

36088では、以前のようにStoryごとに?raw importやwithCssModuleSource()を手動で書くのではなく、Babelプラグインが*.module.css importを検出する仕組みが説明されています。これにより、30個のStoryファイルからボイラープレートが削除されたとされています。(GitHub)

自社環境で確認するポイントは次の通りです。

確認項目具体的に見る場所
CSS Modulesのimportimport classes from './xxx.module.css'のような通常importになっているか
手動helperwithCssModuleSourceや?raw importに依存していないか
Storybook設定sandbox addonにCSS Modules関連の設定が渡っているか
tokens.cssサンプルに必要なトークンファイルのパスが正しいか
生成されるコードStackBlitz上で./styles/<basename>として参照できるか

parameters.themeを使っていた場合は衝突に注意する

36088では、パラメータ名がparameters.themeからparameters.cssModuleSourcesへ変更されています。理由として、Visual Regression Testing側のparameters.themeと衝突しないようにすることが説明されています。(GitHub)

もし社内Storybookでparameters.themeを独自に使っている場合、今回の考え方は参考になります。Storybookのparametersは便利ですが、意味の広い名前を使うと、後から別の用途と衝突しやすくなります。CSS Modulesのソース、テーマオブジェクト、表示テーマ、テスト条件は、それぞれ名前空間を分けて管理するのが安全です。

テストはビルド、Babel、SSR、表示確認を分けて見る

PR #36073では、public-docsite-v9-headless:build-storybookのビルド、Babel presetのテスト、headless storiesのSSRテスト、視覚的な表示確認が検証項目として挙げられています。(GitHub)

社内で似た変更を取り込むなら、次の順序で確認すると手戻りを減らせます。

テスト目的失敗時に疑う箇所
Storybookビルドドキュメントサイト全体が生成できるかwebpack設定、addon設定、パス解決
Babel pluginテストソースコード注入やimport書き換えが正しいかAST処理、CSS Modules検出、import mapping
SSRテストサーバーサイド描画で落ちないかCSS import、raw query、esbuild plugin
Visual Regression Test見た目の差分が意図通りかテーマ、tokens.css、CSS Modules
StackBlitz確認外部サンドボックスで再現できるかsrc/styles/、tokens.css、相対パス

headless componentsのサンプルCSSは「製品標準スタイル」と誤解しない

headless componentsは、基本的に見た目を固定したコンポーネントではなく、振る舞いや構造を活用しながら、スタイルは利用側で設計する前提のコンポーネントです。#36088の関連コミット説明でも、headless componentsはデフォルトスタイルを出荷せず、Story内のCSSは見た目の一例であることを示すdisclaimerが追加されたと説明されています。(GitHub)

そのため、サンプルのマゼンタテーマやCSS Modulesをそのまま本番アプリへコピーする前に、次の点を確認してください。

確認ポイント判断基準
自社デザインシステムとの整合色、余白、角丸、フォーカスリングが既存ルールと合うか
アクセシビリティキーボード操作、フォーカス表示、コントラストが十分か
保守性CSS Modulesの粒度がコンポーネント単位で管理しやすいか
再利用性tokens.cssの値を自社トークンへ置き換えやすいか
サンプル依存StackBlitz用のパスや仮のトークンを本番に持ち込んでいないか

サンプルは「正解のデザイン」ではなく、「実装の考え方を確認する材料」として扱うのが安全です。

よくある勘違いと対処法

勘違い正しい見方対処法
Microsoft developer platform全体の仕様変更だと思う主にFluent UIのheadless docsiteとStorybook周辺の更新影響範囲をFluent UI、Storybook、CSS Modulesに絞って確認する
#36073がそのまま反映されたと思う#36073は#36088へ集約されてクローズ実装確認は#36088も併せて見る
TSXだけコピーすれば動くと思うCSS Modulesやtokens.cssが必要な場合があるShow codeのタブとStackBlitz内のsrc/styles/を確認する
マゼンタテーマを必ず採用すべきだと思うdocsite上のテーマ改善であり、自社採用は任意自社ブランド、アクセシビリティ、VRT差分で判断する
parameters.themeを汎用的に使ってよいと思う名前衝突のリスクがある役割が分かるparameter名に分ける

自社チームで確認するためのチェックリスト

Fluent UIやStorybookを業務で使っている場合は、以下を順番に確認してください。

  • 自社が参照しているFluent UIのバージョンやブランチが、今回の変更を含む範囲か確認する
  • StorybookでShow codeや外部サンドボックス連携を使っているか確認する
  • CSS Modulesを使うStoryで、手動の?raw importや独自helperが残っていないか確認する
  • tokens.cssやデザイントークンの参照パスが、StorybookビルドとStackBlitzの両方で成立するか確認する
  • parameters.themeのような汎用名を使っている場合、別用途と衝突しないか確認する
  • Visual Regression Testで、マゼンタテーマやタブ表示の変更が意図した差分として扱われるか確認する
  • サンプルCSSを本番へ流用する場合、アクセシビリティと自社デザイン基準を満たすか確認する

今回の更新をどう活用すべきか

今回のMicrosoft developer platform documentation updateは、単なるUI微修正ではなく、「ドキュメント上でコンポーネントを見て、コードを理解し、サンドボックスで試す」までの流れを改善する更新です。

Fluent UIのheadless componentsを利用する開発者は、Show codeとStackBlitzを使って、TSX、CSS Modules、tokens.cssの関係を確認しましょう。Storybookを運用するチームは、#36088で示されたCSS Modulesの自動検出、parameter名の整理、設定のDRY化を参考にすると、サンプルコード管理の手間を減らせます。

まず取るべき行動はシンプルです。Fluent UIのheadless componentsを参照している場合は、該当Storyを開き、Show code、CSSタブ、StackBlitzの再現性を確認してください。社内Storybookを持っている場合は、CSS Modulesの登録方法とparameter設計を棚卸しし、手動作業や名前衝突が起きやすい箇所から見直すのが効果的です。

Microsoft
CSS Modules Microsoft developer platform Fluent UI Storybook StackBlitz

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次