MetaMask UI Development — MMDS Guidance
Strategy context: Agentic Design System Strategy
The MetaMask Design System (MMDS) is the default for MetaMask product UI. This
base holds the rules shared by every client. The repository overlay below it
adds platform paths, the styling surface, and platform-only rules.
When to use
Use this skill when you create, change, restyle, or review UI in a MetaMask
client: components, screens, sheets, modals, stories, styles, tokens, themes,
and UI behavior. Use it to decide between an MMDS component, a legacy
component-library component, a feature component, and custom UI.
Copy and wording rules live in content-guidelines, and file layout and test
setup live in component-scaffold, where the repository has them.
Sources, in order
Work from them in this order. None of these needs an MCP server. The Design
Brain step uses a Notion connector when one can reach the MetaMask workspace.
Installed package types (node_modules). The installed version is the
contract for the code you are changing. Read the export index and the
component's .types file (with its JSDoc) under
node_modules/@metamask/<platform package>/dist/. Shared prop and enum
types are declared in
node_modules/@metamask/design-system-shared/dist/types/. Read them
there, but import components and enums from the platform package. When
the types disagree with anything else on this list, the types win.
Hosted Storybook components manifest, for discovery and story
snippets:
The manifests are built from MMDS main, so they can list components or
props that are newer than the version the consumer repo installs. Confirm
anything you find there against the installed types before you use it.
Story import snippets sometimes pull enums from
@metamask/design-system-shared; in product code, import them from the
platform package (@metamask/design-system-react or
@metamask/design-system-react-native). How to read a manifest:
references/reading-mmds-manifests.md.
Design Brain, when Notion is available. Query
Design Brain — Lessons & Rules
for the area you are changing. Apply Active rules (P0 must, P1 should).
Treat Proposed rules as guidance only. Cite the rule you applied in the PR
or review, and check the Brain for patterns too. Installed types still win
on what exists in code. If you have no Notion access, write "Design Brain
not checked" in the PR or review. Do not skip it silently.
Component README at the installed version's tag. READMEs are not in the
npm tarball. Read the installed version from
node_modules/@metamask/<package>/package.json (or the lockfile), then open
the README on GitHub at the per-package tag
@metamask/<package>@<version>. The package CHANGELOG.md compare links
use the same tag names. Never hard-code a release in code comments or
skills.
Existing repository usage and stories. Search the consumer repo for the
component or token. Treat examples as usage evidence, not as the contract.
Figma MCP and Code Connect, when connected. Use them to read the design
and its component mapping. If they are not connected, carry on without them.
Workflow
Create: read the installed types (and README when behavior is unclear)
for each building block, choose the component as below, style with preset
classes and tokens, then run the review checklist on your own diff.
Review: list the changed UI, check each MMDS usage for deprecation (see
Deprecated APIs), then report component choice, deprecated
usage, tokens, typography, and accessibility findings with file, line,
evidence, and a recommended fix. Say whether Design Brain was checked, or
write "Design Brain not checked".
Custom UI without a recorded reason is a finding, not an automatic failure.
Choosing a component
- Before building anything, look up the component by name in the manifest
and the installed exports. For a pattern, use the first place that has it:
Storybook or the manifest docs, then the Design Brain when Notion is
available, then the component README at the installed tag, then existing
repository usage. Never invent a component, a prop, or a variant, and never
port an API from the other platform or another UI library.
- Choose in this order, and record the reason whenever you go past step 1:
- An MMDS component exported by the installed platform package.
- A non-deprecated legacy component-library component, only when MMDS does
not cover the need.
- An existing feature component that already solves it.
- Custom UI composed from MMDS primitives and tokens, with the reason
recorded in the PR or the repository's exception format.
- Do not invent button or control chrome that MMDS does not have. Keep
single-select (checkmark) and multi-select (checkbox) patterns distinct.
- If an MMDS layout makes a primary data point read as secondary, compose a
stronger treatment instead of forcing the wrong primitive.
Deprecated APIs
This rule applies to every client. Repository overlays and scaffolds defer to
it.
- Do not add new usage of anything marked
@deprecated (a component, prop,
or enum value). Use the replacement its JSDoc or README names when the
installed platform package exports it, even if the repository still uses
the deprecated one. If no replacement is exported, keep existing usage and
record the gap.
- To check, search the component's whole installed folder:
grep -rn @deprecated node_modules/@metamask/<platform package>/dist/components/<Name>/.
The tag is often on the component declaration (<Name>.d.cts), and the
.types file can omit it. A non-empty manifest jsDocTags.deprecated, or
@deprecated in the README at the installed tag, is the same signal. An
empty jsDocTags is not evidence that it is current.
Foundations
- Use preset Tailwind classes first for color, type, shadows, motion, spacing,
and radius. Tailwind comes from the MMDS presets configured in the consumer
repo. Use only class names those presets generate, including the 4px spacing
scale (
p-4, gap-2) and the default radii (rounded-lg, rounded-xl,
rounded-2xl, rounded-full). Do not use default Tailwind colors.
- When Tailwind does not make sense or is not possible (a prop or style
object, a third-party component, a chart, an animation, or a place that
needs a CSS variable or theme value), use a semantic token from the
installed
@metamask/design-tokens package, in JS or CSS. No recorded
reason is needed. The overlay says how this platform reads one. Read the
package README at the installed tag
@metamask/design-tokens@<version>.
- Never use a raw palette value, a hex value, or an arbitrary value
(
bg-[#...], p-[15px], rounded-[16px], text-[14px],
borderRadius: 16).
- Meet WCAG AA contrast (normal text 4.5:1, large text and UI graphics 3:1)
and check dark mode.
- Layouts must survive longer translated strings and future RTL without
clipping or overlap. Avoid fixed-width text boxes.
Typography
- Set type with the design-system text component. Use the font family and
variant options the installed types expose, and follow the hosted manifest
and the component README at the installed tag for when each applies. Never
hand-set font sizes, line heights, or arbitrary text classes.
- Amount inputs have no settled typography pattern yet. Use the font family
and variant options the installed types expose, and do not invent a
dedicated amount style.
Incremental migration: Legacy* aliases
When a file imports the same name from a legacy source and from the MMDS
platform package, alias the legacy import with a Legacy prefix and keep the
MMDS import on the plain name. Do the same for clashing enums. Leave legacy
imports that have no MMDS counterpart in the same file on their plain names
until that step migrates them. Do not alias legacy names that MMDS does not export, and never put the
prefix on the MMDS import. Finishing the migration is deleting the Legacy*
import and its usages. The overlay gives the platform's import paths and an
example.
Accessibility
A short floor of plain WCAG basics. Design Brain rules are not copied here;
read them from the Design Brain source above.
- Every input has a persistent label. A placeholder is not a label.
Meaningful icons and icon-only buttons have an accessible name, and
decorative icons are hidden.
- Never show state with color alone, and expose that state to assistive tech.
Do not nest interactive controls.
- Announce async status and errors. Overlays and sheets manage focus and keep
close or back available.
- Respect reduced motion, and meet WCAG AA contrast.
MMDS agent docs
Read these in the MMDS repository instead of copying them into skills:
These track MMDS main. Where they disagree with the installed types, the
installed types win.
Review checklist
1---2name: ui-development-23description: >-4 UI component development standards for MetaMask clients: the strict5 design-system-first component hierarchy, availability checks before6 building custom components, styling with design tokens, and required7 imports. Use when building, restyling, or reviewing any UI component, or8 when choosing between a design-system, component-library, or custom9 component.10base: true11metadata:12 source: https://skillmd.com/skills/jiayaoqijia/ui-development-213---1415# MetaMask UI Development — MMDS Guidance1617Strategy context: [Agentic Design System Strategy](https://github.com/MetaMask/skills/blob/main/domains/ui/knowledge/agentic-design-system-strategy.md)1819The MetaMask Design System (MMDS) is the default for MetaMask product UI. This20base holds the rules shared by every client. The repository overlay below it21adds platform paths, the styling surface, and platform-only rules.2223## When to use2425Use this skill when you create, change, restyle, or review UI in a MetaMask26client: components, screens, sheets, modals, stories, styles, tokens, themes,27and UI behavior. Use it to decide between an MMDS component, a legacy28component-library component, a feature component, and custom UI.2930Copy and wording rules live in `content-guidelines`, and file layout and test31setup live in `component-scaffold`, where the repository has them.3233## Sources, in order3435Work from them in this order. None of these needs an MCP server. The Design36Brain step uses a Notion connector when one can reach the MetaMask workspace.37381. **Installed package types (`node_modules`).** The installed version is the39 contract for the code you are changing. Read the export index and the40 component's `.types` file (with its JSDoc) under41 `node_modules/@metamask/<platform package>/dist/`. Shared prop and enum42 types are declared in43 `node_modules/@metamask/design-system-shared/dist/types/`. Read them44 there, but import components and enums from the platform package. When45 the types disagree with anything else on this list, the types win.462. **Hosted Storybook components manifest**, for discovery and story47 snippets:48 - React (Extension): <https://metamask.github.io/metamask-design-system/manifests/components.json>49 - React Native (Mobile): <https://metamask.github.io/metamask-design-system/react-native/manifests/components.json>5051 The manifests are built from MMDS `main`, so they can list components or52 props that are newer than the version the consumer repo installs. Confirm53 anything you find there against the installed types before you use it.54 Story `import` snippets sometimes pull enums from55 `@metamask/design-system-shared`; in product code, import them from the56 platform package (`@metamask/design-system-react` or57 `@metamask/design-system-react-native`). How to read a manifest:58 [references/reading-mmds-manifests.md](references/reading-mmds-manifests.md).593. **Design Brain, when Notion is available.** Query60 [Design Brain — Lessons & Rules](https://www.notion.so/b71f86d67d68827395a001f7ee7a8a86)61 for the area you are changing. Apply Active rules (P0 must, P1 should).62 Treat Proposed rules as guidance only. Cite the rule you applied in the PR63 or review, and check the Brain for patterns too. Installed types still win64 on what exists in code. If you have no Notion access, write "Design Brain65 not checked" in the PR or review. Do not skip it silently.664. **Component README at the installed version's tag.** READMEs are not in the67 npm tarball. Read the installed version from68 `node_modules/@metamask/<package>/package.json` (or the lockfile), then open69 the README on GitHub at the per-package tag70 `@metamask/<package>@<version>`. The package `CHANGELOG.md` compare links71 use the same tag names. Never hard-code a release in code comments or72 skills.735. **Existing repository usage and stories.** Search the consumer repo for the74 component or token. Treat examples as usage evidence, not as the contract.756. **Figma MCP and Code Connect, when connected.** Use them to read the design76 and its component mapping. If they are not connected, carry on without them.7778## Workflow7980**Create:** read the installed types (and README when behavior is unclear)81for each building block, choose the component as below, style with preset82classes and tokens, then run the review checklist on your own diff.8384**Review:** list the changed UI, check each MMDS usage for deprecation (see85[Deprecated APIs](#deprecated-apis)), then report component choice, deprecated86usage, tokens, typography, and accessibility findings with file, line,87evidence, and a recommended fix. Say whether Design Brain was checked, or88write "Design Brain not checked".89Custom UI without a recorded reason is a finding, not an automatic failure.9091## Choosing a component9293- Before building anything, look up the component by name in the manifest94 and the installed exports. For a pattern, use the first place that has it:95 Storybook or the manifest docs, then the Design Brain when Notion is96 available, then the component README at the installed tag, then existing97 repository usage. Never invent a component, a prop, or a variant, and never98 port an API from the other platform or another UI library.99- Choose in this order, and record the reason whenever you go past step 1:100 1. An MMDS component exported by the installed platform package.101 2. A non-deprecated legacy component-library component, only when MMDS does102 not cover the need.103 3. An existing feature component that already solves it.104 4. Custom UI composed from MMDS primitives and tokens, with the reason105 recorded in the PR or the repository's exception format.106- Do not invent button or control chrome that MMDS does not have. Keep107 single-select (checkmark) and multi-select (checkbox) patterns distinct.108- If an MMDS layout makes a primary data point read as secondary, compose a109 stronger treatment instead of forcing the wrong primitive.110111## Deprecated APIs112113This rule applies to every client. Repository overlays and scaffolds defer to114it.115116- Do not add new usage of anything marked `@deprecated` (a component, prop,117 or enum value). Use the replacement its JSDoc or README names when the118 installed platform package exports it, even if the repository still uses119 the deprecated one. If no replacement is exported, keep existing usage and120 record the gap.121- To check, search the component's whole installed folder:122 `grep -rn @deprecated node_modules/@metamask/<platform package>/dist/components/<Name>/`.123 The tag is often on the component declaration (`<Name>.d.cts`), and the124 `.types` file can omit it. A non-empty manifest `jsDocTags.deprecated`, or125 `@deprecated` in the README at the installed tag, is the same signal. An126 empty `jsDocTags` is not evidence that it is current.127128## Foundations129130- Use preset Tailwind classes first for color, type, shadows, motion, spacing,131 and radius. Tailwind comes from the MMDS presets configured in the consumer132 repo. Use only class names those presets generate, including the 4px spacing133 scale (`p-4`, `gap-2`) and the default radii (`rounded-lg`, `rounded-xl`,134 `rounded-2xl`, `rounded-full`). Do not use default Tailwind colors.135- When Tailwind does not make sense or is not possible (a prop or style136 object, a third-party component, a chart, an animation, or a place that137 needs a CSS variable or theme value), use a semantic token from the138 installed `@metamask/design-tokens` package, in JS or CSS. No recorded139 reason is needed. The overlay says how this platform reads one. Read the140 package README at the installed tag141 `@metamask/design-tokens@<version>`.142- Never use a raw palette value, a hex value, or an arbitrary value143 (`bg-[#...]`, `p-[15px]`, `rounded-[16px]`, `text-[14px]`,144 `borderRadius: 16`).145- Meet WCAG AA contrast (normal text 4.5:1, large text and UI graphics 3:1)146 and check dark mode.147- Layouts must survive longer translated strings and future RTL without148 clipping or overlap. Avoid fixed-width text boxes.149150## Typography151152- Set type with the design-system text component. Use the font family and153 variant options the installed types expose, and follow the hosted manifest154 and the component README at the installed tag for when each applies. Never155 hand-set font sizes, line heights, or arbitrary text classes.156- Amount inputs have no settled typography pattern yet. Use the font family157 and variant options the installed types expose, and do not invent a158 dedicated amount style.159160## Incremental migration: `Legacy*` aliases161162When a file imports the same name from a legacy source and from the MMDS163platform package, alias the legacy import with a `Legacy` prefix and keep the164MMDS import on the plain name. Do the same for clashing enums. Leave legacy165imports that have no MMDS counterpart in the same file on their plain names166until that step migrates them. Do not alias legacy names that MMDS does not export, and never put the167prefix on the MMDS import. Finishing the migration is deleting the `Legacy*`168import and its usages. The overlay gives the platform's import paths and an169example.170171## Accessibility172173A short floor of plain WCAG basics. Design Brain rules are not copied here;174read them from the Design Brain source above.175176- Every input has a persistent label. A placeholder is not a label.177 Meaningful icons and icon-only buttons have an accessible name, and178 decorative icons are hidden.179- Never show state with color alone, and expose that state to assistive tech.180 Do not nest interactive controls.181- Announce async status and errors. Overlays and sheets manage focus and keep182 close or back available.183- Respect reduced motion, and meet WCAG AA contrast.184185## MMDS agent docs186187Read these in the MMDS repository instead of copying them into skills:188189- [`.cursor/rules/styling.md`](https://github.com/MetaMask/metamask-design-system/blob/main/.cursor/rules/styling.md)190- [`.cursor/rules/figma-integration.md`](https://github.com/MetaMask/metamask-design-system/blob/main/.cursor/rules/figma-integration.md)191- [`.cursor/rules/component-migration.md`](https://github.com/MetaMask/metamask-design-system/blob/main/.cursor/rules/component-migration.md)192193These track MMDS `main`. Where they disagree with the installed types, the194installed types win.195196## Review checklist197198- [ ] Installed types were read.199- [ ] Every MMDS building block was checked for deprecation, and the200 [Deprecated APIs](#deprecated-apis) rule holds.201- [ ] MMDS was used wherever it covers the need; any step past MMDS has a202 recorded reason.203- [ ] No invented components, props, or variants, and no cross-platform ports.204- [ ] Preset Tailwind classes first. Where Tailwind does not apply, a semantic205 token from the installed design-tokens package. No raw palette values,206 hex, or arbitrary values.207- [ ] Typography uses the design-system text component and the font family208 and variant options from the installed types.209- [ ] Clashing legacy imports are aliased `Legacy*`; MMDS keeps plain names.210- [ ] The accessibility floor above holds for the changed UI.211- [ ] Design Brain was checked for the area that changed, or the PR or review212 says "Design Brain not checked".