marmo-ui

---
name: marmo-ui
description: Use whenever building, editing, or reviewing UI code that imports from @marmoui/ui (Marmo's internal design system). Triggers on requests involving @marmoui/ui, Marmo components, "build a form/page/dashboard with our design system", "use Marmo UI", "make this look like our app", any UI/component task in a Marmo product app, OR when the prompt mentions analytics/tracking/PostHog/telemetry/events alongside UI work. Walks through the MCP-backed workflow that prevents hallucinated props, wrong imports, and broken compositions, and layers in PostHog instrumentation when the prompt asks for tracking.
---

# Marmo UI workflow

You are working on a Marmo product app that consumes `@marmoui/ui`, Marmo's internal design system. The `marmo-ui` MCP server (auto-started by this plugin) is the source of truth — every prop, variant, and pattern. **Never guess. Always look it up.**

If the `marmo-ui` MCP tools aren't available (calls to `mcp__marmo-ui__*` fail with "tool not found"), stop and tell the user to run `/plugin` and confirm `marmo-ui` is enabled. If the token is wrong (`401 Unauthorized` on any tool call), tell them to disable and reinstall the plugin (`/plugin uninstall marmo-ui@marmoui-plugins` then `/plugin install marmo-ui@marmoui-plugins`) — Claude Code will re-prompt for `marmo_mcp_token`. Don't fall back to writing components from memory.

## Required steps (in order)

### 1. Verify the MCP is fresh

```
mcp__marmo-ui__get_knowledge_version
```

Logs the `gitSha`, `indexedAt`, `componentCount`, and `patternCount`. Confirms you're talking to a healthy MCP. If it errors, surface the error to the user — don't silently fall back to guessing.

### 2. Read the rules (once per session)

```
mcp__marmo-ui__get_design_guidelines  iconLibrary="<library>"
```

Returns import rules, color tokens, icon conventions, and the mandatory generation checklist. Skim it. The hard rules below are a summary.

**Icon library selection (do this before writing any UI code):** Ask the user which icon library they want. Default (no preference): **Phosphor** (`phosphor`). Supported: `phosphor`, `material` (react-icons/md), `lucide`, `tabler`, `heroicons`, `feather`. Pass the chosen `iconLibrary` to `get_design_guidelines` AND to `review_generated_code` — the validator rejects icons imported from any other library as errors. Don't mix libraries within one project.

### 3. Find the right primitive

**If the task is a known multi-component layout** (full app shell, data-table-with-filters, confirmation-dialog, dialogs-for-other-actions, form-with-validation, posthog-tracking):

```
mcp__marmo-ui__get_pattern  patternId="<the-pattern>"
```

The returned code is already validated — adapt it, don't rewrite it from scratch.

**If the prompt mentions analytics, tracking, PostHog, telemetry, events, or "track this":**

```
mcp__marmo-ui__get_pattern  patternId="posthog-tracking"
```

Layer the returned instrumentation **on top of** whatever other pattern or component you're building. The `posthog-tracking` pattern is additive — call it together with `app-shell`, `data-table-with-filters`, `form-with-validation`, etc.

**Otherwise** (single-component or unfamiliar task):

```
mcp__marmo-ui__search_components  query="<keyword>"
mcp__marmo-ui__get_component_info  componentName="<Component>"
```

Call `get_component_info` for **every** component you'll use — even ones you think you remember. Prop signatures change.

### 4. Write the code

- Imports from `@marmoui/ui` only (UI).
- Icons from the user's chosen icon library only (default: `@phosphor-icons/react`). Use the icon name map returned by `get_design_guidelines({ iconLibrary })` for the correct names, and set `weight="duotone"` for two-tone icons when using Phosphor.
- Use the exact prop names, variants, and shapes returned by `get_component_info`.
- Use the layout from `get_pattern` for full pages — don't roll your own sidebar.

### 5. Validate before returning

```
mcp__marmo-ui__review_generated_code  code="<your full output>"  iconLibrary="<library>"
```

Pass the SAME `iconLibrary` you passed to `get_design_guidelines`. Wrong-library icon imports are reported as **errors**. If `valid: false`, fix every error and re-run. Warnings are advisory but read them. **Never return code with errors to the user.**

---

## Hard constraints (the design system doesn't bend)

- **Imports.** `@marmoui/ui` for components; the user's chosen icon library for icons (default `@phosphor-icons/react`; also `react-icons/md`, `lucide-react`, `@tabler/icons-react`, `@heroicons/react`, `react-icons/fi`). Never `@chakra-ui/react`, `@radix-ui/*` directly, `@mui/*`, or an invented `@/components/ui/*`, and never mix icon libraries.
  - **Exception — local ui wrapper.** If the project declares `uiImportPath` in `DESIGN.md` frontmatter (or has a `src/ui/index.ts` that re-exports `@marmoui/ui`), import components from that path (usually `@/ui`) instead — it's the app's override layer (see `/marmo-ui:override`). Only files inside `src/ui/` import `@marmoui/ui` directly. Component props still come from the MCP; local overrides keep the same contracts unless the wrapper file says otherwise.
- **No namespace sub-components.** `Tabs.List`, `Dialog.Content`, `Select.Item` do **not** exist. Always use flat exports: `TabsList`, `TabsTrigger`, `TabsContent`, `DialogContent`, `SelectItem`, etc.
- **`PageSection` is self-closing.** It is a sticky toolbar/header. Never wrap content in it. Correct: `<PageSection pageTitle="..." primaryAction={{...}} />`. Wrong: `<PageSection>...</PageSection>`.
- **The page's main CTA goes in `primaryAction`.** Never render the primary button ("Import CSV", "Create X") in a toolbar row inside the page body — pass it as `primaryAction={{ label, onClick }}` so it sits in the header next to the title. DataTable already ships its own search/columns/filters toolbar and count text; don't rebuild any of it above the table.
- **Full pages require `SidebarProvider`.** There is no `<Sidebar>` component — wrap the layout in `SidebarProvider` and use `SidebarPanel` for navigation. Always start a full page by calling `get_pattern("app-shell")`.
- **Card is not a visual grouping box.** Before adding a `Card`, ask: "Could this block stand alone as a widget anywhere on a dashboard?" If the answer is no, use a plain `<div>` or `<section>` instead.
  - **NOT cards:** agent/plan selector sections, prompt/textarea input areas, wizard steps, settings sections, filter panels, or any section that spans the full page width or is the primary page content.
  - **ARE cards:** stat counters, contact/entity summary panels, analytics widgets, recent-activity feeds, dashboard tiles, media/preview thumbnails.
  - Stats cards are compact and use `CardContent className="px-space-md py-space-md"` (16px on all sides).
  - Use `CardHeader` when a title anchors the card content; put actions in the header only when they affect that card's content (filter, configure, refresh, manage).
- **Breadcrumbs are contextual, not sidebar-derived.** Use breadcrumbs for real hierarchy such as module analytics detail pages, single contact/entity pages, file-manager folder/file paths, or grouped module folders. Use `pageTitle` for ordinary sidebar destinations.
- **Wizard footers sit at the bottom.** Wizard pages should use a `flex min-h-0 flex-1 flex-col` body, scroll the step content, and place the footer after the content with `mt-auto` or sticky bottom styling.
- **DialogHeader is selective.** Use `DialogHeader` for long forms, panels, or large dialogs. For simple confirmations, put `DialogTitle` and `DialogDescription` directly in the content. When `DialogHeader` is used, usually omit `DialogDescription` and put explanatory copy in the body.
- **No invented props.** If `get_component_info` doesn't list it, it doesn't exist. Don't write `variant="danger"` on `Badge` (it's `destructive`). Don't write `size="lg"` on `Text` (use `variant="heading-md"` etc.).

---

## Why this workflow exists

Component props, variants, and composition patterns change as the design system evolves. The MCP rebuilds its knowledge index every time the design-system team merges to `main`. By calling the MCP every time, you get the current truth — not whatever shape was correct last month, and not whatever the model guessed from training data. Skipping these steps is the single biggest cause of broken `@marmoui/ui` code.

This skill ships inside the `marmo-ui` plugin: install once with `/plugin install marmo-ui@marmoui-plugins` and it triggers in every Marmo product repo you open in Claude Code. Updates arrive automatically on `/plugin update` (or every commit, since this plugin uses git-SHA versioning).