[georgewrmarshall]

Description

This reshapes the ui/ui-development skill for MetaMask Mobile so it works without any MCP server and carries no release-pinned inventory. The previous version of this PR pinned MMDS RN 0.54.0 (MMDS v77.0.0) and added a 231-line inventory. Mobile main has since moved to ^0.55.0, which shows how quickly pins go stale. This rewrite removes the pins and the inventory.

Extension gets the same reshape in #213. Both PRs carry an identical first commit with the shared base. I test-merged them into main in both orders and both merges were clean, so whichever lands second just has its copy of that commit drop out.

Commit 1 (shared, identical in #213): expand the ui-development base

domains/ui/skills/ui-development/skill.md goes from a one-line pointer to about 200 lines:

• When to use, and a short Workflow for Create and Review.

• Sources, in order, with no MCP needed:

  1. Installed package types in node_modules. These win whenever sources disagree.
  2. The hosted Storybook components manifests (React, RN), used for discovery, deprecation tags, and snippets. The skill warns that they track MMDS main, and that snippets can import enums from design-system-shared. Enums still come from the platform package.
  3. The README at the per-package tag @metamask/<package>@<installed version>, taken from the installed package.json. No release is hard-coded.
  4. Repository usage and stories.
  5. Figma MCP and Code Connect, when connected.

  Storybook MCP and Context Forge are optional only. Agents never block on them and never configure them.

• Choosing a component: check the manifest and installed exports before inventing anything, and never port across platforms. The order is MMDS, then non-deprecated legacy, then a feature component, then custom UI with a recorded reason. "Deprecated" means @deprecated in the types or jsDocTags.deprecated in the manifest.

• Foundations: tokens, Tailwind through the presets, the spacing and radius scale, no arbitrary values, contrast, and i18n tolerance.

• Typography: FontFamily.Default by default, and Text + TextVariant instead of raw sizes. Hero is for approved hero cases only. For amount inputs, a single line points to the Proposed Typography rule in the Design Brain and MMDS reference; the skill does not settle that question.

• The Legacy* alias rule for incremental migrations.

• Accessibility, trust, and sheets: short Active Design Brain rules, inlined because agents can't read Notion. Proposed rules are linked, not enforced.

• MMDS agent docs: links to AGENTS.md, docs/ai-agents.md, .cursor/rules/styling.md, figma-integration.md, and component-migration.md instead of copies.

It also adds references/reading-mmds-manifests.md, which explains how to read components.json and is never synced to a release. It updates knowledge/agentic-design-system-strategy.md: the baseline is installed types + hosted manifests + consumer Tailwind, Storybook MCP is optional, skills must work with no MCP, and skills carry no release-pinned inventories.

Commit 2 (Mobile only)

• ui-development/repos/metamask-mobile.md goes from 435 lines on main to 128 lines of durable platform rules:

  • Package paths, with the RN manifest for inventory.
  • The twrnc styling surface: useTailwind(), Box/Text, and no StyleSheet.
  • Pressed state through ButtonBase twClassName={(pressed) => ...}. Its style is a plain StyleProp<ViewStyle>, which I confirmed in the manifest.
  • Sheet rules: ScrollView from react-native-gesture-handler, nested sheets, and a single Toaster.
  • React Native accessibility mechanics: announceForAccessibility, the header and tab roles, hitSlop, Dynamic Type, and useReducedMotion.
  • The Legacy* import paths for Mobile's per-folder default exports.

  The component lists, prop inventories, conversion tables, and version pins are gone.

• The pinned references/mmds-react-native.md is deleted. It never landed on main.

• component-scaffold/repos/metamask-mobile.md:

  • READMEs come from the installed version's tag, with no MCP. Deprecation is checked through @deprecated tags instead of a hard-coded list.
  • The useElevatedSurface() step is replaced with the MMDS BottomSheet surface. app/util/theme/themeUtils.ts no longer exists in Mobile.
  • The pressed-state templates now use twClassName, and the strings path is now locales/languages/en.json.

• content-guidelines (base and Mobile overlay): "via Storybook MCP" becomes "the README's Content guidelines section at the installed version's tag; no MCP needed". The copied per-component copy table from the earlier revision is dropped.

Explicitly kept out: the PR media table rule, process and routing (Jev, Slack, Mac mini), copy rules beyond a pointer to content-guidelines, glass patterns, and the Hero-vs-Default decision for amount inputs.

Eval fixes (commit 3 shared, commit 4 per platform)

The eval in #220 found 13 issues. This PR applies the actionable ones. The shared commit (6868dbc here, 1ae0f98 on #213) is byte-identical on both branches:

• ISS-005: use a deprecation's named replacement only if the installed platform package exports it. Otherwise keep existing usage and record the gap.
• ISS-012: the Legacy* alias applies when a file imports the same name from a legacy source and from MMDS. Other legacy imports keep their names until migrated.
• ISS-013: the content-guidelines and component-scaffold pointers are qualified with "where the repository has them".
• ISS-002: the Strategy link is an absolute GitHub URL, so it resolves after install.
• ISS-004: reading-mmds-manifests.md explains the non-component entries (design-tokens-/docs-, patterns-, cast-expression names). An entry counts as a component only when its path is under src/components/ and its name is in the installed export index.

Mobile overlay commit (02bb1c2):

• ISS-007: when you change a component that uses useStyles + *.styles.ts, move the styles to typed Box props or twClassName, then delete the file and the hook call. Interactive ListItem (isInteractive) applies its own pressed background, so do not add bg-pressed.
• ISS-004: names app/components/UI/MarketingMomentTitle for marketing-moment headlines.

The re-run (ui-development-reshape-2026-11-05-rerun.md) gives Pass on all four scenarios on both platforms. ISS-010 and ISS-011 (Design Brain) are deferred to review; this work makes no Notion change. ISS-003 still applies: merge #212 and #213 together.

CHANGELOG

This PR adds no CHANGELOG.md entries. A reviewer asked for the entries to be removed, so commit 82f57eb drops the two bullets this PR had added, and CHANGELOG.md matches main.

Type of Change

• New skill
• Skill improvement/update
• Bug fix
• Documentation update
• Other (please describe):

Checklist

• I have read the CONTRIBUTING.md guidelines
• My skill follows the SKILL_TEMPLATE.md format
• I have tested this skill with an AI agent (see docs(evals): agent eval of the ui-development reshape (#212, #213) #220)
• My skill does not contain any secrets, private keys, or sensitive data
• I have added appropriate documentation
• My changes don't break existing skills

Testing

• yarn test: 76/76 pass. yarn lint: pass. yarn audit:skills: 0 errors, and ui/ui-development no longer warns about missing When To Use or Workflow sections.
• Every relative link under domains/ui/ resolves, and nothing references mmds-react*.md, v77, or a pinned version.
• tools/install --repo metamask-mobile --domain ui renders mms-ui-development/SKILL.md (339 lines, base + overlay) with references/reading-mmds-manifests.md bundled.
• Merging this PR and docs(ui): reshape ui-development for Extension — shared MCP-free base, thin overlay, no Storybook MCP requirement #213 into main is clean in both orders.
• All external URLs return 200: both manifests, the MMDS agent docs, both MIGRATION.md files, and a sample per-package-tag README.

Additional Context

• The Design Brain still lists the Legacy alias rule and the Typography rule as Proposed (ISS-010), and an Active Design Brain rule ranks MMDS main above installed types (ISS-011). Both are deferred to Design Brain review; this PR does not change Notion.
• The base and the Extension overlay sit on separate branches, so the shared commit is duplicated by design to keep one PR per platform.

  

[georgewrmarshall]

@cursoragent remove changelog entry

[cursor]

I removed the CHANGELOG entries from this PR, #212. The reviewer's comment was on the shared base bullet, and the branch also had a second entry for the Mobile overlay. Both are gone, and CHANGELOG.md now matches main. The new commit is 82f57eb.

I also removed the two entries from #213. It carried the same shared bullet, and you had asked that CHANGELOG.md be left alone for these skill changes. That's commit 250424a. If you wanted #213 left as is, I can restore its bullets.

I updated both PR descriptions so they no longer mention a CHANGELOG entry. Nothing else in the skill content changed.

Tests, lint and the two-order merge check still pass on both branches. CI on #212 is still running its CodeQL and finalize scan step, and CI on #213 is still running its CodeQL step; the other checks have passed. I didn't resolve the reviewer's comment thread.