UI Component Library
Relevant source files
The following files were used as context for generating this wiki page:
The UI Component Library provides a standardized set of visual elements and layout structures built on Coss UI and Base UI. It ensures consistent design patterns across the application while maintaining a strict separation between vendor-provided primitives and project-specific extensions.
Sources: README.md:4, AGENTS.md:129
Component Architecture
The library follows a hierarchical structure to balance third-party updates with custom styling needs. Components reside in three specific locations depending on their scope:
- Shared Primitives: Located in
src/components/ui/primitives/. These are vendor components synced from Coss UI. You must never edit these files directly. - UI Extensions: Located in
src/components/ui/. These wrap primitives to add custom styling or project-specific logic. - Feature Components: Located in
src/features/{domain}/components/. These contain domain-specific logic and utilize shared UI components.
Sources: src/components/ui/primitives/README.md:7-12, AGENTS.md:46-51
Import Hierarchy
To ensure extensions are always used over raw primitives, feature code must import from the UI barrel file rather than primitive paths.
The diagram shows how feature code accesses components through the central UI barrel, which re-exports customized wrappers of vendor primitives.
Sources: AGENTS.md:53-61, src/components/ui/primitives/README.md:20-25
Core UI Systems
Overlay Management
The system categorizes overlays based on user interaction intent.
| Overlay Type | Use Case | Component Reference |
|---|---|---|
| Dialog | Centered, blocking UI for confirmations or alerts. | SheetPrimitive (as Root) |
| Sheet | Side or bottom panel for forms and controlled edits. | Sheet / SheetPopup |
| Drawer | Edge panel optimized for swipe-to-dismiss navigation. | Custom wrapper |
Sources: AGENTS.md:63-68, src/components/ui/primitives/sheet.tsx:1-12
Form Integration
Form components utilize React Hook Form and Zod for validation. When using FieldError with external validation libraries, you must pass the match prop to ensure the error renders even when native HTML5 ValidityState is technically valid.
If a FieldError is required outside a standard <Field.Root>, wrap it in a <Field className="contents"> to provide necessary React context without affecting layout.
Sources: AGENTS.md:139-160, package.json:51-68
Implementation Details
Sheet Component
The Sheet implementation leverages @base-ui/react/dialog and provides specific sub-components for layout control.
- SheetPopup: Manages the physical container, including directional transitions (top, bottom, left, right).
- SheetViewport: Controls the fixed positioning and grid layout of the overlay.
- SheetPanel: Includes a
ScrollAreafor handling overflow content within the sheet.
Sources: src/components/ui/primitives/sheet.tsx:50-100, src/components/ui/primitives/sheet.tsx:188-210
Layout Components
Layouts use a composition-based approach to structure pages.
The SidebarLayout component provides structured slots for global navigation and local content, supporting optional sticky behavior for sidebars.
Sources: src/components/layouts/sidebar-layout.tsx:11-44
Component Styling and Tools
The library relies on a modern CSS stack for styling and utility management:
- Tailwind CSS v4: Used for utility-first styling.
- class-variance-authority (CVA): Manages component variants and states.
- tailwind-merge & clsx: Handles conditional class application and prevents style conflicts.
- Lucide React: Provides the standard icon set used across all primitives.
Sources: README.md:20, package.json:55-75, src/components/ui/primitives/sheet.tsx:7
Technical Constraints
- No Manual Memoization: Do not use
useMemo,useCallback, orReact.memoas the React 19 compiler handles optimizations automatically. - Prop Delegation: When spreading props to child elements, name the variable
delegatedinstead ofpropsorrest. - Ref Handling: Use
refas a standard prop instead of wrapping components inforwardRef.
Sources: AGENTS.md:109-125
The UI Component Library establishes a robust foundation for the application by enforcing a single entry point for components and maintaining a clear boundary between vendor primitives and custom domain logic.