Closed
Description
Problems
- Component props are not documented consistently across pages on https://primer.style/react
- Not all component documentation pages include a component status checklist
Goals
- Use the new
PropsTable
component, to render prop documentation consistently across all component pages on https://primer.style/react - The props table should not reference internal types. For example, if you have a string union called
Variants
, you should show each string ('danger' | 'success' | 'warning'
) - Add a component status checklist to every component page
Consistency nice-to-haves ✨
- Every component page should have
source
frontmatter that links to the source code for that component (example) - Every component page should have an
Examples
,Props
, andStatus
heading (in that order) - The top of every component page should show how to import the component (example)
import {Box} from '@primer/react'
Non-goals
The props API of many of our components could be improved. However, changing the props of any component is out of scope for this issue.
Example
An example of how to use PropsTable
and ComponentChecklist
in an .mdx
file:
---
title: ExampleComponent
status: Alpha
---
...
## Props
<PropsTable>
{/* normal prop */}
<PropTableRow
name="variant"
type="'default' | 'danger'"
defaultValue="'inset'"
description={<>...use a string or JSX to describe this prop...</>}
/>
{/* required prop */}
<PropTableRow
name="children"
required={true}
type="React.ReactNode"
description="..."
/>
{/* deprecated prop */}
<PropTableRow
name="scheme"
deprecated
type="'default' | 'danger'"
defaultValue="'inset'"
description={<>Use <InlineCode>variant</InlineCode> instead</>}
/>
{/* sx prop */}
<PropsTableSxRow />
{/* as prop */}
<PropsTablePassthroughProps
defaultElementType="a"
/>
{/* ref prop */}
<PropsTablePassthroughProps
elementType="a"
isPolymorphic={true}
refType="HTMLAnchorElement"
/>
{/* passthrough props */}
<PropsTablePassthroughProps
elementType="a"
isPolymorphic={true}
passthroughPropsLink={
<Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#Attributes">MDN</Link>
}
/>
{/* base props (combines sx, as, ref, and passthrough props) */}
<PropsTableBasePropRows
elementType="a"
isPolymorphic={true}
refType="HTMLAnchorElement"
passthroughPropsLink={
<Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#Attributes">MDN</Link>
}
/>
</PropsTable>
## Status
<ComponentChecklist
items={{
propsDocumented: true,
noUnnecessaryDeps: true,
adaptsToThemes: true,
adaptsToScreenSizes: true,
fullTestCoverage: true,
usedInProduction: true,
usageExamplesDocumented: true,
hasStorybookStories: true
designReviewed: null,
a11yReviewed: null,
stableApi: false,
addressedApiFeedback: false,
hasDesignGuidelines: null,
hasFigmaComponent: null
}}
/>
Components
👋 If you want to update any of the pages listed below, add your username next to the component name so we can avoid duplicating effort
- ActionList
- ActionList v2
- ActionMenu
- ActionMenu v2
- AnchoredOverlay
- Autocomplete @mperrotti
- Avatar
- AvatarPair
- AvatarStack
-
BorderBox - Box
- BranchName
- Breadcrumbs
- Button @mperrotti
- CircleBadge
-
CircleOcticon - CounterLabel @mperrotti
- Details
- Dialog
- Dialog v2
- Dropdown
- DropdownMenu
- FilteredSearch
- FilterList
- Flash
-
Flex - FormGroup
☝️ @colebemis doing above unless indicated otherwise
👇 @rezrah doing below unless indicated otherwise
-
Grid - Checkbox Update component docs (Header, Radio, Checkbox, Heading, Label, LabelGroup) #1708
- Header Update component docs (Header, Radio, Checkbox, Heading, Label, LabelGroup) #1708
- Heading Update component docs (Header, Radio, Checkbox, Heading, Label, LabelGroup) #1708
- Label Update component docs (Header, Radio, Checkbox, Heading, Label, LabelGroup) #1708
- LabelGroup Update component docs (Header, Radio, Checkbox, Heading, Label, LabelGroup) #1708
- Link Add component ids to component pages #1744
- Overlay Improve docs consistency for Overlay, PageHead, Pagination, Popover, Portal, ProgressBar components #1805
- Pagehead Improve docs consistency for Overlay, PageHead, Pagination, Popover, Portal, ProgressBar components #1805
- Pagination Improve docs consistency for Overlay, PageHead, Pagination, Popover, Portal, ProgressBar components #1805
- PointerBox Fixes PointerBox caret not styling correctly using sx props #1804
- Popover Improve docs consistency for Overlay, PageHead, Pagination, Popover, Portal, ProgressBar components #1805
- Portal Improve docs consistency for Overlay, PageHead, Pagination, Popover, Portal, ProgressBar components #1805
-
Position - ProgressBar Improve docs consistency for Overlay, PageHead, Pagination, Popover, Portal, ProgressBar components #1805
- Radio Update component docs (Header, Radio, Checkbox, Heading, Label, LabelGroup) #1708
-
SelectMenu - SelectPanel
- SideNav
- Spinner
- StateLabel
- StyledOcticon
- SubNav
- TabNav
- Text
- TextInput
- TextInputWithTokens @mperrotti
- Timeline
- Token @mperrotti
- Tooltip
- Truncate
- UnderlineNav