The first wave of Codex components were mostly represented in Phabricator by a single task that was passed from design to development, then back to design for review, then back to development for further work, and so on. This often led to:
- Confusion over the status of a component task
- Difficulty finding design/implementation details
- Long comment threads
- Lack of clarity as far as who should be assigned to a task at a given time
Additionally, components were fully designed then fully implemented. This led to:
- Additional design work or design decisions identified during component development or code review
- General lack of alignment between design and development until deep in the process
- Large, complex patches that took many days to finalize and merge
Finally, we'd like for people outside of the Design Systems Team to be able to propose components by adding a task with enough information to kick off the decision-making process. We'd also like smaller tasks for people outside the team to be able to pick up.
To resolve these issues, we'd like to:
- Create a process for iteratively designing and developing a component. This will mean more collaboration between design and development earlier in the process, smaller tasks and patches, the ability to distribute the work among more people, and a clearer Phab workflow.
- Develop a template for component epic tasks that gathers necessary information and walks us through this iterative process
Below is a draft of a template (I don't have permission to create a form in Phab) that we could eventually use to build component epic tasks.
Background
- Description: add a brief description of this component
- History: describe or link to prior discussions related to this component
- Known use case(s): describe known use cases for this component, including the project, team, and timeline
- Considerations: list any known challenges or blockers, or any other important information
User stories
- add at least one user story
Previous implementations
These artifacts are listed for historical context. The figma spec, linked below, is the source of truth for the new component.
- Design style guide: add Design Style Guide link, if applicable
- OOUI: add the relevant OOUI widget name here, if applicable. See OOUI demos.
- Vue: add any existing Vue implementations, if applicable. See Vue component inventory.
Codex implementation
Component task owners
- Designer: add the main designer's name
- Developer: add the main developer's name
Design spec
Once a component spec sheet has been created in Figma, remove the note stating that the spec is missing and link to the spec below.
A component spec sheet has not been created yet.
| Component spec sheet |
Stage 1: Minimum viable product (MVP)
MVP includes basic layout, default states, and most important functionality.
Acceptance criteria
- Determine what MVP includes for this component and document this in a subtask. Assign task to designer.
- Design MVP. Once complete, assign task to developer.
- Implement MVP
Stage 2: Additional states, features, and variants
This might include a disabled state, framed/frameless designs, transitions, supporting different use cases, etc., which will be captured in separate subtasks.
Acceptance criteria
- Document design and implementation of additional states and features in individual subtasks
- Complete each additional state/feature subtask
Stage 3: Refinement
This stage includes any final touches or bug fixes needed before the component can be deemed complete, which will be captured in separate subtasks.
Acceptance criteria
- Finalize docs: open and complete a subtask for any additional demos that need to be added or documentation that needs work
- Meet accessibility standards: open and complete a subtask for any necessary accessibility improvements
- Meet internationalization standards: open and complete a subtask to fix any i18n bugs
- Complete testing: open and complete a subtask for any additional unit or functional tests that are needed