@gusvega/ui

React UI component library built on Tailwind CSS. Pre-compiled styles with built-in theme tokens. No separate tokens package required.

Component Status

Actions

• [x] Button — primary | secondary | ghost | inverted, sm | md | lg, disabled

Form

• [x] Input — forwardRef, error state, disabled
• [x] Label — required marker
• [x] Textarea — forwardRef, resizable
• [x] Checkbox — controlled, disabled
• [x] Radio — controlled, disabled
• [x] Switch — controlled, disabled
• [x] Select — native styled, controlled
• [x] FormField — Label + Input + error message compound
• [ ] Slider — range input (planned)
• [ ] DatePicker — (planned)
• [ ] FileUpload — (planned)

Data Display

• [x] Badge — default | secondary | outline
• [x] Avatar — 3 sizes, 3 colors, image support, stackable
• [x] Tag — with optional remove button
• [x] Stat — metric with optional trend
• [x] Table — Table, TableHeader, TableBody, TableRow, TableHead, TableCell
• [x] Code — inline + block variants
• [x] Kbd — keyboard shortcut key
• [ ] Tooltip — (planned, requires positioning)
• [ ] Timeline — (planned)

Feedback

• [x] Spinner — 3 sizes
• [x] Progress — animated fill bar
• [x] Alert — default | outline | filled with optional title
• [x] Skeleton — shimmer loading placeholder
• [ ] Toast — (planned, requires context/portal)
• [ ] Banner — (planned)

Navigation

• [x] Link — default | muted | underline
• [x] Breadcrumb — with separator
• [x] Tabs — Tabs | TabsList | TabsTrigger | TabsContent
• [ ] Pagination — (planned)
• [ ] Navbar — (planned as a compound)

Layout

• [x] Card — Card | CardHeader | CardContent | CardFooter
• [x] Separator — horizontal / vertical
• [x] Stack — row / col with gap and alignment
• [ ] Grid — (planned)
• [ ] Container — (planned)

Overlay

• [ ] Dialog / Modal — (planned, requires portal)
• [ ] Dropdown — (planned, requires positioning)
• [ ] Popover — (planned, requires positioning)
• [ ] Sheet — (planned, requires portal)

Installation

React UI component library built on top of Tailwind CSS. Styles are pre-compiled and the default theme ships inside the library. Published to npm.

Installation

npm install @gusvega/ui

Usage

1. Import the styles once at your app entry point:

import '@gusvega/ui/style.css';

2. Import and use components:

import { Button, Input, Card, CardHeader, CardContent } from '@gusvega/ui';

export default function App() {
  return (
    <Card>
      <CardHeader>Welcome</CardHeader>
      <CardContent>
        <Input placeholder="Enter name..." />
        <Button variant="primary">Submit</Button>
      </CardContent>
    </Card>
  );
}

Theme Overrides

The library ships with built-in theme values for colors, spacing, and typography. The simplest way to customize them is to override the CSS variables after importing @gusvega/ui/style.css.

Option 1: Override in CSS

:root {
  --gus-color-neutral-900: 15 23 42;
  --gus-color-neutral-100: 241 245 249;
  --gus-font-family-sans: "Satoshi", ui-sans-serif, system-ui, sans-serif;
  --gus-space-4: 1.125rem;
}

Option 2: Override in React with a helper

import { createThemeVariables } from '@gusvega/ui';

const themeVars = createThemeVariables({
  colors: {
    neutral: {
      900: '#0f172a',
      100: '#f1f5f9',
    },
  },
  typography: {
    fontFamily: {
      sans: ['Satoshi', 'ui-sans-serif', 'system-ui', 'sans-serif'],
    },
  },
});

export function App() {
  return <div style={themeVars}>{/* your UI */}</div>;
}

createThemeVariables returns CSS custom properties, so the theme can be applied globally or scoped to a single subtree.

Component API

Actions

• Button — variant: "primary" | "secondary" | "ghost" | "inverted", size: "sm" | "md" | "lg"
• Link — variant: "default" | "muted" | "underline"

Forms

• Input — type, placeholder, error, disabled, forwardRef
• Label — with optional required marker
• Textarea — rows, resizable, disabled, forwardRef
• Checkbox — checked, onChange, disabled
• Radio — checked, onChange, disabled
• Switch — checked, onChange, disabled
• Select — options, value, onChange
• FormField — compound component (Label + Input + error)

Data Display

• Badge — variant: "default" | "secondary" | "outline"
• Avatar — size: "sm" | "md" | "lg", color, image
• Tag — with optional remove button
• Stat — metric with optional trend indicator
• Table — Table, TableHeader, TableBody, TableRow, TableHead, TableCell
• Code — inline and block variants with syntax highlighting support
• Kbd — keyboard shortcut display
• Progress — animated progress bar with percentage

Feedback

• Alert — variant: "default" | "outline" | "filled", optional title
• Spinner — size: "sm" | "md" | "lg"
• Skeleton — shimmer loading placeholder

Navigation

• Breadcrumb — with custom separator
• Tabs — Tabs, TabsList, TabsTrigger, TabsContent

Layout

• Card — Card, CardHeader, CardContent, CardFooter
• Separator — horizontal or vertical
• Stack — direction: "row" | "col", gap, alignment utilities

Development

# Install and build library
cd ../gus-ui-library && npm install && npm run build