[georgewrmarshall]

Description

This reshapes the ui/ui-development skill for MetaMask Extension. On main, the Extension overlay makes Storybook MCP a required first step, so it breaks whenever Context Forge is down. After this PR the skill works with no MCP server and carries no release-pinned inventory. The previous version of this PR added a 231-line inventory pinned to design-system-react@0.49.0 while Extension pinned ^0.47.0. Extension has since moved to ^0.51.0 (metamask-extension#47305), so that inventory would already be stale. This rewrite drops it.

Mobile gets the same reshape in #212. 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 #212): 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 (Extension only)

• ui-development/repos/metamask-extension.md is rewritten as about 100 lines of durable platform rules:

  • Package paths, with the React manifest for inventory and README paths at the installed tag.
  • The styling surface: tailwind.config.js with the MMDS preset and no default palette or font sizes, class names only, and no SASS/SCSS.
  • Web accessibility mechanics: ButtonIcon ariaLabel, role="alert"/aria-live on an already-mounted container, aria-expanded, and keyboard behavior.
  • The Legacy* alias paths for ui/components/component-library, with a do/don't example.

  The "Required Storybook MCP Workflow" section and the separate fallback section are removed, as are version pins and named deprecation lists.

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

Explicitly kept out: the PR media table rule, process and routing, 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 (1ae0f98 here, 6868dbc on #212) 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.

Extension overlay commit (a46f691):

• ISS-009: most legacy enums come from ui/helpers/constants/design-system. Alias the ones the file also imports from MMDS (TextVariant, TextColor, TextAlign, FontWeight, IconColor, …). Legacy-only enums (Display, FlexDirection, AlignItems, JustifyContent, BackgroundColor, BorderColor) keep their names. The Do example shows both.
• ISS-006: "Do not add SASS or SCSS. Deleting SCSS rules, files, and @import lines that your change makes unused is expected." The checklist matches.
• ISS-008: prefer Box typed props for layout and className for the rest. Follow accessible web practices for anything clickable: a native <button type="button"> or <a> (for example via Box asChild) with preset state classes, never onClick on a div/span.
• ISS-002: the duplicate Strategy link is removed.

The re-run (ui-development-reshape-2026-11-05-rerun.md) gives Pass on all four scenarios on both platforms, and both Extension Partials are now Pass. It ran against Extension's new React 0.51.0 pin, with no skill change needed. 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 250424a 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 has no warnings.
• Every relative link under domains/ui/ resolves, and nothing references mmds-react*.md, v77, or a pinned version.
• tools/install --repo metamask-extension --domain ui renders mms-ui-development/SKILL.md (314 lines, base + overlay) with references/reading-mmds-manifests.md bundled.
• Merging this PR and docs(ui): reshape ui-development for Mobile — shared MCP-free base, thin overlay, no pinned inventory #212 into main is clean in both orders.
• I checked the Extension paths against metamask-extension main: tailwind.config.js (preset, colors/fontSize reset), ui/components/component-library, ui/helpers/constants/design-system.ts, and ui/components/ui/marketing-moment.

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.
• ButtonFilter still has no React replacement: its JSDoc names FilterButton, which only RN exports, and React 0.51.0 still lacks it. Under ISS-005 the skill now says to keep existing usage and record the gap when the named replacement is not exported on this platform. That gap should be reported to MMDS.

  

[georgewrmarshall]

@cursoragent remove changelog entry

[cursor]

I removed the shared ui/ui-development entry from CHANGELOG.md, but the branch already had that change pushed before I got to it, so I added no new commit.

My local commit removed the same line that remote commit 250424a had already removed. The remote commit also removed the Extension ui/ui-development entry, so both entries are now gone from the PR. I reset my checkout to the remote branch, which is at 250424a, and nothing else changed. The only remaining ui-development changelog line is an older entry from main.