---
name: mm-ui-component-engineering
description: Design, implement, migrate, validate, document, and release components with @meyermedia/ui across Next.js, React, Tailwind CSS, motion, Radix UI, React Aria, Lexical, icons, themes, layouts, patterns, blocks, domains, and registries. Use for mm-ui, lnxr-mm-ui, SaaS dashboards, Lunexor products, component extraction, design-token governance, accessibility, visual regression, and registry maintenance.
compatibility: Requires Node.js 20.9 or newer and pnpm for the mm-ui repository. Preserve public exports and semantic behavior unless a breaking change is explicitly planned.
license: Apache-2.0
---

# MM-UI component engineering

Use `@meyermedia/ui` as the canonical shared system. Do not copy a component into applications when a stable reusable primitive, pattern or domain component belongs in the package.

## Placement decision

- `primitives`: low-level accessible building blocks;
- `components`: reusable composed UI;
- `patterns`: behavior and composition patterns;
- `blocks`: complete application or marketing sections;
- `layouts`: page and shell structures;
- `motion`: reusable animation behavior;
- `advanced`: complex opt-in functionality;
- `domains`: business-domain components;
- `collections` and icon exports: curated catalogs;
- application repository: product-specific composition only.

## Required workflow

1. Search the catalog, exports and registry before creating anything.
2. Identify existing analogues and intended differences.
3. Define accessibility, responsive, theming, server/client and motion requirements.
4. Choose the narrowest public API and avoid framework leakage.
5. Implement with tokens and shared utilities rather than hard-coded brand values.
6. Preserve keyboard, focus, reduced-motion and semantic behavior.
7. Add type, interaction and visual tests appropriate to the component.
8. Export from the correct entry point and update registry metadata.
9. Validate with `pnpm check`, `pnpm test`, `pnpm build` and registry validation.
10. Test consumption from at least one representative Next.js application.

## Server and client boundaries

Do not call client-only helpers from Server Components. Isolate browser hooks, event handlers, motion runtime and stateful behavior behind explicit client entry points. Keep class-name recipes and serializable data available from server-safe modules where possible.

## Design-token rules

Use semantic tokens for color, spacing, radius, typography, elevation, motion and state. Brand palettes may extend the system but must not replace semantic contracts. Changes to foundations require migration analysis across all consuming applications.

## Accessibility

Require accessible names, visible focus, logical tab order, correct roles and states, keyboard equivalence, touch targets, contrast and reduced-motion behavior. Prefer native elements or mature accessible primitives.

## Release discipline

Classify changes as patch, additive minor or breaking. Document migrations, update examples, verify package contents and avoid publishing generated secrets or application-specific assets.

## Output

Return placement decision, reused components, public API, server/client boundary, tokens used, accessibility behavior, tests, registry and export changes, consuming-app verification, release impact and remaining compatibility risks.