Skip to content

docs: add component-creation.md cursor rule#944

Merged
georgewrmarshall merged 1 commit into
mainfrom
docs/component-creation-cursor-rule
Feb 27, 2026
Merged

docs: add component-creation.md cursor rule#944
georgewrmarshall merged 1 commit into
mainfrom
docs/component-creation-cursor-rule

Conversation

@georgewrmarshall

@georgewrmarshall georgewrmarshall commented Feb 26, 2026

Copy link
Copy Markdown
Contributor

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:

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 refactor: migrate BadgeCount to union and shared types #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

  • I've followed MetaMask Contributor Docs
  • I've completed the PR template to the best of my ability
  • I've included tests if applicable (N/A - documentation)
  • I've documented my code using JSDoc format if applicable (N/A - markdown)
  • I've applied the right labels on the PR (see labeling guidelines). 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.

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.ts vs index.ts export structure, and coverage-related anti-patterns to avoid.

Updates CLAUDE.md to 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.

@github-actions

Copy link
Copy Markdown
Contributor

📖 Storybook Preview

@github-actions

Copy link
Copy Markdown
Contributor

📖 Storybook Preview

georgewrmarshall added a commit that referenced this pull request Feb 26, 2026
- 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
@github-actions

Copy link
Copy Markdown
Contributor

📖 Storybook Preview


**Why this pattern?**

- ✅ Prevents duplicate exports that reduce test coverage

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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%
```

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread .cursor/rules/component-creation.md Outdated

- [ ] Build succeeds: `yarn build`
- [ ] Tests pass: `yarn test`
- [ ] Coverage meets thresholds: `yarn test --coverage` (80% all metrics)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@georgewrmarshall georgewrmarshall marked this pull request as ready for review February 26, 2026 22:05
@georgewrmarshall georgewrmarshall requested a review from a team as a code owner February 26, 2026 22:05
@github-actions

Copy link
Copy Markdown
Contributor

📖 Storybook Preview

georgewrmarshall added a commit that referenced this pull request Feb 26, 2026
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.
brianacnguyen
brianacnguyen previously approved these changes Feb 26, 2026
@georgewrmarshall georgewrmarshall enabled auto-merge (squash) February 27, 2026 00:30
@github-actions

Copy link
Copy Markdown
Contributor

📖 Storybook Preview

@georgewrmarshall georgewrmarshall merged commit 6e81a76 into main Feb 27, 2026
43 checks passed
@georgewrmarshall georgewrmarshall deleted the docs/component-creation-cursor-rule branch February 27, 2026 18:15
georgewrmarshall added a commit that referenced this pull request Mar 3, 2026
## **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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants