Xertica UI

Enterprise-grade React design system built on Tailwind CSS v4, Radix UI, and Lucide Icons — with a robust AI-first documentation layer for precise LLM-driven composition and autonomous agent interaction.

🤖 AI-First Single Source of Truth

Xertica UI is specifically designed to be consumed by AI Agents (LLMs, code assistants, autonomous agents). We provide dedicated entry points for AI context:

| File | Purpose | |---|---| | llms.txt | Standard index for AI crawlers and context-aware agents. | | llms-full.txt | Complete documentation of all 96 components in a single file for large-context LLMs. | | docs/llms.md | Master index for agents to navigate the documentation folder. |

🚀 Quick Start — CLI (Recommended)

Scaffold a full application with pre-configured routing, layout, and components:

npx xertica-ui@latest init my-app
cd my-app
npm run dev

The CLI scaffolds a complete Vite + React + TypeScript project with Portuguese UI localization and English AI-ready documentation.

📦 Installation as a Library

To add Xertica UI to an existing React project:

npm install xertica-ui

1. Import the stylesheet in your entry file (main.tsx or App.tsx):

import 'xertica-ui/style.css';

2. Wrap your app with XerticaProvider:

import { XerticaProvider } from 'xertica-ui';

function App() {
  return (
    <XerticaProvider>
      <YourApp />
    </XerticaProvider>
  );
}

🛠️ The Layout System

Xertica UI features an autonomous layout system managed by LayoutContext.

Mandatory Page Structure

Every page must use the <PageHeader> component for its title and primary actions. Never use raw h1 or div for headers.

import { PageHeader, PageHeaderHeading, Button } from 'xertica-ui';

export function MyPage() {
  return (
    <>
      <PageHeader>
        <PageHeaderHeading>Dashboard</PageHeaderHeading>
        <Button>Action</Button>
      </PageHeader>
      <div className="p-6">
        {/* Page Content */}
      </div>
    </>
  );
}

useLayout() Hook

Access the sidebar state, width, and toggle functions anywhere in the component tree:

const { sidebarWidth, isSidebarOpen, toggleSidebar } = useLayout();

🧩 Component Catalog (96 Components)

Layout & Navigation

Header · Sidebar · PageHeader · Breadcrumb · NavigationMenu · Tabs · Pagination · Accordion · Collapsible

Core Surfaces

Card · Separator · ScrollArea · AspectRatio · Resizable · Skeleton · Empty

Forms & Inputs

Form · Input · Textarea · RichTextEditor · Label · Checkbox · RadioGroup · Switch · Select · Slider · Calendar · InputOTP · FileUpload · Search

Actions & Data

Button · Toggle · ToggleGroup · Rating · Table · Badge · Avatar · Progress · StatsCard · Timeline · Stepper · TreeView · NotificationBadge · Chart

Overlays & Feedback

Dialog · AlertDialog · Sheet · Drawer · Popover · HoverCard · Tooltip · Alert · Sonner (Toast) · Command

🌟 Specialized Modules

🤖 AI Assistant

Integrated AI chat panel with workspace support.

• XerticaAssistant · MarkdownMessage · CodeBlock · AssistantChart

🗺️ Maps & Geolocation

First-class Google Maps integration.

• Map · RouteMap · SimpleMap · GoogleMapsLoader

🎙️ Media

• AudioPlayer · VideoPlayer · FloatingMediaWrapper

🎨 Design Tokens

Xertica UI uses semantic CSS tokens. Never use raw colors or generic Tailwind color classes:

Background:     bg-background          text-foreground
Card surface:   bg-card                text-card-foreground
Muted area:     bg-muted               text-muted-foreground
Primary action: bg-primary             text-primary-foreground
Destructive:    bg-destructive         text-destructive-foreground
Border:         border-border

🌍 Localization

• UI Components: Fully localized in Portuguese (pt-BR) for end-users.
• Documentation/Code: Strictly maintained in English for AI Agent compatibility and global developer standard.

💻 Tech Stack

| Technology | Version | |---|---| | React | 18.3 | | TypeScript | 5.7 | | Tailwind CSS | 4.0 | | Vite | 6.0 | | Radix UI | Latest | | Lucide React | 0.469+ | | Vitest | 4.1 |

📜 Scripts

| Command | Description | |---|---| | npm run dev | Start development server | | npm run build | Production bundle | | npm run storybook | Launch component library documentation | | npm run test | Run unit tests via Vitest | | npm run type-check | TypeScript validation |

⚖️ License

Proprietary — Xertica AI Team.