Proposal: ship guidance as markdown inside the package

Examina el directorio raíz del proyecto y el package.json para comprender la estructura actual. Busca archivos .mdx existentes de Storybook para ver el contenido de orientación. La tarea consiste en crear un directorio docs/, agregar los archivos Markdown necesarios (index.md, foundation/colour.md, components/buttons.md, etc.) y actualizar el package.json para incluir 'docs/' en los archivos que se publicarán. Verifica cómo Storybook puede importar y renderizar estos archivos Markdown. El éxito significa que la documentación está incluida en el paquete npm y es accesible en 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.