Background/Goal

Provide a baseline level of guidelines and supporting documentation so that design system contributors can easily onboard, with minimal assistance.

User stories

Design Contributors:

• Design guidelines for consultation:
  • Component Catalog: As a designer, I can easily locate components supported by the design system and their current state. (Figma | Codex demo)
  • Visual Styles (Design Tokens) Guidelines: As a designer, I can easily locate and understand defined visual styles (design tokens) that should be leveraged when designing (T313933) (Design Tokens overview)
  • Tokens Catalog: As a designer, I can easily locate what tokens have been created/codified (T313935) (Figma | Codex demo)
  • Icons: document how to use icons in the different design projects T301328

• Design guidelines for contribution:
  • Component design process: As a designer, I understand the steps I need to follow to design new components (T312023) or redesign the existing ones (T312024).
  • Icon design process: As a designer, I understand the steps I need to follow to design new icons or redesign existing ones (T312025).
  • Token design process: As a designer, I understand the steps I need to follow to design new tokens or update existing ones. (We could repurpose T295605)

Front-End Development Contributors:

• Design System Repo: As a front-end developer, I can easily locate the Design System code.
• Code Contribution Guidelines: As a front-end developer, I understand the steps required to merge and/or update code related to the Design System.

Cross-Functional Front-End Contributors:

• Component Management Guidelines: As a front-end development team, we need to know how to determine whether we should extend an existing component (aka variation) or add a new component.
• Component Creation Guidelines: As a front-end development team, we need know how to contribute NEW components to the design system.
• Design Guidelines: As a front-end development team, we need to ensure that components are accessible and meet accessibility standards.
• Component Testing Guidelines: As a front-end development team, we need to ensure that components work as expected.

Considerations

• We will focus on completing governance and guidelines that make it easier to onboard design system contributors.
• This is NOT meant to include all potential documentation we will eventually need or want to create.

Development considerations

[to come]

Acceptance criteria

• There is a single source of truth for each user story (aka document)
• All documentation should link back to a central Design System Portal/Wiki
• Documents should be:
  • easy to read (limited jargon),
  • clear to follow (written as steps, checklists, visual diagrams, etc.)
  • Concise and to the point (not verbose)
• Access to documents should NOT be restricted for viewing by target users (aka remove or update permissions as necessary)

Test scenarios

[to come]

Open questions

[to come]