feat: component docs styles tab #328

hcopp · 2026-01-26T15:44:37Z

What changed? Why?

This PR adds

StylesAndClassnames type (for web) to enable shared static classnames that share the same key as styles and classnames
Styles tab to doc site showcasing styles table and explorer (for use cases of styles only or styles & static classnames)
Styles props (and static classnames) to NavigationBar - this is a guinea pig component for static classnames
New cursor command to support adding component styles to a component (tested with NavigationBar)
- Not 100% confident in this command yet as we haven't tested it widespread, it should be improved incrementally
Updates to existing component docs to support this styles tab
- Tested this with all components in web and mobile that supported styles, to great success

Future tasks

Support data attributes in styles tab
(optional) show styles tab for components taht do not support styles/classNames but have a root static className or data attributes (such as button if we don't add styles)
Concrete decision on when to support static classNames for a component
Update component style descriptions/make descriptions consistent across the board

Styles tab

Selectors

This table is generated by docgen by trying to select the styles prop from a component. It also looks for this new StylesAndClassNames

export type StylesAndClassNames<ComponentClassNamesMap extends Record<string, string>> = {
  classNames?: { [key in keyof ComponentClassNamesMap]?: string };
  styles?: { [key in keyof ComponentClassNamesMap]?: React.CSSProperties };
};

it uses these values to display one of two tables

Explorer (web only)

The code example is generated by AI and paired with the same selectors from above to let the user highlight

It also works with SVG components

UI

Carousel Web

Carousel Mobile

Other library implementations

Ant

Mantine

Testing

Tested all of these components manually

How has it been tested?

Testing instructions

Illustrations/Icons Checklist

Required if this PR changes files under packages/illustrations/** or packages/icons/**

verified visreg changes with Terran (include link to visreg run/approval)
all illustration/icons names have been reviewed by Dom and/or Terran

Change management

type=routine
risk=low
impact=sev5

automerge=false

cb-heimdall · 2026-01-26T15:44:41Z

🟡 Heimdall Review Status

Requirement Status More Info

Reviews

🟡 0/1

Denominator calculation

Show calculation

1 if user is bot 0

1 if user is external 0

2 if repo is sensitive 0

From .codeflow.yml 1

Additional review requirements

Show calculation

Max	0

0

From CODEOWNERS 1

Global minimum 0

Max 1

1

1 if commit is unverified 0

Sum 1

CODEOWNERS 🟡 See below

🟡 `CODEOWNERS`

Code Owner Status Calculation

ui-systems-eng-team

🟡 0/1

Denominator calculation

Additional CODEOWNERS Requirement

Show calculation

Sum	0

0

From CODEOWNERS 1

Sum 1

hcopp · 2026-01-26T16:10:56Z

.cursor/commands/component-styles.md

+| `titleStackContainer` | Container wrapping titleStack                         |
+| `topContent`          | Top section content                                   |
+| `track`               | Track/rail element (in progress bars, sliders)        |
+| `trigger`             | Trigger element that opens a dropdown/popover         |


I know we have discussed potential concern over having a wide range of style names for similar sub-elements so keeping a list should help with this

hcopp · 2026-01-26T16:11:41Z

packages/mobile/src/chips/Chip.tsx

 import { Text } from '../typography/Text';

-import type { ChipProps } from './ChipProps';
+export type { ChipProps } from './ChipProps';


For docgen to pick this up we need to export it from the file. This will also allow us to be more consisent with other components.

hcopp · 2026-01-26T17:01:21Z

packages/web/src/types.ts

+export type StylesAndClassNames<ComponentClassNamesMap extends Record<string, string>> = {
+  classNames?: { [key in keyof ComponentClassNamesMap]?: string };
+  styles?: { [key in keyof ComponentClassNamesMap]?: React.CSSProperties };
+};


Let me know what y'all think about this for web. It allows us to keep the keys consistent across classNames, styles, and static classNames. We still haven't decided if we want static classNames for everything but we could start applying to some components now.

I tested this with NavigationBar.

hcopp · 2026-01-26T17:06:04Z

apps/docs/docs/components/data-display/ContentCell/_mobileStyles.mdx

+
+## Selectors
+
+<ComponentStylesTable componentName="ContentCell" styles={mobileStylesData} />


hcopp

Tested all the docs

hcopp · 2026-01-26T17:06:23Z

apps/docs/docs/components/data-display/ContentCell/_webStyles.mdx

+      media={<Avatar size="m" />}
+    />
+  )}
+</StylesExplorer>


hcopp · 2026-01-26T17:06:53Z

apps/docs/docs/components/data-display/ListCell/_mobileStyles.mdx

+
+## Selectors
+
+<ComponentStylesTable componentName="ListCell" styles={mobileStylesData} />


hcopp · 2026-01-26T17:07:09Z

apps/docs/docs/components/data-display/ListCell/_webStyles.mdx

+      }
+    />
+  )}
+</StylesExplorer>


hcopp · 2026-01-26T17:07:27Z

apps/docs/docs/components/feedback/ProgressBar/_mobileStyles.mdx

+
+## Selectors
+
+<ComponentStylesTable componentName="ProgressBar" styles={mobileStylesData} />


hcopp · 2026-01-26T17:07:38Z

apps/docs/docs/components/feedback/ProgressBar/_webStyles.mdx

+
+<StylesExplorer selectors={webStylesData.selectors}>
+  {(classNames) => <ProgressBar progress={0.65} classNames={classNames} />}
+</StylesExplorer>


hcopp · 2026-01-26T17:20:02Z

apps/docs/docs/components/navigation/Sidebar/_webStyles.mdx

+
+<StylesExplorer selectors={webStylesData.selectors}>
+  {(classNames) => <SidebarExample classNames={classNames} />}
+</StylesExplorer>


Here's an example where the component is taller than the # of styles

hcopp · 2026-01-26T17:20:36Z

apps/docs/docs/components/navigation/Stepper/_webStyles.mdx

+
+<StylesExplorer selectors={webStylesData.selectors}>
+  {(classNames) => <StepperExample classNames={classNames} direction="vertical" />}
+</StylesExplorer>


We can even do multiple examples

hcopp · 2026-01-26T17:21:25Z

apps/docs/docs/components/other/DotCount/_webStyles.mdx

+      <IconButton name="bell" />
+    </DotCount>
+  )}
+</StylesExplorer>


This is the hardest example to see the outline but I think it is fine.

hcopp · 2026-01-26T17:21:48Z

apps/docs/src/components/page/ComponentStylesTable/index.tsx

+      </Box>
+    </VStack>
+  );
+});


I followed the design of component props table

hcopp · 2026-01-26T17:22:58Z

apps/docs/src/components/page/StylesExplorer/index.tsx

+      </Box>
+    </VStack>
+  );
+});


Didn't have a ton to go off here, I choose to do background of bg to match our code examples. I initially tried setting the sidebar of selectors to match table colors (so gray10 for the top part and then no extra background for the list cells) but this current setup was the one that looked the best to me.

hcopp · 2026-01-26T17:27:23Z

I'll wait to bump versions since this PR might not get merged for a bit

hcopp added 8 commits January 24, 2026 19:22

feat: support classnames on navbar

5f920c1

Start doc support for web components styles tab

0aa0d83

Update styling and docparser

4902e9f

Improve docs

e164f88

Simplify styles doc code

dc871b9

Support chip with re-export

05a2d1e

Fix example

2f8675d

Improve styles table

8a79a2d

hcopp self-assigned this Jan 26, 2026

hcopp had a problem deploying to production January 26, 2026 15:44 — with GitHub Actions Error

github-actions bot added packages:web packages:mobile apps:docs libs:docusaurus-plugin-docgen labels Jan 26, 2026

Simplify component styles table

80d1063

hcopp had a problem deploying to production January 26, 2026 15:52 — with GitHub Actions Error

Revert changes to ListCell examples

0e9dfc7

hcopp had a problem deploying to production January 26, 2026 15:55 — with GitHub Actions Error

Improve state based examples

5b7509d

hcopp temporarily deployed to production January 26, 2026 16:10 — with GitHub Actions Inactive

hcopp commented Jan 26, 2026

View reviewed changes

Update navbar

5b1d06f

hcopp had a problem deploying to production January 26, 2026 16:59 — with GitHub Actions Error

hcopp commented Jan 26, 2026

View reviewed changes

Add navbar tests and fix typecheck

8b73f61

hcopp had a problem deploying to production January 26, 2026 17:04 — with GitHub Actions Error

hcopp commented Jan 26, 2026

View reviewed changes

Fix broken docs

0badbc8

hcopp commented Jan 26, 2026

View reviewed changes

Merge branch 'master' into hunter/navbar-classnames

166a38d

hcopp had a problem deploying to production January 26, 2026 17:23 — with GitHub Actions Error

hcopp marked this pull request as ready for review January 26, 2026 17:24

Update ci

c923cc3

hcopp had a problem deploying to production January 26, 2026 17:36 — with GitHub Actions Error

Add more examples

5b2d58d

hcopp temporarily deployed to production January 26, 2026 17:45 — with GitHub Actions Inactive

hcopp requested review from adrienzheng-cb and sverg-cb January 26, 2026 22:55

Merge branch 'master' into hunter/navbar-classnames

cd65e58

hcopp temporarily deployed to production January 26, 2026 22:55 — with GitHub Actions Inactive


		## Selectors

		<ComponentStylesTable componentName="ContentCell" styles={mobileStylesData} />


		## Selectors

		<ComponentStylesTable componentName="ListCell" styles={mobileStylesData} />


		## Selectors

		<ComponentStylesTable componentName="ProgressBar" styles={mobileStylesData} />

feat: component docs styles tab #328

Are you sure you want to change the base?

feat: component docs styles tab #328

Uh oh!

Conversation

hcopp commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed? Why?

Styles tab

Selectors

Explorer (web only)

UI

Carousel Web

Carousel Mobile

Other library implementations

Ant

Mantine

Testing

How has it been tested?

Testing instructions

Illustrations/Icons Checklist

Change management

Uh oh!

cb-heimdall commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟡 Heimdall Review Status

🟡 CODEOWNERS

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hcopp Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hcopp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hcopp commented Jan 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

hcopp commented Jan 26, 2026 •

edited

Loading

cb-heimdall commented Jan 26, 2026 •

edited

Loading

🟡 `CODEOWNERS`

hcopp Jan 26, 2026 •

edited

Loading