Design System Refactoring & Remediation

Every component carried its own isolated copy of color styles, each behind a long, component-specific path name — such as colors/text/button/primary/default/base/disabled.

Massive technical debt

The same value existed under dozens of names. A single brand change touched every component, and no one could say which value was canonical.

Broken theme scalability

Colors were bound to elements, not roles, and the Theme collection also held fonts, spacing, sizes and borders — so four theme modes existed for two real appearances.

No governance

Without naming rules or ownership, styles were added ad hoc and drifted further from the code.

AI-assisted token audit

Before changing anything, I audited the existing variables and tokens with Claude — flagging invalid styles, duplicate values, overlong paths and structural gaps in the token hierarchy. What would have taken days of manual inspection became a prioritized remediation plan the team could review and agree on.

From findings to decisions

CollectionsLayersColor libraryFont library

Collections

~2–3× over the recommended range

• Each collection measured against ranges from large-scale CMS design systems
• Theme flagged: 4 themes instead of 2, component-based instead of semantic
• The 4th breakpoint (1600+) flagged for removal
• Roadmap: cut to 2 themes first (−50%), then consolidate into semantic tokens — the final Theme landed at 59

I moved the system from element-bound tokens to role-based semantic tokens — named for what a color does, not where it appears. Theme is now only for color switching, and Light and Dark resolve from the same set.

Shorter paths

colors/text/button/primary/default/base/disabled became foreground/disabled.

Semantic, not per component

Tokens describe a role — background, foreground, action — and every component shares them.

Collections reordered

Theme comes first, so designers see and choose semantic colors before anything else.

Color system principles

Two modes

Theme modes limited to Light and Dark, with primary, secondary and tertiary backgrounds in each.

Reusable, not specific

A variable is created only when multiple components need it.

Few pairings

Foreground and background combinations kept low — avoiding authorable colors on authorable backgrounds.

No over-tokenization

Names stay short, self-explanatory and searchable, grouped into bg, foreground, border, gradient, shadow and utility.

Sub-collections for multi-language

English and Japanese need different sizes, line heights and spacing to read well. Typography lives in Responsive EN with a Responsive JA sub-collection, each with its own dynamic scale across breakpoints. Components switch language without separate variants.

Theme          59  color switching
Responsive EN  88  language × responsive
└ Responsive JA
Scale          35  absolute values
Brand         195

• Responsive scale for widths and component paddings
• Retired Display, Lead and Quote sizes; added Label and Absolute
• Each style documents where it is used, e.g. Stat lg in Stat Block and Content Grid

Accessibility was built into the foundation rather than checked at the end. Fixes live in tokens and base components, so every page inherits WCAG AA across core interactive components.

CTA contrast

Fills and text CTAs raised to AA, including on gray backgrounds.

Inputs

Borders and text brought into AA contrast range.

Focus rings

AA-safe color, aligned to component bounds, on every interactive element.

Touch targets

Expanded from 16×16 to 28×28 and above.

Interactive states

Missing hover, focus, active and disabled states supplied.

Button · Color · Tag

Recreated in code from the audit. Colors are illustrative; contrast ratios are calculated live.

Card system: Card Block & List Item

• Use-case variant names (Event, Person, Episode…) removed
• Child variations handled at the child component level
• Compact image ratio changed from 3:2 to 16:9
• Eyebrow always aligned to the top

AEM authors constantly change text length, imagery and language. The Figma components had to flex the same way the code does.

Elastic components

Removed rigid line objects and fixed heights; text overflow and truncation are specified per component.

Authoring behavior

Re-specified component behavior around the authoring experience.

Grid alignment

Components adapt to the grid system and its sizing.

Image aspect ratios

Dynamic Media allows one profile per folder, so renditions should stay minimal: 22 → 7 ratios.

CompareBeforeAfter

BeforeFixed heights and minimum heights in the right slots — long content overflowed and broke the layout.

AfterHeights flex with content and always stack to the top. Background media is full-bleed; on desktop the image fills the space beside the left slot, on tablet and mobile it locks to 16:9.

Guides for authors and designers

I created AEM-compatible component templates and design guidelines, along with accessibility guidelines for both designers and content authors — so anyone can build accessible pages without needing to know the system's internals.

TemplatesComponentsAuthoring

Templates

Component Templates and Design Guidelines

• Templates to detach before use, with auto grid layout aligned to the CSS grid implementation for MCP
• Typography: 12px minimum, 16px+ for body copy, 14px+ for CTAs and navigation
• Semantic color tokens only; new tokens are reviewed before they are added
• Interaction semantics: CTA = action, Tab = section navigation, Tag = categorization
• Responsive validation across breakpoints and languages before review and hand-off

Figma MCP: one structure for design and code

I proposed Figma MCP to the development team as a shared bridge between design and code. Instead of treating the design system as data closed off inside Figma, I worked with engineers to make the token and component structure MCP-friendly — semantic tokens that map 1:1 to CSS classes, and auto layout aligned with the CSS grid — so what designers build is what MCP hands to code.

Decision

Preserve nested structures in Figma, and support engineering with clear hand-off documentation.

Aligned with the engineering team, we kept nesting where it reflects how components are built, and documented the edge cases and layout variations MCP can't interpret on its own.

The Content Grid replaced four legacy components. Its hand-off doc covers every background and layout, maps each element to its AEM authoring field, and charts which grid items work at which column count — the edge cases MCP can't infer.

Specs & authoringVariation chartResponsive & corner casesMaster components

• Each element numbered and matched to its AEM dialog field
• Section header, settings and grid item options
• Grid item types: Stat List, Stat List Text, Card Block and List Item