MCM-51 — MCM Design System
Overview, personas, and architecture for a shared design system — tokens, components, and icons — spanning MCM's product console, customer portal, and marketing site.
MCM-51 — MCM Design System
MCM ships three separate web surfaces — an internal product console, a centrally-hosted customer portal, and a public marketing site — built and extended by different people at different times. As MCM adds more surfaces and grows the existing ones, the three have already started to disagree with each other: a colour or spacing value meant to match one surface no longer does, icon libraries are pinned to different versions on different surfaces, and there is no shared package of any kind between them today, so a fix or improvement has to be copied by hand three times or drifts apart on its own. The MCM Design System establishes one shared, versioned source for design tokens, common UI components, and icons that all three surfaces install as a dependency, plus the documentation and automated checks needed to stop them drifting again.
Each user story below is a self-contained page with its own acceptance criteria, technical design, and UI changes. This page holds only what's shared across all of them.
Personas
| Persona | Role | Primary concern |
|---|---|---|
| Frontend Engineer | Builds and maintains one of the three surfaces (product console, customer portal, or marketing site) | Reusing an established look and feel instead of re-implementing or guessing at colours, spacing, and components each time |
| Design Lead | Defines and maintains MCM's visual language | Having one place to change a colour, spacing value, or icon and have it apply everywhere, instead of manually syncing several codebases by hand |
| End User (any surface) | Anyone using the product console, customer portal, or marketing site | Experiencing one coherent, recognisable MCM look and feel no matter which surface they're on |
System Context
All three surfaces install the same shared package as an ordinary dependency; none of them need to change their underlying framework to adopt it. The documentation site and the automated consistency check both read from the same published package, so neither can fall out of sync with what a surface actually consumes.
User Stories
| Story | Summary |
|---|---|
| MCM-52 — Shared Design Tokens | One versioned source for colour, typography, spacing, and radius values, consumed by all three surfaces. |
| MCM-53 — Shared UI Component Library | Common components (buttons, cards, tabs, tables, form fields) as an installable package. |
| MCM-54 — Unified Icon System | One icon library, one version, one curated icon set, with a documented escape hatch for brand icons. |
| MCM-55 — Design System Documentation & Living Catalog | A browsable, always-current catalog of every token, component, and icon with usage guidance. |
| MCM-56 — Automated Consistency Checks | A build-time check that flags drift from the shared tokens, components, or icons before it merges. |
Cross-Cutting Non-Functional Requirements
| ID | Requirement |
|---|---|
| NFR-01 | The shared package must be versioned (semantic versioning) so each surface can upgrade independently and roll back a release that introduces a visual regression. |
| NFR-02 | Adopting the design system must not require any surface to change its underlying framework — it is consumed as an ordinary dependency, not a rewrite. |
| NFR-03 | A change to a token, component, or icon must be reviewable and diffable before it is published, so it cannot silently ship to all three surfaces unreviewed. |
Out of Scope
- Migrating existing screens in the product console, customer portal, or marketing site over to the new shared components — this establishes the system itself; adopting it across already-built screens is tracked separately as follow-on work.
- A visual redesign or new brand identity — this standardises and shares the existing look and feel across surfaces, it does not invent a new one.
- Design tooling for non-web surfaces (native mobile apps, transactional email templates).
- Governance or branding rules for third-party or white-labeled UI.
Open Questions
- Marketing site's component depth: the marketing site is structured differently from the other two surfaces today and may only be able to adopt the shared tokens and a subset of primitives without a deeper rebuild. How much of the shared component library it ultimately adopts, versus staying token-only, is not yet decided — see MCM-53.
- Adoption timeline for existing screens: whether adoption of the shared library across already-built screens happens incrementally, surface by surface, or on a fixed schedule is not yet decided; this module only covers building the system itself.
MCM-48 — Draft a Policy from a Natural-Language Description
Describe a compliance rule in plain English to the AI assistant, refine it through conversation, and prefill the accepted draft into the existing policy creation flow.
MCM-52 — Shared Design Tokens
One versioned source for colour, typography, spacing, and radius values, consumed by all three MCM surfaces.