CLAUDE.md

1# MetaMask Design System
2 
3Design tokens and components for MetaMask extension (React) and mobile (React Native).
4 
5## Documentation for AI Agents
6 
7Repository-specific conventions and patterns:
8 
9- @.cursor/rules/styling.md
10- @.cursor/rules/testing.md
11- @.cursor/rules/component-documentation.md
12- @.cursor/rules/component-architecture.md
13- @.cursor/rules/component-creation.md
14- @.cursor/rules/component-enum-union-migration.md
15- @.cursor/rules/component-migration.md
16- @.cursor/rules/figma-integration.md
17- @.cursor/rules/release-workflow.md
18 
19See @docs/ai-agents.md for comprehensive strategy explanation.
20 
21## Monorepo Structure
22 
23**This is a yarn workspaces monorepo.** Run all commands from the repository root.
24 
25### Command Patterns
26 
27Two ways to run commands:
28 
291. **Root scripts** (preferred for common tasks)
30 
31```bash
32   yarn build                 # Builds all packages
33   yarn test                  # Runs all tests
34   yarn lint                  # Lints entire monorepo
35```
36 
372. **Workspace-specific commands** (for targeting single packages)
38```bash
39   yarn workspace @metamask/design-system-react run test
40   yarn workspace @metamask/design-system-react run build
41   yarn workspace @metamask/design-system-react run lint
42```
43 
44**Never** use `cd packages/*/` - always run commands from root using one of the patterns above.
45 
46### Essential Commands
47 
48```bash
49# Build
50yarn build                    # All packages
51yarn build:types              # TypeScript only
52 
53# Test
54yarn test                     # All tests
55yarn test:storybook           # Accessibility tests
56yarn workspace @metamask/design-system-react run test              # Single package
57 
58# Lint
59yarn lint                     # Check all
60yarn lint:fix                 # Auto-fix
61 
62# Component Creation
63yarn create-component:react --name ComponentName --description "Brief description"
64yarn create-component:react-native --name ComponentName --description "Brief description"
65 
66# Storybook
67yarn storybook                # React web (port 6006)
68yarn storybook:ios:build      # React Native iOS dev client (first time / native dep changes)
69yarn storybook:ios            # React Native iOS (Metro + dev client)
70yarn storybook:android:build  # React Native Android dev client (first time / native dep changes)
71yarn storybook:android        # React Native Android (Metro + dev client)
72 
73# Dependencies
74yarn constraints --fix        # Fix dependency constraints
75yarn dedupe                   # Deduplicate dependencies
76```
77 
78### Packages
79 
80- `@metamask/design-tokens` - Foundation tokens
81- `@metamask/design-system-shared` - Shared utilities
82- `@metamask/design-system-react` - Web components
83- `@metamask/design-system-react-native` - Mobile components
84- `@metamask/design-system-tailwind-preset` - Web Tailwind preset
85- `@metamask/design-system-twrnc-preset` - Mobile twrnc preset
86 
87### Apps (Consumer Platforms)
88 
89Storybook apps in `apps/` consume packages for development and testing:
90 
91- `@metamask/storybook-react` - Web component development (`yarn storybook`)
92- `@metamask/storybook-react-native` - Mobile development (`yarn storybook:ios:build` then `yarn storybook:ios`)
93 
94These platforms are for manual testing and component showcase. Visual regression testing is planned but not yet implemented.
95 
96**Import using package names, never file paths:**
97 
98```tsx
99// ✅ Correct
100import { Button } from '@metamask/design-system-react';
101 
102// ❌ Wrong
103import { Button } from '../../../packages/design-system-react';
104```
105 
106## Personal Overrides
107 
108As per [Claude Code best practices](https://code.claude.com/docs/en/best-practices), create `CLAUDE.local.md` for personal preferences (gitignored).
109See `CLAUDE.local.md.example` for template.
110