# @apliteni/apliteni-ui
[](https://www.npmjs.com/package/@apliteni/apliteni-ui)
[](./LICENSE)
[](https://ui.apli.tech)
The Apliteni design system and UI kit provides shared design tokens, React components,
themes and UI rules for the strategy deck, the text portal, `/account` and future product
surfaces.
The kit ships tokens, component CSS and React components together. Server-rendered pages
that do not use a component framework can still take the CSS, tokens and the inline
strings, or write the kit's `.ui-*` classes by hand. The helpers the root entry publishes —
`icon`, `prism`, `sun`, `moon`, `brand`, `esc`, `safeUrl` and the shared logic — serve
both.
Every component is in Storybook at **[ui.apli.tech](https://ui.apli.tech)**.
## Install
The package is published on the public npm registry. You do not need scope configuration or
an npm token:
```bash
npm install @apliteni/apliteni-ui react react-dom
```
Install React and React DOM yourself, using version 18 or newer. The kit does not declare
either package as a regular or peer dependency. npm therefore does not install them or warn
when they are missing. If they are missing, importing `@apliteni/apliteni-ui/react` fails
at build time or runtime with a module-not-found error.
The React components are a subpath of this package, not a separate package. You get one
install, one version and one version pin.
| Import | What it is |
| --- | --- |
| `@apliteni/apliteni-ui/css` | Tokens and every component stylesheet. Import once at the app root. |
| `@apliteni/apliteni-ui` | The helpers and shared logic: `icon`, `prism`, `sun`, `moon`, `brand`, `esc`, `safeUrl`, motion and the dropdown, chart, pagination and filter helpers. |
| `@apliteni/apliteni-ui/react` | The React components, TypeScript types included. |
| `@apliteni/apliteni-ui/react/css` | Their shell styles. |
| `@apliteni/apliteni-ui/inline` | The same CSS as strings, for a server that inlines it. |
| `@apliteni/apliteni-ui/guidelines/*` | The UI rules as Markdown. |
## Use it
```tsx
import '@apliteni/apliteni-ui/css';
import '@apliteni/apliteni-ui/react/css';
import { AppShell, DataTable, Modal } from '@apliteni/apliteni-ui/react';
import { icon } from '@apliteni/apliteni-ui';
```
The `AppShell` component provides the complete product layout: the rail, the page body and
a topbar over it when you ask for one, so no product rebuilds it. The
[component catalog](docs/components.md#component-catalog) lists it and every other component.
Account and personal settings belong in a modal over the product rather than on a page of
their own — see [Guidelines / Account and settings](guidelines/account-and-settings.md).
### Fonts
The kit defines two font families but does not bundle them, so the host page must load them.
Poppins is `--font-display`, used for headings, brand marks and large readouts. IBM Plex Sans
is `--font-sans`, used for tables, fields, paragraphs, chat and most application text. Both
families support weights 300–700.
```html
```
If a family does not load, the browser uses its system fallback stack. The kit does not
display a message about this fallback.
## Theme and accent
Set the theme on `` with `data-theme="dark|light"`. You can set an accent separately
with `data-accent`:
```html
```
An accent changes only the accent family: `--accent`, `--purple*`, `--glow-purple`, `--ring`
and `--grad-*`. Surfaces, text and signal colours remain unchanged. Green remains the live
colour and pink remains the danger colour. As a result, every accent works in both themes
without requiring component changes. The shipped accents are **Nebula** (purple and the
default), **Phoenix** (ember), **Ocean** (azure) and **Emerald** (jade).
Both attributes override the defaults. If neither is present, the kit uses dark Nebula. If
only `data-accent` is present, the kit uses that accent with the dark theme. An absent
`data-theme` does *not* mean “follow the system”: the kit has no `prefers-color-scheme`
rule. If the host wants to follow the operating system preference, its JavaScript must
choose the theme and add the attribute. See
[an absent attribute means dark](docs/components.md#an-absent-attribute-means-dark).
## The rules
The **Guidelines** explain what a page may contain, which component to choose, which states
it must support, and how to handle colour and wording. The kit follows these rules.
The guidelines ship as Markdown in the package and are also available as a Storybook
section.
- [guidelines/overview.md](guidelines/overview.md) — the index, and the rules the kit has yet to meet.
- [guidelines/the-page.md](guidelines/the-page.md) — read this one before designing a screen.
- [Guidelines in Storybook](https://ui.apli.tech/storybook/?path=/story/guidelines-overview--overview) — the same pages with live specimens.
## Documentation
| Page | What it answers |
| --- | --- |
| [foundations.md](docs/foundations.md) | The tokens and the floors: widths, breakpoints, spacing, type, colour, elevation, the focus ring, the tap floor. |
| [components.md](docs/components.md) | The package: what to import, theming, the component catalog, and what each component guarantees. |
| [react/README.md](react/README.md) | The React components and their props. |
| [contributing.md](docs/contributing.md) | Working on the kit: the repository's layout, Storybook, the guidelines collection, the site, the changelog and releases. |
## Contribute
Use Node 20 or newer. Install [jq](https://jqlang.github.io/jq/), then run:
```bash
npm ci
npm run storybook
npm test && npm test -w react && npm run build-storybook && node site/build.mjs
```
Run the final command before opening a PR.
Add a general, composable kit component only when all three conditions are true: the issue
names at least two products that use it or have requested it; existing components cannot
provide it without copying markup or logic; and it contains no domain-specific data or
rules. If any condition is missing, compose the UI from existing components and add a
Storybook showcase.
To add a component, put its token-based CSS in `src/styles/`. Include that CSS in
`src/index.css` and in both the `styles` map and `cssText` in `src/inline.js`. Put the
React component in `react/src/`; each one needs a test and a story that use the shared
classes and tokens. Shared logic the React components take from the root entry lives in
`src/logic/` and is exported from `src/index.js`. The [guidelines](guidelines/overview.md)
define the design rules.
Open an issue, create a branch from `main`, and link the issue in your PR. If you change a
published file, including this README, bump the version in `package.json` and
`package-lock.json`, and add an entry to `site/changelog.mjs`. Merging that version bump
starts the release workflow. Do not push a tag or publish manually.
[AGENTS.md](AGENTS.md) describes the review, data-handling and release checks.
## License
[MIT](./LICENSE) © Apliteni, for the **code**. The Apliteni name, logos and brand marks
are trademarks and are **not** covered by the MIT license — see
[TRADEMARK.md](./TRADEMARK.md).