MetaMask / MetaMask/metamask-design-system
docs: update component documentation rules/templates based on BannerBase migration
- Dominant language
- TypeScript
- Stars
- 37
- Forks
- 14
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 60
Description
## Context
During the BannerBase migration, we hit repeated docs/storybook mismatches that are not clearly encoded in our current documentation rule and README templates.
This issue proposes updates to:
- `.cursor/rules/component-documentation.md`
- `docs/component-readme-examples/react-readme-example.mdx`
- `docs/component-readme-examples/react-native-readme-example.md`
## What we learned (BannerBase)
### Storybook conventions
- Keep `Default` first with controls wired in `argTypes`.
- Use handler-specific story names when behavior is handler-gated and clearer than a raw prop name (for example `ActionButtonOnClick` / `ActionButtonOnPress`).
- Prevent prop leakage across stories (especially docs/canvas render) by explicitly setting unrelated args to `undefined` where needed.
- For single-prop stories (for example `Description`), avoid unrelated major props unless required for context.
### README conventions (React web)
- Use Canvas as the canonical source of examples/code generation.
- Avoid duplicate inline code snippets in prop sections.
- Keep prop tables and include related prop-object rows where helpful (for example `title` + `titleProps`, `onClose` + `closeButtonProps`).
- Mention related prop objects in prose within the main prop section.
### README conventions (React Native)
- Keep static code examples per prop section.
- Keep `style` guidance and `tw.style(...)` conditional example aligned with template wording.
- Include related prop-object rows in prop tables where helpful.
### Cross-platform consistency
- Keep prop coverage and section structure aligned across web/native.
- Allow format differences by platform:
- Web: Canvas-first.
- Native: static snippet examples retained.
## Proposed rule updates (`.cursor/rules/component-documentation.md`)
1. Add explicit guidance for handler-gated story naming.
2. Add explicit guidance for story arg isolation (`undefined` for unrelated props when needed).
3. Add single-prop story purity guidance.
4. Clarify web/native README format split (web Canvas-first, native snippet-first).
5. Clarify related prop-object documentation pattern (prose + table row grouping).
## Proposed template updates
### `react-readme-example.mdx`
- Add Canvas-first guidance.
- Add optional table format with `PROP` column for grouped rows.
- Show grouped prop-object example rows.
### `react-native-readme-example.md`
- Preserve per-prop snippet structure.
- Preserve `tw.style(...)` conditional style example.
- Add grouped `PROP` row variant for related prop objects.
## Suggested acceptance criteria
- [ ] Rule doc updated with handler-story, story isolation, and platform-format guidance.
- [ ] React template updated for Canvas-first + grouped prop-object table pattern.
- [ ] RN template updated for grouped prop-object table pattern while preserving static snippets.
- [ ] Docs for touched components follow the updated rule/template.
Contributor guide
Research direction
Start by reading .cursor/rules/component-documentation.md, docs/component-readme-examples/react-readme-example.mdx, and docs/component-readme-examples/react-native-readme-example.md, then compare the BannerBase findings with the current guidance. Done means all three files cover the listed story, prop-table, Canvas, snippet, and cross-platform requirements, with the acceptance criteria addressed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react, react-native
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100