docs: add component-creation.md cursor rule#944
Conversation
📖 Storybook Preview |
📖 Storybook Preview |
- Remove Box/Button examples (align with PR #943 - these components don't follow ADR-0003/0004 yet) - Add Step 11: Verify Coverage section with critical warning about duplicate exports - Add coverage check to verification checklist - Clarify type vs interface rule with composition/intersection rationale - Reference BadgeCount PR #942 coverage issue as real-world example Addresses review feedback from PR #944 code review
📖 Storybook Preview |
|
|
||
| **Why this pattern?** | ||
|
|
||
| - ✅ Prevents duplicate exports that reduce test coverage |
There was a problem hiding this comment.
Critical two-file pattern prevents duplicate const object exports. When const objects are exported from both .types.ts and index.ts, Jest coverage tracking sees uncovered code paths, failing 80% thresholds discovered in BadgeCount PR #942.
| # - Lines: 80% | ||
| # - Statements: 80% | ||
| ``` | ||
|
|
There was a problem hiding this comment.
New section added during review to explicitly document coverage requirements. BadgeCount PR #942 demonstrated how duplicate const exports create uncovered branches, causing CI failures at 80% threshold.
|
|
||
| - @packages/design-system-shared/src/types/BadgeStatus/ (Shared types - SOURCE OF TRUTH) | ||
| - @packages/design-system-react/src/components/BadgeStatus/ (React implementation) | ||
| - @packages/design-system-react-native/src/components/BadgeStatus/ (React Native implementation) |
There was a problem hiding this comment.
BadgeStatus is the ONLY component example referenced. Box and Button were removed during review for consistency with PR #943 - those components haven't been migrated to ADR-0003/0004 patterns yet. BadgeStatus is the single source of truth for correct implementation.
| - ✅ Create in `packages/design-system-shared/src/types/ComponentName/` | ||
| - ✅ Use const objects (ADR-0003): `export const MyComponentVariant = { Primary: 'primary' } as const;` | ||
| - ✅ Derive types: `export type MyComponentVariant = (typeof MyComponentVariant)[keyof typeof MyComponentVariant];` | ||
| - ✅ Use `type` not `interface` for props (enforced by ESLint for better composition and intersection patterns) |
There was a problem hiding this comment.
Clarified during review with rationale. Type is preferred over interface for better composition with intersection types and union types, which are heavily used in the platform extension pattern.
|
|
||
| - [ ] Build succeeds: `yarn build` | ||
| - [ ] Tests pass: `yarn test` | ||
| - [ ] Coverage meets thresholds: `yarn test --coverage` (80% all metrics) |
There was a problem hiding this comment.
Coverage check added to verification checklist during review. Ensures AI agents verify coverage thresholds before considering component complete. Links back to Step 11 for detailed explanation.
📖 Storybook Preview |
Added coverage threshold verification to Build & Tests checklist for consistency with component-creation.md (PR #944). Uses correct 100% thresholds for branches, functions, lines, and statements.
3d3ae57 to
91a98c0
Compare
📖 Storybook Preview |
## **Description** Adds `component-creation.md` cursor rule providing step-by-step technical guidance for creating design system components. This HOW-TO guide ensures AI agents follow ADR-0003 (const objects) and ADR-0004 (centralized types) patterns when scaffolding new components. **Key guidance provided:** - Using `create-component:react` and `create-component:react-native` scripts - Two-file export structure: `.types.ts` imports only, `index.ts` exports only - Creating shared types in `@metamask/design-system-shared` package - Transforming generated templates to use Box/Text primitives and design tokens generated tailwind classnames - Cross-platform consistency between React and React Native implementations **Critical anti-patterns documented:** - Using TypeScript enums instead of const objects with `as const` - Not creating shared types (violates ADR-0004 layered architecture) - Including platform-specific props in shared types - Leaving template code unchanged (raw div/View elements) **Why this matters:** We need to ensure our components are consistent across platforms and use the most up to date typescript conventions **Relationship to other rules:** - Depends on: `component-architecture.md` (foundational patterns) - Used by: `component-migration.md` (references this for scaffolding steps) **References:** - Golden path: BadgeStatus component (complete implementation) - Validation: BadgeCount PR #942 (demonstrated coverage issue and fix) - Scripts: `create-component:react` and `create-component:react-native` ## **Related issues** Fixes: https://consensyssoftware.atlassian.net/browse/DSYS-341 ## **Manual testing steps** 1. Review the cursor rule file: `.cursor/rules/component-creation.md` 2. Verify changes in BadgeCount PR #942 align with most up to date coventions 3. Verify golden path examples reference BadgeStatus implementation 4. Check that CLAUDE.md includes reference to this new rule ## **Screenshots/Recordings** N/A - Documentation only ## **Pre-merge author checklist** - [x] I've followed [MetaMask Contributor Docs](https://github.com/MetaMask/contributor-docs) - [x] I've completed the PR template to the best of my ability - [x] I've included tests if applicable (N/A - documentation) - [x] I've documented my code using [JSDoc](https://jsdoc.app/) format if applicable (N/A - markdown) - [ ] I've applied the right labels on the PR (see [labeling guidelines](https://github.com/MetaMask/metamask-extension/blob/develop/.github/guidelines/LABELING_GUIDELINES.md)). Not required for external contributors. ## **Pre-merge reviewer checklist** - [ ] I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed). - [ ] I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots. <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Documentation-only changes that affect developer/agent guidance, not runtime behavior. Risk is limited to potential confusion if guidance is inaccurate or drifts from actual scripts/architecture. > > **Overview** > Adds a new Cursor rule `component-creation.md` that standardizes the step-by-step process for creating cross-platform design-system components, including shared-types-first (ADR-0003/0004), Box/Text + token usage, and a strict export pattern (`.types.ts` imports only; `index.ts` is the single const-object export point to avoid coverage gaps). > > Updates existing AI-agent docs to reference this new rule, expands Storybook story naming guidance with concrete examples, and documents the `create-component:react-native` scaffolding command alongside the React one. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 3d3ae57. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Claude <noreply@anthropic.com>
Description
Adds
component-creation.mdcursor rule providing step-by-step technical guidance for creating design system components. This HOW-TO guide ensures AI agents follow ADR-0003 (const objects) and ADR-0004 (centralized types) patterns when scaffolding new components.Key guidance provided:
create-component:reactandcreate-component:react-nativescripts.types.tsimports only,index.tsexports only@metamask/design-system-sharedpackageCritical anti-patterns documented:
as constWhy this matters:
We need to ensure our components are consistent across platforms and use the most up to date typescript conventions
Relationship to other rules:
component-architecture.md(foundational patterns)component-migration.md(references this for scaffolding steps)References:
create-component:reactandcreate-component:react-nativeRelated issues
Fixes: https://consensyssoftware.atlassian.net/browse/DSYS-341
Manual testing steps
.cursor/rules/component-creation.mdScreenshots/Recordings
N/A - Documentation only
Pre-merge author checklist
Pre-merge reviewer checklist
Note
Low Risk
Documentation-only changes that don’t affect runtime behavior; risk is limited to potential convention drift if guidance is incorrect.
Overview
Adds a new Cursor rule,
component-creation.md, documenting a step-by-step process for creating cross-platform design-system components, including ADR-0003/0004 type patterns, a strict.types.tsvsindex.tsexport structure, and coverage-related anti-patterns to avoid.Updates
CLAUDE.mdto reference this new rule in the AI-agent documentation index.Written by Cursor Bugbot for commit 91a98c0. This will update automatically on new commits. Configure here.