Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[material-ui][docs] Refine the Component demo page template #39702

Closed
samuelsycamore opened this issue Nov 1, 2023 · 0 comments
Closed

[material-ui][docs] Refine the Component demo page template #39702

samuelsycamore opened this issue Nov 1, 2023 · 0 comments
Assignees
Labels
docs Improvements or additions to the documentation package: material-ui Specific to @mui/material

Comments

@samuelsycamore
Copy link
Contributor

samuelsycamore commented Nov 1, 2023

Related to #33998 & #35158

Following the discussion here - #39298 (comment) - it was concluded that "if everything is Customization, then nothing is Customization." 😅 As such, I think we should update the template for the Component demo pages in Material UI and Joy UI, primarily to move more content from "Customization" to "Basics."

(This doesn't apply to Base UI because those docs have their own structure to account for both components and hooks.)

How do we decide what's "Basic" and what's "Customization" and beyond?

The basic premise is that the demos on the page should get increasingly more sophisticated from one section to the next, starting with out-of-the-box features and eventually concluding with real-world examples of the component in context.

Basics

  • out-of-the-box usage details
  • implementation of built-in props

Customization

  • more complex usage beyond built-in props - but not quite real-world examples
  • use with other components

Common examples

  • these are closest to real-world examples

Third-party integrations

  • any examples that involve non-MUI stuff

Templates - before and after

Before:

# {{Component Name}}

## Introduction

## Basics
- import
- basic usage description and demo

## Customization
### Variants
### Sizes
### Colors
### Decorators
### etc.

## Usage with {{Other Component}}
### Details on specific usage

## Common examples
### Example 
### etc.

## Accessibility

## Anatomy

## API

After:

# {{Component Name}}

## Introduction
### Usage
- appropriate use cases, how it compares/contrasts with similar components

## Basics
- import
- basic description and demo
### Variants
### Sizes
### Colors
### Decorators
### etc.

## Customization
### Use with {{Other Component}}
### etc.

## Common examples
### {{Sophisticated example from well-known app/UI}}

## Third-party integrations
### {{Integration Name}}

## Accessibility

## Anatomy

## API
@samuelsycamore samuelsycamore added docs Improvements or additions to the documentation package: material-ui Specific to @mui/material package: joy-ui Specific to @mui/joy labels Nov 1, 2023
@samuelsycamore samuelsycamore self-assigned this Nov 1, 2023
@samuelsycamore samuelsycamore changed the title [core][docs] Refine the Component demo page template for Material UI and Joy UI [material-ui][docs] Refine the Component demo page template Dec 28, 2023
@samuelsycamore samuelsycamore removed the package: joy-ui Specific to @mui/joy label Dec 28, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Improvements or additions to the documentation package: material-ui Specific to @mui/material
Projects
None yet
Development

No branches or pull requests

1 participant