What is being proposed?
Ship the design system’s guidance as Markdown within sci-react-ui package, making it available without leaving the editor, and consumable by both humans and agents.
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. Some content, such as swatches view, 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 need to go to the Storybook instance or access the full repo in order to see the documentation, which can lead to guessing implementation guidelines already covered elsewhere.
- 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.
What is being proposed?
Ship the design system’s guidance as Markdown within
sci-react-uipackage, making it available without leaving the editor, and consumable by both humans and agents.Key suggestion: Add a root-level
docs/directory and add it topackage.json.Where possible, Storybook’s
.mdxpages would use the same Markdown. Some content, such as swatches view, 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.jsonincludes onlydist/, so the Markdown and MDX documentation is excluded from the installed package.Storybook is not available within the editor
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?
docs/directory.dist/,docs/]..mdxpages to use the Markdown files.readme.mdto 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
.mdxpages authoritative and maintain a smaller Markdown subset, accepting some duplication.Proposed file set
Create one Markdown file per existing guidance page, plus an index:
docs/index.mdwould provide an entry point to the full set.Breaking change?
No.