Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Proposal: ship guidance as markdown inside the package

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#325 1 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
75/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
markdown, react, typescript
Lĩnh vực
developer-experience, documentation

Hướng nghiên cứu

Kiểm tra thư mục gốc của dự án và package.json để hiểu cấu trúc hiện tại. Tìm các tệp .mdx Storybook hiện có để xem nội dung hướng dẫn. Nhiệm vụ là tạo một thư mục docs/, thêm các tệp Markdown cần thiết (index.md, foundation/colour.md, components/buttons.md, v.v.) và cập nhật package.json để bao gồm 'docs/' trong các tệp sẽ được xuất bản. Xác minh cách Storybook có thể nhập và hiển thị các tệp Markdown này. Thành công có nghĩa là tài liệu được bao gồm trong gói npm và có thể truy cập được trong Storybook.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

needs-triage

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.

Ngôn ngữ chính
TypeScript
Star
8
Fork
3
Merge trung bình
1 ngày 15 giờ
Pull request đã merge (30 ngày)
10

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của DiamondLightSource/sci-react-ui

Tất cả issue của DiamondLightSource/sci-react-ui

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.