Repository navigation
docs(ui): reshape ui-development for Mobile — shared MCP-free base, thin overlay, no pinned inventory - #212
Conversation
…e MCP-free Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
…m rules Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
1b4cfd3 to
2d1ba46
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>
Explain retiring useStyles + .styles.ts pairs, note that interactive ListItem applies its own pressed background, and point at MarketingMomentTitle. 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>
…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>
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
Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
…f name Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
…rop the Storybook MCP note Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
The Foo template is now a layout-primitive container that renders children and passes twClassName and testID through. Actions use the design-system Button, with the base button or Pressable only when Button cannot express the design. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
…ry folders Layer 2 and the Mobile ui-development paths no longer name the component-library folders or a plan to move them. Agents search the repo and use an existing app-level component only when MMDS has no equivalent. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
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, and Text is the MMDS text component. Utility props and twClassName are both fine. The scaffold test uses MMDS Text, and the old elevated-surface line is gone. 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>
…recation to the base - Remove the app/components product UI line. - Describe the root toaster without its path. - Point deprecation handling at the base Deprecated APIs rule. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
- Remove stale fallback export paths and the docs/readme/storybook.md pointer. - Defer deprecation handling to the ui-development base rule. - Make the eslint-disable rule and the checklist agree. - Remove the stray separator and fix the three-layer intro. 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-mobile-skills-refresh-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-mobile-skills-refresh-7309 Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
Read design tokens outside Tailwind from the installed design-tokens README, link MIGRATION.md at the installed tag, and replace the scaffold import example's real app file with a generic one. Co-authored-by: George Marshall <georgewrmarshall@users.noreply.github.com>
| ### Basic Container: | ||
| # MetaMask Mobile overlay | ||
|
|
||
| Platform rules for React Native UI in `metamask-mobile`. The base above covers |
There was a problem hiding this comment.
This overlay only covers what's different on Mobile: package paths, the twrnc styling surface, sheets and React Native accessibility mechanics. Everything shared, including sources, deprecation, tokens and the Legacy* rule, lives in the base in #242 so the two platforms can't drift apart. The Extension overlay in #213 has the same shape.
| ## Styling surface | ||
|
|
||
| - Use `const tw = useTailwind();`. Never `import tw from 'twrnc'`. | ||
| - `Box` is the default for layout. Using it makes code easier to move between |
There was a problem hiding this comment.
The only components these skills name are Box, Button and Text, because they're stable and agents reach for them constantly. Everything else, like sheets, list items and the toaster, is described by role and looked up in the installed exports, since component names and enums move between releases. App folder paths are left out for the same reason, and the agent searches the repo instead.
| share across platforms. Read which props exist from `Box`'s installed types. | ||
| When a style has no utility prop (radius, for example), use a class such as | ||
| `twClassName="rounded-xl"`. | ||
| - Outside Tailwind, read a semantic token in JS from the installed `@metamask/design-tokens` package, through the app theme. How Mobile 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 Mobile, a token outside Tailwind comes through the app theme, which covers things like a third-party component's style prop or an animation value. It points at the design-tokens README at the installed tag instead of naming tokens, so it stays right as the token set grows. This is the platform half of the Foundations rule in #242.
| Always reference the patterns from `app/component-library/components/design-system.stories.tsx` for proper usage examples. | ||
|
|
||
| ## Enforcement | ||
| 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-native/package.json`: |
There was a problem hiding this comment.
MIGRATION.md and component READMEs are always read at the installed per-package tag, never main. READMEs aren't in the npm tarball, and main can describe props the repo hasn't upgraded to yet, so the tag keeps the prop mapping in step with what's actually installed.
| ```tsx | ||
| import { strings } from '../../../../../locales/i18n'; | ||
| import { useElevatedSurface } from '../../../../util/theme/themeUtils'; | ||
| import { strings } from '../../../../locales/i18n'; |
There was a problem hiding this comment.
The import example uses placeholder files so it doesn't point agents at a real app component that could move or get deprecated. The placement table, import fences and barrel paths in this scaffold are the one place I kept real app paths, because they're structural rules an agent can't work out from searching. Deprecation and component choice defer to ui-development rather than being repeated here.
<!-- 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>
…ills-refresh-7309
## 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 Mobile
ui-developmentandcomponent-scaffoldoverlays so agents work from the MMDS sources of truth instead of copies of them in skills.Stacked on #242; merge that first.
ui-developmentoverlay (repos/metamask-mobile.md): reduced to durable platform rules.Boxis the layout default because it moves between Mobile and Extension, and text uses the MMDSTextcomponent.Boxutility props andtwClassNameare both fine. It also covers package routing, existing app-level components (search the repo, and use one only when MMDS has no equivalent), the twrnc styling surface throughuseTailwind(), pressed state through the base button'stwClassNamefunction orPressable+tw.style(), thereact-native-gesture-handlerScrollViewinside sheets, the single design-system toaster mounted at the app root, Mobile accessibility mechanics, theLegacy*alias rule, and a checklist. Deprecation defers to the base rule in feat(ui-development): no-MCP MMDS lookup baseline (shared) #242.component-scaffoldoverlay (repos/metamask-mobile.md): points at the manifest and the installed types and README at the installed tag, and fixes thelocales/languages/en.jsonpath. Removes the outdateduseElevatedSurface()sheet step. Layer 2 is existing app-level components: search the repo and use one only when MMDS has no equivalent. Actions use the design-system Button; the base button orPressableonly when Button cannot express the design. The file templates follow the MMDS create-component template: a container that renderschildrenand passestwClassNameandtestIDthroughBox. The test example uses the MMDSTextcomponent. Placement, import example, ESLint fence, and barrel paths stay as scaffold-specific guidance.Boxis the layout default, the MMDSTextcomponent is used for text, and Button is the control for actions. No other design-system component names, 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 and MetaMask/metamask-mobile. README links are templates for the installed version's tag. The base button'stwClassNamepressed-function signature was checked against the MMDS React Native types.Additional Context
No
CHANGELOG.mdentry, per review.