docs(ui): reshape ui-development for Extension — shared MCP-free base, thin overlay, no Storybook MCP requirement

domains/ui/knowledge/agentic-design-system-strategy.md

@@ -29,36 +29,38 @@ 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. |
 
 ## Producer / consumer split
 
 - **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.
 
 ## Horizon
 
 | 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. |
 
 ## Principles for skills
 
 - 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.

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) | <https://metamask.github.io/metamask-design-system/manifests/components.json> |
+| React Native (Mobile) | <https://metamask.github.io/metamask-design-system/react-native/manifests/components.json> |
+
+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 <url> | jq` or a script, rather than reading it whole.
+- It is a discovery and deprecation index, not the API contract.
+
+## Shape
+
+```text
+{
+  "v": <format version>,
+  "components": {
+    "<story id>": {
+      "id":          "<story id>",
+      "name":        "<ComponentName>",
+      "path":        "<story file in the MMDS repo>",
+      "import":      "<import line(s) used by the stories>",
+      "jsDocTags":   { "deprecated": ["<reason and replacement>"] },
+      "reactDocgen": { "description": "...", "props": { "<prop>": { "required": ..., "tsType": ..., "description": "..." } } },
+      "stories":     [ { "id": "...", "name": "...", "snippet": "<example JSX>" } ],
+      "description": "<optional>",
+      "error":       "<present instead of reactDocgen when docgen failed>"
+    }
+  },
+  "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.