-
Notifications
You must be signed in to change notification settings - Fork 669
docs: add modular design system adr #8012
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
Draft
joshblack
wants to merge
18
commits into
main
Choose a base branch
from
docs/add-modular-ds-adr
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+338
−0
Draft
Changes from all commits
Commits
Show all changes
18 commits
Select commit
Hold shift + click to select a range
da62864
docs: add initial modular design system draft
joshblack 8a3230f
docs: add initial support tables
joshblack ef931ea
docs: begin filling out tables
joshblack a74d0a5
docs: begin audit
joshblack a8140fd
docs: update audit table
joshblack e38e50f
docs: add sections for low-level and spectrum docs
joshblack 429d646
Add Disclosure component for content visibility
joshblack 81c03ec
Update list of breaking components in ADR-024
joshblack 5f69d47
Merge branch 'main' of github.com:primer/react into docs/add-modular-…
joshblack 2aa4abf
Merge branch 'main' of github.com:primer/react into docs/add-modular-…
joshblack 2e25fbe
docs: update breaking into parts section and low-level section
joshblack 29c3227
docs: update syntax
joshblack fed5fa0
Merge branch 'main' of github.com:primer/react into docs/add-modular-…
joshblack d69d2c8
Apply suggestions from code review
joshblack 0d439ac
Apply suggestion from @llastflowers
joshblack 3fca490
chore: update adr
joshblack b161f54
Merge branch 'docs/add-modular-ds-adr' of github.com:primer/react int…
joshblack d72d0c7
docs: update adr description for dialog
joshblack File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,338 @@ | ||
| # Modular Design System | ||
|
|
||
| 📆 Date: 2026-05-17 | ||
|
|
||
| ## Status | ||
|
|
||
| | Stage | State | | ||
| | -------------- | ----------- | | ||
| | Status | Proposed ⚠️ | | ||
| | Implementation | Pending ⚠️ | | ||
|
|
||
| ## Context | ||
|
|
||
| There is a proposal for enabling better pattern creation via modular building | ||
| blocks in: https://github.com/github/core-ux/issues/2238. In this proposal, it | ||
| details several layers that Primer could be structured into: | ||
|
|
||
| - Layer 3: Ready-made, props-based components that are ready to use | ||
| - Layer 2: Parts, presentiontational-style components that one combines with hooks to | ||
| create components | ||
| - Layer 1: Foundations, unstyled primitives to allow for full markup and style | ||
| control | ||
| - Layer 0: Hooks, state management, and other logic that can be used to build components | ||
|
|
||
| We took this proposal into a Modular design System Workshop: | ||
| https://github.com/github/primer/discussions/6703. In this workshop, we | ||
| identified several scenarios where teams run into challenges when building with | ||
| Primer: | ||
|
|
||
| - It can be difficult to extend or add new functionality to a component | ||
| - It can be difficult to customize the appearance, content, or semantics of a | ||
| component | ||
| - It can be difficult to build new experiences using established patterns (like accessibility primitives) | ||
|
|
||
| These challenges lead to custom implementations, forks, or overrides of Primer | ||
| components that reuslt in adoption challenges and ecosystem fragmentation. | ||
|
|
||
| As a result, we applied the layer model to several situations in a | ||
| [FigJam](https://www.figma.com/board/mgApQG7vL3imdUIhgyhG2n/Modular-DS-Workshop?node-id=84-152&t=dBKm8jx1UsKRXyzu-1). From this work, we pulled out insights about this model that we want to adopt in Primer today. | ||
|
|
||
| ## Decision | ||
|
|
||
| From the Modular Design System workshop, we identified several key areas that we | ||
| want to focus on in order to improve Primer: | ||
|
|
||
| - Embrace layer 2 from the layer model, offering parts for our components that | ||
| can be combined with hooks for improved flexibility | ||
| - Provide low-level components and hooks to make it easier to build | ||
| quality, accessible experiences | ||
| - Create a model for upstreaming work where people have already built on top of Primer | ||
|
|
||
| To do this, we will: | ||
|
|
||
| - Identify and deliver components that can be broken down into parts, which can be used to create more | ||
| flexible and extensible components | ||
| - Identify and deliver low-level components, hooks, and utilities that can be used to quickly build out accessible experiences | ||
| - Embrace the spectrum of abstraction model, authoring presentational components | ||
| that combine with hooks to provide flexible patterns and opinionated defaults. | ||
|
|
||
| ### Breaking components down into parts | ||
|
|
||
| We will break down the following components into parts plus appropriate | ||
| behavioral hooks. These changes will make it easier for teams to layer behavior | ||
| on top of these components. | ||
|
|
||
| - SelectPanel | ||
| - Dialog (and ConfirmationDialog) | ||
| - DataTable (write documentation for `useTable` and `Table.*` components) | ||
| - ActionList (break down into list primitives) | ||
|
|
||
| ### Delivering low-level components, hooks, and utilities | ||
|
|
||
| We will immediately deliver high-priority components that will assist in building accessible experiences, including: | ||
|
|
||
| - **Dialog** for modal and nonmodal experiences with built-in parts for dialog | ||
| headings, content, and actions | ||
| - **ScrollableRegion** for scrollable containers with built-in accessibility and behaviors | ||
| - **Popover** for positioned, transient experiences | ||
| - **Tabs** for building tabs-based experiences | ||
| - **ToggleButton**, **ToggleSwitch** for building toggle-based experiences | ||
| - **Disclosure** for showing/hiding content | ||
| - **Accordion** for showing/hiding content | ||
|
|
||
| We will also deliver documentation for all existing low-level components, | ||
| hooks, and utilities. | ||
|
|
||
| In the future, we are investigating the following opportunities for offering | ||
| additional low-level components, hooks, and utilities: | ||
|
|
||
| - **Listbox** for selection-based experiences | ||
| - **Combobox** for filtering and selection-based experiences | ||
| wiring up accessibility, behaviors, and semantics | ||
| - **Menu** for action-based experiences | ||
| - **Tree** for tree-based experiences | ||
| - useFilter | ||
| - useSelection | ||
|
|
||
| #### Audit | ||
|
|
||
| | Entrypoint | Type | Name | | ||
| | :------------- | :-------- | :--------------------------- | | ||
| | . | component | VisuallyHidden | | ||
| | | | Announce | | ||
| | | | AriaStatus | | ||
| | | | AriaAlert | | ||
| | | hook | useAnchoredPosition | | ||
| | | | useColorSchemeVar | | ||
| | | | useConfirm | | ||
| | | | useDetails | | ||
| | | | useFocusTrap | | ||
| | | | useFocusZone | | ||
| | | | useFormControlForwardedProps | | ||
| | | | useId | | ||
| | | | useIsomorphicLayoutEffect | | ||
| | | | useMergedRefs | | ||
| | | | useOnEscapePress | | ||
| | | | useOnOutsideClick | | ||
| | | | useOpenAndCloseFocus | | ||
| | | | useOverlay | | ||
| | | | useProvidedRefOrCreate | | ||
| | | | useRefObjectAsForwardedRef | | ||
| | | | useResizeObserver | | ||
| | | | useResponsiveValue | | ||
| | | | useRovingTabIndex | | ||
| | | | useSafeTimeout | | ||
| | | | useSlots | | ||
| | | | useSyncedState | | ||
| | | | useTheme | | ||
| | ./experimental | component | Hidden | | ||
| | | | Tabs | | ||
| | | hook | useSlots | | ||
| | | | useOverflow | | ||
| | | | useTab | | ||
| | | | useTabList | | ||
| | | | useTabPanel | | ||
|
|
||
| ### Embracing the spectrum of abstraction model | ||
|
|
||
| We will author components with a spectrum of abstraction in mind, specifically | ||
| beginning with presentational components that can combine with hooks to provide | ||
| opionated, config-driven components. | ||
|
|
||
| This model allows us to offer opinionated defaults that work for common | ||
| scenarios while still allowing teams to extend and customize components as needed. | ||
|
|
||
| Default to building presentational components, then add behavior through hooks. | ||
| As opinions or defaults are established, create config-driven components that | ||
| combine presentational components and hooks to offer a higher level of | ||
| abstraction for common use-cases. | ||
|
|
||
| #### Config components | ||
|
|
||
| These components are "all-in-one"; they provide a high level of abstraction that | ||
| support common use-cases making it simple to quickly build out established | ||
| patterns and experiences. However, they are often inflexible and difficult to | ||
| extend. | ||
|
|
||
| ```tsx | ||
| <List | ||
| items={[{label: 'Item one'}, {label: 'Item two'}, {label: 'Item three'}]} | ||
| onSelect={item => { | ||
| /* ... */ | ||
| }} | ||
| onFilter={query => { | ||
| /* ... */ | ||
| }} | ||
| /> | ||
| ``` | ||
|
|
||
| #### Presentational components | ||
|
|
||
| These components provide a lower level of abstraction and are more flexible and extensible, but require more work to build out common patterns and experiences. | ||
|
|
||
| ```tsx | ||
| function Example({items}) { | ||
| const [state, actions] = useList({ | ||
| defaultSelected: [], | ||
| }) | ||
|
|
||
| return ( | ||
| <List> | ||
| <List.Filter | ||
| query={state.query} | ||
| onChange={query => { | ||
| actions.updateQuery(query) | ||
| }} | ||
| /> | ||
| {items | ||
| .filter(item => item.label.includes(state.query)) | ||
| .map(item => { | ||
| return ( | ||
| <List.Item | ||
| key={item.label} | ||
| onClick={() => { | ||
| actions.toggleSelect(item.label) | ||
| }} | ||
| > | ||
| <List.ItemLeadingVisual> | ||
| <Checkbox checked={state.selected.has(item.label)} /> | ||
| </List.ItemLeadingVisual> | ||
| <List.ItemLabel>{item.label}</List.ItemLabel> | ||
| </List.Item> | ||
| ) | ||
| })} | ||
| </List> | ||
| ) | ||
| } | ||
| ``` | ||
|
|
||
| Presentational components are accompanied by behavior or state hooks for a | ||
| component's core functionality. Oftentimes, config components are built by | ||
| combining presentational components with the corresponding behavior and state | ||
| hooks needed for a feature. | ||
|
|
||
| #### Base components | ||
|
|
||
| Base components are unstyled and may optionally provide behavior. These | ||
| components are fundamental primitives that are used to build components, such as | ||
| accessibility primitives. | ||
|
|
||
| ```tsx | ||
| function Example() { | ||
| return ( | ||
| <Dialog.Root> | ||
| <Dialog.Trigger /> | ||
| <Dialog.Overlay /> | ||
| <Dialog.Content> | ||
| <Dialog.Close /> | ||
| </Dialog.Content> | ||
| </Dialog.Root> | ||
| ) | ||
| } | ||
| ``` | ||
|
|
||
| Other examples include: | ||
|
|
||
| - Combobox (filtering, selection) | ||
| - Listbox (selection) | ||
| - Popover | ||
| - Tabs | ||
| - Treeview | ||
|
|
||
| #### Utilities | ||
|
|
||
| There are core utilities, hooks, functions, etc that are commonly used when | ||
| building out components or React applications. We provide hooks for established | ||
| patterns so that teams can build on solid foundations when authoring new | ||
| experiences. These can include hooks such as `useMergedRefs`, | ||
| `useOnEscapePress`, `useTimeout` and more. | ||
|
|
||
| These utilities may extend beyond hooks, such as `@primer/behaviors` or custom | ||
| elements, where appropriate. | ||
|
|
||
| ## Consequences | ||
|
|
||
| ## Alternatives | ||
|
|
||
| ## Questions | ||
|
|
||
| ## Audit | ||
|
|
||
| | Entrypoint | Type | Name | Parts | Hooks | Config | Notes | | ||
| | :------------- | :------- | :----------------- | :---- | :---- | :----- | :---- | | ||
| | . | Compound | ActionBar | ✅ | | | | | ||
| | | | ActionList | ✅ | | | | | ||
| | | | ActionMenu | ✅ | | | | | ||
| | | | Banner | ✅ | | | | | ||
| | | | Breadcrumbs | ✅ | | | | | ||
| | | | ConfirmationDialog | | | ✅ | | | ||
| | | | Details | ✅ | | | | | ||
| | | | Dialog | | | ✅ | | | ||
| | | | FormControl | ✅ | | | | | ||
| | | | Header | ✅ | | | | | ||
| | | | NavList | ✅ | | | | | ||
| | | | PageHeader | ✅ | | | | | ||
| | | | PageLayout | ✅ | | | | | ||
| | | | Pagination | | | ✅ | | | ||
| | | | Popover | ✅ | | | | | ||
| | | | ProgressBar | ✅ | | | | | ||
| | | | SegmentedControl | ✅ | | | | | ||
| | | | Select | ✅ | | | | | ||
| | | | SelectPanel | | | ✅ | | | ||
| | | | SplitPageLayout | ✅ | | | | | ||
| | | | Stack | ✅ | | | | | ||
| | | | SubNav | ✅ | | | | | ||
| | | | Timeline | ✅ | | | | | ||
| | | | TreeView | ✅ | | | | | ||
| | | | UnderlineNav | ✅ | | | | | ||
| | . | Leaf | Autocomplete | | | | | | ||
| | | | Avatar | | | | | | ||
| | | | AvatarStack | | | | | | ||
| | | | BranchName | | | | | | ||
| | | | Button | | | | | | ||
| | | | ButtonGroup | | | | | | ||
| | | | Checkbox | | | | | | ||
| | | | CheckboxGroup | | | | | | ||
| | | | CircleBadge | | | | | | ||
| | | | CounterLabel | | | | | | ||
| | | | Heading | | | | | | ||
| | | | IconButton | | | | | | ||
| | | | IssueLabelToken | | | | | | ||
| | | | Label | | | | | | ||
| | | | LabelGroup | | | | | | ||
| | | | Link | | | | | | ||
| | | | LinkButton | | | | | | ||
| | | | Overlay | | | | | | ||
| | | | Radio | | | | | | ||
| | | | RadioGroup | | | | | | ||
| | | | RelativeTime | | | | | | ||
| | | | SkeletonBox | | | | | | ||
| | | | Spinner | | | | | | ||
| | | | StateLabel | | | | | | ||
| | | | Text | | | | | | ||
| | | | TextInput | | | | | | ||
| | | | Textarea | | | | | | ||
| | | | ToggleSwitch | | | | | | ||
| | | | Token | | | | | | ||
| | | | Tooltip | | | | | | ||
| | | | Truncate | | | | | | ||
| | | Utility | AnchoredOverlay | | | | | | ||
| | | | VisuallyHidden | | | | | | ||
| | ./experimental | Compound | Blankslate | ✅ | | | | | ||
| | | | Card | ✅ | | | | | ||
| | | | DataTable | | | ✅ | | | ||
| | | | FilteredActionList | | | ✅ | | | ||
| | | | KeybindingHint | | | ✅ | | | ||
| | | | SelectPanel | ✅ | | | | | ||
| | | | Stack | ✅ | | | | | ||
| | | | Table | ✅ | | | | | ||
| | | | Tabs | ✅ | ✅ | | | | ||
| | | | UnderlinePanels | ✅ | | | | | ||
| | | Leaf | InlineMessage | | | | | | ||
| | | | IssueLabel | | | | | | ||
| | | | SkeletonAvatar | | | | | | ||
| | | | SkeletonText | | | | | | ||
| | | | Tooltip | | | | | | ||
| | | | TopicTag | | | | | | ||
| | | Utility | Hidden | | | | | | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.