@plumile/ui
v0.2.28
Published
Shared React UI primitives and theme for Kronex applications
Maintainers
Readme
@plumile/ui
Shared React UI primitives, layouts, and theme foundations for Kronex applications.
Status
Specialized public package. This package is intended for teams adopting the Kronex design language and component conventions. It is not a generic UI kit for arbitrary React applications.
Purpose
@plumile/ui is the visual layer of the Kronex ecosystem. It provides:
- theme contracts and tokens
- low-level form and feedback primitives
- shared layouts and page shells
- data-heavy and admin-oriented widgets
- reusable backoffice visual components
It does not provide:
- application business logic
- GraphQL orchestration
- router orchestration beyond consuming router links where needed
Installation
npm install @plumile/uiPeer dependencies:
npm install react@^19.3.1 react-dom@^19.3.1 i18next@^27.0.0 react-i18next@^18.0.0 @plumile/router@^0.2.15@plumile/router is a required peer in the current manifest, including for
applications using another router. Such applications can use the router-neutral
ButtonLink render adapter or the native LinkButton.
Load the component styles once from the application entry point. The Kronex reset and page baseline are deliberately separate and opt-in:
import '@plumile/ui/style.css';
import '@plumile/ui/baseline.css'; // Optional application reset.The package does not bundle a font. To use the design-system typography, load
Inter 400 and 600 through the application's font pipeline; otherwise the
fontFamily.sans token falls back to its system stack. Additional Inter weights
are optional and should only be loaded when the application uses them. The
baseline consumes that token but never controls an application root or hides
horizontal overflow.
Quick Start
import type { JSX } from 'react';
import '@plumile/ui/style.css';
// Opt in once when the application wants the Kronex reset:
import '@plumile/ui/baseline.css';
import { Toolbar, ToolbarGroup } from '@plumile/ui';
import { Button } from '@plumile/ui/button';
import { ThemeProvider } from '@plumile/ui/theme';
export function ExampleScreen(): JSX.Element {
return (
<ThemeProvider defaultMode="light">
<Toolbar aria-label="Screen actions" role="region">
<ToolbarGroup>
<Button>Save</Button>
</ToolbarGroup>
<ToolbarGroup justify="end">
<Button variant="soft" tone="neutral">
Cancel
</Button>
</ToolbarGroup>
</Toolbar>
</ThemeProvider>
);
}Importing or mounting ThemeProvider does not install global CSS. The only
public stylesheet entry points are the required component stylesheet
@plumile/ui/style.css and the optional application baseline
@plumile/ui/baseline.css.
For composition, nested themes and server rendering, see the layout guide and theme guide.
Main Public Surface
The package exposes the general component catalogue from @plumile/ui and
stable family entry points for contracts that benefit from explicit ownership:
@plumile/ui/buttonforButton,IconButton, native, router-neutral, and Plumile-router button links;@plumile/ui/selectforSelect,NativeSelect,Combobox, its compound parts,AutocompleteField,CollectionFilter,TreeSelect,Cascader, and their public types;@plumile/ui/tabsfor interactive tabs and routed navigation tabs;@plumile/ui/datesfor civil and zoned temporal values, calendars and pickers;@plumile/ui/colorsfor color values, fields and pickers;@plumile/ui/chartsfor chart data contracts and the extended chart families;@plumile/ui/editorforRichTextEditor,RichTokenField, their versioned document schemas, parsers and explicit plain-text export;@plumile/ui/schedulefor controlled planning, its independent views, and shared event/resource/selection contracts;@plumile/ui/themefor providers, tokens, Sprinkles, recipes, breakpoints, contrast metadata, and custom-theme helpers;@plumile/ui/icons/<IconName>for one icon per explicit tree-shakeable entry point.
Do not import private src/ paths, nested icon-owner paths, or an undocumented
subpath. The package exports map is the complete public module boundary.
Start with customization and content contracts. Detailed contracts are owned by the linked guides; Storybook supplies examples and interaction evidence. Specialized entry guides:
For small usage costs and unit rates, MoneyAmount and formatCurrencyAmount
accept opt-in adaptive precision. See monetary display
for bounds, detailed values and the unchanged native-currency default.
Public Family Owners
The inventory guard derives these families from public source owners. The matching Storybook navigation is the visual catalogue; focused tests remain the behavioral owner. The comments are stable machine-readable reconciliation keys.
| Family | Discoverable owner |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Actions | Atomic/Atoms and action-group stories |
| Backoffice | Backoffice and Admin stories |
| Data display | table, record-list, tile, metric, timeline, and chart stories |
| Feedback | banner, empty, toast, spinner, skeleton, and status stories |
| Forms | input, checkbox, radio, switch, select, and field stories |
| Icons | generated icon exports and icon catalogue stories |
| Layout | foundation, shell, surface, card, and panel stories |
| Media | image and image-preview stories |
| Navigation | navigation tabs, interactive tabs, breadcrumbs, sidebar, and menu stories |
| Overlay | modal, dialog, popover, and preview stories |
| Theme | public/backoffice theme provider stories |
| Typography | heading, text, Markdown, and code stories |
| Utilities | remaining focused public helpers and their owner stories |
Package Layout
Source lives under src/; it is not an import surface. Follow the
export map when consuming the package. The
source tree
contains these owners:
index.tsassembles the root public catalogue;button.ts,select.tsandtabs.tsassemble their focused entries.theme/owns design tokens, providers, Sprinkles and shared style recipes.atomic/contains established low-level components;components/contains generic components and layouts. Read the owning component, its CSS, and colocated stories/tests together.dates.tsanddates/own temporal values, calendars and pickers.colors.tsandcolors/own canonical color values and controls.editor.tsandeditor/own structured editors and document contracts.charts.tsandcharts/own extended charts and data contracts.schedule.tsandschedule/own planning views and event contracts.backoffice/owns reusable admin presentation; application integrations live in the separate@plumile/backoffice-reactpackage.internal/andshared/contain implementation infrastructure, not new consumer entry points.hooks/,icons/andi18n/own their respective helpers, artwork and English/French resources.
Validation Notes
See validation commands and evidence boundaries. Run contributor commands from the installed repository root. Package scripts and dependencies are defined in package.json.
Limitations
- supported browsers are Chromium and WebKit; Firefox is outside the support scope
- this package assumes Kronex theme tokens and styling conventions
- it is intentionally opinionated for backoffice and admin-style interfaces
- it does not try to be a framework-agnostic design system
- some components assume other Kronex packages, especially
@plumile/router - the package ships English and French UI resources; applications own their product locales and translated domain content
- Storybook matrices and PNG baselines are repository acceptance tools, not a promise that every consumer shell, browser extension, portal host, or assistive-technology combination has been exercised
- partial themes may override only existing typed tokens; they cannot add arbitrary token keys or theme-dependent React structure
Related Docs
The root export SynchronizationIndicator provides a compact accessible status
button with informational tooltip and popover. Applications supply its
presentation state; connection management belongs to their integration layer.
See feedback components for the
shared header pattern.
