Skip to content

Samsen Internal Framework

This is Samsen's internal framework content for Design Systems. It is read-only reference material.

Design System Maintenance Patterns

The Reality

80% of design system work is maintenance. After the initial build — the exciting part where you define tokens, create components, and ship the first version — the work shifts to keeping the system alive, consistent, and evolving.

This isn't failure. It's the nature of systems that serve real products. Products change, brands evolve, new patterns emerge, old ones deprecate. The system must keep pace.

Categories of Maintenance Work

Token Updates

The most common maintenance task. A brand refresh changes the primary color. A product decision changes the spacing scale. An accessibility audit requires contrast ratio improvements.

Each token change can cascade:

  • Primitive token changes → semantic tokens may need remapping
  • Semantic token changes → every component referencing that token updates
  • Component token changes → specific components update, others unaffected

With proper token architecture, this cascade is managed automatically. With poor architecture, it's manual and error-prone.

Variant Addition

Products constantly need new component variants:

  • "We need a compact version of this card for the sidebar"
  • "Can the button have an icon-only variant?"
  • "We need a loading state for every interactive component"

Each variant needs to be added in both Figma and code, with matching token usage and documented behavior.

Pattern Migration

When the system introduces a new pattern (e.g., moving from BEM to CSS modules, or from class-based variants to data attributes), existing components need migration. This is tedious, widespread, and exactly the kind of systematic work AI excels at.

Documentation Updates

Components evolve faster than their documentation. New props get added without docs. Usage examples become outdated. Context rules change but aren't updated.

Cross-Platform Consistency

Design systems serving multiple platforms (web, iOS, Android, email) need their tokens and components synchronized. A change in the web system needs to propagate to native implementations.

Deprecation

Removing old patterns is harder than adding new ones. Deprecation requires:

  • Identifying all usages of the old pattern
  • Providing migration guidance
  • Setting a timeline
  • Actually removing the old code once migration is complete

AI-Assisted Maintenance Patterns

Token Propagation

Task: Primary color changes from #2563eb to #1e40af.

Without AI: Manually find every file that references the old value (or the token that pointed to it), update, test, review. Hours of tedious work.

With AI: "Update --color-blue-500 to #1e40af and verify all semantic tokens that reference it still meet WCAG contrast requirements." Claude Code makes the change, runs contrast checks, flags any issues. Minutes.

Variant Generation

Task: Add a compact variant to the card component.

Without AI: Designer creates the variant in Figma, writes a spec, developer implements, QA reviews. Days across multiple people.

With AI: Designer creates the variant in Figma. Tells Claude Code: "Add a compact variant to the card component based on the Figma file. Use --spacing-sm for padding instead of --spacing-md. Reduce the title to --font-size-caption." Claude Code implements, designer reviews in browser. Minutes.

Systematic Migration

Task: Migrate all components from CSS modules to Tailwind utility classes.

Without AI: Developer manually rewrites every component's styling. Weeks of work.

With AI: "Migrate the Button component from CSS modules to Tailwind utility classes. Use the existing token mapping: --spacing-md maps to p-4, etc." Repeat for each component. Claude Code handles the mechanical transformation, human reviews the output.

Documentation Sync

Task: Update component documentation to match current implementation.

Without AI: Someone has to read the code, compare to docs, update manually. This task is perpetually deprioritized.

With AI: "Read the current Button component implementation and update its documentation to match. Include all current props, variants, and usage examples." AI reads code, generates accurate docs.

The Maintenance Mindset

The 80/20 split (80% maintenance, 20% new development) isn't something to fix — it's something to optimize. The goal isn't less maintenance. It's faster, more reliable maintenance.

AI doesn't eliminate maintenance work. It changes the economics:

  • Tasks that took hours take minutes
  • Tasks that required developer expertise can be directed by designers
  • Systematic changes that were too tedious to prioritize become feasible
  • Documentation stays current because updating it is trivial

This is the practical payoff of the Shipping AI Designer framework. Not just building new things faster, but keeping existing things healthy with less effort.