MetaMask / MetaMask/metamask-extension
Add Documentation on Styling Best Practices and Component Library Usage
- Dominant language
- TypeScript
- Stars
- 13.2k
- Forks
- 5.6k
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 451
Description
### What is this about?
To enhance the consistency, maintainability, and overall quality of the MetaMask extension's UI, we propose the creation of comprehensive documentation outlining best practices for styling and utilizing components from the `component-library/` folder. This documentation will serve as a guideline for developers, emphasizing the hierarchical approach to styling components within the project. The aim is to encourage the use of existing component library components and their style utility props, promote the creation of new classnames and style files for custom styles, and recommend inline styles as a last resort for dynamic values.
### Scenario
_No response_
### Design
_No response_
### Technical Details
- **Objective**: Develop documentation that details a hierarchical approach to styling components within the MetaMask extension, including:
1. **Primary Approach**: Utilizing existing components from the `component-library/` folder.
2. **Secondary Approach**: Leveraging style utility props included in all components (link to list of props).
3. **Tertiary Approach**: Adding new classnames and corresponding styles files within the component for unsupported styles.
4. **Last Resort**: Employing inline styles for dynamic styling values.
- **Benefits**:
- **Consistency**: Ensures a uniform look and feel across the extension by using predefined components and styles.
- **Reusability**: Encourages the reuse of existing components and styles, reducing redundancy and effort.
- **Maintainability**: Simplifies updates and maintenance by centralizing styles and reducing inline styling.
- **Performance**: Minimizes the performance impact by avoiding excessive inline styles and leveraging optimized components.
- **Implementation Steps**:
1. Audit the current usage of components and styles within the extension to identify common patterns and exceptions.
2. Collaborate with UI/UX designers and front-end developers to outline the best practices based on the audit findings.
3. Draft the documentation, incorporating input from stakeholders and including examples and references.
4. Review and finalize the documentation with the team, ensuring clarity and comprehensiveness.
### Threat Modeling Framework
_No response_
### Acceptance Criteria
- Documentation on styling best practices and component library usage is created and made accessible to all developers.
- The documentation clearly outlines the hierarchical approach to styling, supported by examples and benefits.
- Developers report an understanding of the preferred styling approaches and are able to apply the guidelines to their work.
- A review of project code after documentation adoption shows increased adherence to the outlined best practices.
### Stakeholder review needed before the work gets merged
- [X] Engineering (needed in most cases)
- [ ] Design
- [ ] Product
- [ ] QA (automation tests are required to pass before merging PRs but not all changes are covered by automation tests - please review if QA is needed beyond automation tests)
- [ ] Security
- [ ] Legal
- [ ] Marketing
- [ ] Management (please specify)
- [ ] Other (please specify)
### References
https://metamask.github.io/metamask-storybook/?path=/docs/components-componentlibrary-introduction--docs
Contributor guide
Research direction
Start by reviewing the component-library/ folder and the linked MetaMask Storybook introduction to identify the components and style utility props that the guidance should cover. Then document the proposed styling hierarchy with examples, benefits, and references, and make it accessible to extension developers. Done means the guidance is reviewed by Engineering and clearly explains the preferred approaches.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- storybook, typescript
- Domain
- documentation, frontend
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100