MetaMask / MetaMask/metamask-extension

Add Documentation on Styling Best Practices and Component Library Usage

Open
#23,856 0 comments 0 reactions 0 assignees View on GitHub
team-design-system
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.