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..29a7eb00 --- /dev/null +++ b/domains/ui/skills/ui-development/references/reading-mmds-manifests.md @@ -0,0 +1,81 @@ +# 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, 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 + +- **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/repos/metamask-extension.md b/domains/ui/skills/ui-development/repos/metamask-extension.md index 120f26dc..d69abe3f 100644 --- a/domains/ui/skills/ui-development/repos/metamask-extension.md +++ b/domains/ui/skills/ui-development/repos/metamask-extension.md @@ -3,157 +3,106 @@ repo: metamask-extension parent: ui-development --- -# MetaMask Extension Product UI — MMDS Guidance - -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. +# 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. + +## 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. +- 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. + +## 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. +- Follow accessible web practices for anything clickable: a native + `