@apliteni/apliteni-ui

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.

Install

The package is published on the public npm registry. You do not need scope configuration or an npm token:

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.

Use it

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 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.

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.

<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700&family=IBM+Plex+Sans:wght@300;400;500;600;700&display=swap">

If a family does not load, the browser uses its system fallback stack. The kit does not display a message about this fallback.

Lint app styles

The package ships a stylelint config at @apliteni/apliteni-ui/stylelint. It refuses a raw colour, a raw px, rem or em spacing value, and an override of a .ui-* kit class. Install stylelint, then extend the config:

npm install --save-dev stylelint

{
  "extends": ["@apliteni/apliteni-ui/stylelint"]
}

Use a semantic colour token such as var(--text) and a spacing token such as var(--space-4) from @apliteni/apliteni-ui/tokens. Turn a rule off only with a comment that names the approved exception, after --:

/* stylelint-disable color-no-hex -- an approved brand colour */

Theme and accent

Set the theme on <html> with data-theme="dark|light". You can set an accent separately with data-accent:

<html data-theme="dark" data-accent="phoenix">

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.

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 — the index, and the rules the kit has yet to meet.
• guidelines/the-page.md — read this one before designing a screen.
• Guidelines in Storybook — the same pages with live specimens.

Documentation

Contribute

Use Node 20 or newer. Install jq, then run:

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 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 describes the review, data-handling and release checks.

License

MIT © Apliteni, for the code. The Apliteni name, logos and brand marks are trademarks and are not covered by the MIT license — see TRADEMARK.md.