@pithyx/ui

@pithyx/ui is the React component library of the Pithyx desktop, built on React Aria Components (keyboard, touch and screen reader support), together with the design tokens in tokens.css. The tokens and the class names for plain HTML elements work without React. Third-party apps can use it to look like the desktop; the SDK does not require it.

Installing

npm install @pithyx/ui@next react react-dom

React and React DOM 19 are peer dependencies. Import the token file once and wrap your app in the provider:

import '@pithyx/ui/tokens.css';
import { UiProvider, Button } from '@pithyx/ui';

export function App() {
  return (
    <UiProvider locale="de-AT">
      <Button>Save</Button>
    </UiProvider>
  );
}

UiProvider sets the locale for React Aria and for the package’s own texts (English and German; other languages show English). Without it the components follow the browser.

Tokens without React

@pithyx/ui/tokens.css is the only token file of Pithyx and needs no JavaScript. Colors follow the system’s light or dark setting (light-dark()); force one with <html data-theme="light"> or "dark". In an app the SDK sets data-theme to the desktop’s scheme on connect and on every theme change, so the components follow the desktop, not the browser. Choose an accent with <html data-accent="...">: petrol (the default), ocean, indigo, plum, moss or graphite. Every preset is contrast-checked in both themes. The token names are on Theming and design tokens.

The components read the --color-*, --space-*, --radius-* and --control-height tokens, not the SDK’s --pithyx-* properties. An app that uses the components therefore imports tokens.css. Once the SDK connected, the components follow the desktop without code: the SDK sets the scheme and data-pithyx-theme on the root, and tokens.css then takes the desktop’s colors and fonts from the --pithyx-* properties, including the user’s accent; hover and pressed shades of the accent are derived from it.

For your own CSS next to the components, use the same tokens of tokens.css (--color-*, --space-*, --radius-*, --font-*, --control-height); their names belong to the API of @pithyx/ui and follow its SemVer, so a rename is a major version. An app without @pithyx/ui uses the SDK’s --pithyx-* properties instead, a stable contract of the SDK.

@pithyx/ui/native exports class names for native elements that look like the components, without React Aria: buttonStyles, controlStyles and textFieldStyles, plus cx and uiTexts. It is meant for code that has to stay small.

Components

• Buttons: Button (with ButtonVariant) and IconButton.
• Fields: TextField, PasswordField, SearchField and OtpField.
• Controls: Checkbox, Switch, ProgressBar and Badge.
• Overlays: Dialog, Menu, MenuItem, MenuTrigger, MenuPopover, MenuSeparator, ContextMenuPopover, Tooltip and TooltipTrigger.
• Helpers: UiProvider, useDeliberatePress, cx and uiTexts.

There is no select or list box component yet. For a choice from a list use a native <select> styled with the tokens (min-height: var(--control-height), border: 1px solid var(--color-border), border-radius: var(--radius-sm), background: var(--color-surface-1), color: var(--color-text)), or a list of Button variant="quiet" for choices that open something.

Checkbox and Switch take their label as children (<Checkbox isSelected={done} onChange={setDone}>Done</Checkbox>), ProgressBar as label.

The API reference has a page per component, generated from its TSDoc (for example Button and Dialog), and every token with its value on tokens.

Icons

@pithyx/ui exports no icons. The desktop uses Tabler Icons (MIT); to look the same, add @tabler/icons-react to your app with the range @pithyx/ui itself depends on (^3.48.0, so your bundle keeps one copy) and import each icon you use, for example import { IconTrash } from '@tabler/icons-react';. Give an IconButton its label, which is also its tooltip and accessible name.