Design System Operating Plan

B2B SaaS Web Application — Comprehensive Design System Initiative

1. Executive Summary

This plan establishes a design system to resolve inconsistent UI, eliminate one-off CSS, introduce shared design tokens, and accelerate design-to-dev handoff. The system will be built incrementally by a small team (2 designers, 6 engineers) with first measurable impact targeted within 6 weeks. Accessibility (WCAG 2.1 AA minimum) is a non-negotiable requirement throughout.

2. Current State Assessment

Problems Identified

• Inconsistent UI: Screens use different spacing, typography, colors, and component patterns for the same interactions.
• One-off CSS: Duplicated and conflicting styles scattered across the codebase, increasing maintenance burden and regression risk.
• No shared tokens: Color values, font sizes, spacing units, and breakpoints are hardcoded in individual files rather than centralized.
• Slow design-to-dev handoff: Designers specify intent in Figma; engineers re-interpret from scratch each time, leading to drift and rework.

Impact of Current State

• Higher bug rate on visual/layout issues
• Longer cycle time for new features (each screen is designed/built from zero)
• Accessibility gaps: no systematic color contrast enforcement, inconsistent focus states, missing ARIA patterns
• Onboarding friction for new team members

3. Design System Vision and Principles

Vision

A single source of truth — shared tokens, documented components, and usage guidelines — that lets any designer or engineer ship consistent, accessible UI without re-inventing patterns.

Guiding Principles

1. Adopt, don't invent: Start from what already exists in the product. Extract and standardize the best current patterns before creating anything new.
2. Tokens first: Every visual decision (color, spacing, typography, elevation, motion) flows from a token. No magic numbers.
3. Accessible by default: Components ship with correct contrast ratios, focus management, keyboard navigation, and ARIA attributes baked in. Accessibility is not a post-hoc audit.
4. Small surface, high coverage: Prioritize the 15-20 components that cover 80%+ of screens. Resist scope creep.
5. Living system: The design system is a product, not a project. It ships continuously alongside the application.
6. Documentation is the UI: If it's not documented, it doesn't exist in the system.

4. Team Structure and Roles

Dedicated Roles (Part-Time Allocation)

Governance

• Weekly sync (30 min): Review progress, unblock issues, triage requests.
• Bi-weekly design review (45 min): Walk through new components, get feedback from full team.
• RFC process for new components: Any team member can propose; requires sign-off from Design Lead + System Lead before work begins.

5. Technical Architecture

5.1 Design Tokens

Format: Define tokens in a platform-agnostic format (JSON or YAML) and transform to CSS custom properties, SCSS variables, and JavaScript constants via a build step (e.g., Style Dictionary or a lightweight custom script).

Token Tiers:

Global Tokens (primitive)
├── color.blue.500: #2563EB
├── color.neutral.100: #F5F5F5
├── spacing.4: 16px
├── font.size.md: 16px
└── ...

Semantic Tokens (alias)
├── color.text.primary → color.neutral.900
├── color.text.secondary → color.neutral.600
├── color.action.primary → color.blue.600
├── color.action.primary.hover → color.blue.700
├── color.border.default → color.neutral.200
├── spacing.component.padding → spacing.4
└── ...

Component Tokens (scoped)
├── button.color.background → color.action.primary
├── button.color.text → color.neutral.white
├── input.border.color → color.border.default
├── input.border.color.focus → color.action.primary
└── ...

Accessibility Enforcement at Token Level:

• All foreground/background token pairings must meet WCAG AA contrast (4.5:1 for normal text, 3:1 for large text).
• Focus indicator tokens must produce visible outlines meeting 3:1 contrast against adjacent colors.
• Automated contrast checks run in the token build pipeline.

5.2 Component Library

Technology: Build as a shared package within the existing monorepo (or as an internal npm package if using a multi-repo setup). Use the same framework as the application (React assumed here; adjust if Vue/Angular/Svelte).

Component API Conventions:

• Props use semantic names, not visual ones (variant="primary" not color="blue")
• All interactive components accept standard HTML attributes via spread/rest props
• Every component forwards refs
• Every component supports a className escape hatch for edge cases (but discouraged in docs)
• TypeScript interfaces for all props

Accessibility Requirements per Component:

• Correct semantic HTML element (button is <button>, not <div>)
• ARIA roles/attributes where native semantics are insufficient
• Keyboard interaction pattern matching WAI-ARIA Authoring Practices
• Visible focus indicator using the system focus token
• Color is never the sole means of conveying information
• Motion respects prefers-reduced-motion

Component Folder Structure:

src/design-system/
├── tokens/
│   ├── global.json
│   ├── semantic.json
│   └── build.js
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.styles.ts (or .module.css)
│   │   ├── Button.test.tsx
│   │   ├── Button.a11y.test.tsx
│   │   ├── Button.stories.tsx
│   │   └── index.ts
│   ├── Input/
│   ├── Select/
│   ├── Modal/
│   └── ...
├── hooks/
│   ├── useFocusTrap.ts
│   ├── useKeyboardNavigation.ts
│   └── ...
├── utils/
│   └── a11y.ts
└── index.ts (barrel export)

5.3 Styling Strategy

Approach: Replace one-off CSS with token-based styles. Recommended migration path:

1. Introduce CSS custom properties derived from tokens at the :root level.
2. New components use only token-based custom properties (no hardcoded values).
3. Existing screens migrate incrementally: when a feature touches a screen, swap hardcoded values for tokens.
4. Add a stylelint rule to warn/error on raw color hex values and pixel values outside the token scale.

5.4 Documentation Site

Use Storybook as the documentation and development environment:

• Stories for every component: Default state, all variants, edge cases (long text, empty state, loading state).
• Accessibility tab: Integrated axe-core addon showing live violations.
• Design token page: Visual display of all tokens (color swatches, type scale, spacing scale).
• Usage guidelines: When to use, when not to use, do/don't examples.
• Code snippets: Copy-pasteable usage examples.

6. Component Prioritization

Tier 1 — Foundation (Weeks 1-3)

These are the atomic building blocks that everything else depends on:

Tier 2 — Core Patterns (Weeks 3-5)

Tier 3 — Composite (Weeks 5-6+)

7. Six-Week Execution Plan

Week 1: Foundation and Audit

Design:

• Audit top 10 most-visited screens: screenshot, annotate every unique color, font size, spacing value, and component variant
• Propose consolidated token set: colors (8-12 semantic colors), type scale (6 sizes), spacing scale (8 values), border radii, shadows
• Set up Figma token library using proposed values

Engineering:

• Set up design system directory structure in repo
• Implement token build pipeline (JSON source -> CSS custom properties + JS constants)
• Inject token CSS custom properties into app root
• Configure Storybook with accessibility addon (axe-core)
• Add stylelint rule to flag raw hex colors (warning mode, not blocking)

Milestone: Token pipeline running; Figma library draft shared for review.

Week 2: First Components

Design:

• Finalize token values based on team feedback
• Create Figma component specs for Button (all variants: primary, secondary, ghost, destructive; all sizes; all states: default, hover, focus, active, disabled, loading)
• Create Figma component specs for Input (text, with label, with error, with helper text, disabled)

Engineering:

• Build Button component with full variant/size/state matrix
• Build Input component (text) with label, error, helper text, disabled states
• Build Typography components (Heading, Text, Label)
• Write unit tests and accessibility tests for each
• Write Storybook stories for each

Milestone: 3 production-ready components in Storybook with passing a11y tests.

Week 3: Layout and Expansion

Design:

• Spec layout primitives (Stack, Flex, Grid helpers)
• Spec Icon system (size variants, color inheritance)
• Spec Select, Checkbox, Radio components
• Begin writing usage guidelines for completed components

Engineering:

• Build layout primitives (Stack, Flex, Grid)
• Implement icon system (SVG sprite or individual imports with standard sizing)
• Build Select component with keyboard navigation
• Build Checkbox and Radio components
• Begin first migration: pick one high-traffic screen and replace hardcoded styles + one-off components with system components

Milestone: Layout system usable; first screen migration underway.

Week 4: Interactive Patterns and Migration

Design:

• Spec Modal/Dialog with focus management requirements
• Spec Table component (sortable headers, row selection, empty state)
• Spec Toast/Alert patterns
• Document do/don't guidelines for all Tier 1 components

Engineering:

• Build Modal/Dialog with focus trap hook
• Build Table component (basic: header, rows, responsive behavior)
• Build Toast/Alert component with auto-dismiss and screen reader announcements
• Build Card and Badge components
• Complete first screen migration; begin second screen migration
• Measure: count remaining one-off CSS files vs. token-based files

Milestone: All Tier 2 components in progress; 2 screens migrated.

Week 5: Composition and Handoff

Design:

• Spec composed Form pattern (field groups, validation display, submission states)
• Spec Navigation components (sidebar, topbar)
• Create "kitchen sink" Figma page showing all components together
• Establish Figma-to-code handoff workflow: designers annotate with component names and prop values, not visual specs

Engineering:

• Build Form composition layer (FormField wrapper, validation integration)
• Build Tabs component
• Build Pagination component
• Build Tooltip/Popover with accessible dismiss patterns
• Promote stylelint rule from warning to error for new files
• Migrate 2 more screens (total: 4 screens on design system)

Milestone: Full Tier 1-3 component set available; handoff workflow documented.

Week 6: Polish, Document, and Measure

Design:

• Complete documentation for all components (usage guidelines, do/don't, accessibility notes)
• Run accessibility audit on all components using screen reader (VoiceOver + NVDA or JAWS)
• Create onboarding guide: "How to use the design system" for new team members

Engineering:

• Fix any accessibility issues found in audit
• Performance review: ensure component bundle adds < 30KB gzipped to app
• Add CI checks: a11y tests run on every PR; Storybook deploys on merge
• Migrate 2 more screens (total: 6 screens on design system)
• Document: contribution guide for adding new components

Milestone: Design system v1.0 declared; 6 screens migrated; CI pipeline enforcing standards.

8. Design-to-Dev Handoff Process (New)

Before (Current Pain)

1. Designer creates mockup in Figma with arbitrary values
2. Engineer inspects Figma, eyeballs spacing and colors
3. Engineer writes custom CSS to approximate the design
4. Designer reviews, finds discrepancies, files feedback
5. Cycle repeats 2-3 times

After (With Design System)

1. Designer composes screen in Figma using component library and token values
2. Designer annotates: "This is <Button variant='primary' size='md'>, <Input error={true}>, spacing is spacing.6"
3. Engineer assembles screen using system components and token classes — no custom CSS for standard patterns
4. Designer reviews: matches 1:1 because both reference the same system
5. One round of review (if any) for layout/content, not styling

Expected Time Savings

9. Accessibility Plan

Standards

• Target: WCAG 2.1 Level AA compliance
• Stretch: WCAG 2.2 Level AA for new components

Automated Testing

Manual Testing Cadence

Component-Level Requirements Checklist

Every component PR must confirm:

• Renders correct semantic HTML element
• Has accessible name (visible label or aria-label)
• Keyboard operable (Tab, Enter, Space, Escape, Arrow keys as appropriate)
• Focus indicator visible and meets 3:1 contrast
• Color contrast meets 4.5:1 (text) or 3:1 (large text, UI components)
• States (error, disabled, loading) communicated to assistive technology
• No information conveyed by color alone
• Respects prefers-reduced-motion for animations
• jest-axe test passes with zero violations
• Tested with VoiceOver (macOS) — reads sensibly

10. Migration Strategy

Approach: Incremental Adoption, Not Big Bang

Rewriting the entire app to use the design system at once would stall feature work. Instead:

Rule 1: All new screens/features use the design system. No exceptions after Week 3.

Rule 2: Existing screens migrate when touched. If a feature or bug fix touches a screen, that screen gets migrated to system components as part of the work. Budget +30% time on that ticket for migration.

Rule 3: Dedicated migration sprints for high-traffic screens. The top 10 screens (by usage analytics) get explicitly scheduled for migration, 2 per week.

Migration Checklist per Screen

• Replace hardcoded colors with token CSS custom properties
• Replace hardcoded spacing/sizing with token values
• Replace custom button implementations with <Button> component
• Replace custom input implementations with <Input> component
• Replace custom modals with <Modal> component
• Replace custom tables with <Table> component
• Remove orphaned CSS that is no longer referenced
• Run axe-core on migrated screen — zero violations
• Visual regression test (screenshot comparison) — no unintended changes
• Designer sign-off

Migration Tracking

Maintain a spreadsheet or project board:

11. Success Metrics

Leading Indicators (Track Weekly)

Lagging Indicators (Track Monthly After Launch)

12. Ongoing Governance (Post-6-Weeks)

Component Lifecycle

1. Proposal: Anyone files an RFC (1-page template: problem, use cases, API sketch, accessibility considerations).
2. Review: Design Lead + System Lead review within 1 week. Approve, request changes, or redirect to existing component.
3. Build: Assigned engineer builds; designer provides Figma spec.
4. Review: Code review + design review + a11y review.
5. Ship: Merge, publish to Storybook, announce in team channel.
6. Deprecate: When a component is superseded, mark as deprecated in Storybook with migration guide. Remove after all usages migrated.

Versioning

• Use semantic versioning for the design system package.
• Breaking changes (prop renames, removed variants) require a minor or major version bump and a migration guide.
• Maintain a CHANGELOG.

Health Checks

• Monthly: Review adoption metrics. Are new screens using the system? Are old screens getting migrated?
• Quarterly: Full accessibility audit (automated + manual). Review component request backlog. Assess if token values need updates (brand refresh, new product areas).
• Annually: Major review — is the architecture still serving the team? Evaluate tooling updates (Figma plugins, Storybook versions, testing tools).

13. Risks and Mitigations

14. Tools and Infrastructure

15. Quick-Start Checklist (Day 1)

For the team lead kicking this off:

• Get leadership buy-in: present this plan, secure time allocation commitment
• Create #design-system Slack channel
• Assign Design System Lead and Design Lead roles
• Set up design system directory in codebase
• Install and configure Storybook
• Schedule recurring weekly sync (30 min) and bi-weekly design review (45 min)
• Begin screen audit (assign top 10 screens across both designers)
• Draft initial token set from audit findings
• Create project board with Week 1 tasks

This plan is designed to deliver tangible value within 6 weeks while establishing sustainable practices for long-term design system health. The key insight is to start with tokens (the foundation everything else builds on), prioritize components by actual usage, and migrate incrementally rather than attempting a risky big-bang rewrite.