Codegen flow
Take your idea → Convert to promt
→ Install MCP → Generate UI
Important! Request Product Design Core and Product Design Library. It is absolutely essential to avoid inaccuracies during generation, so that the product resembles Muse. This is the foundation of any product's design, which includes:
- Palette
- Typography
- Spacing
- Basic set of product components
As a result, you should have a namespace in Figma where design tokens, basic design components, spacing system, and product screens will be gathered. Then you can proceed to assemble the product.
Implementation flow:
- Connect DS MCP.
- Scaffold Product DS.
- Install Echo and the Product DS package.
- Configure the theme, layers, and Storybook.
- Create product-specific components through the Figma new-component workflow.
- Run MCP review + product CI before merging
Principles and constraints:
- Reuse existing Echo components wherever possible.
- Migrate or extend an Echo component only when the product has genuine product-specific requirements.
- Do not recreate components that can be covered through Echo configuration, composition, theming, or variants.
- All unique product components must follow the approved Figma-to-code workflow.
This way, we do not create yet another UI kit independent of Echo, but build a product layer on top of the common foundation: reusing what is ready, maintaining unified accessibility and behavior contracts, while allowing the product its own tokens, compositions, and API.
01
MuseWeb DS MCP →
02
Figma & Requirements →
03
Development flow →
To set up MСP, you need to gain access to Nexus, our private package registry.
Next, you need to ask the agent to install the package @muse-web/ds-mcp: You will receive local settings, Tools for generation, and an assistant.
DS MCP is not a standalone code generator that writes files by itself. It connects the agent to the current playbooks and standards of Muse DS. The files are created by Cursor/Claude, but strictly following the process from MCP.
What DS MCP does:
First, it explores the repository, proposes a solution, gets confirmation, generates code, and conducts QA.
Main workflows:
• scaffold — creates the framework for a new Product DS: component structure, barrels, product CSS layer, namespace tokens, icon framework, and mandatory instructions for AI agents.
• install — connects Echo and ds to the application: dependencies, tokens, data-theme, CSS layers, Webpack/Vite/Preact settings, and a minimal Storybook.
• migrate — forks an existing Echo component into Product DS following the shadcn approach.
• new-component — creates a new component based on the Figma design.
• review — read-only audit of the existing component according to general rules and architectural pillars.
With MСP, you can build new interfaces, prototypes, and scenarios; they will be streamlined and properly organised.
Typically, the agent receives:
• a link to a specific Figma node;
• if available — YAML from the corp Figma plugin;
• context via Figma MCP (get_design_context).
It is essential to gather requirements for the feature/scenario; otherwise, the agent will invent all states and missing areas on their own, which will likely result in something irrelevant that will need to be redone later.
However, Figma here serves as a visual source and a set of hints, not a ready-made API specification. MCP does not thoughtlessly copy the list of props from the design: it separately clarifies semantics, states, behaviour, accessibility, controlled/uncontrolled models, and edge cases.
So the overall process is not "Figma and magically ready production front", but rather:
Figma context and requirements → analysis of the existing DS → selection of reuse strategy → API agreement → generation → QA.
Use the ready-made Echo component
This is the primary and cheapest way: import { Button } from '@muse-web/echo/components'
If the API and appearance are suitable, the component does not need to be copied. In Product DS, a re-export can be made for a single import point and its story can be moved to showcase the component with product tokens.
Adapt Echo for the product
If the Echo component conceptually fits but requires product-specific sizes, variants, defaults, analytics/test props, or other tokenization, migration is initiated.
MCP takes the actual Echo source files from the installed package — TSX, types, CSS Module, and story — and forks them into Product DS. After this, the component becomes autonomous: further updates to Echo do not automatically apply to it.
If Echo is used at runtime, --echo-* tokens can be retained. If the package was only used as a source for migration, all tokens must be mapped to --<product>-*.
Create a new component that does not exist in Echo
Here, MCP first checks the reuse chain:
Product DS → Echo → ds Base → ds ARIA
• If a similar product component already exists — we extend or compose it.
• If there is an Echo analogue — we use or migrate it.
• If there is a suitable BaseButton, BaseModal, BasePopover, etc. — we wrap it.
• Only if nothing fits, we build the component using ARIA hooks/RAC from @muse-web/ds.
Thus, a component is not created "from scratch according to the canons" without restrictions. Even a unique UI is usually assembled from existing layout, typography, behavior, and accessibility primitives. One can go down to a low level, but the agent must explain why the higher levels of the reuse chain are not suitable.
For a new component, MCP conducts a mandatory interview on one solution at a time: purpose, API, variants, slots, ref, states, loading/error/empty, RTL, motion, accessibility, stories, and tests. Before recording files, it shows the complete plan and waits for confirmation.
What is created in Product DS
Usually, this is a separate package with a structure like this:
components/ actions/ feedback/ foundation/ inputs/ navigation/ utils/ tokens/ styles/ icons/
Components use CSS Modules, semantic --<product>-*/--echo-* tokens, and data-disabled, data-focused, data-hovered, data-pending, and other states. Direct imports from react-aria are prohibited — everything goes through @muse-web/ds to maintain consistent versions and behavior.
In Echo, the automated import of colors and monochrome icons from foundation Figma occurs. Other tokens, including typography, spacing, and radius, are supported as curated CSS. For the product DS, a custom token namespace is usually created, and if necessary, its own icon surface.
What happens after generation
It is not advisable to immediately push the generated component to production. Generation concludes with a QA pass:
• Deterministic rules: imports/exports, TypeScript API, tokens, CSS, a11y, texts, and security;
• Architectural pillars: reuse, React API, React Aria, accessibility, performance, robustness, and testing;
• Storybook Sandbox and play tests, if the product has the corresponding infrastructure;
• Then product type-check, lint, tests, visual inspection, and standard PR review.
Safe mechanical violations are automatically corrected by the agent in draft. Decisions requiring product context — such as translation, sanitization, or contentious API architecture — are referred to the developer.
A separate review workflow does not change anything at all: it provides a structured report, and corrections are applied only after explicit confirmation of specific findings.
We mitigate these risks through multiple layers of protection:
1. 3-Day Quarantine.
Newly published packages cannot be installed immediately.
Only packages that have been available for at least 3 days are allowed.
This gives the community time to detect and report malicious activity.
2. Restricted Sources
Dependencies can only be installed from trusted registries. No arbitrary GitHub links, no external archives, no unverified sources
3. Protection Against Hidden Scripts
If a package did not previously execute scripts during installation, it cannot suddenly start doing so. This blocks a common attack vector where malicious code is injected via install-time scripts.
4. Private Registry
All internal packages are distributed through our private registry (Nexus) rather than public npm.
This ensures:
- full control over internal dependencies
- no risk of external package substitution
5. Strict Version Pinning
All versions are strictly locked:
- dependencies
- package manager
- CI tooling
Nothing can be updated or replaced without explicit review via pull requests.
6. Automated Auditing
Every pull request triggers automated dependency checks in CI:
- known vulnerabilities
- security advisories
- risk detection
Securing the Repository Against Supply Chain Attacks
In simple terms, a supply chain attack is when malicious code is introduced not directly into our codebase, but through one of the external dependencies we rely on.
Even if a widely used package is compromised, our multi-layered protection significantly reduces the risk of malicious code entering our product.
Security is not a single mechanism — it’s a system of constraints.
A — Z
30 essential terms compiled for automated repository refactoring and design system alignment.
Base component — готовый headless-примитив из @muse-web/ds, например BaseButton или BaseModal.
CSS layer — уровень CSS-каскада. Порядок приоритетов: foundation → echo → product.
Data attributes — атрибуты состояния вроде data-disabled, data-focused и data-pending, используемые для стилизации.
Design tokens — CSS-переменные для цветов, spacing, typography, radius и состояний.
DS MCP — сервер, который передаёт AI-агенту актуальные DS-процессы и стандарты. Сам файлы не изменяет.
Echo / @muse-web/echo — готовый визуальный дизайн-системный слой Muse поверх ds: компоненты, токены, темы, стили и иконки.
Figma context — макет, данные Figma MCP и YAML плагина. Это визуальная подсказка, но не окончательная спецификация API.
Headless component — компонент с поведением и accessibility, но без финального продуктового оформления.
Host agent — Cursor/Claude или другой AI-агент, который читает MCP playbook и выполняет изменения в репозитории.
Install — подключение Echo и ds к приложению: зависимости, токены, тема, CSS layers, bundler и Storybook.
Migrate / fork — копирование исходников Echo-компонента в Product DS для продуктовой адаптации. После fork компонент развивается независимо от Echo.
Muse DS / @muse-web/ds — headless foundation: базовое поведение, accessibility, React Aria-интеграция, Base-компоненты и общие типы.
New component — создание нового компонента по Figma-контексту, когда подходящего компонента нет в Product DS или Echo.
Peer dependency — зависимость, версию которой должен установить продукт. Echo и Product DS должны использовать одну совместимую версию @muse-web/ds.
Pillars — архитектурная оценка: reuse, React API, React Aria, accessibility, performance, robustness и testing.
Play test — автоматическая проверка поведения компонента внутри Storybook: click, keyboard, состояния и accessibility.
Playbook — пошаговая инструкция для агента: что исследовать, какие решения согласовать, что создать и как проверить.
Product DS — дизайн-система конкретного продукта поверх ds и Echo: продуктовые токены, адаптированные и уникальные компоненты.
Product tokens — собственные токены продукта с namespace вида --<product>-*.
Pure Echo consumer — продукт, который только использует готовые Echo-компоненты и не создаёт собственный Product DS.
React Aria — набор accessibility-примитивов для интерактивных компонентов. В наших проектах используется только через @muse-web/ds.
Reuse chain — обязательный порядок поиска решения: Product DS → Echo → ds Base → ds ARIA.
Review workflow — read-only аудит компонента. Сначала формируется отчёт; изменения применяются только после подтверждения.
Rules — детерминированные MCP-проверки: TypeScript, CSS, imports, API, a11y, тексты и security.
Sandbox story — интерактивная story, управляемая через args, для ручного исследования props.
Scaffold — создание пустого каркаса Product DS: структура, exports, токены, CSS layer и каркас иконок.
Semantic token — токен, описывающий назначение, а не конкретное значение, например color-content-primary.
Source-first package — пакет, публикующий исходные TSX/CSS-файлы, а не только собранный dist. Благодаря этому Echo-компоненты можно изучать и мигрировать.
Storybook story — изолированный пример компонента и его состояний.
Workflow — сценарий работы MCP: scaffold, install, migrate, new-component или review.
In case of questions
These channels will help you find answers to any questions related to DS or its surrounding topics. Please share your ideas and problems here:
Channels:
#ug-design-system
#ug-design-system
#mu-design-system
#au-design-system