Proposal: ship guidance as markdown inside the package

Esamina la directory root del progetto e il package.json per comprendere la struttura attuale. Cerca i file .mdx di Storybook esistenti per vedere il contenuto di guida. Il compito consiste nel creare una directory docs/, aggiungere i file Markdown necessari (index.md, foundation/colour.md, components/buttons.md, ecc.) e aggiornare il package.json per includere 'docs/' nei file da pubblicare. Verifica come Storybook può importare e renderizzare questi file Markdown. Il successo significa che la documentazione è inclusa nel pacchetto npm e accessibile in 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.