UI Component Library (Shadcn)
Relevant source files
The following files were used as context for generating this wiki page:
The UI Component Library in Barekey is built using Shadcn UI integrated with Tailwind CSS and React. It provides a set of reusable, accessible components designed to deliver a high-quality developer experience (DX). The library is structured to support both core atomic components (e.g., buttons, sheets) and "custom" higher-order components (e.g., org-workspace layouts) specifically tailored for the Barekey vault manager interface.
The design system prioritizes a clean, minimal aesthetic with support for dark mode, custom color themes, and typography presets using fonts like Google Sans and JetBrains Mono.
Sources: AGENTS.md:14-22, pkg/ui/src/main.css:1-10
Architecture and Configuration
The component library follows the standard Shadcn architecture where configuration is defined at the root, and component source code is co-located within the project.
Core Configuration
The components.json file defines the structural aliases and styling preferences for the library. It uses the base-nova style and configures Tailwind to use CSS variables for dynamic theming.
| Property | Value | Description |
|---|---|---|
| Style | base-nova | The base design system style. |
| RSC | false | Indicates the project does not use React Server Components. |
| Icon Library | tabler | Standardized icons provided by @tabler/icons-react. |
| Base Color | neutral | The foundation for the gray scale. |
| CSS Variables | true | Allows runtime theme switching via CSS variables. |
Sources: pkg/ui/components.json:1-25
Styling System
Styles are managed through Tailwind CSS version 4. The system relies on OKLCH color definitions for superior color manipulation, particularly for the primary, secondary, and accent colors.
The diagram shows how CSS variables flow from base definitions into the Tailwind theme.
Sources: pkg/ui/src/main.css:12-140
Design System Elements
Typography
The project utilizes several font families to distinguish between UI elements and technical content:
- Sans-serif: Google Sans and Geist Variable are used for general UI text.
- Monospace: JetBrains Mono and Geist Mono are used for keys, slugs, and code snippets.
- Specialty: "Outfit" is used for high-impact "kicker" text (uppercase, wide tracking).
Sources: pkg/ui/src/main.css:118-164
Theming and "Debugger"
Barekey includes an internal Debugger system that allows real-time manipulation of the UI's visual parameters during development. This system interacts directly with CSS variables to test different Tailwind color families and spacing scales.
| Control | Targeted CSS Variable | Range/Options |
|---|---|---|
| Color Family | Various (via OKLCH mapping) | red, blue, olive, taupe, etc. |
| Spacing | --spacing | 0.125rem to 0.5rem |
| Border Radius | --radius | 0px to 24px |
| Font Mode | html.classList | default vs instrument |
Sources: pkg/ui/src/components/custom/debugger.tsx:8-55, pkg/ui/src/components/custom/debugger.tsx:325-360
Component Categories
Atomic UI Components
These are standard Shadcn components implemented using @base-ui/react or Radix UI primitives.
- Sheet: A side-aligned dialog primitive used for mobile navigation or detail views. It includes
SheetOverlay,SheetContent, and side-specific animations (top, right, bottom, left). Sources: pkg/ui/src/components/ui/sheet.tsx:1-92 - Button: Interactive elements with multiple variants (default, outline, ghost, destructive) and sizes (sm, icon-sm, etc.). Sources: pkg/ui/src/pages/o/[org]/overview/page.tsx:15, pkg/ui/src/components/ui/sheet.tsx:64
Custom Workspace Components
Located in pkg/ui/src/components/custom/, these components represent higher-level patterns specific to the Barekey domain.
This diagram illustrates the relationship between custom domain components and atomic UI primitives.
Sources: pkg/ui/src/components/custom/org-workspace.tsx:1-175
Component Details Table
| Component | Source File | Purpose |
|---|---|---|
OrgPageHero | org-workspace.tsx | Main header for organization and project pages with radial gradient backgrounds. |
OrgMetricCard | org-workspace.tsx | Displays usage stats (Static Requests, Storage) with "accent" or "muted" tones. |
OrgRoleBadge | org-workspace.tsx | Maps Clerk roles (e.g., org:admin) to UI variants (default, secondary, outline). |
Sheet | sheet.tsx | Extends @base-ui/react for slide-out panels. |
Sources: pkg/ui/src/components/custom/org-workspace.tsx:21-140, pkg/ui/src/components/ui/sheet.tsx:7-20
Implementation Patterns
OKLCH Color Scaling
The design system defines colors using the OKLCH space to ensure consistent lightness across different hues. Dark mode is implemented by overriding these variables within a .dark selector.
:root {
--primary: oklch(37.8% 0.015 216); /* Light Mode */
}
.dark {
--primary: oklch(87.2% 0.007 219.6); /* Dark Mode */
}
Sources: pkg/ui/src/main.css:16-60
Role-Based Styling
The library dynamically adjusts component variants based on user permissions. For instance, the OrgRoleBadge component uses a helper function to resolve styles:
org:admin->defaultvariant (high contrast).org:member->secondaryvariant.- Other roles ->
outlinevariant.
Sources: pkg/ui/src/components/custom/org-workspace.tsx:27-38
Summary
The Barekey UI library is a highly configurable system that leverages Shadcn UI and Tailwind CSS 4. It separates atomic primitives from custom workspace components, allowing for consistent branding across organization, project, and secret management views. Through the use of OKLCH colors and a dedicated development debugger, the system ensures visual fidelity and accessibility in both light and dark modes.