Orange-OpenSource
[OUDS] Create a component page template for the doc
Prerequisites
- [x] I have searched for duplicate or closed feature requests
- [x] I have read the contributing guidelines
Proposal
It could look like this:
## Overview
Describe here :
- key concepts
- base class
- standard display, including basic colors (?)
- Versions of the components (Chip, Tag) with cards leading to the right content. In the case, the following paragraphs should be written for each version of the component.
## Layout
Describe here :
- what happens when texts wrap
- how to use utilities to display components aside or in block, how they should behave
## Variants
Describe here all the component's variants
### On colored background
### With asset
#### Icon
#### Chevron
#### Bullet
### Helper text
## Sizes
Give some examples of the possible sizes.
## States
### Visited
### Loading
### Read only
### Disabled
Of course, we should keep only the relevant pargraphs for each component.
Then other specific paragraphs could come after.
For components witg two types/versions/global variants, same with a common overview:
## Overview
Explain briefly the difference of usage between the two (or more) types/versions/global variants, with lonks to the right sections. A simple example of code could be useful to show what's in common,
## Component type 1
Describe here :
- key concepts
- base class
- standard display, including basic colors (?)
- Versions of the components (Chip, Tag) with cards leading to the right content. In the case, the following paragraphs should be written for each version of the component.
### Layout
Describe here :
- what happens when texts wrap
- how to use utilities to display components aside or in block, how they should behave
### Variants
Describe here all the component's variants
#### On colored background
#### With asset
##### Icon
##### Chevron
##### Bullet
#### Helper text
### Sizes
Give some examples of the possible sizes.
### States
#### Visited
#### Loading
#### Read only
#### Disabled
## Component type 2
Describe here :
- key concepts
- base class
- standard display, including basic colors (?)
- Versions of the components (Chip, Tag) with cards leading to the right content. In the case, the following paragraphs should be written for each version of the component.
### Layout
Describe here :
- what happens when texts wrap
- how to use utilities to display components aside or in block, how they should behave
### Variants
Describe here all the component's variants
#### On colored background
#### With asset
##### Icon
##### Chevron
##### Bullet
#### Helper text
### Sizes
Give some examples of the possible sizes.
### States
#### Visited
#### Loading
#### Read only
#### Disabled
Motivation and context
To ease the writting of a new component page, we could have a mdx hidden file which would contain a template/pattern for the doc.
Original menu for Button:
## Base class
## Standard variants
### Rounded
## Variants on colored background
## With icon
### Text and icon
### Icon only
## Disable text wrapping
## Button tags
## Outline buttons
## Disabled state
## Loading state
## Block buttons
Proposal:
## Overview
(Including standard variants and button tags)
## Layout
### Block buttons
### Disable text wrapping
## Variants
### On colored background
### Rounded
### With icon
#### Text and icon
#### Icon only
### Outline (see if we keep it)
## States
### Disabled
### Loading
Original menu for Badge:
## Base class
## Standard variants
## Sizes
## With count
## With icons
### Positioned
Proposal:
## Overview
Includes Base class and standard variants with colors
### Variants
## With count
## With icons (is 's' needed ?)
### Positioned
## Sizes
Original menu for Link:
## Standard variant
## Variants on colored background
## Link chevron
## Icon link
## Sizes
## Link tags
## Disabled state
### Disabled link accessibility warning
Proposal:
## Overview
Includes standard variant and Link tags
## Variants
### On colored background
### With chevron
### With icon
## Sizes
## States
### Disabled
Including Disabled link accessibility warning
Original menu for Bullet list:
## Unordered lists
### Default display
### Nested unordered lists
### Marker color
### Custom marker
#### CSS class
#### Inline SVG in ul
#### Different custom markers
### Tick marker
#### Using SCSS
#### Using a custom marker
## Ordered lists
### Default display
### Nested ordered lists
## Mixed lists
## Bare lists
## Text style
### Body medium
### Font weight normal
## Native list
## Utilities
### Unstyled
### Inline
Proposal:
## Overview
## Unordered lists
(including default displayexample)
### Nested unordered lists
### Variants
#### Marker color
#### Custom marker
##### Using CSS class
##### Using inline SVG in ul
##### Different custom markers
#### Tick marker
##### Using SCSS
##### Using a custom marker
## Ordered lists
(including default display example)
### Nested ordered lists
## Mixed lists
## Bare lists
## Common variants
### Text style
#### Body medium
#### Font weight normal
#### Unstyled
#### Inline
## Native list
I'm wondering if the 2 paragraphs CSS class, Inline SVG in ul and different custom markers shouldn't all start with "Using ... be in the same pargraph to make it clearer these are just some ways to do the same thing. Or
Original menu for Breadcrumb:
## Basic example
## Behavior on smaller viewports
Proposal:
## Overview
## Layout
Original menu for Tag:
## Tag
### Color variants
### Squared
### With asset
#### Bullet
#### Icon
#### Loader
### Sizes
## Tag input
### Disabled
Proposal:
## Overview
## Tag
Put here the global description of Tag, including color variants
### Variants
#### Squared
#### With asset
##### Bullet
##### Icon
##### Loader
### Sizes
## Tag input
Put here the global description of Tag input
### States
#### Disabled
Original menu for Chip:
## Filter chip
### Text and icon
### Icon only
### Using radio buttons
### With `<input />` inside label
### Using buttons
### Disabled state
## Suggestion chip
### Text and icon
### Icon only
### Disabled state
## Layout
### Overflowing
### Wrapping
### Mix of both
#### Vertical overflow
#### Horizontal overflow
### Pseudo elements
## Button plugin
### Toggle states
### Methods
Proposal:
## Overview
inclunding Pseudo elements?
## Filter chip
Put here the global description of Filter chip
### Technical implementation
#### Using radio buttons
#### Using buttons
Put here what was in Using buttons + Button plugin
##### Toggle states
##### Methods
#### With `<input />` inside label => Not sure this pargraph should be kept
### Variants
#### Text and icon
#### Icon only
### States
#### Disabled
## Suggestion chip
Put here the global description of Suggestion chip
### Variants
#### Text and icon
#### Icon only
### States
#### Disabled
## Layout
### Overflowing
### Wrapping
### Mix of both
#### Vertical overflow
#### Horizontal overflow
## Pseudo elements => shouldn't this info should be dislpayed in the overview and maybe reminded at the beggining of Filter chip and Suggestion chip? Is it really linked to layout?
Original menu for Checkbox:
## Basic example
### Indeterminate
## Approach
## Variants
### Divider
### Icon
### Helper text
## Layout
### Default
### Reverse
## States
### Disabled
### Read only
### Invalid
## Group
## Standalone
Proposal:
## Overview
### Indeterminate
### Approach
## Variants
### Divider
### Icon
### Helper text
## Layout
### Default
### Reverse
## States
### Disabled
### Read only
### Invalid
## Group
## Standalone
Original menu for Radio button:
## Basic example
## Approach
## Variants
### Divider
### Icon
### Additional label
### Helper text
### Outlined
## Layout
### Default
### Reverse
## States
### Disabled
### Read only
### Invalid
## Group
## Standalone
Proposal:
## Overview
### Approach
## Variants
### Divider
### Icon
### Additional label
### Helper text
### Outlined
## Layout
### Default
### Reverse
## States
### Disabled
### Read only
### Invalid
## Group
## Standalone
Original menu for Switch:
## Basic example
## Approach
## Variants
### Divider
### Icon
### Helper text
## Layout
### Default
### Reverse
## States
### Disabled
### Read only
### Invalid
## Group
## Standalone
## Native switches
Proposal:
## Overview
### Approach
### IOS native switches => should be explained at the beginning
## Variants
### Divider
### Icon
### Helper text
## Layout
### Default
### Reverse
## States
### Disabled
### Read only
### Invalid
## Group
## Standalone
Should we ask Franco's input on this?
One issue that may arise is that if we display all variants in the overview Example, we are in effect showing something that we do not want people to do (case in point for the tag example that is showing both tag and tag input). I'm not strongly against that, but we had to change many examples for control items after Benoit and Maxime reviews because of mixed examples...
Should we ask Franco's input on this?
For Franco's input, why not. Do we have to all agree before?
One issue that may arise is that if we display all variants in the overview Example, we are in effect showing something that we do not want people to do (case in point for the tag example that is showing both tag and tag input). I'm not strongly against that, but we had to change many examples for control items after Benoit and Maxime reviews because of mixed examples...
When you say variants, you mean "versions", right? Maybe we can display each in a different example, would it be better? Or jsut maybe the two verisons on two lines? (See https://deploy-preview-3062--boosted.netlify.app/docs/0.5/components/tag/)
I wonder if at the top of the component page you should have when there are multiple variants a top list to recirculate in the page:
## Component overview
...
## component types
* Variant 1 > anchor link in the page
* Variant 2 > anchor link in the page
## Type 1
Describtion
### Layout
### Variants
### Sizes
### States
## Type 2
Describtion
### Layout
### Variants
### Sizes
### States
I wonder if at the top of the component page you should have when there are multiple variants a top list to recirculate in the page:
Isn't it what we proposed (with some small differencies in the presentation)? see in the main description:
## Overview
Explain briefly the difference of usage between the two (or more) types/versions/global variants, with lonks to the right sections. A simple example of code could be useful to show what's in common,
## Component type 1
...
## Component type 2
...
The example made by @hannahiss on Tag / Tag input has those links at the top https://deploy-preview-3062--boosted.netlify.app/docs/0.5/components/tag/
Also with the new nomenclature we have:
# Group overview
Component 1 shortcut
Component 2 shortcut
# Component 1
## Layout
...
# Component 2
## Layout
...