@soujvnunes/ui
v0.1.0
Published
Unstyled React component skeletons that a product themes through CSS custom properties.
Maintainers
Readme
@soujvnunes/ui
Unstyled React component skeletons: markup, props, accessibility and one stylesheet per component, with no colour of their own. A product themes them by mapping each component's CSS custom properties to its own tokens.
Install
pnpm add @soujvnunes/ui reactimport { Icon } from '@soujvnunes/ui'
import { Icon } from '@soujvnunes/ui/Icon'Both paths resolve to the same module, so pick one per codebase.
Stylesheet
Import the stylesheet once, in the CSS entry that holds the theme:
@import 'tailwindcss';
@import '@soujvnunes/ui/styles.css';Every declaration sits in @layer components, so a utility class passed as className wins over it by layer order. Without the import, a component still renders its markup and attributes, unstyled.
Variable grammar
A component's root carries data-slot="<name>" and one data-<axis> attribute per variant, and the stylesheet selects on those attributes. Every value it sets reads one variable:
--<component>-[<variant value>-]<property>[--<state>]| Variable | Reads as |
| --- | --- |
| --icon-md-size | the md size of an icon, its width and height |
| --button-large-height | the large size of a button, its height |
| --button-main-border-color--hover | the main variant of a button, its border colour while hovered |
- Structural values default to the ladder. Size, padding, gap and radius read
calc(var(--spacing) * <number>)andvar(--radius-<number>), so a theme that declares a one-pixel--spacingand the radius steps maps nothing to get them. - Paint values have no default. A colour no theme maps is transparent.
- The mapping goes in a plain
:rootblock, never in@theme:
:root {
--icon-md-size: calc(var(--spacing) * 24);
}Every component takes asChild and then renders its child with the same attributes, so a product extends one by wrapping its own element, such as its own svg inside an Icon.
Storybook
pnpm dev # from the repo root
pnpm storybook # from ui/
pnpm build-storybook # the static build, in ui/storybook-staticIt serves on port 6006, or on the port PORT names, and opens no browser tab: open http://localhost:6006 by hand. It answers component docs to agents at http://localhost:6006/mcp. Its theme, in .storybook/theme.css, is a reference theme with placeholder values, in a light and a dark mode that follow the system setting; it is not part of the npm package.
The Storybook of main is published at main--6af4b1d8205ec2517800544d.chromatic.com, and it serves the component docs to agents at /mcp there too. The Chromatic workflow publishes a build on every push, with chromatic.config.json as its CLI config.
