القائمة
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/digital-go-jp/design-system-example-components-html --skill write-documentيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| name | write-document |
| description | コンポーネントのMDXドキュメントを作成・更新する |
デジタル庁デザインシステム（HTML版）のコンポーネントドキュメント（MDX）を作成・更新するためのガイドラインです。
各コンポーネントのドキュメントは以下の場所に配置します：
src/components/<component-name>/<component-name>.mdx
ドキュメントを執筆する前に、以下のファイルを全て読み込んでコンポーネントの全体像を把握します：
コンポーネントディレクトリ内の全HTMLファイル
src/components/<component-name>/*.htmlStoriesファイル
src/components/<component-name>/<component-name>.stories.tsargTypesからバリエーション（data属性の値）を把握render関数内で動的に設定される属性を確認CSSファイル
src/components/<component-name>/<component-name>.cssJavaScriptファイル（存在する場合）
src/components/<component-name>/<component-name>.js既存のMDXファイル（更新の場合）
src/components/<component-name>/<component-name>.mdxこれらを総合的に分析した上で、ドキュメントを執筆します。
Storiesファイルから以下の情報を読み取ります：
argTypes: どのようなオプション（選択肢）が使えるかを把握render関数: そのオプションがHTMLのどの属性・要素に反映されるかを確認<Canvas>+<Controls>を配置（ただし原則<Canvas withToolbar>を使用）argTypesだけではHTMLへの反映方法はわからないため、必ずrender関数も確認してください。
MDXファイルは以下の構成に従います。セクションの順序を守ってください：
import { Canvas, Controls, Description, Meta, Source, Stories, Subtitle, Title, Unstyled } from "@storybook/addon-docs/blocks";
import * as ComponentStories from "./component-name.stories";
import componentCss from "./component-name.css?raw";
<Meta of={ComponentStories} />
<Unstyled>
<div className="prose">
<Title />
<Subtitle />
<Description />
<Canvas of={ComponentStories.Playground} withToolbar />
<Controls of={ComponentStories.Playground} />
## ソースコード
## 仕様（該当する場合）
### バリエーション（該当する場合）
### 機能仕様（該当する場合）
## 使い方（該当する場合）
### インストール（該当する場合）
### （バリエーションのガイド：該当する場合）
### マークアップ（該当する場合）
### アクセシビリティ（該当する場合）
<Stories title="デモ" includePrimary={false} />
## 参考情報（該当する場合）
</div>
</Unstyled>
重要: <Canvas of={ComponentStories.Playground} withToolbar />と<Controls of={ComponentStories.Playground} />は常にドキュメントの最上部（<Description />の直後）に配置します。
data属性によるバリエーションやJavaScriptがなく、特筆すべき注意点もないシンプルなコンポーネント（blockquote等）では、「仕様」「使い方」セクションを省略した最小構成が許容されます：
import { Canvas, Controls, Description, Meta, Source, Stories, Subtitle, Title, Unstyled } from "@storybook/addon-docs/blocks";
import * as ComponentStories from "./component-name.stories";
import componentCss from "./component-name.css?raw";
<Meta of={ComponentStories} />
<Unstyled>
<div className="prose">
<Title />
<Subtitle />
<Description />
<Canvas of={ComponentStories.Playground} withToolbar />
<Controls of={ComponentStories.Playground} />
## ソースコード
<details>
<summary>HTML</summary>
（HTMLマークアップ）
</details>
<details>
<summary>component-name.css</summary>
<Source code={componentCss} language="css" />
</details>
<Stories title="デモ" includePrimary={false} />
</div>
</Unstyled>
最小構成の判断基準:
card（カード）のように、単一のコンポーネントではなく複数の作例を提示する性質のコンポーネントでは、通常のテンプレートに従わない構成が許容されます。各作例ごとに<Canvas>+<Controls>とCSSソースコードを配置する形式を取ります。
上記テンプレートに含まれないセクションを必要に応じて追加できます。例：
追加セクションは「使い方」の後、「デモ」の前に配置してください。
@storybook/addon-docs/blocksから、以下のコンポーネントをインポートします。効率化のため、未使用のものがあっても常に全てインポートします。
import { Canvas, Controls, Description, Meta, Source, Stories, Subtitle, Title, Unstyled } from "@storybook/addon-docs/blocks";
./component-name.stories./component-name.css?raw（?rawでソースを文字列として取得）./component-name.js?raw../other-component/other-component.css?raw./docs/image.webpスクリーンショット等の画像をドキュメントに含める場合、画像ファイルをインポートして<img>要素で表示します：
import screenshot from "./docs/screenshot.webp";
import screenshotAt2x from "./docs/screenshot@2x.webp";
<div class="border-image">
<img src={screenshot} srcSet={`${screenshotAt2x} 2x`} alt="スクリーンショットの説明" width="768" height="320" style={{ maxWidth: '100%', height: 'auto' }} />
</div>
画像ファイルはsrc/components/<component-name>/docs/ディレクトリに配置します。
コンポーネントのHTML、CSS、JS、依存ファイルのソースコードを<details>要素で折りたたんで記載します。
<details>のsummaryテキスト<summary>HTML</summary>（「HTML」と表記）<summary>component-name.css</summary>（ファイル名を使用）<summary>button.css</summary>（ファイル名を使用）## ソースコード
<details>
<summary>HTML</summary>
```html
<button class="dads-button" data-size="md" data-type="solid-fill">ボタン</button>
```
</details>
<details>
<summary>component-name.css</summary>
<Source code={componentCss} language="css" />
</details>
<details>
<summary>component-name.js</summary>
<Source code={componentJs} language="javascript" />
</details>
### 依存ファイル
<details>
<summary>button.css</summary>
<Source code={buttonCss} language="css" />
</details>
コンポーネントの「型」を示す完全なHTMLマークアップを記載します。
<button> / <a>）data-typeやdata-sizeの値が異なるだけのもの（仕様セクションの表で説明）複数のバリエーションがあっても、マークアップの差分が小さい場合（クラス名の違い、アイコンの追加程度）は、ソースコードセクションには基本形のみを記載し、差分は「使い方」セクションで説明します。
例: パンくずリストで「ラベル表示」「ホームアイコン付き」などのバリエーションがある場合
## 使い方
### ラベルを表示する
ラベルを視覚的に表示する場合は、`dads-u-visually-hidden`の代わりに`dads-breadcrumb__label`クラスを使用します。
```html
<span id="breadcrumb-label" class="dads-breadcrumb__label">現在位置</span>
```
### ホームアイコンを追加する
リンクテキストの前にアイコンを追加できます。
```html
<a class="dads-breadcrumb__link" href="#">
<svg class="dads-breadcrumb__link-icon" ...>...</svg>
ホーム
</a>
```
マークアップの構造自体が異なる場合は、ソースコードセクションに複数のパターンを記載します：
<details>
<summary>HTML</summary>
#### 基本形
```html
<label class="dads-checkbox" data-size="sm">
<span class="dads-checkbox__checkbox">
<input class="dads-checkbox__input" type="checkbox">
</span>
<span class="dads-checkbox__label">ラベル</span>
</label>
```
#### スタンドアロン（ラベルなし）
```html
<span class="dads-checkbox" data-size="sm">
<span class="dads-checkbox__checkbox">
<input id="article-1-checkbox" class="dads-checkbox__input" type="checkbox">
</span>
</span>
```
</details>
他のコンポーネントのCSS/JSに依存している場合は、ソースコードセクション内に「### 依存ファイル」見出しを設けて記載します：
### 依存ファイル
<details>
<summary>button.css</summary>
<Source code={buttonCss} language="css" />
</details>
<details>
<summary>calendar.css</summary>
<Source code={calendarCss} language="css" />
</details>
<details>
<summary>calendar.js</summary>
<Source code={calendarJs} language="javascript" />
</details>
コンポーネントが備える静的な性質を記載します。data属性によるバリエーションがなく、JavaScriptによる複雑な機能もないコンポーネントでは、このセクション全体を省略できます。
記載しないもの:
data属性によるバリエーションがある場合、Markdownテーブルで記載します。
data属性によるバリエーションがないコンポーネントでは、このセクションは省略します。
### バリエーション
| 属性 | 値 | 説明 |
| --- | --- | --- |
| `data-type` | `solid-fill`（デフォルト）, `outline`, `text` | ボタンのスタイル |
| `data-size` | `lg`, `md`, `sm`, `xs` | ボタンのサイズ |
JavaScriptを含む複雑なコンポーネントの場合、機能の詳細仕様を記載します：
data-type属性の値ごとの動作の違い）コンポーネントを正しく使うための情報を記載します。特筆すべき情報がないシンプルなコンポーネントでは、このセクション全体を省略できます。
このセクションでは、ソースコードセクションの「型」に対する差分を説明します：
コード例を含めて具体的に説明します。
コンポーネントを導入する際に必要な情報を記載します。
記載する場合:
記載しない場合:
### インストール
#### 必要なファイル
- **共通**
- `component-name.css`
- `component-name.js`
- **追加で必要**
- `button.css`（ボタンを使用する場合）
スクリプトを読み込む際は必ず、`<script type="module">`を使用しES Moduleとして読み込んでください。
ソースコードセクションで基本形のみを記載した場合、バリエーションの適用方法をここで説明します。各バリエーションごとに見出しを設け、差分となるコードスニペットを提示します。
### ラベルを表示する
ラベルを視覚的に表示する場合は、`dads-u-visually-hidden`の代わりに`dads-breadcrumb__label`クラスを使用します。
```html
<span id="breadcrumb-label" class="dads-breadcrumb__label">現在位置</span>
```
コンポーネントを正しく使用するための情報を記載します：
記載する場合:
<label>と<fieldset>の使い分けなど、利用者の判断が必要な場合aria-invalidやaria-describedbyなど、状況に応じて利用者が設定する属性がある場合記載しない場合:
aria-hidden、キーボード操作対応、スクリーンリーダー対応など）つまり、「コンポーネントが既に対応していること」ではなく、「利用者が正しく使うために知っておくべきこと」のみを記載します。
Storybookのインタラクティブなデモを配置します。title属性でh2見出しを指定します。
<Stories title="デモ" includePrimary={false} />
注意: <Canvas>と<Controls>はドキュメント最上部に配置するため、デモセクションでは<Stories title="デモ" includePrimary={false} />のみを配置します。
<Canvas>の使い分け原則として<Canvas of={ComponentStories.Playground} withToolbar />と<Controls of={ComponentStories.Playground} />をドキュメント最上部に配置します。
Storiesに複数のPlaygroundがある場合でも、先頭のPlaygroundストーリーを<Canvas withToolbar>で表示し、追加のPlaygroundはデモセクション内に個別配置します：
### Separatedタイプ
<Canvas of={DatePickerStories.PlaygroundSeparated} meta={DatePickerStories} />
<Controls of={DatePickerStories.PlaygroundSeparated} meta={DatePickerStories} />
<Stories title="デモ" includePrimary={false} />
外部リソースへのリンクを提供します（該当する場合）：
## 参考情報
- [H71: fieldset 要素及び legend 要素を使用して... [WCAG 2.1]](https://waic.jp/translations/WCAG21/Techniques/html/H71)
他のコンポーネントのドキュメントへリンクする場合、以下の書式を使用します：
詳細は[フォームコントロールラベル](?path=/docs/components-フォームコントロールラベル--docs)を参照してください。
特定のセクションにリンクする場合：
[フォームコントロールラベル](?path=/docs/components-フォームコントロールラベル--docs#複数のコントロールにラベルを付ける)
リンクパスの規則:
?path=/docs/components-{Storiesのtitleのスラッシュ以降}--docstitleが"Components/フォームコントロールラベル"の場合: ?path=/docs/components-フォームコントロールラベル--docsドキュメント作成時に確認すること：
?raw付きでインポートしている?raw付きでインポートしている<Unstyled>と<div className="prose">で全体を囲んでいる<Canvas of={ComponentStories.Playground} withToolbar />と<Controls of={ComponentStories.Playground} />がドキュメント最上部（<Description />直後）に配置されている<details>で折りたたんで記載<Stories title="デモ" includePrimary={false} />を配置している?path=/docs/components-{名前}--docs）