@cystackapp/ui

CyStack design system — reusable React UI components used across CyStack's platform dashboards. Built with React 18, TypeScript and Tailwind CSS v4.

Installation

npm install @cystackapp/ui
# or
yarn add @cystackapp/ui

Peer dependencies

Install these in the host app if not already present:

npm install react react-dom react-router-dom react-i18next i18next @untitled-ui/icons-react

| Package | Version | | -------------------------- | --------- | | react | ^18.0.0 | | react-dom | ^18.0.0 | | react-router-dom | ^6.0.0 | | react-i18next | ^15.0.0 | | i18next | >=23 | | @untitled-ui/icons-react | ^0.1.4 |

Setup

The package ships components and a Tailwind theme stylesheet. The host app must use Tailwind CSS v4 and import the theme once in its root stylesheet:

/* src/app/index.css (or your global CSS) */
@import "tailwindcss";
@import "@cystackapp/ui/theme.css";

theme.css registers CSS variables (color tokens, spacing, etc.) and a @source directive so Tailwind can scan the package's classes.

Some components (Table, LoadingState, Notification, …) render translated text via react-i18next. Merge the package's resources into the host app's i18next instance:

import { resources as uiResources } from "@cystackapp/ui";
// merge uiResources into your i18next init

Usage

import { Badge, Button, Tooltip, cn } from "@cystackapp/ui";

export const Example = () => (
  <Tooltip content="Hello">
    <Badge color="brand" size="md">
      New
    </Badge>
  </Tooltip>
);

Available exports

Form controls — Button, Input, Textarea, Checkbox, Radio, Switch, Select, Combobox, Searchbox, TagsInput, FormField

Display — Badge, BadgeTag, BadgeMore, Avatar, Card, Divider, Skeleton, ProgressBar, Media, OperatingSystemIcon, FeaturedIcon, KeyboardShortcutLabel, BackgroundPatternGrid

Feedback — Alert, Banner, Toaster/createToast, NotificationBox/createNotification, EmptyState, ErrorState, LoadingState, Loader

Overlays — Modal, Drawer, Popover, Tooltip, Dropdown

Navigation — Tabs, Breadcrumb, PageTitle

Data — Table, ExpandableTable, TableActionButton, FilterDropdown, useFilters, DonutChart, ChartLegend

Disclosure — Accordion, Collapsible

Hooks — useResizeObserver, useScrollListener, useWindowResizeListener, useMutationObserver, useTransitionEndListener, useAnimationFrame, useElementShift, usePopoverCoord, useValidatedCombobox, useClickOutsideModal, useCountdown, useDebounce, useToastList

Utilities — cn (clsx + tailwind-merge), Observable, getBadgeAutoColor, URL param codecs (stringCodec, searchCodec, numberCodec, csvCodec)

The authoritative list lives in src/index.ts — anything not exported there is internal and may change without notice.

Development

npm install          # install dependencies
npm run storybook    # component playground at :6007
npm run build        # build dist/ (vite + dts)
npm run typecheck    # tsc --noEmit
npm run lint         # eslint
npm run test         # vitest + playwright component tests
npm run i18n         # regenerate src/i18n/resources.ts from locale/ folders

Component tests need Playwright browsers on first run:

npx playwright install chromium

Publishing

CI publishes to npm automatically. On pushes to main (or tags), the build job runs cystack-deployer, which builds the Dockerfile: install → typecheck + lint → build → scripts/publish.sh. The publish step skips when the version in package.json already exists on the registry, so re-runs are safe.

To release: bump version in package.json, update CHANGELOG.md, and merge to main. The NPM_TOKEN build arg / CI variable must hold an npm automation token with publish access to the @cystackapp scope.

License

MIT