Repository navigation
docs(ui): reshape ui-development for Extension — shared MCP-free base, thin overlay, no Storybook MCP requirement - #213
Conversation
…e MCP-free Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
…form rules Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
7306caf to
9c57432
Compare
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 <georgewrmarshall@users.noreply.github.com>
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 <georgewrmarshall@users.noreply.github.com>
… and #213 Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
Skill reshape changes are not release-note material for this PR. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
Context Forge has no timeline to return, so skills no longer mention Storybook MCP or the broker. The no-MCP baseline and Figma MCP stay. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
Manifest and pattern examples no longer name MarketingMoment or other components. Agents look a component up by name and search the manifest for an existing pattern before building custom UI. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
MMDS no longer has an Accent face, and skills should not pin font-family or legacy enum members. Agents read the installed exports, the hosted manifest, and the README at the installed tag. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
…n overlays (#221) <!-- CURSOR_AGENT_PR_BODY_BEGIN --> ## Description Edits the existing `content-guidelines` skill in place at `domains/ui/skills/content-guidelines/`. Shared rules live in `skill.md`. The mobile overlay is updated. A new extension overlay is at `repos/metamask-extension.md`. The skill is the agent-readable implementation of approved MetaMask content guidance, for agents to use day to day. It follows the [MetaMask Content Design Style Guide](https://app.notion.com/p/43cbae51680544b28d5287683089cc9b) and Design Brain. If those sources disagree with this file, flag it to the content owner. Do not invent a rule. No app strings were migrated. ### Key decisions - Wallet vs account - Network fee instead of gas in default flows - Spending cap - Button verbs: Continue, Confirm, Approve, with Cancel as the default decline - Secret Recovery Phrase spelled out. Private Key is title case - Error pattern: what happened, then what to do - Voice: no "please" or "successfully". No "sorry" or "unfortunately" in a routine error. Exclamation points only for a really exciting moment, never in an error or an alert - No "(s)" plurals or `\n` in strings - Time: local time, "ET" as the fallback, written times like `6:30 am` - "NFT" only when the thing is an NFT. The Collectibles feature keeps its name - "Paid by MetaMask" only when MetaMask covers a fee the user would otherwise pay (a sponsored network fee). Never for a $0 or waived MetaMask fee. No chain names in the example - Empty states: first-time empty states have character and a next step. Search and filter results stay plain. No puns or emoji - Bulleted lists are allowed, one item per string. The bullet character (•) can also separate data ### Aligned with the Style Guide No Style Guide overrides: - Em dash (`—`) with no spaces may offset an aside - Written times use a space and lowercase `am` / `pm` (`6:30 am`) - No loading ellipsis. Loading is animation, or a present participle with no `...` or `…`. An ellipsis is only for a shortened address - Question marks are avoided. Not on buttons. A statement is used when the outcome is known - Exclamation points, emoji, colons, and bullets follow the guide: exciting moments only, emoji sparingly on lower-impact messages, a colon may offset a list, no comma at the end of a bullet ### George's review Non-blocking callouts are addressed: authority and source links, contractions when they read naturally, "your" only on onboarding titles, consent "I understand…" kept as a skill exception not yet in the Style Guide, directional words limited to pointing on screen, "MetaMask Snaps" on first mention in a page or flow, Rewards vs points vs redeemed, no yield/ROI/securities analogies, loading status announced to assistive tech, "site" in consumer UI and "dapp" for a technical audience, and the safety example no longer says funds are safe. Polymarket and Predictions label casing is in the mobile overlay. Activity-row copy is in the extension overlay. Component README lines tied to #212 and #213 were left unchanged. ### Audit fixes - Removed the false claim that sentence-casing a Polymarket title would break team matching - "Learn more." cites mobile keys only (`app_settings.learn_more`, `predict.consent_sheet.learn_more`) - Removed the invented "Hold to reveal private key" row - Directional words narrowed to pointing at something on screen - Dropped the "apologize when appropriate" line - "Paid by MetaMask" example is generic - Design Brain is named, not linked - Collectibles keeps its name, with no "upcoming" or "gacha cards" ### Still proposed or unresolved - Periods on single sentences: the one-sentence, no-period rule was removed. Content design is writing a context-based rule. Multi-sentence copy still periods every sentence, and headers, buttons, labels, and tabs take no period - Number ranges: the Style Guide says both a hyphen (`1-20`) and an en dash for a fixed range. Not migrated - The Style Guide's WIP glossary still has a struck-through note preferring "transaction fee" over "Network fee", and an unfinished "dapps" entry. The main guide body does not decide those. This skill keeps "Network fee", and "site" in consumer UI - Curly quotes, the "I understand…" consent exception, and not showing "fiat" to users are not covered by the Style Guide. They stay. The consent line is marked as a skill exception not yet in the Style Guide ### Rollout checks not yet done - Onboarding layout, larger text, and translation checks before dropping "your" on onboarding titles - Enable/Disable edge-case pass for toggles - Signature and permission decline wording before replacing Reject with Cancel ### How agents get it `yarn skills` syncs this into the app repos as `mms-content-guidelines`. The copy under `.claude/skills/mms-content-guidelines` is generated. Do not edit it there. AGENTS.md pointers are in draft PRs [metamask-mobile #39056](MetaMask/metamask-mobile#39056) and [metamask-extension #47681](MetaMask/metamask-extension#47681). The extension gets the skill after this PR merges. A Consensys/skills overlay may exist. This environment could not read that repo. Reviewers should check it does not override these rules. ## Type of Change - [ ] New skill - [x] Skill improvement/update - [ ] Bug fix - [ ] Documentation update - [ ] Other (please describe): ## Skill Details (if adding a new skill) **Provider Name:** **Skill Name:** content-guidelines (existing) **Brief Description:** Agent-readable MetaMask content guidance for mobile and extension. ## Checklist - [x] I have read the [CONTRIBUTING.md](https://github.com/MetaMask/skills/blob/main/CONTRIBUTING.md) guidelines - [x] My skill follows the [SKILL_TEMPLATE.md](https://github.com/MetaMask/skills/blob/main/.github/SKILL_TEMPLATE.md) format - [ ] I have tested this skill with an AI agent - [x] My skill does not contain any secrets, private keys, or sensitive data - [x] I have added appropriate documentation - [x] My changes don't break existing skills ## Testing `yarn audit:skills` on this skill reports no errors. `yarn test` passed. A local install for `metamask-mobile` and `metamask-extension` writes `mms-content-guidelines` and appends only the matching overlay. ## Additional Context No app-repo string migrations are included. <!-- CURSOR_AGENT_PR_BODY_END --> <div><a href="https://cursor.com/agents/bc-ef9ee196-1774-5573-8fe4-ec6bfc42b057?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-ef9ee196-1774-5573-8fe4-ec6bfc42b057&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: alidotforrest <alidotforrest@users.noreply.github.com>
…p-7309 Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com> # Conflicts: # domains/ui/skills/content-guidelines/repos/metamask-mobile.md # domains/ui/skills/content-guidelines/skill.md
Replace the bare MMDS README path with the monorepo URL pinned to the installed release tag. READMEs are not in the npm package. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
Prop data now lives under reactDocgenTypescript, with type name, raw, and value. The reference also covers kept host props, filtered inherited props, and the React-only docs manifest. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
Box is the layout default because it moves between Mobile and Extension. Utility props and className are both fine, and type uses the MMDS Text component. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
Pattern, foundation, and design-token stories are not in the hosted manifests. Look up a pattern in the component README at the installed tag and in existing repository usage. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
An empty manifest jsDocTags and a clean .types file do not mean a component is current. Search the component folder for @deprecated, read the README at the installed tag, and prefer the exported replacement over existing repo usage. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
… MCP docs - Remove the MMDS AGENTS.md and docs/ai-agents.md links; both point to Storybook MCP. - Inline the amount-input typography guidance instead of linking to Notion. - Keep one Deprecated APIs section in the base; the manifest reference points to it. - Read shared types from design-system-shared, import from the platform package. - Describe the manifest size as a few MB. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
…rsion pin - Replace hardcoded legacy library, feature UI, and enum paths with repo-search guidance and placeholder example paths. - Defer deprecation handling to the base Deprecated APIs rule. - Remove the Tailwind CSS v3 pin. - Add a Box for layout, MMDS Text for text checklist item. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
…tension Point ui-development at installed types, hosted component manifests, and READMEs at the installed tag. State deprecation once, inline the amount-input guidance, and drop the links that lead to Storybook MCP. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
…/mmds-extension-skills-no-storybook-mcp-7309 Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
Replace the inlined Design Brain section with a Notion source step and a short WCAG floor. Look patterns up in Storybook first, use Tailwind before design-tokens, and restore the installed-types checklist item. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
…/mmds-extension-skills-no-storybook-mcp-7309 Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
Read design tokens outside Tailwind from the installed design-tokens README, and link MIGRATION.md at the installed tag instead of MMDS main. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
| - [ ] No SASS or SCSS files were created or modified. | ||
| # MetaMask Extension overlay | ||
|
|
||
| Platform rules for React web UI in `metamask-extension`. The base above covers |
There was a problem hiding this comment.
Same shape as the Mobile overlay in #212: only Extension paths, the Tailwind preset surface and web accessibility mechanics live here. Sources, tokens, deprecation and the Legacy* rule all come from the base in #242, and the deprecation line below just tells the agent which folder to grep.
| - Legacy component library: being deprecated in favor of MMDS. Search the | ||
| repo for the existing legacy import. Do not add new usage where MMDS covers | ||
| the need. | ||
| - Existing app-level components: use one only when |
There was a problem hiding this comment.
App-level components follow the same rule as Mobile in #212: only when MMDS has no equivalent, found by searching the repo, and checked against the base deprecation rule. Keeping the wording the same in both overlays makes it clear it's one policy across platforms.
| 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. | ||
| - Outside Tailwind, read a semantic token as a CSS variable from the installed `@metamask/design-tokens` package. How Extension reads one is in the README at `https://github.com/MetaMask/metamask-design-system/blob/@metamask/design-tokens@<installed version>/packages/design-tokens/README.md` (version from `node_modules/@metamask/design-tokens/package.json`). |
There was a problem hiding this comment.
On Extension, a token outside Tailwind is read as a CSS variable, which is what you need for things like a third-party component or a chart that can't take a class. Like Mobile, it points at the design-tokens README at the installed tag rather than naming tokens, so there's nothing here to go stale.
|
|
||
| ## Incremental migration paths | ||
|
|
||
| Search the repo for the existing legacy imports. Legacy components and legacy |
There was a problem hiding this comment.
Legacy components and their enums often come from different modules in Extension, so the example uses placeholders and the agent searches the repo for the real imports. Hardcoding those paths would break the first time a file moves. LegacyOnlyEnum shows that names MMDS doesn't export keep their plain names, which is the base rule in #242.
| import { Component } from '../../<legacy-component-module>'; | ||
| ``` | ||
|
|
||
| Prop mapping from legacy to MMDS components is in `MIGRATION.md` at the installed tag. Take `<installed version>` from `node_modules/@metamask/design-system-react/package.json`: |
There was a problem hiding this comment.
MIGRATION.md and the component READMEs are read at the installed per-package tag for the same reason as Mobile. READMEs aren't in the npm tarball, and main can be ahead of what Extension installs, so the tag keeps the prop mapping honest.
The base branch was changed.
<!-- CURSOR_AGENT_PR_BODY_BEGIN --> ## Description Shared MMDS lookup baseline, split out of #212 and #213 so it is reviewed once. It changes only these three files: - **`domains/ui/skills/ui-development/skill.md`**: an ordered source list that needs no MCP server (installed package types, hosted Storybook components manifests, Design Brain when a Notion connector can reach the MetaMask workspace, component READMEs at the installed tag, existing repo usage, then Figma MCP and Code Connect when connected). Active Design Brain rules are queried and cited, not copied in. A short WCAG accessibility floor stays inline. If Notion is unavailable, the PR or review says "Design Brain not checked". Patterns use the first place that has them: Storybook or the manifest docs, then Design Brain, then the README, then existing usage. Preset Tailwind classes come first; where Tailwind does not apply, use a semantic token from the installed `@metamask/design-tokens` package, with no recorded reason. One Deprecated APIs rule: do not add new usage of anything marked `@deprecated`; if no replacement is exported, keep existing usage and record the gap. Typography, including amount inputs, follows the installed types. No Storybook MCP or Context Forge guidance. - **`domains/ui/skills/ui-development/references/reading-mmds-manifests.md`**: how to read the React and React Native components manifests, with no component, version, or prop inventory. Pattern lookup points at the skill instead of saying patterns are absent. Deprecation handling points at the base rule. - **`domains/ui/knowledge/agentic-design-system-strategy.md`**: the baseline delivery is installed types, hosted manifests, and the consumer Tailwind config. Skills query Design Brain instead of copying its rules. Storybook MCP and Context Forge are no longer the preferred path. #212 (Mobile) and #213 (Extension) stack on this branch and contain only their own overlay and scaffold files. Merge this PR first. ## Type of Change - [ ] New skill - [x] Skill improvement/update - [ ] Bug fix - [ ] Documentation update - [ ] Other (please describe): ## Skill Details (if adding a new skill) **Provider Name:** **Skill Name:** **Brief Description:** ## Checklist - [x] I have read the [CONTRIBUTING.md](https://github.com/MetaMask/skills/blob/main/CONTRIBUTING.md) guidelines - [x] My skill follows the [SKILL_TEMPLATE.md](https://github.com/MetaMask/skills/blob/main/.github/SKILL_TEMPLATE.md) format - [x] I have tested this skill with an AI agent - [x] My skill does not contain any secrets, private keys, or sensitive data - [x] I have added appropriate documentation - [x] My changes don't break existing skills ## Testing - `yarn lint`, `yarn test`, and `yarn audit:skills` pass. The audit has no errors and no new warnings (128 warnings, same as before). - The three files are byte-identical to the copies on #212 and #213. ## Additional Context No `CHANGELOG.md` entry, matching #212 and #213. <!-- CURSOR_AGENT_PR_BODY_END --> <div><a href="https://cursor.com/agents/bc-858fa289-cce3-5d07-a2fb-5ffa46334462?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-858fa289-cce3-5d07-a2fb-5ffa46334462&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
## Release `@metamask/skills` 0.4.0 This is the release candidate for **0.4.0**, a minor release that brings in everything merged to `main` since [v0.3.1](https://github.com/MetaMask/skills/releases/tag/v0.3.1) (66 PRs). See `CHANGELOG.md` for the full list with PR links. ### Highlights **New domains** - `observability`: Sentry, Tempo and telemetry cost-control skills - `performance`: measurement, anti-pattern scanning and React Compiler triage - `typescript`: authoring and migration skills - `platform`: Extension runtime architecture and failure modes **New skills** - Mobile planning (`planning`, `planning-spec`, `jira-brief`), now stable `base` skills for Mobile and Extension - `analytics`, `feature-flags`, `navigation` and `selector-patterns`, each with a repo-agnostic base and a Mobile overlay - A PR review base skill, generated Perps review checklists, `notifications-category-sync`, a profiling regression proposal skill and activity mapper guidance - Recipe planning and cooking skills, pinned to a single mm-harness version with an install-time version check **UI development and content** - A shared, MCP-free `ui-development` baseline for looking up MetaMask Design System components, with thin Mobile and Extension overlays - Content guidelines with shared rules plus Mobile and Extension overlays, which now also apply when existing strings are edited **Testing** - `visual-testing` and `mobile-visual-testing` updated for `@metamask/client-mcp-core` 0.14.0 and `@metamask/device-mcp` 0.8.0 - Component-view flake rules and Appium stability patterns added to `mobile-testing` **Installer / CLI** - Explicit-only skill invocation, preserved repository overlays and pruning of retired skill names during sync - Syncs of each shared skill source run one at a time, so concurrent syncs can't collide during a Git fetch - Skill descriptions over the 1024-character catalog limit are shortened ### Changelog The auto-generated `[0.4.0]` section has been rewritten into Added, Changed and Fixed entries, written for consumers. It replaces the `Uncategorized` commit titles, removes duplicates and adds the PRs that were missing (#159, #183, #212 and #213). ### Release steps 1. Approve the pending workflow run so CI runs on this PR, including `yarn lint:changelog --rc`, the tests and `yarn pack:dry-run`. 2. Get a review from @MetaMask/extension-platform or @MetaMask/mobile-platform. 3. Squash-merge, keeping github-actions as the commit author. That's what lets **Publish Release** run. 4. @metamask-npm-publishers approve the `npm-publish` environment. Then `@metamask/skills@0.4.0` is published to npm, and the `v0.4.0` GitHub release and tag are created. --------- Co-authored-by: github-actions <github-actions@github.com> Co-authored-by: George Marshall <george.marshall@consensys.net>
Description
Refreshes the MetaMask Extension
ui-developmentoverlay so agents work from the MMDS sources of truth instead of copies of them in skills.Stacked on #242; merge that first.
repos/metamask-extension.md): reduced to durable platform rules: package routing, the Tailwind styling surface, Extension accessibility mechanics,Legacy*aliasing for migration (search the repo for the existing legacy imports; the example uses placeholder paths only), and a checklist.Boxis the layout default because it moves between Mobile and Extension, and eitherBoxutility props orclassNameis fine. Type uses the MMDSTextcomponent. No app folder paths or version pins. Deprecation defers to the base rule in feat(ui-development): no-MCP MMDS lookup baseline (shared) #242.The overlay names
BoxandText. It names no other design-system components, enum values, or version pins.Merged
main(including #221) into this branch.domains/ui/skills/content-guidelines/now equalsmain, because #221 already covers those files.Type of Change
Skill Details (if adding a new skill)
Provider Name:
Skill Name:
Brief Description:
Checklist
Testing
yarn lint,yarn test, andyarn audit:skillspass. The audit has no errors and no new warnings.mainof MetaMask/metamask-design-system. README links are templates for the installed version's tag.Additional Context
No
CHANGELOG.mdentry, per review.