UI Kit

A reusable, themeable component library built with React, TypeScript, and Tailwind CSS.

Features

• 🎨 Themeable: Supports dark and light modes with CSS variables
• 🔧 TypeScript: Fully typed components and props
• 🎯 Accessible: Built with accessibility best practices
• 📦 Packaged: Ready for npm distribution
• 🧩 Composable: Primitive components with semantic wrappers
• ⚡ Lightweight: Minimal dependencies (only clsx and tailwind-merge)
• 🎭 Dynamic Sizing: Components adapt to content with minimum size constraints

Components

Primitive Components

• Button: Generic visual button with variants, sizes, and states
• Input: Form input field with error states and dynamic sizing
• Checkbox: Animated SVG checkbox with smooth checkmark animation and label support
• RadioButton: Windows-style radio button with RadioGroup support for form selections
• Toggle: Switch/toggle component with celestial sparkle effects
• Loader: Animated loading spinner with rotating faces and glowing effects
• ThemeSwitch: Animated dark/light mode toggle with sun/moon and stars/clouds visual effects
• SearchBar: Gradient search bar input with integrated search icon and dynamic placeholder sizing
• Card: Flexible card container with header, content, and footer sections
• Tooltip: Accessible tooltip component with position control and delay support
• SocialLinks: Social media links component with platform icons and tooltips
• ContextMenu: Context menu component with grouped items, icons, and variants

Semantic Wrappers

• Form: Form container with backdrop blur and composable form components (dynamically sized)
• SubmitButton: Button wrapper for form submissions with loading/success states

Requirements

• React 19.2.3 or higher
• React DOM 19.2.3 or higher
• Node.js 16.0.0 or higher (for development)

Note: Tailwind CSS is compiled at build time. Consumers do not need Tailwind installed or configured.

Installation

npm install @possibly6400/ui-kit

Usage

Import components and styles separately:

import { Button, Input, ThemeProvider } from '@possibly6400/ui-kit';
import '@possibly6400/ui-kit/styles'; // Required: Import styles explicitly

function App() {
  return (
    <ThemeProvider defaultTheme="dark">
      <Button variant="primary">Click me</Button>
      <Input placeholder="Enter text" />
    </ThemeProvider>
  );
}

Important: You must import the styles explicitly. The CSS is not automatically included when importing components.

Styling & Global CSS

The UI Kit includes global CSS that affects the document root:

• CSS Variables: Theme variables are defined on :root and .theme-light
• Global Resets: Basic resets for box-sizing, html, and body elements
• Theme Classes: Theme switching applies classes to document.documentElement

These global styles are intentional and necessary for the theme system to function. If you need to scope styles or avoid global resets, you can override them in your application CSS.

SSR Compatibility: The ThemeProvider is SSR-safe and works correctly with Next.js, Remix, and other SSR frameworks. All browser API access is properly guarded.

Theme System

The UI Kit supports dark and light themes:

import { ThemeProvider, useTheme } from '@possibly6400/ui-kit';

function App() {
  const { theme, setTheme } = useTheme();

  return (
    <ThemeProvider defaultTheme="dark">
      <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
        Toggle Theme
      </button>
    </ThemeProvider>
  );
}

Development

Preview

Start the preview environment to see all components:

npm run dev

The preview includes:

• Component Showcase: Full demonstration of all component variants and states
• Landing Page: Beautiful landing page preview showcasing all components in a cohesive design

Toggle between the showcase and landing page using the button in the bottom-right corner.

Build

Build the library for distribution:

npm run build

Type Checking

npm run type-check

Linting

npm run lint

Component API

Button

<Button
  variant="primary" | "secondary" | "danger" | "ghost"
  size="sm" | "md" | "lg"
  loading={boolean}
  disabled={boolean}
  onClick={function}
>
  Button text
</Button>

SubmitButton

<SubmitButton
  variant="primary" | "secondary" | "danger"
  size="sm" | "md" | "lg"
  disabled={boolean}
  onSubmit={async () => { /* submit logic */ }}
  successText="Submitted!"
>
  Submit Form
</SubmitButton>

States:

• Disabled (form incomplete): Greyed out, no animations
• Ready (form valid): Full effects and animations
• Success (after submission): Automatic "sent" animation

Input

<Input
  size="sm" | "md" | "lg"
  error={boolean}
  placeholder="Enter text"
  value={string}
  onChange={function}
/>

SearchBar

Search bar component with dynamic sizing based on placeholder text. Automatically adjusts width to fit placeholder content while maintaining minimum size constraints.

<SearchBar
  size="sm" | "md" | "lg"
  placeholder="Search for components..."
  value={string}
  onChange={function}
/>

Features:

• Dynamic width calculation based on placeholder text
• Minimum width constraints per size (sm: 200px, md: 260px, lg: 320px)
• Integrated search icon with hover effects
• Gradient background with neumorphic design

Checkbox

Animated checkbox with smooth SVG checkmark animation. The checkmark animates when checked/unchecked using stroke-dasharray transitions.

<Checkbox
  label="Accept terms"
  checked={boolean}
  onChange={function}
  error={boolean}
  disabled={boolean}
/>

Features:

• Smooth animated checkmark using SVG path animation
• Theme-aware colors (adapts to light/dark mode)
• Error state support with danger color
• Disabled state with reduced opacity
• Size: 2em × 2em (scales with font size)

RadioButton

Windows-style radio button component with RadioGroup support for form selections. Features custom-styled radio buttons with hover effects and smooth transitions.

// Standalone radio button
<RadioButton
  label="Option 1"
  value="option1"
  checked={boolean}
  onChange={function}
  disabled={boolean}
/>

// Radio group
<RadioGroup
  name="options"
  legend="Choose an option"
  value={string}
  onValueChange={function}
  disabled={boolean}
>
  <RadioButton label="Option 1" value="option1" />
  <RadioButton label="Option 2" value="option2" />
  <RadioButton label="Option 3" value="option3" />
</RadioGroup>

Components:

• RadioButton: Individual radio button with label support
• RadioGroup: Container for managing multiple radio buttons as a group

Props:

• RadioButton: label?: string, value: string, checked?: boolean, disabled?: boolean, onChange?: function, onCheckedChange?: function
• RadioGroup: name?: string, legend?: string, value?: string, defaultValue?: string, disabled?: boolean, onValueChange?: function

Features:

• Windows-style custom radio button appearance with 3D effects
• Smooth hover transitions with blue accent colors
• Support for controlled and uncontrolled modes
• RadioGroup context for managing multiple options
• Disabled state with grayscale filter
• Focus-visible outline for accessibility
• Standalone or grouped usage

Toggle

Animated toggle switch with celestial sparkle effects and smooth transitions. Features a star icon with animated sparkles that enhance when the toggle is active.

<Toggle
  label="Enable feature"
  checked={boolean}
  onChange={function}
  error={boolean}
  disabled={boolean}
/>

Features:

• Beautiful animated sparkle effects with multiple particles
• Star icon that rotates and transforms when toggled
• Smooth transitions with radial gradient backgrounds
• Error state with red border indicator
• Disabled state with reduced opacity and paused animations
• Compact size (15px height) with responsive design

ThemeSwitch

Animated theme toggle component with beautiful sun/moon and stars/clouds visual effects. Automatically integrates with the ThemeProvider to switch between dark and light modes.

import { ThemeSwitch, ThemeProvider } from '@possibly6400/ui-kit';

function App() {
  return (
    <ThemeProvider defaultTheme="dark">
      <ThemeSwitch showLabel={true} />
    </ThemeProvider>
  );
}

Props:

• showLabel?: boolean - Show "Dark"/"Light" text next to the toggle (default: true)
• className?: string - Additional CSS classes

Features:

• Beautiful animated sun/moon transition
• Stars appear in dark mode, clouds in light mode
• Smooth animations with cubic-bezier easing
• Size matches medium button height (40px)
• Fully integrated with ThemeProvider

Loader

Animated loading spinner with two rotating circular faces featuring glowing effects. Perfect for indicating loading states in your application.

import { Loader, Spinner } from '@possibly6400/ui-kit';

// Standalone spinner
<Spinner size="sm" | "md" | "lg" />

// Inline loader with label
<Loader 
  variant="inline" | "container"
  size="sm" | "md" | "lg"
  label="Loading..."
/>

// Full container loader
<Loader variant="container" size="lg" label="Loading content" />

Components:

• Spinner: Standalone animated spinner without label
• Loader: Full loader component with optional label and container variant

Props:

• size?: "sm" | "md" | "lg" - Size of the loader (default: "md")
• variant?: "inline" | "container" - Display variant (default: "inline")
• label?: string - Optional loading text label

Features:

• Beautiful rotating faces animation with two circular arcs
• Gold and black arcs with white glow effects
• Smooth 3-second rotation animation
• Three size variants (sm, md, lg)
• Inline and full container display modes
• Optional loading text label

Card

Flexible card component for displaying content with header, content, and footer sections.

import { Card, CardHeader, CardContent, CardFooter } from '@possibly6400/ui-kit';

<Card>
  <CardHeader>
    <h3>Card Title</h3>
  </CardHeader>
  <CardContent>
    <p>Card content goes here</p>
  </CardContent>
  <CardFooter>
    <Button variant="ghost" size="sm">Action</Button>
  </CardFooter>
</Card>

Components:

• Card: Main card container
• CardHeader: Header section with bottom border
• CardContent: Main content area
• CardFooter: Footer section with top border

Features:

• Theme-aware styling with CSS variables
• Flexible layout with composable sections
• Border separators between sections
• Full TypeScript support

Tooltip

Accessible tooltip component that displays contextual information on hover or focus.

import { Tooltip } from '@possibly6400/ui-kit';

const [tooltipOpen, setTooltipOpen] = useState(false);

<Tooltip
  open={tooltipOpen}
  onOpenChange={setTooltipOpen}
  content="This is a tooltip"
  position="top" | "bottom" | "left" | "right"
  delay={number}
  disabled={boolean}
>
  <Button>Hover me</Button>
</Tooltip>

Props:

• open: boolean - Controlled open state
• onOpenChange?: (open: boolean) => void - Callback when open state changes
• content: React.ReactNode - Tooltip content
• position?: "top" | "bottom" | "left" | "right" - Tooltip position (default: "top")
• delay?: number - Delay before showing tooltip in milliseconds (default: 0)
• disabled?: boolean - Disable tooltip functionality
• children: React.ReactElement - Child element to attach tooltip to

Features:

• Accessible with ARIA attributes
• Keyboard support (focus/blur events)
• Position control (top, bottom, left, right)
• Configurable delay
• Arrow indicator pointing to trigger element
• Theme-aware styling

SocialLinks

Social media links component with platform-specific icons and tooltips.

import { SocialLinks } from '@possibly6400/ui-kit';

const links = [
  { platform: 'github', url: 'https://github.com', label: 'GitHub' },
  { platform: 'linkedin', url: 'https://linkedin.com' },
  { platform: 'x', url: 'https://x.com' },
];

<SocialLinks
  links={links}
  orientation="vertical" | "horizontal"
/>

Props:

• links: SocialLink[] - Array of social link objects
• orientation?: "vertical" | "horizontal" - Layout orientation (default: "vertical")
• className?: string - Additional CSS classes

Supported Platforms:

• LinkedIn, GitHub, Instagram, YouTube, Facebook, Spotify, Telegram, Pinterest, X (Twitter)

Features:

• Platform-specific SVG icons
• Hover tooltips with platform names
• Vertical and horizontal layouts
• Smooth animations and transitions
• Accessible with proper ARIA labels

ContextMenu

Context menu component with grouped items, icons, and variant support.

import { ContextMenu } from '@possibly6400/ui-kit';

<ContextMenu
  groups={[
    {
      id: 'actions',
      items: [
        {
          id: 'edit',
          label: 'Edit',
          icon: <EditIcon />,
          onClick: () => console.log('Edit'),
        },
        {
          id: 'copy',
          label: 'Copy',
          icon: <CopyIcon />,
          onClick: () => console.log('Copy'),
        },
      ],
    },
    {
      id: 'danger',
      items: [
        {
          id: 'delete',
          label: 'Delete',
          variant: 'danger',
          icon: <DeleteIcon />,
          onClick: () => console.log('Delete'),
        },
      ],
    },
  ]}
  showSeparators={true}
/>

Props:

• groups: ContextMenuGroupData[] - Array of menu groups
• showSeparators?: boolean - Show separators between groups (default: true)
• className?: string - Additional CSS classes

Item Variants:

• default - Standard menu item
• danger - Destructive action (red styling)
• accent - Accented item (highlighted)

Features:

• Grouped menu items with separators
• Icon support for each item
• Variant styling (default, danger, accent)
• Disabled state support
• Theme-aware styling

Form

Form container component with backdrop blur and composable form elements. Dynamically sizes based on content.

import { Form, FormField, FormButton, FormFooter, FormFooterLink } from '@possibly6400/ui-kit';

// Basic login form
<Form
  title="Welcome Back"
  showLogo={boolean}
  width={number}
  aspectRatio={number}
  footer={ReactNode}
  onSubmit={function}
>
  <FormField
    type="email"
    placeholder="Email"
    label="Email"
    error={boolean}
  />
  <FormField
    type="password"
    placeholder="Password"
  />
  <FormButton type="submit">Sign In</FormButton>
  <FormButton variant="google" type="button">
    Sign in with Google
  </FormButton>
  <FormFooter>
    Don't have an account?{' '}
    <FormFooterLink href="#">Sign up</FormFooterLink>
  </FormFooter>
</Form>

Components:

• Form: Main form container with backdrop blur
• FormField: Input field wrapper with optional label and error state
• FormButton: Button component with primary and Google sign-in variants
• FormFooter: Footer container for form links and text
• FormFooterLink: Animated link component for footer content

Props:

• Form: title?: string, showLogo?: boolean, width?: number, aspectRatio?: number, footer?: ReactNode, className?: string, plus all standard form HTML attributes
• FormField: label?: string, error?: boolean, size?: "sm" | "md" | "lg", plus all standard input HTML attributes
• FormButton: variant?: "primary" | "google", plus all standard button HTML attributes
• FormFooter: Standard div HTML attributes
• FormFooterLink: Standard anchor HTML attributes

Features:

• Backdrop blur effect for modern glassmorphism look
• Optional user/logo icon with animated design
• Theme-aware colors using CSS variables
• Composable structure - works with Checkbox, RadioButton, and other components
• Animated footer links with hover effects
• Customizable width and aspect ratio
• Dynamic sizing based on content
• Full TypeScript support

Architecture Principles

1. Intent-based separation: Components are separated by intent, not by feature
2. Primitive + Semantic: Generic visual components with semantic wrappers
3. No hardcoded colors: All colors derive from CSS variables
4. Theme agnostic: No OS theme detection, explicit theme control
5. Composable: Components can be combined and extended
6. Dynamic sizing: Components adapt to content while maintaining minimum constraints

Quality Assurance

A comprehensive professional audit has been conducted on all components. See docs/AUDIT_REPORT.md for detailed findings, including:

• Architecture and design system integrity analysis
• Component API quality assessment
• Accessibility (A11y) compliance review
• Performance and maintainability evaluation
• Visual consistency and UX rules validation
• Styling strategy assessment
• Improvement recommendations prioritized by severity

The audit identifies critical issues, medium-priority improvements, and long-term scalability considerations to help harden the UI Kit into a production-ready design system.

License

MIT