UI Component Library

Relevant source files

The following files were used as context for generating this wiki page:

• apps/frontend/components.json
• apps/frontend/app/globals.css
• apps/frontend/components/ui/sidebar.tsx
• apps/frontend/components/ui/sheet.tsx
• apps/frontend/components/ui/tabs.tsx
• apps/frontend/app/dashboard/page.tsx
• apps/frontend/package.json
• apps/frontend/components/ui/card.tsx
• apps/frontend/components/ui/button.tsx

The OnChain Sage frontend utilizes a robust and themeable UI component library built with Next.js, React, and Tailwind CSS. The library follows the principles of shadcn/ui, emphasizing composition over configuration. It leverages unstyled, accessible primitives from Radix UI and provides a consistent look and feel across the application, particularly within the user dashboard.

This library is configured via components.json and styled globally through app/globals.css, which defines CSS variables for light and dark themes. Components are designed to be composable, allowing developers to build complex user interfaces from simple, reusable blocks. Key dependencies include class-variance-authority for creating variant-based styles and tailwind-merge for utility class management.

Sources: apps/frontend/README.md, apps/frontend/components.json, apps/frontend/app/globals.css, apps/frontend/package.json

Configuration and Theming

The foundation of the UI library is its configuration and theming system, which allows for consistent styling and easy management of components.

components.json

This file configures the shadcn/ui CLI, defining the project's structure, styling choices, and path aliases. It specifies that the project uses the "new-york" style, enables TypeScript (tsx) and React Server Components (rsc), and uses lucide for icons.

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

Sources: apps/frontend/components.json

The table below details the configuration options found in components.json.

Property	Value	Description
style	new-york	The predefined style from shadcn/ui.
rsc	true	Indicates that React Server Components are used.
tsx	true	Components are written in TypeScript with JSX.
tailwind.config	tailwind.config.ts	Path to the Tailwind CSS configuration file.
tailwind.css	app/globals.css	Path to the global CSS file where variables are defined.
tailwind.baseColor	neutral	The base color palette for the UI.
tailwind.cssVariables	true	Enables the use of CSS variables for theming.
aliases.components	@/components	Path alias for the main components directory.
aliases.ui	@/components/ui	Path alias for the UI library components.

Sources: apps/frontend/components.json

CSS Variables and Theming

Theming is managed through CSS variables defined in apps/frontend/app/globals.css. The file sets up variables for both light (default :root) and dark (.dark) modes, covering background, foreground, primary, secondary, accent, and other colors. This allows for dynamic theme switching, as seen in the dashboard's theme toggle button.

The diagram below shows how theming is applied.

A separate set of variables is defined specifically for the Sidebar component, allowing it to have a distinct style from the rest of the application.

Variable	Light Mode Value	Dark Mode Value	Purpose
--background	0 0% 100%	240 10% 3.9%	Main background color.
--foreground	240 10% 3.9%	0 0% 98%	Main text color.
--primary	262.1 83.3% 57.8%	262.1 83.3% 57.8%	Primary action color.
--card	0 0% 100%	240 10% 3.9%	Card background color.
--border	240 5.9% 90%	240 3.7% 15.9%	Border color for elements.
--sidebar-background	240 10% 3.9%	240 10% 3.9%	Sidebar background color.
--sidebar-foreground	0 0% 98%	0 0% 98%	Sidebar text color.
--sidebar-accent	240 3.7% 15.9%	240 3.7% 15.9%	Sidebar accent color for active/hover states.

Sources: apps/frontend/app/globals.css:5-70

Core Components

The library consists of several core components that are composed to build the application's UI. These components are built on top of Radix UI primitives, ensuring they are accessible and functional out of the box.

Card

The Card component is a container for displaying content in a structured format. It is composed of several sub-components: CardHeader, CardTitle, CardDescription, CardContent, and CardFooter. This compositional approach provides flexibility in structuring card content.

The diagram below illustrates the composition of the Card component.

Example Usage:
The dashboard uses Card components to display overview statistics like "Total Signals" and "High Confidence".

// From apps/frontend/app/dashboard/page.tsx
<Card>
  <CardHeader className="pb-2">
    <CardTitle className="text-sm font-medium">Total Signals</CardTitle>
  </CardHeader>
  <CardContent>
    <div className="text-2xl font-bold">142</div>
    <p className="text-xs text-green-500">
      +22% from last month
    </p>
  </CardContent>
</Card>

Sources: apps/frontend/app/dashboard/page.tsx:160-174, apps/frontend/components/ui/card.tsx

Tabs

The Tabs component is used to organize content into different sections that can be switched between. It is built on TabsPrimitive from Radix UI and consists of Tabs, TabsList, TabsTrigger, and TabsContent.

Example Usage:
In the dashboard, Tabs are used to filter the "Trading Signals" table by category (e.g., All, High Confidence, Emerging, Risky).

// From apps/frontend/app/dashboard/page.tsx
<Tabs defaultValue="all">
  <TabsList className="mb-4 w-full justify-start overflow-auto">
    <TabsTrigger value="all">All Signals</TabsTrigger>
    <TabsTrigger value="high">High Confidence</TabsTrigger>
    <TabsTrigger value="emerging">Emerging</TabsTrigger>
    <TabsTrigger value="risky">Risky</TabsTrigger>
  </TabsList>
  <TabsContent value="all">
    <SignalTable />
  </TabsContent>
  {/* ... other TabsContent components */}
</Tabs>

Sources: apps/frontend/app/dashboard/page.tsx:201-218, apps/frontend/components/ui/tabs.tsx

Sheet

The Sheet component provides a slide-out panel that can appear from any side of the screen. It is built using @radix-ui/react-dialog and is highly configurable through variants for the side property (top, bottom, left, right). This component is fundamental for creating experiences like off-canvas navigation.

Sources: apps/frontend/components/ui/sheet.tsx:32-46

Layout Components

Sidebar

The Sidebar is a complex layout component responsible for the main navigation in the dashboard. It is built with a context provider (SidebarProvider) and a useSidebar hook to manage its state (expanded/collapsed).

Architecture:
The Sidebar's state management allows any child component to access and modify the sidebar's state, such as toggling its visibility.

This diagram shows the flow of toggling the sidebar.

Responsive Behavior:
On mobile devices, the Sidebar component leverages the Sheet component to render as an off-canvas menu, ensuring a good user experience on smaller screens. The useIsMobile hook determines which version to render.

Sources: apps/frontend/components/ui/sidebar.tsx:168-193

Sub-components:
The Sidebar is composed of many smaller parts to create a flexible and structured layout:

• SidebarProvider: Wraps the layout to provide sidebar context.
• SidebarTrigger: A button to toggle the sidebar's visibility.
• SidebarHeader: Container for the top section of the sidebar, often holding a logo or title.
• SidebarContent: A scrollable area for the main navigation items.
• SidebarGroup: A section within the content, with an optional label.
• SidebarMenu: A list (<ul>) to hold menu items.
• SidebarMenuItem: A list item (<li>) for a menu button.
• SidebarMenuButton: The actual button/link for navigation.
• SidebarFooter: A container for the bottom section of the sidebar.

Example Usage:
The dashboard page implements the full sidebar structure for its primary navigation.

// From apps/frontend/app/dashboard/page.tsx
<SidebarProvider>
  <div className="flex h-screen w-full overflow-hidden bg-background dark">
    <Sidebar className="border-r">
      <SidebarHeader>
        {/* ... */}
      </SidebarHeader>
      <SidebarContent>
        <SidebarMenu>
          {/* ... SidebarMenuItems */}
        </SidebarMenu>
      </SidebarContent>
      <SidebarFooter>
        {/* ... */}
      </SidebarFooter>
    </Sidebar>
    {/* ... main content */}
  </div>
</SidebarProvider>

Sources: apps/frontend/app/dashboard/page.tsx:47-87, apps/frontend/components/ui/sidebar.tsx

Dependencies and Tooling

The UI component library relies on several key npm packages to function.

Package	Role
@radix-ui/react-*	Provides the unstyled, accessible, and functional primitives for components like Dialog (used in Sheet), Tabs, DropdownMenu, etc.
class-variance-authority	A utility for creating variants of components with different styles (e.g., button sizes, colors).
clsx	A tiny utility for constructing className strings conditionally.
tailwind-merge	A utility to intelligently merge Tailwind CSS classes without style conflicts.
tailwindcss-animate	A Tailwind CSS plugin for adding enter/exit animations.
lucide-react	Provides the icon set used throughout the components.

Sources: apps/frontend/package.json:11-28, apps/frontend/components.json:20

Conclusion

The OnChain Sage UI Component Library is a modern, well-structured system for building the application's frontend. By using shadcn/ui's methodology, it combines the power of Radix UI's accessible primitives with the flexibility of Tailwind CSS. The use of composition, CSS variables for theming, and a clear configuration file (components.json) results in a developer-friendly, maintainable, and visually consistent set of components that are central to the user experience.