SOP: Creating & Managing Shared Master Libraries

1. Purpose

To define the process, governance, and responsibilities for creating and maintaining shared master libraries that power all project-specific design systems.

This ensures consistency across projects, scalability, and smooth design–dev alignment.

2. Scope

  • Applies to all design teams, leads, and developers who use shared libraries.
  • Covers setup, publishing, maintenance, contribution, and version control.
  • Includes tokens, components, variants, and patterns.

3. Why This Matters

  • Without a single shared library → each project drifts in its own direction.
  • Duplicated components = dev confusion, QA mismatches.
  • Shared libraries provide:
    • Efficiency: Reuse, don’t reinvent.
    • Consistency: Same button looks and behaves the same across all projects.
    • Scalability: One update = cascades to all consumers.

4. Library Setup

Stage A – Foundations First

  1. Create a Foundations File:
    • Tokens: Color, Spacing, Typography, Radius, Shadows.
    • Exportable to dev via Style Dictionary / JSON.
  2. Create a Components File:
    • Buttons, Inputs, Cards, Modals, Navigation, Alerts, Tables.
    • Each with full variants + states.
  3. Create a Patterns File:
    • Assemblies (pricing cards, dashboards, forms).
    • Document with usage guidelines.
  4. Organize Figma Pages:
    • 01 Foundations → Tokens.
    • 02 Components → Atomic components.
    • 03 Patterns → Assemblies & flows.
    • 04 Archive → Deprecated items.

5. Publishing & Version Control

  • Initial Publish: Version v1.0.
  • Micro Changes: Bug fixes, visual tweaks → v1.0.1.
  • Minor Changes: New components added → v1.1.
  • Major Changes: Breaking updates → v2.0.
  • Always publish with a changelog entry (Doc 10.8: Component Review Log).
  • Consumers must update to latest version within 1 sprint unless breaking.

6. Governance & Contribution Model

  • Only Design Leads can approve new components into master.
  • Designers submit requests via Contribution Log (Doc 10.9).
  • Dev Leads consulted before publishing breaking updates.
  • Deprecated components tagged with Deprecated_DO-NOT-USE for 1 sprint before deletion.
  • Monthly audit → remove unused orphans, normalize tokens.

7. Maintenance Workflow

StepActivityTool/Doc ReferenceOwner
1New request loggedContribution Log (Doc 10.9)Designer
2Peer reviewComponent Consistency Checklist (Doc 4.7)Peer Designer
3Lead approvalDoc 10.2 + Doc 10.3Design Lead
4Dev feasibility checkToken–Component Sync Map (Doc 10.6)Dev Lead
5Version tag & publishDoc 10.8 ChangelogDesign Lead
6Notify consumersSlack/Email update + migration tableDesign Ops
7Monitor adoptionAudit Sheet (Doc 5.6 style)QA Lead

8. Failure Handling

  • If consumers find broken components → log issue in Component Review Log.
  • Urgent bug fixes → publish hotfix vX.Y.Z (same day).
  • If duplicate components appear → merge, deprecate old, document replacement.

9. Exit Criteria Before Publish

  • Tokens normalized, no raw hex/manual styles.
  • Variants/states complete.
  • Naming conventions aligned.
  • Documentation updated (Doc 10.2).
  • Peer + Lead review complete.
  • Dev feasibility confirmed.
  • Changelog prepared.

10. Usage Notes

  • Treat master library as codebase: no casual edits.
  • Consumers must not detach or override → log a request instead.
  • Master library sync must be reviewed monthly with dev team.