MetaMask / MetaMask/metamask-design-system

docs: update component documentation rules/templates based on BannerBase migration

Open
#956 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.