---
robots: nofollow, noindex
tags: component, convergence, plan
---
Quesiton on other platforms? Alignment vs convergence.
# RFC: Fluent UI compoent process - WIP
Contributors: Mak, Ben, Josche, Aneesha, David
## Summary
This RFC covers a proposal for a process to track and bring clarity to the engineering work required to build a Fluent UI Next component
## Problem statement
We have had difficulty talking about the status of our converged components. If they are done, inprogress, what is done, whether they are ready to use or not, etc. The reality is that convergence is not just a single step, it's a long effort with multiple checkpoints along the way that all may be in varying states of progress. Therefore simply tracking a single component's status is not sufficent.
We also need to, as a team, both focus on and scale out the component convergence effort. If things go well, we will have many components in flight at the same time. For this to work, we will need a way to know what is in progess, and what will be needed to keep the progress moving.
## TODOs
- [ ] Need a wiki for preparation steps - [Ben overall wiki]
- [ ] Need process for component spec - [Justin]
- [ ] Component implementation guide - create package script, introduce tokes, styling, etc. Script+Readme - [Josche]
## Proposal
To solve the above problem, we propose a few things
1. The phases of convergence
2. A component spec template and review process
3. A GitHub issue template to track detailed component status
4. An update to the existing component spreadsheet to track high level status
### 1. The Phases of convergence
The purpose of the phases of convergence is to give us both a common langauge to discuss both what needs to be done to "converge" a component, as well as to understand how far along we are.
- Preparation
- Design spec
- Open UI Research complete - Mak
- Comparison on v7 and v0 complete (react native encourage alignment?)
- Gather open GitHub issues related to component in epic issue
- Package scaffolded with /next folder
- Component Spec authored and reviewed - Justin
- Including what has been tried/done so far
- Including example usage for key scenarios
- Including migration steps from v7 and v0
- Including accessibility spec
- Token names
- **Deliverable:** Reviewed component spec
- Implementation
- Implement component
- Add storybook stories
- Add tests - Conformance, Unit, and VR
- **Deliverable:** Experimental component ready for partner use
- Has README covering basic usage or add to docsite if we have it
- Has initial migration guide from v7 and v0
- Validation
- Add and validate in UI Builder
- Validate with token pipeline
- Validate in product
- Finalize migration guide
- Author codemods
- **Deliverable:** Preview component ready for broader/3rd party use
### 2. Spec review process and Template [TODO]
The goals of the spec review process are to enable asynchronous reviews, authors of components not within our immediate team, and unblocking incremental progress on implementing the component.
Preqs:
- Package is scaffolded (where API.md will be added)
- Research, comparison, issue analysis can be performed ahead of time
Steps:
1. Spec should be added as API.md file in component package folder
2. Spec review takes place async in PR
- PR is for adding API.md and other files to the package folder
4. Schedule an initial meeting to review spec
- Initial spec review meeting should focus on progress through spec and track contenious issues in PR for follow up later
5. Follow up offline on open issues from initial review
- It's fine to schedule follow up discussions or meetings as needed
#### Proposed Sections of Spec
Based on: https://github.com/microsoft/fluentui/tree/master/specs
Recomendation: Write a component.types.ts file instead of documenting props in markdown table
- **Background**
- **Prior Art**
- Link to open UI research
- Link to comparison of v7 and v0
- Link to GitHub epic issue
- **Sample Code**
- Provide some representative Sample code
- **Variants**
- **API**
- **Props** - Link to component.types.ts
- **Slots**
- **Structure**
- Public
- Internal
- DOM Structure
- **Migration**
- Migration from v7
- Migration from v0
- **Behaviors**
- Component States
- Interaction
- Keyboard
- Cursor
- Touch
- **Accessibility**
- Screenreader accessibility
### 3. GitHub Issue template
Below is the propose GitHub Issue template. We would have 1 per component. This is the source of truth for status on component convergence.
From: [#15759](https://github.com/microsoft/fluentui/issues/15759)
> # Preparation:
> - [ ] Open UI Research complete
> - [link to https://open-ui.org/]
> - [ ] Comparison on v7 and v0 complete
> - [link to issue]
> - [ ] Gather open GitHub issues related to component in epic issue
> - [link to issue]
> - [ ] react-* package scaffolded
> - [link to package]
> - [ ] Component Spec authored and reviewed
> - [link to spec in component package]
> - [ ] **Deliverable:** Reviewed component spec
>
> # Implementation
> [link to react-* package folder]
> - [ ] Implement component
> - [ ] Add storybook stories
> - [ ] Add tests - Conformance, Unit, and VR
> - [ ] Write README.md covering basic usage
> - [ ] Write initial MIGRATION.md guide (include v7 and v0)
> - [ ] **Deliverable:** Experimental component ready for partner use
>
> # Validation
> - [ ] Add and validate in UI Builder
> - [ ] Add and validate in docs site
> - [ ] Validate with token pipeline
> - [ ] Validate in product
> - [ ] Finalize migration guide
> - [ ] Author codemods
> - [ ] **Deliverable:** Preview component ready for broader/3rd party use
### 4. Tracking sheet
[TODO screenshot]
### Pros and Cons
:+1: Gives structure and clarity to convergence
:+1: Allows us to provide status and rough ETAs to partners
:-1: Has the risk to just add more overhead tracking things
## Discarded Solutions
This is the first try at a solution. We did iterate on some small choices around where we put the spec.
## Open Issues
[TBD]
---
# :warning: Below here is old
---
# Component Refresh + Convergence Schedule
Needed for MetaOS
- Variants support
- And full styling control through tokens
S = 2 weeks, M = 1+ month, L = months
## Q4 2020 (July - September)
- [x] Button
## Q1 2021 (October - December) - for //BUILD
- [ ] Separator (S) - Josche/Mak
- A bit trivial
- Good first component
- Not started
- [ ] Link (S) - Mak
- Not started
- [ ] Avatar (S) - Ben
- [ ] Recompose it to replace PersonaCoin
- [ ] Colors based on the name
- [ ] Callout (M) - Mak
- [ ] Text (S) - Shift?
- [ ] Not many updates needed
- [ ] A few variants updates
- [ ] Menu (XL) - Ben
- Important and Large
- Balance between menu and contextual menu
- [ ] Icon (M) [#15434](https://github.com/microsoft/fluentui/issues/15434) - Tomi
- [ ] Needs discussion (RFC)
- [ ] FocusZone (XS) - Mak
- [ ] Update to function component
- [ ] FocusTrapZone (S) - Mak
- [ ] Move to focus package?
- [ ] Dropdown (XL) ???
- What about combo box?
- Collaborate on spec
- [ ] Image (S) - Shift?
- [ ] Performance issues with v7 Image component
- [ ] We should get this out soon
- [ ] Badge/Status (S) - Lingfan
- [ ] Tied up to Avatar and questions about presence
- [ ] Card (S) - Mak
- Mostly done?
## Q2 2021 (April - May)
- [ ] Tabs - (M) - Ben
- [ ] Variants updates
- [ ] Move to hooks composition
- [x] Rename
- [ ] Remove old button dependency
- [ ] Support for slots and tokens
- [ ] Tooltip (L) [#15102](https://github.com/microsoft/fluentui/issues/15102) - Mak or Josche
---
Start in Q4 but finish in Q1
## Q1 2021 (Jan - March)
- [ ] TextField (M) - Elizabeth?
- What about form validation?
- [ ] Dialog (?)
- [ ] Checkbox (S) - contribute
- [ ] RadioGroup (S) - contribute
- [ ] Label (S) - contribute
- [ ] Toggle (S) - contribute
- [ ] Slider (S) - contribute
- [ ] Spinner/Loader (S) - contribute
## Q2 2021 (April - June)
## Q3 2021 (July - September)
## Challenges converging
- Full convergence is v0 and v8 is same component
- Including styling
- Good thing
- Going forward dive into styling
- Difficult little things
- In order for changes to be consumed by teams. Need to be better
- Have to be able to believe our story on why to pickup converged components
- Sensitivity around updates
- Teams has a lot of inline style overrides
- We are trying to reduce this, will be costly teams to adopt
- Key next steps
- Integrate button in a scenario
- Integrate avatar in a scenario
- Cards scenario?
- No timeline, but they think "soon"
- during FHL they are upgrading to v8
- What does it take to get to a collaborative stage
- Ribbon:
- Awesome to have shared goals and both be invested in the success
- Took a lot of iteration, changed 3 times mid-stream
- This was the first time we were doing this
- Looked at a lot of approaches before settling on one approach
- Figuring out the basics as we go on the first ones
- Moving forward we can move faster
- When is the API done enough (stable)?
# Rollout Table
| Component | ETA | GitHub Issue | Component Model | Design Tokens | Fluent Design 2.0 | Product | Status |
| -------------- | ------ | --------------------------------------------------------------------- | --------------- | ------------- | ----------------- | --- | ------ |
| Button | Q42020 | [#15434](https://github.com/microsoft/fluentui/issues/15434) - Tomi | DONE | DONE | TBD | | |
| Tabs | Q42020 | | | | | | |
| Text | Q42020 | | | | | | |
| Image | Q42020 | | | | | | |
| Avatar | Q42020 | | | | | | |
| Badge/Status | Q42020 | | | | | | |
| FocusZone | Q42020 | | | | | | |
| FocusTrapZone | Q42020 | | | | | | |
| Card | Q42020 | | | | | | |
| Link | Q42020 | | | | | | |
| Separator | Q42020 | | | | | | |
| Callout | Q12021 | | | | | | |
| Icon | Q12021 | | | | | | |
| Tooltip | Q12021 | [#15102](https://github.com/microsoft/fluentui/issues/15102) - Josche | | | | | |
| Menu | Q12021 | | | | | | |
| Dropdown | Q12021 | | | | | | |
| Textfield | Q12021 | | | | | | |
| Dialog | Q12021 | | | | | | |
| Checkbox | Q12021 | | | | | | |
| RadioGroup | Q12021 | | | | | | |
| Label | Q12021 | | | | | | |
| Toggle | Q12021 | | | | | | |
| Slider | Q12021 | | | | | | |
| Spinner/Loader | Q12021 | Text | | | | | |
## This is a excel to markdown test
| Converged Component | Design Spec | Assigned To | Status - D | In Toolkit |
|---------------------|-------------------------------------------------------------------------------|-------------|---------------|------------|
| Button | https://www.figma.com/file/Nj9EBBvOZmS11zKNJfilVR/Buttons?node-id=2360%3A4716 | Daisy | Spec Complete | No |
| SplitButton | https://www.figma.com/file/Nj9EBBvOZmS11zKNJfilVR/Buttons?node-id=999%3A158 | Daisy | Spec Complete | No |
| MenuButton | https://www.figma.com/file/Nj9EBBvOZmS11zKNJfilVR/Buttons?node-id=451%3A0 | Daisy | Spec Complete | No |
| Card | https://www.figma.com/file/berhUBA6mJV9sCPpjgfKRj/Card?node-id=1520%3A5036 | Kay | Spec Complete | No |
Sign in with Wallet
Connect another wallet