@uxf/ui
v16.1.0
Published
React UI component library (Tailwind CSS) for UXF projects
Readme
@uxf/ui
React UI component library (Tailwind CSS) for UXF projects. Each component is a subpath import — e.g. import { Button } from "@uxf/ui/button" — and ships with its own README under packages/ui/<component>/.
When to use
Use @uxf/ui for presentational, controlled UI primitives — buttons, inputs, overlays, layout, feedback. For form fields wired to react-hook-form, use the matching @uxf/form/<name> component, which wraps the @uxf/ui primitive and manages value/validation for you.
Installation
yarn add @uxf/uiPeer dependencies: @uxf/core, @uxf/core-react, @uxf/styles, @uxf/datepicker, @uxf/localize, @floating-ui/react, @base-ui/react, react-dropzone, dayjs, react, react-dom, and optionally next (>=16.4.3): Next.js before 16.0.0 lacks the React APIs @uxf/ui uses in App Router pages, and before 16.4.3 it has two critical remote code execution vulnerabilities.
Setup
1. Provider
Wrap the app once in UiContextProvider (from @uxf/ui/context). It configures translations, locale, color scheme, the icon sprite, and raster-image breakpoints, and internally provides TranslationsProvider (@uxf/core-react/translations) and the localize provider — so you do not add those separately.
import { UiContextProvider } from "@uxf/ui/context";
<UiContextProvider
value={{
colorScheme,
domain: "https://www.example.com",
icon: { spriteFilePath, iconsConfig },
localeConfig: { locale: "cs" },
rasterImage: { breakpoints },
translationFn,
}}
>
{children}
</UiContextProvider>;Icon-rendering components (Icon, and anything using it) and responsive RasterImage throw without this provider.
2. Styles
CSS is published under @uxf/ui/css/. Import the shared token layer once, globally:
@import url("@uxf/ui/css/tokens/generated/figma-colors.css");
@import url("@uxf/ui/css/tokens/common.css");
@import url("@uxf/ui/css/tokens/typography.css");Then import the stylesheet of each component you use (each component's README lists its exact set), e.g.:
@import url("@uxf/ui/css/button.css");
@import url("@uxf/ui/css/select.css");Component CSS is flattened into
@uxf/ui/css/<file>.cssat build time (bin/css-prepare.sh); this is the published path. Inside this monorepo, workspaces resolve@uxf/uito source, where the same files live at@uxf/ui/<name>/<name>.css.
Popup offset
The gap between a field or button and its dropdown, date picker panel or menu is 4px. Set
--uxf-popup-offset (in px) to change it. The popups render in a portal, so set it on :root, or on
.uxf-dropdown-positioner, .uxf-input-with-popover__positioner or .uxf-button-list__positioner for one
kind of popup:
:root {
--uxf-popup-offset: 6px;
}Do not add a margin to the popup instead: the popup is measured with its margins, and a margin that differs
by side makes it jump between the top and the bottom of the field.
3. Tailwind colors
Extend your Tailwind theme with the Figma color tokens:
const { figmaColors } = require("@uxf/ui/figma-colors");
module.exports = {
theme: { extend: { colors: { ...figmaColors } } },
};The primary scale is aliased to your brand color (e.g. primary_surface_default → brand_surface_default).
Components
Every component is documented in its own README under packages/ui/<component>/ (e.g. button, select, modal). Components come in @uxf/ui (controlled primitive) and, for form fields, a matching @uxf/form twin — each component's README states which to use when.
