Skip to content

Proposal: Path to UI kit v2

UI kit improvements (&22) • Unassigned lays out a vision for a UI kit that addresses existing challenges.

This issue explores different approaches, tradeoffs, and constraints to consider while working towards making this reality.

WIP raw bullets

  • Base components & dark mode
    • refactoring from base-components to not-base-components will be breaking changes
    • there is a time cost for designers migrating their components
    • our hypothesis is dark mode compatibility will be a good incentive for designers, making the cost worthwhile
    • that is, if we make only the new version of the component dark mode compatible, designers will update to the new component
      • note: at this time there are no known constraints that require new component architectures to support dark mode
    • note: Workshop file created to figure out how we want these new components to be architected https://www.figma.com/file/64nRef1iJPk3IOQ6FP08Dr/UI-kit-v2-workshop?type=design&mode=design&t=ra3cPjLQjZ3BJgnO-0
  • Moving non-design system things out of the component library
    • This requires a duplication, or a deprecation, move, and migration process for these things. Examples include:
      • Navigation
      • Merge request reports
      • Severity status
    • Owners/maintainers need to be identified for these
  • Remove circular dependencies
    • Create files for 'extensions'
    • Deprecation, move, and migration
    • Constructed with self contained styles
  • Early proposals were to put the existing UI kit 'on ice', that is no updates, and create a new UI kit from scratch. This new UI kit would be installed alongside the existing or would be big bang launched when complete
    • Benefits
      • Simpler to build
      • No historic artefacts / file ghosts
      • (If we stop milestone releases) faster publish cycles
    • Disadvantages
      • If big bang launch: Value and learning withheld, delay designers having access to dark mode components, delay learning about designer token use
      • If alongside launch: Designers pulling from two libraries might cause confusion
      • Maintaining two UI kits
  • Proposal, build the UI kit iteratively in-situ, using usual deprecate and release processes
    • Benefits
      • We can keep designer incentive if we refactor and update to use design tokens in the same action
      • Single component library to maintain
      • Value delivery not delayed
      • Easier designer experience (single library, no big bang migation)
    • Disadvantages
      • More upfront maintainer effort
        • Nested components
        • Branching issues
      • Historic artefacts / file ghosts exist
    • Ghost mitigation
      • We can still move to a clean file later using Figma swap library. After a certain update/migration threshold has been met here's how we could do it:
        • 1. Create clean file, with the same components as our now fully updated component library. Important: To avoid breaking changes component names and properties must be identical. This should be a 1:1 copy
        • 2. Turn on the new library by default in files, turn off the old one
        • 3. Instruct designers to use swap library, we might even be able to force this programatically using the API
        • 4. Unpublish the old library
        • 5. Remove the old library
Edited by Dan MH