From 260dac1f7f0ef01416d291988e96ccf5909de6c1 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 5 Nov 2026 20:44:54 +0000 Subject: [PATCH 1/5] docs(ui): expand the shared ui-development base and make MMDS guidance MCP-free Co-authored-by: George Marshall --- CHANGELOG.md | 1 + .../agentic-design-system-strategy.md | 18 +- .../references/reading-mmds-manifests.md | 70 ++++++ domains/ui/skills/ui-development/skill.md | 199 ++++++++++++++++++ 4 files changed, 280 insertions(+), 8 deletions(-) create mode 100644 domains/ui/skills/ui-development/references/reading-mmds-manifests.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 6915cacb..da248184 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- Expand the shared `ui/ui-development` base so it works with no MCP server: a source order (installed package types win, then the hosted Storybook components manifests, the component README at the installed version's tag, repository usage, and Figma MCP with Code Connect when connected), component choice and deprecation rules, foundations, durable typography rules, the `Legacy*` alias rule for incremental migrations, and the Active accessibility, trust, and sheet rules from the Design Brain. Add `references/reading-mmds-manifests.md`, and update the agentic design system strategy so Storybook MCP is optional and skills carry no release-pinned inventories. - Update the `testing/visual-testing` skill for `@metamask/client-mcp-core` 0.13.1: remove the knowledge store commands and the mandatory knowledge-reuse step, and document the global `--observe` and `--pretty` flags, one-line JSON output, observations without app state, `run-steps` `observe` (replaces `includeObservations`), timed-out calls being cancelled, and one element per ref. Replace the removed `yarn build:test:webpack` script with `yarn build:test`. - Update the MetaMask Mobile performance overlay and animation references for React Native 0.86.x, Expo SDK 57, and Reanimated 4.x with `react-native-worklets`. From a worklet, call `scheduleOnRN` (`runOnJS` is a deprecated alias). Static-ESM tree-shaking stays off. ([#203](https://github.com/MetaMask/skills/pull/203)) - Require every revert yes/no to be one line that names the pull request or commit, the files, and exactly one yes/no question, whether or not security or privacy is involved. A shorter message is not that step. diff --git a/domains/ui/knowledge/agentic-design-system-strategy.md b/domains/ui/knowledge/agentic-design-system-strategy.md index 50d6dd6f..7113569b 100644 --- a/domains/ui/knowledge/agentic-design-system-strategy.md +++ b/domains/ui/knowledge/agentic-design-system-strategy.md @@ -29,7 +29,7 @@ One knowledge layer, three deliveries. MMDS holds tokens, components, and patter | Moment | What happens | | :---- | :---- | -| **Create** | Agents read current MMDS guidance before building — through skills, Storybook MCP, Figma MCP, and Code Connect. | +| **Create** | Agents read current MMDS guidance before building — through skills, installed package types, the hosted Storybook components manifests, and Figma MCP with Code Connect when connected. | | **Review** | Deterministic checks (ESLint, fitness functions) plus agentic review for judgment calls. | | **Audit** | Recurring queries across existing screens to find drift, custom UI, and documentation gaps. | @@ -37,13 +37,14 @@ One knowledge layer, three deliveries. MMDS holds tokens, components, and patter - **Consumer skills** (`ui-development` repo overlays) route agents to current MMDS guidance for product UI create and review workflows. - **Provider skills** (future `design-system` domain) support MMDS authoring, release, and documentation maintenance. -- **Storybook MCP** (`storybook-broker-mcp`) is the preferred delivery mechanism for current MMDS knowledge in coding agents. Package exports and consumer Tailwind configuration are the ordered fallback when the broker is unavailable. +- **Baseline delivery** needs no MCP server: the installed package types in the consumer repo, the hosted Storybook components manifests ([React](https://metamask.github.io/metamask-design-system/manifests/components.json), [React Native](https://metamask.github.io/metamask-design-system/react-native/manifests/components.json)), and the consumer Tailwind configuration. Installed types win when sources disagree, because the manifests track MMDS `main`. +- **Storybook MCP** (`storybook-broker-mcp`, via Context Forge) is optional. Agents may use it when it is already configured and responds, but skills must never depend on it. ## Foundation workstreams 1. **Thin consumer gateway skills** — Refine `ui-development` overlays into stable routers (Create + Review) instead of static component inventories. -2. **Storybook MCP integration** — Treat Context Forge's preconfigured `storybook-broker-mcp` as the primary source; document explicit fallback behavior without embedding setup instructions in skills. -3. **MMDS source and broker readiness** — Keep Storybook documentation, exports, and broker surfaces current for agent consumption. +2. **No-MCP baseline** — Keep the installed types, hosted components manifests, and consumer Tailwind configuration sufficient on their own. Storybook MCP is an optional extra, never a prerequisite, and skills carry no setup instructions for it. +3. **MMDS source readiness** — Keep type JSDoc (including `@deprecated`), READMEs, stories, and the published components manifests current for agent consumption. 4. **Automated alignment checks** — Extend CI and review workflows to validate tokens, components, and patterns where feasible. 5. **Provider-side skills** — Add a `design-system` domain and `metamask-design-system` maintainer overlay in the skills repo. @@ -51,7 +52,7 @@ One knowledge layer, three deliveries. MMDS holds tokens, components, and patter | Horizon | Focus | | :---- | :---- | -| **Now** | Build the shared knowledge path and establish quality baselines — point MetaMask Skills to Storybook MCP, begin Figma/React/React Native alignment, expand Code Connect, audit MMDS and product usage. | +| **Now** | Build the shared knowledge path and establish quality baselines — point MetaMask Skills at installed types and the hosted components manifests, begin Figma/React/React Native alignment, expand Code Connect, audit MMDS and product usage. | | **Next** | Operationalize Create, Review, and Audit in normal delivery — enable the gateway by default in Extension and Mobile, run MMDS-focused review, load relevant skills per UI PR, run recurring audits. | | **Later** | Build a trusted feedback and remediation loop — agents create issues or PRs for alignment gaps, automate low-risk fixes, retain human approval for judgment calls. | @@ -59,6 +60,7 @@ One knowledge layer, three deliveries. MMDS holds tokens, components, and patter - MMDS is the default; intentional documented custom UI is allowed. - Skills are gateways and durable constraints, not second copies of MMDS documentation. -- Do not maintain static component inventories, deprecated-name lists, or MCP setup instructions in consumer skills. -- Query current Storybook guidance before choosing components, APIs, tokens, or patterns. -- When Storybook MCP is unavailable, follow the ordered fallback defined in the relevant repo overlay. +- Skills must work with no MCP server connected. +- Do not put release-pinned inventories, version pins, prop lists, or MCP setup instructions in skills. Point at the installed package and the hosted manifests instead. +- Read the installed types before choosing components, APIs, tokens, or patterns. When anything disagrees with them, the installed types win. +- Inline only durable rules that agents need and cannot read elsewhere (for example Active Design Brain rules). Link to Proposed rules; do not enforce them. diff --git a/domains/ui/skills/ui-development/references/reading-mmds-manifests.md b/domains/ui/skills/ui-development/references/reading-mmds-manifests.md new file mode 100644 index 00000000..1f8742e0 --- /dev/null +++ b/domains/ui/skills/ui-development/references/reading-mmds-manifests.md @@ -0,0 +1,70 @@ +# Reading the MMDS components manifests + +MMDS publishes a Storybook components manifest for each platform: + +| Platform | Manifest | +| --- | --- | +| React (Extension) | | +| React Native (Mobile) | | + +This file explains the format. It deliberately lists no components, versions, +or props: read those from the manifest and the installed package. + +## What the manifest is + +- It is generated from the Storybook build of MMDS `main`. It can be ahead of + the version a consumer repo installs, so a component or prop in the manifest + may not exist in `node_modules` yet. The installed types decide. +- It is large (around 1 MB). Fetch it once and search it, for example with + `curl -s | jq` or a script, rather than reading it whole. +- It is a discovery and deprecation index, not the API contract. + +## Shape + +```text +{ + "v": , + "components": { + "": { + "id": "", + "name": "", + "path": "", + "import": "", + "jsDocTags": { "deprecated": [""] }, + "reactDocgen": { "description": "...", "props": { "": { "required": ..., "tsType": ..., "description": "..." } } }, + "stories": [ { "id": "...", "name": "...", "snippet": "" } ], + "description": "", + "error": "" + } + }, + "meta": { ... } +} +``` + +Entries are keyed by Storybook story id, not by component name. Some entries +are design-token or foundation pages rather than components. Match on `name`. + +## Common queries + +- **Is there a component for X?** Search `name` and `reactDocgen.description`, then confirm + the name is exported by the installed package index. +- **Is it deprecated?** A non-empty `jsDocTags.deprecated` means deprecated; + the message names the replacement. Also check for `@deprecated` in the + installed `.types` file, because the installed version may differ. +- **Which props does it take?** `reactDocgen.props` gives names, types, + `required`, and descriptions for `main`. Confirm each prop in the installed + types before using it. +- **How is it used?** `stories[].snippet` shows example JSX. + +## Caveats + +- `import` lines come from MMDS story files. They may import enums from + `@metamask/design-system-shared` or use relative paths. In product code, + import components and enums from the platform package + (`@metamask/design-system-react` or `@metamask/design-system-react-native`). +- `jsDocTags` is `{}` when a component has no tags. An entry without a + `deprecated` key is not deprecated in `main`; the installed version can + still differ. +- An entry with `error` and no `reactDocgen` has no prop data. Read the + installed types instead. +- Do not copy manifest content into a skill. It changes with every MMDS merge. diff --git a/domains/ui/skills/ui-development/skill.md b/domains/ui/skills/ui-development/skill.md index 6b89a949..faa73595 100644 --- a/domains/ui/skills/ui-development/skill.md +++ b/domains/ui/skills/ui-development/skill.md @@ -10,4 +10,203 @@ description: >- base: true --- +# MetaMask UI Development — MMDS Guidance + Strategy context: [Agentic Design System Strategy](../../knowledge/agentic-design-system-strategy.md) + +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`. File layout and test +setup live in `component-scaffold` where the repository has it. + +## Sources, in order + +None of these needs an MCP server. Work from them in this order: + +1. **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//dist/`. Shared props and enums + come from `node_modules/@metamask/design-system-shared/dist/types/`. When the + types disagree with anything else on this list, the types win. +2. **Hosted Storybook components manifest**, for discovery, deprecation tags, + and story snippets: + - React (Extension): + - React Native (Mobile): + + 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 components and + enums from the platform package (`@metamask/design-system-react` or + `@metamask/design-system-react-native`). How to read a manifest: + [references/reading-mmds-manifests.md](references/reading-mmds-manifests.md). +3. **Component README at the installed version's tag.** READMEs are not in the + npm tarball. Read the installed version from + `node_modules/@metamask//package.json` (or the lockfile), then open + the README on GitHub at the per-package tag + `@metamask/@`. The package `CHANGELOG.md` compare links + use the same tag names. Never hard-code a release in code comments or + skills. +4. **Existing repository usage and stories.** Search the consumer repo for the + component or token. Treat examples as usage evidence, not as the contract. +5. **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. + +Storybook MCP or Context Forge may add pattern docs when one is already +configured and responds. It is optional: never block on it, do not install, +configure, or authenticate it, and do not mention its absence unless a +question can only be answered there. + +## 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 against the installed +types, then report component choice, deprecated usage, tokens, typography, +and accessibility findings with file, line, evidence, and a recommended fix. +Custom UI without a recorded reason is a finding, not an automatic failure. + +## Choosing a component + +- Before building anything, check the manifest and the installed exports for + an existing component. 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: + 1. An MMDS component exported by the installed platform package. + 2. A non-deprecated legacy component-library component, only when MMDS does + not cover the need. + 3. An existing feature component that already solves it. + 4. Custom UI composed from MMDS primitives and tokens, with the reason + recorded in the PR or the repository's exception format. +- A component, prop, or enum value is deprecated when its installed type + carries `@deprecated` or its manifest entry has `jsDocTags.deprecated`. Do + not add new usage. Use the replacement the JSDoc names; if none is named, + keep existing usage and record the gap. +- 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. + +## Foundations + +- Color, typography, shadows, and motion come from MMDS design tokens. Use + semantic tokens (`background-*`, `text-*`, `border-*`, `icon-*`, status + tokens), never hex values or raw palette names. +- Tailwind comes from the MMDS presets configured in the consumer repo. Use + only class names those presets generate. Do not use default Tailwind colors + or arbitrary values (`bg-[#...]`, `p-[15px]`, `rounded-[16px]`, + `text-[14px]`). +- Spacing and radius use the Tailwind scale through the presets: the 4px + spacing scale (`p-4`, `gap-2`) and the default radii (`rounded-lg`, + `rounded-xl`, `rounded-2xl`, `rounded-full`). MMDS has no separate spacing + or radius tokens. Never hard-code numbers such as `borderRadius: 16`. +- Meet WCAG AA contrast with semantic tokens (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 + +- `FontFamily.Default` is the default for all UI text. +- Set type with `Text` and a `TextVariant`. Never hand-set font sizes, line + heights, or arbitrary text classes. +- Use `FontFamily.Hero` only for approved hero cases: the single primary + display amount of a view and marketing-moment headlines through the + platform's `MarketingMomentTitle`. Never pair Hero with a font weight, and + never use it for body text, labels, buttons, titles, or small numbers. +- Do not use `FontFamily.Accent`; it has been removed from MMDS. +- Amount inputs are not settled. See the Proposed Typography rule in the + [Design Brain](https://www.notion.so/b71f86d67d68827395a001f7ee7a8a86) and the + [MMDS reference](https://www.notion.so/40ef86d67d68811c9b31cf9992a076cd) + before choosing a face for one. + +## Incremental migration: `Legacy*` aliases + +When a file still imports a legacy component-library export whose name is also +exported by 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. 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, trust, and sheets + +These are Active rules from the Design Brain, inlined because agents in code +repositories cannot read Notion. Proposed rules are guidance only: link to +them, do not enforce them. + +- Every text field has a persistent accessible label tied to the input. A + placeholder alone is not a label. +- Meaningful icons have an accessible name. Decorative icons next to visible + text are hidden from assistive tech, so the control is not read twice. +- Icon-only buttons need an accessible name and a real action. Do not ship an + info button whose press does nothing. +- Keep the visible text in a control's accessible name (WCAG 2.5.3). Put extra + context in a hint instead of replacing visible words. +- When visible text is abbreviated, put the full term in the accessible name. +- Do not show selected, active, or unread state through color alone. Add a + non-color cue and expose the state (selected, checked, expanded) to + assistive tech. Tabs expose the tab role and the selected state. +- Do not nest interactive controls inside another link or button. Make one + primary target, or split the actions. +- Announce async errors and status changes (save, load, retry, failures) to + screen readers. The overlay gives the platform mechanism. +- Autocomplete and suggestion lists use combobox/listbox semantics and stay + reachable by keyboard. +- Full-screen overlays on top of another flow use the MMDS modal or dialog + pattern: an accessible name, dialog semantics, and focus moved into the + overlay until it is confirmed or cancelled. +- Sheets and modals must not trap keyboard or assistive-tech focus, keep + close or back available, and follow visual reading order. +- Respect reduced motion. Never rely on animation alone to show state. +- Protect trust in wallet UI: use semantic color only for real meaning; + reconcile displayed totals and units exactly; keep sensitive details off + overviews; give irreversible send, approve, and connect actions a clear + preview (asset, amount, network, recipient or permission) with proportionate + confirmation; keep back, cancel, and recovery available; never imply + certainty the system does not have. Keep available, pending, claimed, paid, + estimated, and lifetime values distinct. Never expose the Secret Recovery + Phrase or other secrets in labels. + +Full rule set, including Proposed rules: +[Design Brain — Lessons & Rules](https://www.notion.so/b71f86d67d68827395a001f7ee7a8a86). + +## MMDS agent docs + +Read these in the MMDS repository instead of copying them into skills: + +- [`AGENTS.md`](https://github.com/MetaMask/metamask-design-system/blob/main/AGENTS.md) +- [`docs/ai-agents.md`](https://github.com/MetaMask/metamask-design-system/blob/main/docs/ai-agents.md) +- [`.cursor/rules/styling.md`](https://github.com/MetaMask/metamask-design-system/blob/main/.cursor/rules/styling.md) +- [`.cursor/rules/figma-integration.md`](https://github.com/MetaMask/metamask-design-system/blob/main/.cursor/rules/figma-integration.md) +- [`.cursor/rules/component-migration.md`](https://github.com/MetaMask/metamask-design-system/blob/main/.cursor/rules/component-migration.md) + +These track MMDS `main`. Where they disagree with the installed types, the +installed types win. + +## Review checklist + +- [ ] Installed types were read for every MMDS building block; the manifest + and README were used only as supporting sources. +- [ ] MMDS was used wherever it covers the need; any step past MMDS has a + recorded reason. +- [ ] No invented components, props, or variants, and no cross-platform ports. +- [ ] No new usage of anything tagged `@deprecated`. +- [ ] Only preset-generated classes and semantic tokens; no arbitrary values. +- [ ] Typography uses `Text` + `TextVariant`; Hero only for approved cases. +- [ ] Clashing legacy imports are aliased `Legacy*`; MMDS keeps plain names. +- [ ] The accessibility and trust rules above hold for the changed UI. From 9c57432aa38c67810e6ca6e64f88ca849073a310 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 5 Nov 2026 20:47:16 +0000 Subject: [PATCH 2/5] docs(ui): reduce the Extension ui-development overlay to durable platform rules Co-authored-by: George Marshall --- CHANGELOG.md | 1 + .../repos/metamask-extension.md | 235 +++++++----------- 2 files changed, 84 insertions(+), 152 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index da248184..d749ef9a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Expand the shared `ui/ui-development` base so it works with no MCP server: a source order (installed package types win, then the hosted Storybook components manifests, the component README at the installed version's tag, repository usage, and Figma MCP with Code Connect when connected), component choice and deprecation rules, foundations, durable typography rules, the `Legacy*` alias rule for incremental migrations, and the Active accessibility, trust, and sheet rules from the Design Brain. Add `references/reading-mmds-manifests.md`, and update the agentic design system strategy so Storybook MCP is optional and skills carry no release-pinned inventories. - Update the `testing/visual-testing` skill for `@metamask/client-mcp-core` 0.13.1: remove the knowledge store commands and the mandatory knowledge-reuse step, and document the global `--observe` and `--pretty` flags, one-line JSON output, observations without app state, `run-steps` `observe` (replaces `includeObservations`), timed-out calls being cancelled, and one element per ref. Replace the removed `yarn build:test:webpack` script with `yarn build:test`. +- Reduce the MetaMask Extension `ui/ui-development` overlay to durable platform rules: package paths and the React components manifest for inventory, the Tailwind preset styling surface with no SCSS, web accessibility mechanics, and the `Legacy*` alias paths for `ui/components/component-library`. Remove the required Storybook MCP workflow; Storybook MCP is now optional and never blocks. - Update the MetaMask Mobile performance overlay and animation references for React Native 0.86.x, Expo SDK 57, and Reanimated 4.x with `react-native-worklets`. From a worklet, call `scheduleOnRN` (`runOnJS` is a deprecated alias). Static-ESM tree-shaking stays off. ([#203](https://github.com/MetaMask/skills/pull/203)) - Require every revert yes/no to be one line that names the pull request or commit, the files, and exactly one yes/no question, whether or not security or privacy is involved. A shorter message is not that step. - Keep a new public method or other contract change on the brief and spec path when the objection is that another package should own the edit. Put that objection in the brief. diff --git a/domains/ui/skills/ui-development/repos/metamask-extension.md b/domains/ui/skills/ui-development/repos/metamask-extension.md index 120f26dc..94c88211 100644 --- a/domains/ui/skills/ui-development/repos/metamask-extension.md +++ b/domains/ui/skills/ui-development/repos/metamask-extension.md @@ -3,157 +3,88 @@ repo: metamask-extension parent: ui-development --- -# MetaMask Extension Product UI — MMDS Guidance +# MetaMask Extension overlay + +Platform rules for React web UI in `metamask-extension`. The base above covers +sources, component choice, foundations, typography, migration, and the shared +accessibility rules. Strategy: [Agentic Design System Strategy](../../../knowledge/agentic-design-system-strategy.md) -([Google Doc](https://docs.google.com/document/d/1wwvEJxom097q-ehSJAfqKvWb01ZW-kmlpy7BQW5In40/edit)) - -For Extension UI, the MetaMask Design System (MMDS) is the default source for -components, tokens, and documented patterns. Align new and changed UI with MMDS -wherever it supports the need, using current Storybook documentation as the -source of truth. Custom UI remains valid when it serves an intentional product -need that MMDS does not cover, but the rationale should be recorded. - -This is a consumer gateway, not a second MMDS knowledge base. Do not add static -component inventories, release-specific API lists, or copied component -documentation here. Storybook MCP and the installed package provide current -knowledge; this skill provides the Extension workflow and durable constraints. - -## When to Use - -Use this guidance when creating, changing, or reviewing Extension UI, including -components, screens, stories, styles, tokens, themes, and UI behavior. - -This skill owns MMDS alignment for product UI. Generic TypeScript and React -quality, component file scaffolding, and PR process remain separate concerns and -may be used alongside it. If a repository-specific scaffolding skill is -available, use it for file and test setup; do not duplicate its templates here. - -## Create Workflow - -1. Query current MMDS guidance before choosing a component, pattern, API, token, - or interaction. -2. Use `@metamask/design-system-react` when it supports the need. -3. Search the Extension codebase and reuse suitable existing UI, including UI - that is not yet in MMDS or is intentionally feature-specific. -4. Use Tailwind classes and the repository's design-token configuration for - styling and layout not provided by MMDS. -5. Build new feature UI only when no suitable MMDS or existing Extension UI can - be reused. -6. If no suitable component or documented pattern exists, record the - documentation or system gap and make the custom decision explicit. Do not - guess an API or silently substitute another platform's component. - -## Review Workflow - -When reviewing a UI diff, perform an MMDS-specific sub-review. Do not duplicate -general code-review etiquette or decide PR status; report the design-system -evidence and leave PR mechanics to the relevant workflow. - -1. Identify changed UI files, components, stories, styles, tokens, themes, and - renderable behavior. -2. Query current Storybook guidance for each changed MMDS building block and - relevant pattern, using the Extension React/web documentation first. -3. Check that the implementation uses documented or story-proven props, - variants, tokens, composition, and behavior. -4. Check component and pattern choice, existing-UI reuse, styling/token usage, - accessibility, localization, keyboard behavior, and platform fit. -5. Check for new use of APIs or components marked `@deprecated` in current - package metadata or documentation. Do not maintain a deprecated-name list in - this skill; read the current replacement guidance and report a finding when - no replacement is documented. -6. Identify custom UI and overrides. Treat them as findings when their product - rationale or exception record is missing, not as automatic failures. -7. Separate deterministic issues from judgment findings, and report each finding - with its file/line, evidence, current source, and recommended action. - -Component or pattern choice, custom UI, and missing documentation are -design-system findings that generally need human judgment. Deterministic -repository checks may enforce token or deprecated-usage rules separately. - -## Required Storybook MCP Workflow - -Before creating, changing, or reviewing UI: - -1. Start by querying `storybook-broker-mcp` with `list-all-documentation` so the - available guidance reflects the current MMDS release. -2. Find the relevant Extension pattern documentation in the React/web Storybook. -3. Query `get-documentation` for the selected pattern and each UI building block. -4. Query `get-documentation-for-story` when documentation does not answer the - question or a story is needed to establish real usage. -5. Use only props, variants, tokens, composition, and behavior explicitly - documented or demonstrated by a story. - -The Context Forge-provided `storybook-broker-mcp` is expected to be -preconfigured by the agent environment. Do not install, configure, authenticate, -or invent an endpoint for it from this skill. If the server or a required tool -is unavailable, or a call fails, state that the broker could not be reached and -use the fallback below. - -Never infer an API from a name, a previous implementation, another platform, or -another UI library. If the required guidance is absent, record the gap and use -the fallback process below rather than guessing. - -Do not apply guidance from another platform without an Extension mapping -documented in Storybook. If no mapping exists, treat it as a documentation gap. - -## Fallback When Storybook MCP Is Unavailable - -Use these sources in order: - -1. The installed `@metamask/design-system-react` package and its type - definitions under `node_modules`. -2. The installed Extension-facing MMDS styling surfaces: - `@metamask/design-system-tailwind-preset` for Tailwind CSS v3, or the - `@metamask/design-tokens/tailwind/theme.css` export for Tailwind CSS v4. - Use `@metamask/design-tokens` for the installed token exports and styles. -3. The Extension's current Tailwind configuration and package configuration. - Check the installed Tailwind version, preset or theme import, content - globs, plugins, and safelist. Use only class names generated by that - configuration and the installed MMDS preset or theme. If availability is - unclear, verify the generated CSS or build output instead of inventing a - class. Do not use default Tailwind colors, arbitrary values, or a manual - safelist as a substitute for an MMDS token. -4. Current Extension usage and stories found by searching the repository for - the installed component or token. Treat examples as usage evidence, not as - a replacement for the installed package contract. -5. A generated MMDS release manifest or repository-provided release guidance. -6. The MMDS source repository as a last resort. - -`@metamask/design-system-shared` may be relevant to Tailwind content scanning -when required by the installed MMDS configuration, but it is not a source for -Extension component APIs. Do not use React Native or TWRNC packages for -Extension UI. - -The installed package version is the source of truth for the code being -changed. Read the matching exports and type definitions before writing or -reviewing usage. Do not restore a static inventory or copy undocumented APIs -into this skill to compensate for missing MCP. - -## Durable Extension Constraints - -- Prefer `@metamask/design-system-react` components. -- Reuse suitable existing Extension UI before creating new feature UI. -- Use Tailwind class names instead of SCSS for styling and layout. -- Do not create or modify SASS or SCSS files. -- Reuse an existing feature-level solution when the documented pattern calls - for one; otherwise compose the smallest supported solution. -- Preserve accessibility, localization, and keyboard interaction requirements - shown in the relevant Storybook documentation and stories. -- Use repository-approved exception documentation when custom UI is necessary; - do not invent a new annotation format in this skill. - -## Create and Review Checklist - -- [ ] Current Storybook pattern and building-block guidance was queried, or the - MCP fallback, Tailwind configuration checks, and any documentation gap - were recorded. -- [ ] MMDS was used wherever it supports the need, and suitable existing - Extension UI was considered. -- [ ] Only documented, story-proven, or installed-package-typed APIs are used. -- [ ] No new deprecated API or component usage was introduced. -- [ ] No undocumented platform substitution was made. -- [ ] Custom UI has an intentional product rationale and exception record when - required by repository practice. -- [ ] Accessibility, localization, and keyboard behavior were preserved. -- [ ] No SASS or SCSS files were created or modified. + +## Packages and paths + +- Components and enums: `@metamask/design-system-react`. Do not import enums + from `@metamask/design-system-shared`; that package is listed in the Tailwind + `content` globs only so its classes are generated. +- Inventory and deprecations: the + [React components manifest](https://metamask.github.io/metamask-design-system/manifests/components.json), + confirmed against `node_modules/@metamask/design-system-react/dist/components/index.d.cts`. +- README: `packages/design-system-react/src/components//README.mdx` + at the tag `@metamask/design-system-react@`. +- Legacy component library: `ui/components/component-library` (being + deprecated in favor of MMDS). Do not add new usage where MMDS covers the need. +- Existing feature UI that is intentionally outside MMDS lives under + `ui/components/` (for example `ui/components/ui/marketing-moment`). Reuse it + before building new feature UI. + +Do not apply React Native guidance or APIs (`twClassName`, twrnc, +`accessibilityRole`, `BottomSheet`) to Extension. + +## Styling surface + +- `tailwind.config.js` uses `@metamask/design-system-tailwind-preset` + (Tailwind CSS v3) and removes the default palette and font sizes. Use only + classes that configuration generates. If a class is in doubt, check the + preset source or the built CSS; do not invent one or add a safelist entry. +- Use Tailwind class names (`className`) for styling and layout. Do not create + or modify SASS or SCSS files. +- Set type with `Text` variants. Font-size utilities do not exist in this + config, so `text-[14px]` and similar are always wrong. + +## Extension accessibility mechanics + +- Icon-only controls need an accessible name: `ButtonIcon` takes `ariaLabel`. + Search fields need an input label; check the installed `TextFieldSearch` + types for the prop name. +- Announce async errors and status with `role="alert"` or + `aria-live="polite"` on a container that is already mounted before its text + changes. +- Expandable controls expose `aria-expanded`; toggles and tabs expose their + selected or pressed state. +- Preserve the keyboard behavior documented in the component README and + stories, including focus order and how popovers and modals close. + +## Incremental migration paths + +The legacy barrel is `ui/components/component-library` (`Box`, `Text`, +`Button`, `Icon`, and the rest). Apply the base `Legacy*` rule to any export +from that barrel whose name MMDS also exports, including enums such as +`IconName`. Adjust the `../` depth to the file. + +```tsx +// Do: MMDS keeps the plain names. Legacy gets the prefix. +import { Box, Text } from '@metamask/design-system-react'; +import { Box as LegacyBox, Text as LegacyText } from '../../component-library'; + +// Don't: prefix the MMDS import, or leave both on the plain name. +import { Box as LegacyBox, Text as LegacyText } from '@metamask/design-system-react'; +import { Box, Text } from '../../component-library'; +``` + +Prop mapping from legacy to MMDS components: +[React `MIGRATION.md`](https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react/MIGRATION.md). + +## Exceptions + +When custom UI is necessary, use the repository's existing exception +documentation. Do not invent a new annotation format. + +## Extension checklist + +- [ ] Only classes generated by the Extension Tailwind config; no default + palette, arbitrary values, or safelist workarounds. +- [ ] No SASS or SCSS files created or modified. +- [ ] No new usage of `ui/components/component-library` where MMDS covers the + need; clashing legacy imports are aliased `Legacy*`. +- [ ] Icon-only controls and search fields have accessible names; status + changes are announced; keyboard behavior still works. From 1ae0f980190b9a552b5711a1cd4e40ebd2e84ae3 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 5 Nov 2026 22:46:06 +0000 Subject: [PATCH 3/5] docs(ui): apply eval fixes to the shared ui-development base Deprecation replacements must be exported on the installed platform, Legacy* aliases trigger only on same-file clashes, cross-skill pointers are qualified, the Strategy link survives install, and the manifest reference explains non-component entries. Co-authored-by: George Marshall --- .../references/reading-mmds-manifests.md | 15 ++++++++++++-- domains/ui/skills/ui-development/skill.md | 20 ++++++++++--------- 2 files changed, 24 insertions(+), 11 deletions(-) diff --git a/domains/ui/skills/ui-development/references/reading-mmds-manifests.md b/domains/ui/skills/ui-development/references/reading-mmds-manifests.md index 1f8742e0..29a7eb00 100644 --- a/domains/ui/skills/ui-development/references/reading-mmds-manifests.md +++ b/domains/ui/skills/ui-development/references/reading-mmds-manifests.md @@ -41,8 +41,19 @@ or props: read those from the manifest and the installed package. } ``` -Entries are keyed by Storybook story id, not by component name. Some entries -are design-token or foundation pages rather than components. Match on `name`. +Entries are keyed by Storybook story id, not by component name, and not every +entry is a component: + +- Design-token and foundation pages (ids starting `design-tokens-` or `docs-`, + with story paths in `packages/design-tokens`). +- Pattern stories (ids starting `patterns-`). These are composition examples. + Their `name` can look like a component (for example `MarketingMoment`) or + be a code fragment (`() => null`), and nothing with that name is exported. +- Story wrappers whose `name` is a cast expression rather than an identifier. + +Treat an entry as a component only when its `path` is a story under the +platform package's `src/components/` (including `temp-components/`) and the +component name appears in the installed export index. ## Common queries diff --git a/domains/ui/skills/ui-development/skill.md b/domains/ui/skills/ui-development/skill.md index faa73595..bc9986f5 100644 --- a/domains/ui/skills/ui-development/skill.md +++ b/domains/ui/skills/ui-development/skill.md @@ -12,7 +12,7 @@ base: true # MetaMask UI Development — MMDS Guidance -Strategy context: [Agentic Design System Strategy](../../knowledge/agentic-design-system-strategy.md) +Strategy context: [Agentic Design System Strategy](https://github.com/MetaMask/skills/blob/main/domains/ui/knowledge/agentic-design-system-strategy.md) 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 @@ -25,8 +25,8 @@ 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`. File layout and test -setup live in `component-scaffold` where the repository has it. +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 @@ -93,8 +93,9 @@ Custom UI without a recorded reason is a finding, not an automatic failure. recorded in the PR or the repository's exception format. - A component, prop, or enum value is deprecated when its installed type carries `@deprecated` or its manifest entry has `jsDocTags.deprecated`. Do - not add new usage. Use the replacement the JSDoc names; if none is named, - keep existing usage and record the gap. + not add new usage. Use the replacement the JSDoc names if the installed + platform package exports it. If no replacement is named, or the named one is + not exported on this platform, keep existing usage and record the gap. - 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 @@ -135,10 +136,11 @@ Custom UI without a recorded reason is a finding, not an automatic failure. ## Incremental migration: `Legacy*` aliases -When a file still imports a legacy component-library export whose name is also -exported by 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. Do not alias legacy names that MMDS does not export, and never put the +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. From a46f6913e8db2a01421ee2f338037592785b10cb Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 5 Nov 2026 22:46:36 +0000 Subject: [PATCH 4/5] docs(ui): apply eval fixes to the Extension ui-development overlay Name ui/helpers/constants/design-system as the source of clashing legacy enums, allow deleting SCSS a change makes unused, prefer Box typed props for layout, require native buttons or links for clickable UI, and drop the duplicate Strategy link. Co-authored-by: George Marshall --- .../repos/metamask-extension.md | 36 ++++++++++++++----- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/domains/ui/skills/ui-development/repos/metamask-extension.md b/domains/ui/skills/ui-development/repos/metamask-extension.md index 94c88211..d69abe3f 100644 --- a/domains/ui/skills/ui-development/repos/metamask-extension.md +++ b/domains/ui/skills/ui-development/repos/metamask-extension.md @@ -9,8 +9,6 @@ Platform rules for React web UI in `metamask-extension`. The base above covers sources, component choice, foundations, typography, migration, and the shared accessibility rules. -Strategy: [Agentic Design System Strategy](../../../knowledge/agentic-design-system-strategy.md) - ## Packages and paths - Components and enums: `@metamask/design-system-react`. Do not import enums @@ -36,8 +34,11 @@ Do not apply React Native guidance or APIs (`twClassName`, twrnc, (Tailwind CSS v3) and removes the default palette and font sizes. Use only classes that configuration generates. If a class is in doubt, check the preset source or the built CSS; do not invent one or add a safelist entry. -- Use Tailwind class names (`className`) for styling and layout. Do not create - or modify SASS or SCSS files. +- Prefer MMDS `Box` typed props (`flexDirection`, `alignItems`, `gap`, + `padding*`, `margin*`) for layout, and Tailwind class names (`className`) for + everything else. +- Do not add SASS or SCSS. Deleting SCSS rules, files, and `@import` lines + that your change makes unused is expected. - Set type with `Text` variants. Font-size utilities do not exist in this config, so `text-[14px]` and similar are always wrong. @@ -51,6 +52,10 @@ Do not apply React Native guidance or APIs (`twClassName`, twrnc, changes. - Expandable controls expose `aria-expanded`; toggles and tabs expose their selected or pressed state. +- Follow accessible web practices for anything clickable: a native + `