Repository navigation
Add React components as a shadcn registry - #376
Open
Jeremy-Walton wants to merge 8 commits into
Open
Jeremy-Walton wants to merge 8 commits into
Jeremy-Walton wants to merge 8 commits into
Conversation
Bring the components from optics-components-react into a react/ workspace. They ship as a shadcn registry, not in the npm package. - 32 components on Base UI and cva, with kebab-case shadcn paths - Split Alert.Flash from Alert.Root and Tabs.Nav from Tabs.List - React Storybook, composed into the main Storybook under "React" - build-docs publishes it to /react and the registry to /r - Test that registry.json matches each file's imports Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each component gets an MDX page with the same sections and variations as its CSS docs page, and an args-driven story file so every option is in Controls. - Code panel shows the JSX each story renders, named like Accordion.Root - Reset Optics .tag styles on Prism tokens in code blocks - Render MDX tables with remark-gfm - Avatar renders a div by default, so a plain avatar has no hover state - Layout components take only the options the CSS docs offer: align and gap on Cluster, Split, Stack; end and gap on Flank Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Plan: current status, next steps for review, PR, and release checks - README: give components only the options their CSS docs offer, and copy the Accordion story and MDX pattern for new docs pages Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each React component states the Optics version it was checked against, and the PR template asks about the React component when a CSS component changes. - Line 1 of each component and its MDX page say the Optics version; the registry test checks they match - PR template: React checks for added, updated, and changed components - Boolean cva variants drop `false: null` - lib/dialog.tsx shares the Modal and Confirm Dialog trigger and close handler, and replaces lib/invoker-commands.ts - Layout stories share helpers; story args use component prop types - Text Pair shares one size map; Form.Textarea and Form.Select share one native control - Stop exporting unused part variants; drop an unused env override, empty registry dependencies, and a duplicate test Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every Optics release sets all React components to the new version, and the React parts now cover the variations the CSS docs show. - `yarn set-optics-version:react` sets each component and MDX page to the root package.json version; the registry test fails until they match - PR template: run it with a version bump; drop the per-component bump - Pagination.Link `shape`, Navbar.Content `render`, Form.Control `indeterminate`, TableContainer, and Frame `inlineSize` - Form label, hint, and error render plain elements outside a Form.Group - Icon packs through setIconPack() in lib/icon-pack.ts, adapted from experiment/restructure; Icon takes `duotone` and `weight="thin"` - Storybook toolbar to switch icon packs Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`yarn set-optics-version <version>` bumps package.json, the .storybook/assets example pages, and every React component and MDX page, so a version bump is one step. - Move the script to tools/ and take the version as an argument - PR template prompts for the command instead of a hand edit - Test failure message names the command with the version Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The plan's work is done, and its one open convention moves to the React README. The launch file only served one local setup and would clash with an untracked launch file in the main checkout. - README: use Base UI's render prop to change a part's element Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Jeremy-Walton
requested review from
BenEinwechter,
dallasbpeters and
zoopmaster
and
a balanced review from Copilot
and removed request for
zoopmaster
November 9, 2026 21:01
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved icon-pack incompatibilities, incorrect toast timing, and accessibility and duplicate-ID defects cause missing controls, premature visual dismissal, and broken interactions in supported configurations and examples.
10 open issues
Resolve the default accordion icon for the selected icon pack · New Let toast state control dismissal animations · New Use a pack-independent close icon in both branches · New Prevent disabled linked avatars from receiving focus or activating · New Use a pack-independent default breadcrumb separator · New Make the modal close icon work with every supported pack · New Give the confirm dialog an accessible name · New Generate a unique dialog ID for each story instance · New Associate modal titles with their native dialogs · New Generate unique switch IDs for each rendered instance · New
What changed in this PR
Adds 32 typed React components as a shadcn registry served from the Optics documentation site, rather than bundled in the npm package. A dedicated React Storybook provides installation guidance, interactive examples, and API documentation.
Changes:
- Adds React components using Optics styles, Base UI behavior, and cva variants.
- Composes the React Storybook into the existing documentation.
- Adds workspace dependencies, registry validation, and synchronized version-update tooling.
- Integrates React type-checking, documentation builds, and contributor checks.
This pull request requires changes. Unresolved moderate findings affect icon-pack compatibility, toast timing, disabled-control behavior, RTL tooltip styling, and example correctness and accessibility.
| File | Description |
|---|---|
tools/set-optics-version.mjs |
Synchronizes package, example, component, and documentation versions. |
test/react/registry.test.cjs |
Checks registry dependencies and component version consistency. |
react/tsconfig.json |
Configures strict React TypeScript checks. |
react/stories/tooltip.stories.tsx |
Demonstrates tooltip positions and trigger types. |
react/stories/tooltip.mdx |
Documents tooltip behavior and customization. |
react/stories/text-pair.stories.tsx |
Demonstrates text-pair sizing and inline layouts. |
react/stories/text-pair.mdx |
Documents title/subtitle composition. |
react/stories/tag.stories.tsx |
Demonstrates tag variants and optional buttons. |
react/stories/tag.mdx |
Documents tag composition and removal controls. |
react/stories/tabs.stories.tsx |
Demonstrates navigation tabs and interactive panels. |
react/stories/tabs.mdx |
Documents both tab composition patterns. |
react/stories/table.mdx |
Documents table variants, sticky sections, and pagination. |
react/stories/switch.stories.tsx |
Demonstrates switches; instance-specific IDs are needed to prevent misdirected labels. |
react/stories/switch.mdx |
Documents switches; duplicate story mounts produce conflicting input IDs. |
react/stories/stack.stories.tsx |
Demonstrates vertical-stack alignment variations. |
react/stories/stack.mdx |
Documents stack layout controls. |
react/stories/split.stories.tsx |
Demonstrates distributed-row alignment. |
react/stories/split.mdx |
Documents split layout controls. |
react/stories/spinner.stories.tsx |
Demonstrates spinner sizes. |
react/stories/spinner.mdx |
Documents loading indicators and accessible labels. |
react/stories/sidebar.stories.tsx |
Demonstrates drawer, compact, and rail configurations. |
react/stories/sidebar.mdx |
Documents sidebar sizing and content placement. |
react/stories/side-panel.stories.tsx |
Demonstrates panel sections, borders, and padding. |
react/stories/side-panel.mdx |
Documents panel composition and scrolling. |
react/stories/segmented-control.stories.tsx |
Demonstrates radio segments, sizes, and icons. |
react/stories/segmented-control.mdx |
Documents segmented-control structure and behavior. |
react/stories/pagination.stories.tsx |
Demonstrates page links and page-size selection. |
react/stories/pagination.mdx |
Documents pagination composition. |
react/stories/navbar.stories.tsx |
Demonstrates branding and navigation alignment. |
react/stories/navbar.mdx |
Documents navbar composition. |
react/stories/modal.stories.tsx |
Demonstrates native dialogs; examples need explicit accessible names. |
react/stories/modal.mdx |
Documents modal behavior and browser requirements. |
react/stories/layout-helpers.tsx |
Shares layout-demo content and controls. |
react/stories/Introduction.mdx |
Explains setup, registry installation, and component ownership. |
react/stories/icon.mdx |
Documents icon packs, SVGs, and styling variants. |
react/stories/grid.stories.tsx |
Demonstrates grid columns and spacing. |
react/stories/grid.mdx |
Documents grid layout properties. |
react/stories/frame.stories.tsx |
Demonstrates aspect ratios and width constraints. |
react/stories/frame.mdx |
Documents frame sizing and media behavior. |
react/stories/form.mdx |
Documents form controls, grouping, and validation. |
react/stories/flank.stories.tsx |
Demonstrates asymmetric layouts and avatar compositions. |
react/stories/flank.mdx |
Documents flank behavior and spacing. |
react/stories/divider.stories.tsx |
Demonstrates separator orientation, thickness, and spacing. |
react/stories/divider.mdx |
Documents divider properties and semantics. |
react/stories/content-header.stories.tsx |
Demonstrates header content, sections, and actions. |
react/stories/content-header.mdx |
Documents structured header parts. |
react/stories/confirm-dialog.stories.tsx |
Demonstrates confirmation actions; needs unique instance IDs and an accessible dialog name. |
react/stories/confirm-dialog.mdx |
Documents confirmation dialogs; duplicate mounts cause invokers to target the wrong instance. |
react/stories/cluster.stories.tsx |
Demonstrates wrapping-row alignment. |
react/stories/cluster.mdx |
Documents cluster layout behavior. |
react/stories/card.stories.tsx |
Demonstrates card sections, padding, and shadows. |
react/stories/card.mdx |
Documents card composition and styling. |
react/stories/button.stories.tsx |
Demonstrates button styles, states, and render targets. |
react/stories/button.mdx |
Documents button properties and variations. |
react/stories/button-group.stories.tsx |
Demonstrates grouped buttons and toolbars. |
react/stories/button-group.mdx |
Documents button-group composition. |
react/stories/breadcrumbs.stories.tsx |
Demonstrates breadcrumb sizes and separators. |
react/stories/breadcrumbs.mdx |
Documents breadcrumb navigation composition. |
react/stories/badge.stories.tsx |
Demonstrates badge variants and notification placement. |
react/stories/badge.mdx |
Documents badges and notifications. |
react/stories/avatar.stories.tsx |
Demonstrates avatar images, fallbacks, sizes, and links. |
react/stories/avatar.mdx |
Documents avatar composition and variants. |
react/stories/alert.stories.tsx |
Demonstrates alerts and toasts; generated examples need escaped title and description literals. |
react/stories/alert.mdx |
Documents alerts, dismissal, and toast setup. |
react/stories/accordion.stories.tsx |
Demonstrates disclosure configurations and grouping. |
react/stories/accordion.mdx |
Documents accordion parts and behavior. |
react/registry/optics/ui/tooltip.tsx |
Adds portaled Base UI tooltips. |
react/registry/optics/ui/tooltip.module.css |
Styles tooltip popups and arrows; physical side offsets need RTL correction. |
react/registry/optics/ui/text-pair.tsx |
Adds title/subtitle sizing and inline layouts. |
react/registry/optics/ui/tag.tsx |
Adds tag containers, variants, and labels. |
react/registry/optics/ui/tabs.tsx |
Adds panel tabs and navigation links; disabled links must suppress navigation and activation. |
react/registry/optics/ui/table.tsx |
Adds table variants and sticky containers. |
react/registry/optics/ui/switch.tsx |
Adds styled native checkbox switches. |
react/registry/optics/ui/stack.tsx |
Adds vertical-stack layout properties. |
react/registry/optics/ui/split.tsx |
Adds distributed-row layouts. |
react/registry/optics/ui/spinner.tsx |
Adds loading indicators with status text. |
react/registry/optics/ui/sidebar.tsx |
Adds sidebar sizes and content positioning. |
react/registry/optics/ui/side-panel.tsx |
Adds panel sections and padding variants. |
react/registry/optics/ui/segmented-control.tsx |
Adds grouped native radio options. |
react/registry/optics/ui/pagination.tsx |
Adds pagination links and dividers. |
react/registry/optics/ui/navbar.tsx |
Adds navbar branding and content sections. |
react/registry/optics/ui/modal.tsx |
Adds native modal parts; the default close glyph needs supported-pack compatibility. |
react/registry/optics/ui/icon.tsx |
Adds font and inline-SVG icons. |
react/registry/optics/ui/grid.tsx |
Adds grid column and spacing variants. |
react/registry/optics/ui/frame.tsx |
Adds aspect-ratio and width controls. |
react/registry/optics/ui/flank.tsx |
Adds asymmetric two-item layouts. |
react/registry/optics/ui/divider.tsx |
Adds separator orientation, thickness, and spacing. |
react/registry/optics/ui/content-header.tsx |
Adds compound page-header sections. |
react/registry/optics/ui/confirm-dialog.tsx |
Adds native confirmation-dialog components. |
react/registry/optics/ui/cluster.tsx |
Adds wrapping-row layout properties. |
react/registry/optics/ui/card.tsx |
Adds card sections and styling variants. |
react/registry/optics/ui/button.tsx |
Maps button properties to Optics variants and Base UI behavior. |
react/registry/optics/ui/button-group.tsx |
Adds a styled button-group container. |
react/registry/optics/ui/breadcrumbs.tsx |
Adds breadcrumb parts; the default separator needs supported-pack compatibility. |
react/registry/optics/ui/badge.tsx |
Adds badge variants and notification positioning. |
react/registry/optics/ui/avatar.tsx |
Adds styled avatars; interactive roots need disabled semantics and activation suppression. |
react/registry/optics/ui/alert.tsx |
Adds alerts and toasts; dismissal timing and both close-button glyphs need correction. |
react/registry/optics/ui/accordion.tsx |
Adds native disclosures; the default marker needs pack-aware resolution. |
react/registry/optics/lib/icon-pack.ts |
Resolves glyph names for supported icon packs. |
react/registry/optics/lib/flex-utilities.ts |
Shares alignment and spacing variants. |
react/registry/optics/lib/dialog.tsx |
Shares dialog trigger and close behavior. |
react/README.md |
Documents contributor workflows and component conventions. |
react/package.json |
Defines React dependencies and workspace scripts. |
react/.storybook/preview.tsx |
Configures themes, icon packs, and source display. |
react/.storybook/preview.css |
Loads Optics styles and adjusts documentation presentation. |
react/.storybook/main.ts |
Configures React stories, MDX tables, and aliases. |
package.json |
Adds the React workspace and build, validation, and version commands. |
.storybook/main.js |
Composes the React Storybook into existing documentation. |
.npmignore |
Excludes React sources from npm publication. |
.github/workflows/linting.yml |
Adds React type-checking and documentation/registry builds. |
.github/pull_request_template.md |
Adds React maintenance, validation, and version-update checks. |
Review effort: Balanced
- Resolve built-in close and arrow icons for the selected icon pack - Let Base UI time flash toasts and slide them with a transition - Make disabled linked avatars leave the tab order and ignore clicks - Give story dialogs accessible names and per-instance ids Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This branch has not been deployed
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.

Why?
React apps using Optics had to write and manage their components by hand. This adds them here as a shadcn registry, so apps copy typed components that match the current Optics classes and docs.
The components ship from the docs site (
/r), not in the npm package, and the registry links resolve only after the first release deploys the docs.What Changed
What changed in this PR?
/react, composed into the docs under "React"@base-ui/react,class-variance-authority, andshadcnin a newreact/workspaceyarn set-optics-versionto bump the version everywhere, including each componentQuality Assurance
Have you updated any usage of changed tokens?Did you add a component?Have you added it to the dependency graph?Have you added it to the docs?Have you added a React component, or noted why not? (seereact/README.md)Did you update a component?Have you updated the dependency graph?Have you updated the docs?Have you updated the React component inreact/registry/optics/ui/, with its stories and MDX page, to match?react/registry.jsonif its imports changed?Do you need to update the package version? Don't edit it by hand. Runyarn set-optics-version <version>, such asyarn set-optics-version 2.6.2. It sets the version inpackage.json, the.storybook/assetsexample pages, and every React component.Have you runyarn set-optics-version <version>?Have you adjusted the React components for this release?Were any changes made to the top level optics.css file?Were those changes reflected in the other top level files?Screenshots
The React docs are composed into the main docs under "React". Each component page shows its Optics version, the shadcn install command, a playground, and every CSS variation. The code panel shows the JSX each story renders, with compound parts named like
Alert.Root.