Proposal: ship guidance as markdown inside the package

プロジェクトのルートディレクトリと package.json を調べて、現在の構造を理解します。既存の Storybook .mdx ファイルを探し、ガイダンスの内容を確認します。タスクは、docs/ ディレクトリを作成し、必要な Markdown ファイル（index.md、foundation/colour.md、components/buttons.md など）を追加し、package.json を更新して公開するファイルに 'docs/' を含めることです。Storybook がこれらの Markdown ファイルをどのようにインポートしてレンダリングできるかを確認します。成功とは、ドキュメントが npm パッケージに含まれ、Storybook でアクセス可能になることを意味します。

What is being proposed?

Ship the design system’s guidance as Markdown within sci-react-ui, making it available without leaving the editor.

Key suggestion: Add a root-level docs/ directory and add it to package.json.

Where possible, Storybook’s .mdx pages would use the same Markdown. Interactive content, such as live swatches, would remain in Storybook.

This would make the guidance available in Storybook, GitHub and the installed package.

Why is this needed?

The guidance does not currently ship

package.json includes only dist/, so the Markdown and MDX documentation is excluded from the installed package.

Storybook is not available within the editor

• Developers may guess at decisions already covered by the guidance.
• Coding agents can inspect the installed package but cannot reliably read a deployed Storybook site. This can lead them to use standard MUI patterns rather than our semantic roles.

The documentation would match the installed version

Storybook shows the deployed version. Packaged documentation would match the version used by each consumer.

What will change?

• Add a root-level docs/ directory.
• Package files to [dist/, docs/].
• Where practical, refactor .mdx pages to use the Markdown files.
• Trim readme.md to the introduction and installation instructions, linking to docs/ for further guidance.

There would be no changes to components, props or behaviour.

A short spike is needed to confirm how Storybook can render imported Markdown alongside MDX-specific layouts and interactive content.

Fallback: keep the .mdx pages authoritative and maintain a smaller Markdown subset, accepting some duplication.

Proposed file set

Create one Markdown file per existing guidance page, plus an index:

• dist/
• docs/
  • index.md
  • foundation/colour.md
  • …
  • components/buttons.md
  • …
• readme.md

docs/index.md would provide an entry point to the full set.

Breaking change?

No.