ui-sucks

Production-grade, tree-shakeable, headless React primitives built for real design systems.

_{Documentation v1. The atlas visualizes the broader primitive vision. Shipping in 0.1.0 today: Button, Dialog, and Toast.}

Why ui-sucks

ui-sucks is intentionally small, strict, and boring in the right places:

• Headless by default, so your design system owns the presentation
• TypeScript-first with exported public types
• Tree-shakeable ESM and CJS builds
• Accessibility-focused behavior and ARIA wiring
• Minimal dependency surface with React and React DOM as peers
• Production-ready release flow with Changesets, CI, tests, and size budgets

Current Production Components

Button

• Headless native button primitive
• Supports toggle mode
• Controlled and uncontrolled APIs

Dialog

• Composable Dialog, DialogTrigger, DialogContent, DialogTitle, DialogDescription, DialogClose, and DialogPortal
• Focus management and keyboard dismissal
• Modal and non-modal patterns

Toast

• ToastProvider, ToastViewport, Toast, and useToast
• Queue-driven notifications
• Auto-dismiss with pause and resume interactions

Component Atlas

The SVG atlas in this README is a visual roadmap that highlights the broader primitive direction for the repository, including:

• Button
• Icon Button
• Navbar
• Bento Grid
• Input
• Textarea
• Select
• Combobox
• Checkbox
• Radio Group
• Switch
• Tabs
• Accordion
• Tooltip
• Popover
• Dropdown
• Dialog
• Drawer
• Toast
• Table
• Breadcrumb
• Pagination
• Avatar
• Badge
• Command Palette

See docs/COMPONENT-CATALOG.md for a clear split between shipped components and roadmap items.

Installation

npm install ui-sucks

Peer dependencies:

npm install react react-dom

With pnpm:

pnpm add ui-sucks react react-dom

Quick Start

import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
  ToastProvider,
  ToastViewport,
  useToast,
} from 'ui-sucks';

function Demo() {
  const { push } = useToast();

  return (
    <>
      <Button
        toggle
        onPressedChange={(pressed) => {
          if (pressed) {
            push({
              title: 'Saved',
              description: 'Your changes were stored.',
            });
          }
        }}
      >
        Save
      </Button>

      <Dialog>
        <DialogTrigger>Open dialog</DialogTrigger>
        <DialogContent aria-label="Example dialog">
          <DialogTitle>Dialog title</DialogTitle>
          <DialogDescription>Accessible content with focus management.</DialogDescription>
          <DialogClose>Close</DialogClose>
        </DialogContent>
      </Dialog>

      <ToastViewport />
    </>
  );
}

export function App() {
  return (
    <ToastProvider>
      <Demo />
    </ToastProvider>
  );
}

API Snapshot

Button

import { Button } from 'ui-sucks';

<Button toggle defaultPressed onPressedChange={(value) => console.log(value)}>
  Toggle me
</Button>;

Props:

• toggle?: boolean
• pressed?: boolean
• defaultPressed?: boolean
• onPressedChange?: (pressed: boolean) => void
• All native button props

Dialog

import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogTitle,
  DialogTrigger,
} from 'ui-sucks';

<Dialog defaultOpen={false} onOpenChange={(open) => console.log(open)}>
  <DialogTrigger>Open</DialogTrigger>
  <DialogContent aria-label="Settings">
    <DialogTitle>Settings</DialogTitle>
    <DialogDescription>Review your preferences.</DialogDescription>
    <DialogClose>Close</DialogClose>
  </DialogContent>
</Dialog>;

Toast

import { Button, ToastProvider, ToastViewport, useToast } from 'ui-sucks';

function Demo() {
  const { push } = useToast();

  return (
    <>
      <Button
        onClick={() =>
          push({
            title: 'Profile updated',
            description: 'All changes have been synced.',
          })
        }
      >
        Show toast
      </Button>
      <ToastViewport />
    </>
  );
}

Repository Structure

ui-sucks/
  src/
    components/
      button/
      dialog/
      toast/
    utils/
  tests/
  docs/
  examples/
    nextjs/
    vite/

Documentation

• Architecture
• Component Catalog
• Roadmap
• Publishing
• Contributing
• Security Policy
• Support
• Changelog

Development

Install dependencies:

corepack pnpm install

Run the main scripts:

corepack pnpm dev
corepack pnpm lint
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build
corepack pnpm size
corepack pnpm smoke

Examples

Build the library first, or run the watch build in another terminal.

corepack pnpm build
corepack pnpm --filter vite-example dev
corepack pnpm --filter nextjs-example dev

Release Process

Manual release:

npm login
corepack pnpm changeset
corepack pnpm version-packages
corepack pnpm smoke
corepack pnpm publish --access public

Automated release:

• Push changesets to main
• Configure the repository secret NPM_TOKEN
• Let the included GitHub Actions release workflow create the version PR or publish automatically

Open Source Standards

• MIT licensed
• GitHub Actions CI
• Dependabot configuration
• Issue templates and pull request template
• CODEOWNERS and release workflow
• Smoke-tested local build

Created By

ui-sucks was created by Hariom Kumar Pandit.