covers:
- apps/web/src/components/**
- apps/web/components.json
Web UI Components
Overview
The reusable web UI component layer lives under apps/web/src/components/ui/** and is configured by apps/…/components.json. The config identifies this as a shadcn-style component set with style: "base-mira", TypeScript enabled, Tailwind CSS variables sourced from src/styles.css, Hugeicons as the icon library, and aliases such as #/components/ui, #/lib/utils, and #/hooks. The components themselves are thin typed wrappers around accessibility-focused primitives, with all styling assembled through cn from #/lib/utils.ts and, where variants are needed, class-variance-authority.
Most files export a compound component family rather than a single widget. Base primitives such as apps/…/button.tsx, input.tsx, textarea.tsx, label.tsx, badge.tsx, separator.tsx, skeleton.tsx, spinner.tsx, kbd.tsx, progress.tsx, avatar.tsx, and aspect-ratio.tsx provide the leaf controls and display elements used by larger compositions. button.tsx is the central action primitive: it wraps @base-ui/react/button, exports buttonVariants, and standardizes variants (default, outline, secondary, ghost, destructive, link) and sizes including icon-only sizes. Components such as Calendar, Dialog, Sheet, AlertDialog, InputGroup, and Carousel reuse Button so their default controls inherit the same visual contract.
Interactive overlays and menus are mostly Base UI wrappers. apps/…/dialog.tsx, sheet.tsx, popover.tsx, tooltip.tsx, hover-card.tsx, select.tsx, combobox.tsx, dropdown-menu.tsx, context-menu.tsx, menubar.tsx, navigation-menu.tsx, accordion.tsx, collapsible.tsx, tabs.tsx, toggle.tsx, toggle-group.tsx, checkbox.tsx, radio-group.tsx, switch.tsx, and slider.tsx preserve the underlying primitive state model while adding project Tailwind classes, data-slot markers, portal/positioner defaults, and Hugeicons indicators. Popup-like components consistently render through primitive portals and positioners with z-50, --available-height, --anchor-width, and --transform-origin-based classes so collision, sizing, and animation are handled by the primitive while styling remains local to the wrapper.
Forms are split between react-hook-form integration and layout primitives. apps/…/form.tsx exports Form as FormProvider, FormField as a Controller wrapper, and useFormField-driven FormItem, FormLabel, FormControl, FormDescription, and FormMessage that derive ids, descriptions, and error text for accessible field wiring. apps/…/field.tsx is a lower-level layout system for fieldsets, labels, descriptions, separators, and aggregated errors without coupling to react-hook-form. input-group.tsx, native-select.tsx, input-otp.tsx, checkbox.tsx, radio-group.tsx, switch.tsx, and slider.tsx provide the actual controls those form shells compose.
Layout and content primitives are plain React wrappers with slot metadata and Tailwind structure. apps/…/card.tsx, item.tsx, empty.tsx, table.tsx, breadcrumb.tsx, pagination.tsx, scroll-area.tsx, resizable.tsx, and button-group.tsx organize repeated page structures. item.tsx and button-group.tsx use Base UI useRender/mergeProps so callers can change the rendered tag while retaining class and data-state conventions. table.tsx wraps tables in an overflow container, while resizable.tsx maps directly onto react-resizable-panels groups, panels, and separators.
Several higher-level widgets carry their own runtime state or third-party integrations. apps/…/sidebar.tsx defines a SidebarProvider context that tracks desktop and mobile open state, persists desktop state in the sidebar_state cookie, toggles via Ctrl/Cmd+B, and switches to a Sheet-backed mobile sidebar using useIsMobile from #/hooks/use-mobile.ts. apps/…/carousel.tsx wraps embla-carousel-react, exposes useCarousel, publishes the Embla API through setApi, and keeps previous/next buttons disabled based on select/reInit events. apps/…/chart.tsx wraps Recharts with a ChartContainer context, injects per-chart CSS variables for light/dark colors, and provides tooltip/legend renderers that resolve labels, icons, and colors from ChartConfig. apps/…/calendar.tsx wraps react-day-picker, substituting project button classes and Hugeicons chevrons while supporting locale-aware day/month formatting. apps/…/command.tsx composes cmdk with the local Dialog and InputGroup primitives, and apps/…/sonner.tsx wraps sonner with next-themes theme selection and Hugeicons toast icons.
The component layer has no application-owned persistence or network access. State is local React/component state except for sidebar.tsx writing document.cookie, sonner.tsx reading the current theme from next-themes, and third-party UI libraries managing their own DOM state. Components are intended to be imported directly from their file path under #/components/ui/...; there is no barrel file in apps/web/src/components/ui/**.
Coupling
- If apps/…/components.json aliases change, update imports across
apps/web/src/components/ui/**; these files consistently import shared utilities and peer components through#/lib/utils.ts,#/components/ui/..., and#/hooks/..., so alias drift breaks the component library at compile time. - If the Tailwind theme tokens or CSS variables in apps/…/components.json's tailwind.css target change, verify every component that uses semantic tokens such as
bg-popover,text-muted-foreground,border-input,ring-ring,bg-sidebar, andtext-destructive; the wrappers do not define fallback colors locally. - If
buttonVariantsin apps/…/button.tsx changes, check apps/…/calendar.tsx, alert-dialog.tsx, dialog.tsx, sheet.tsx, carousel.tsx, combobox.tsx, and input-group.tsx; they reuseButtonorbuttonVariantsfor embedded controls and inherit both size names and variant names. - If Base UI primitive APIs or their
data-*state attributes change, audit the wrappers in apps/…/accordion.tsx, dialog.tsx, dropdown-menu.tsx, select.tsx, combobox.tsx, navigation-menu.tsx, tabs.tsx, toggle-group.tsx, tooltip.tsx, and related files; their styling depends on primitive props, portal/positioner behavior, and selectors likedata-open,data-closed,data-highlighted,data-checked, anddata-active. - If form id or error wiring in apps/…/form.tsx changes, verify consumers still render
FormFieldinsideFormandFormItem;useFormFieldderivesaria-describedby,aria-invalid, and message ids from both contexts, so separating those pieces can silently degrade accessibility. - If apps/…/sidebar.tsx cookie name, widths, or keyboard shortcut changes, verify the application shell and any server/client code that seeds
defaultOpen; the provider persistssidebar_stateindocument.cookieand desktop layout widths are exposed through CSS variables on the wrapper. - If chart color handling in apps/…/chart.tsx changes, verify Recharts payload keys and
ChartConfig; tooltips and legends resolve labels/colors by matching payloadname,dataKey, or nested payload values to config keys rather than by schema validation.
Risks
- apps/…/slider.tsx defaults
_valuesto[min, max]when neithervaluenordefaultValueis an array. If a caller expects a single-thumb uncontrolled slider without passing a one-element default, two thumbs are rendered and the control behaves like a range slider. - apps/…/sidebar.tsx's
SidebarMenuSkeletonusesMath.random()during React state initialization to set skeleton width. If this component is rendered during SSR or hydration-sensitive paths, the generated width can differ between server and client and produce visual or hydration instability. - apps/…/form.tsx initializes contexts with empty objects and only checks
if (!fieldContext), which never fires for the default context object. IfuseFormFieldis called outsideFormFieldorFormItem, it can construct ids with an undefinedname/idinstead of failing loudly.