462: Refactoring a Design System

What It Covers

Marshall Bock shares lessons from refactoring his design system during a no-meeting week at his company. He covers creating component tracking spreadsheets, establishing naming conventions with emojis, organizing variant properties, managing Figma libraries, and developing meta-organization strategies. He discusses breaking changes, template creation, and maintaining design system hygiene through regular quarterly audits.

Key Questions Answered

• •Component Audit Tracking: Create a spreadsheet with heat map colors (red to green) evaluating each component across multiple dimensions: production match accuracy, color variable usage, typography consistency, layer naming, component properties, and variant implementation. Add letter grades (A+ to F) based on the worst-performing dimension to identify refactoring priorities and visualize system health at a glance.
• •Property Organization Hierarchy: Order component properties from global to local (type, size, layout, style, orientation, device), then visually top-to-bottom and left-to-right. Place text editing properties directly under their visibility toggles so related controls appear adjacent. Use consistent emojis for each property type (eyeball for visibility, pencil for text, diamond for icons) to enable rapid scanning of the properties panel.
• •Component Description Templates: Structure descriptions with rich text formatting: component name, home library, short description, and usage guidelines. Use code styling for interface terms like "fill width" or "height." Include cross-reference links to related subcomponents. Add SEO tags at bottom for alternative search terms (example: "message bubble left" component includes "comments" tag for discoverability).
• •Library Migration Strategy: When moving components between Figma libraries, enable both libraries for each other first. Cut and paste components together with their underscored subcomponents in a single operation to maintain connections, since unpublished subcomponents lose references when separated. Publish immediately after pasting to prevent breaking downstream instances. Frame links break when moved between files but persist within files.
• •Meta-Organization Philosophy: Organize library files for maintainer efficiency (back-of-house) rather than end-user presentation (front-of-house). Use auto layout with doubling padding scale: 32pt radius and spacing within components, 64pt padding around components, 128pt between labeled groups, 256pt between categories, 512pt between major sections. Scale font sizes proportionally so labels remain readable at different zoom levels.