Page MenuHomePhabricator

Governance & Guidelines: Publish Guidelines & Documentation required for Design System Contribution V1
Closed, InvalidPublic7 Estimated Story PointsGoal

Description

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]

Related Objects

StatusSubtypeAssignedTask
InvalidGoalDAbad
Resolvedldelench_wmf
ResolvedDAbad
ResolvedSpikeDAbad
ResolvedDAbad
ResolvedDAbad
ResolvedDAbad
DuplicateNone
Resolvedldelench_wmf
DuplicateNone
Resolvedldelench_wmf
ResolvedSpikeDAbad
ResolvedDAbad
OpenNone
Resolvedegardner
OpenNone
ResolvedDAbad
ResolvedDAbad
ResolvedDAbad
ResolvedDAbad
DuplicateNone
ResolvedAnneT
ResolvedDAbad
ResolvedDAbad

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
DAbad renamed this task from Governance & Guidelines: Publish Guidelines & Documentation Required for Design System Contribution to Governance & Guidelines: Publish Guidelines & Documentation Required for Design System Contribution V1.Jul 27 2022, 2:53 PM

Thanks for creating this, @DAbad! Can I suggest an addition to the "Documents should be:" list under acceptance criteria? I think it's important for us to keep documentation as short and scannable as possible, so I would suggest that we require that documentation is concise, or if it must be longer, we require a bulleted summary that appears at the top in a consistent format. We've done a version of this within the (very long) code contribution guidelines, where we sometimes include a "TL;DR" block above a long section (unit tests, for example). Standardizing something similar across our documentation might help make it all more predictable and readable.

Thanks for creating this, @DAbad! Can I suggest an addition to the "Documents should be:" list under acceptance criteria? I think it's important for us to keep documentation as short and scannable as possible, so I would suggest that we require that documentation is concise, or if it must be longer, we require a bulleted summary that appears at the top in a consistent format. We've done a version of this within the (very long) code contribution guidelines, where we sometimes include a "TL;DR" block above a long section (unit tests, for example). Standardizing something similar across our documentation might help make it all more predictable and readable.

I added a bullet "concise and to the point". I think we can define what that looks like by document as it is unlikely a one-size fits all approach would work. For example, design style principals will inherently be longer, but we can add a FAQ, etc to make it easier to digest. Let's maybe put suggestions for format under the relevant documentation tickets on this Epic

In conversation with Designers, may want to add a task for iconography contribution workflow as we are getting consistent requests for this from designers.

DAbad changed the subtype of this task from "Task" to "Goal".
Volker_E renamed this task from Governance & Guidelines: Publish Guidelines & Documentation Required for Design System Contribution V1 to Governance & Guidelines: Publish Guidelines & Documentation required for Design System Contribution V1.Sep 6 2022, 5:28 PM

@DAbad, during a conversation with @bmartinezcalvo, we realized that the current documentation structure of our demo site might need to be adjusted in order to make room for new sections derived from the work on the governance & guidelines documentation. We hope that this will also bring some order to the existing content. We documented said task, together with a proposal, in T317198.

Volker_E changed the point value for this task from 5 to 7.Dec 20 2022, 9:37 PM

@ldelench_wmf I think this epic task T311671 should be part of this task since design contributors will need to consult the UX writing guidelines when designing. Also developers could consult these guidelines in some moment.

The Design Systems team is removing the majority of our "tracking" tasks like this one.
Subtasks will be unlinked.