prime-ui-kit

v0.7.13

Published

7 days ago

React 19 UI kit: CSS Modules, semantic design tokens (--prime-sys-*), composable components — forms, modals, selects, tables, navigation, overlays. TypeScript, ESM, a11y-oriented.

prime-ui-kit

A React 19 component library built with CSS Modules, design tokens as CSS variables (--prime-sys-*), and a composable API (Modal.Root, Input.Field, Select.Trigger, …). Works with Vite, Next.js, Remix, or any bundler that supports CSS Modules. Accessibility follows react-aria-components where it fits.

Links: npm · Repository & issues

Metadata (for tooling and LLMs)

name: prime-ui-kit
ecosystem: react
react_version: "^19.0.0"
module_system: ESM
styling: CSS Modules + CSS variables (--prime-sys-*)
a11y_stack: react-aria-components (peer)
documentation_per_component: src/components/<name>/COMPONENT.md
component_examples_glob: src/components/<name>/examples/*.tsx
layout_examples_glob: src/layout/<name>/examples/*.tsx
repository: https://github.com/esurkov1/prime-ui
typography: variant_roles  # see src/components/typography/COMPONENT.md

Key features

Tokens & themes — semantic variables, light and dark themes via data-theme.
Composition — subcomponent pattern (Root, Field, Trigger, …) instead of monolithic prop blobs.
Forms — inputs, selects, toggles, file upload, color, OTP-style fields, sliders.
Overlays — modals, drawers, popovers, menus, tooltips, command palette.
Navigation & layout — sidebar, breadcrumbs, tabs, accordion, stepper, pagination, page shell.
Data — table with sorting, pagination, or infinite scroll.
Types — published .d.ts alongside the package.
Notifications — toast queue via NotificationProvider and useNotifications().

Requirements

| Dependency | Version | |------------|---------| | react / react-dom | ^19.0.0 | | react-aria-components | ^1.16.0 | | react-day-picker | ^9.14.0 | | date-fns | ^4.0.0 |

The package bundles lucide-react, framer-motion, and react-router-dom (icons, notification motion, and Sidebar routing). Use a router (e.g. BrowserRouter) if Sidebar renders navigation items.

Installation

npm install prime-ui-kit react react-dom react-aria-components react-day-picker date-fns

pnpm add prime-ui-kit react react-dom react-aria-components react-day-picker date-fns

bun add prime-ui-kit react react-dom react-aria-components react-day-picker date-fns

Styles and theming

Import global styles (fonts, reset, tokens, both themes) and the bundled component CSS (CSS Modules output from the published build):

@import "prime-ui-kit/styles.css";
@import "prime-ui-kit/bundle.css";

styles.css — Google Fonts, CSS reset, design tokens, light and dark themes.
bundle.css — class rules that match the JS bundle (Button, Input, …).

Light / dark: set data-theme="light" or data-theme="dark" on <html>, a layout root, or any wrapper.

Fine-grained imports (custom reset, single theme):

@import "prime-ui-kit/tokens.css";
@import "prime-ui-kit/theme-light.css";
/* @import "prime-ui-kit/theme-dark.css"; */
@import "prime-ui-kit/bundle.css";

If you only use prime-ui-kit/components, swap bundle.css for prime-ui-kit/components.css.

Quick start

import { Button, Input, Modal } from "prime-ui-kit";

export function Example() {
  return (
    <>
      <Input.Root size="m" label="Email" id="email">
        <Input.Wrapper>
          <Input.Field type="email" placeholder="[email protected]" />
        </Input.Wrapper>
      </Input.Root>

      <Button variant="primary" mode="filled" size="l">
        Submit
      </Button>
    </>
  );
}

Typography

Текст страницы оформляется компонентом Typography с ролями variant: каждая роль задаёт пару кегль/межстрочный интервал из темы (typography.role → --prime-sys-typography-role-*). Примитивы font.size.* согласованы со шкалой MD3; роли выстроены по смыслу рядом с MD3, Apple SF и Polaris — таблица соответствий и примерных rem/px при корне 16px — в Typography COMPONENT.md.

Imports: main entry and heavy modules

prime-ui-kit — main entry; use for most apps.
prime-ui-kit/components — alternate entry for tree-shaking heavier modules (e.g. DataTable).

import { DataTable } from "prime-ui-kit/components";

Providers and context

| API | Purpose | |-----|---------| | NotificationProvider + useNotifications() | Toast queue: notify, dismiss, dismissAll. Wrap your app or a subtree. | | ControlSizeProvider | Default s | m | l | xl for controls inside the subtree. |

Component catalog

Descriptions are short summaries from the About section in each COMPONENT.md (where it exists). Full API, parts, and examples are in the linked files. AppShell, ExampleFrame, and ScrollContainer ship without a dedicated COMPONENT.md — use the linked source folders.

Documentation base URL in the repo: https://github.com/esurkov1/prime-ui/blob/main/src/components/

| Category | Component | Description | Docs | |----------|-----------|-------------|------| | Forms & input | Checkbox | Checkbox with chrome, label, hint, and error text. | COMPONENT.md | | Forms & input | ColorPicker | Color selection: 2D area, channel sliders, swatches, hex, eyedropper (react-aria). | COMPONENT.md | | Forms & input | DigitInput | OTP-style one-character cells with paste and focus handoff. | COMPONENT.md | | Forms & input | FileUpload | File picking: hidden input, drag-and-drop, per-file rows with progress. | COMPONENT.md | | Forms & input | Hint | Helper or status line under a field, optional leading icon. | COMPONENT.md | | Forms & input | Input | Single-line field with wrapper, affixes, and hint/error lines. | COMPONENT.md | | Forms & input | Kbd | Keyboard shortcuts styled as UI chrome (kbd). | COMPONENT.md | | Forms & input | Label | Field caption: icon, required asterisk, secondary text. | COMPONENT.md | | Forms & input | Radio | Radio group with label, hint, and error wiring. | COMPONENT.md | | Forms & input | SegmentedControl | Horizontal radiogroup with segments and a sliding indicator. | COMPONENT.md | | Forms & input | Select | Single-select combobox with a portaled listbox. | COMPONENT.md | | Forms & input | Slider | Horizontal input type="range" with kit sizing. | COMPONENT.md | | Forms & input | Switch | On/off control with label and metadata slots. | COMPONENT.md | | Forms & input | Textarea | Multiline field, character counter, hints and errors. | COMPONENT.md | | Date & time | Datepicker | Calendar, ranges, presets, optional time (react-day-picker + date-fns). | COMPONENT.md | | Overlays | CommandMenu | Modal command palette: search and pick from the list with the keyboard. | COMPONENT.md | | Overlays | Drawer | Side sheet in a portal with scroll lock and focus management. | COMPONENT.md | | Overlays | Dropdown | Action menu with trigger and portaled panel (role="menu"). | COMPONENT.md | | Overlays | Modal | Centered dialog with backdrop, focus trap, optional built-in chrome. | COMPONENT.md | | Overlays | Popover | Anchor + portaled panel; non-modal surface next to the trigger. | COMPONENT.md | | Overlays | Tooltip | Delayed hint; trigger and content in a portal. | COMPONENT.md | | Navigation & layout | Accordion | Expandable sections (FAQ, settings groups) with height animation. | COMPONENT.md | | Navigation & layout | Breadcrumb | nav trail with links, separators, and optional ellipsis. | COMPONENT.md | | Navigation & layout | Pagination | Page controls: prev/next, page numbers, ellipsis. | COMPONENT.md | | Navigation & layout | Sidebar | Side navigation: single panel, groups, menus, responsive overlay. | COMPONENT.md | | Navigation & layout | Stepper | Multi-step flow on <ol> / <li> plus horizontal/vertical primitives. | COMPONENT.md | | Navigation & layout | Tabs | Tablist, indicator, one visible panel at a time. | COMPONENT.md | | Navigation & layout | PageContent | Main column: Section or Root, title, description (measure), body. | COMPONENT.md | | Navigation & layout | AppShell | Application shell: grid root, nav slot, scrollable main with page gutters (x6) on Main. | COMPONENT.md | | Navigation & layout | ScrollContainer | Scrollable region with horizontal or vertical axis (overflow wrapper). | Source | | Data | DataTable | Table with scroll, sorting, pagination or infinite scroll, sticky regions. | COMPONENT.md | | Display & content | Avatar | Circular avatar: image, fallback, group with overflow cell. | COMPONENT.md | | Display & content | Badge | Compact status or count; optional presence dot variant. | COMPONENT.md | | Display & content | Banner | In-flow announcement strip with icon, copy, and actions. | COMPONENT.md | | Display & content | CodeBlock | TS/TSX syntax highlighting in pre/code (static presentation). | COMPONENT.md | | Display & content | ExampleFrame | Preview stage + code layout for playgrounds and internal docs. | Source | | Display & content | Card | Dashboard tiles: mini, mini-media, metric, panel, stat-trend, cta, list, split, cover. | COMPONENT.md | | Display & content | Divider | Horizontal or vertical rule with optional inset label. | COMPONENT.md | | Display & content | ProgressBar | Horizontal progress on the native <progress> element. | COMPONENT.md | | Display & content | SegmentedProgressBar | Stacked horizontal segments with proportional weights and semantic tones. | COMPONENT.md | | Display & content | ProgressCircle | Circular progress ring (SVG + progressbar). | COMPONENT.md | | Display & content | Tag | Chip with optional icon, trailing dismiss when onRemove is set. | COMPONENT.md | | Display & content | Typography | Reading text via semantic variant (roles), weight, tracking, muted tone. | COMPONENT.md | | Actions & feedback | Button | Action control: asChild, icon, loading spinner. | COMPONENT.md | | Actions & feedback | ButtonGroup | Button row sharing one outline and internal dividers. | COMPONENT.md | | Actions & feedback | LinkButton | Text-style link with control padding and underline on hover/focus. | COMPONENT.md | | Actions & feedback | Notification | Toasts: provider, queue, positions, semantic types. | COMPONENT.md |

Package exports (`package.json` / `exports`)

| Path | Purpose | |------|---------| | prime-ui-kit | Main JS/TS API. | | prime-ui-kit/components | Alternate entry for tree-shaking heavier chunks. | | prime-ui-kit/styles.css | Global styles (fonts, reset, tokens, themes). | | prime-ui-kit/tokens.css | Tokens only. | | prime-ui-kit/theme-light.css / theme-dark.css | Individual theme files. | | prime-ui-kit/bundle.css | CSS aligned with the main bundle. | | prime-ui-kit/components.css | CSS for the components entry. |

TypeScript

Type definitions ship with the package (dist/*.d.ts).

Where component docs live

In the repo / on GitHub: each component has src/components/<name>/COMPONENT.md (see the table above). Sidebar uses src/layout/sidebar/COMPONENT.md.
Canonical + extended examples: next to each COMPONENT.md, the examples/ folder holds 3–5 self-contained .tsx files (and optional examples.module.css) with real product scenarios. COMPONENT.md lists them under Extended examples; start from the Canonical example in the same file for a maximal single-block overview.
Why separate files (not one examples.md): each file is one scenario with a clear filename — easier for humans to navigate and for LLMs to retrieve the right chunk without loading an entire mega-document.
In the installed package: COMPONENT.md and examples/** are published (package.json → files), e.g. node_modules/prime-ui-kit/src/components/button/examples/ and node_modules/prime-ui-kit/src/layout/sidebar/COMPONENT.md.

ExampleFrame and ScrollContainer do not have a dedicated COMPONENT.md; refer to the linked source folders and types in the .tsx files.

Application shell layout

Use AppShell.Template so routes render inside AppShell.Main, which applies canonical --prime-sys-spacing-x6 padding (no extra wrapper). PageContent.Root does not add edge padding; pair PageContent with the shell. Import prime-ui-kit/styles.css and prime-ui-kit/bundle.css so layout CSS applies.

Full diagram, token table, and troubleshooting (“margins disappeared”): src/layout/app-shell/COMPONENT.md.

License

MIT — see LICENSE in the repo and in the npm package.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

prime-ui-kit

Table of contents

Metadata (for tooling and LLMs)

Key features

Requirements

Installation

Styles and theming

Quick start

Typography

Imports: main entry and heavy modules

Providers and context

Component catalog

Package exports (package.json / exports)

TypeScript

Where component docs live

Application shell layout

License

Package exports (`package.json` / `exports`)