@serenis/ui

Main UI component library for the Serenis design system. Provides reusable React components with Storybook documentation, design-token integration, and accessibility support. Components are styled with colocated CSS Modules and @serenis/design-tokens.

Install

npm install @serenis/ui

Quick start

# Build
yarn workspace @serenis/ui build

# Dev (watch mode)
yarn workspace @serenis/ui dev

# Test
yarn workspace @serenis/ui test

# Typecheck
yarn workspace @serenis/ui typecheck

# Lint
yarn workspace @serenis/ui lint
yarn workspace @serenis/ui lint:css

When consuming the published package from npm, load component CSS modules once with import '@serenis/ui/css'. This ships a single dist/index.css for all CSS-module components. Monorepo apps that resolve @serenis/ui to source must not import it (the app bundler handles *.module.css). Per-component CSS loading may replace this later.

import '@serenis/ui/css'

import { cx } from '@serenis/design-tokens'
import { Button, Card } from '@serenis/ui'
;<Card>
  <div className={cx('flex', 'flex-col', 'gap-sm')}>
    <h2 className={cx('typography-h2')}>Session details</h2>
    <p className={cx('typography-paragraph', 'text-neutral-80')}>Your next session is scheduled for tomorrow.</p>
    <Button kind="primary">Confirm</Button>
  </div>
</Card>

Directory structure

libraries/ui/
├── src/
│   ├── {ComponentName}/
│   │   ├── index.tsx               # Main component (or {ComponentName}.tsx)
│   │   ├── index.test.tsx          # Tests
│   │   ├── Playground.stories.tsx  # Primary Storybook story
│   │   ├── Overview.mdx            # Component documentation
│   │   └── types.ts                # Type definitions (if complex)
│   ├── Form/                       # Composite form module
│   │   ├── TextField/
│   │   ├── TextAreaField/
│   │   ├── SelectField/
│   │   ├── PasswordField/
│   │   ├── PhoneNumberField/
│   │   ├── PinCodeField/
│   │   ├── Autocomplete/
│   │   ├── MultiSelect/
│   │   ├── Checkbox/
│   │   ├── CheckboxButton/
│   │   ├── Radio/
│   │   ├── RadioButton/
│   │   ├── SliderField/
│   │   ├── Switch/
│   │   ├── SwitchField/
│   │   ├── FileUploadField/
│   │   ├── internal/               # Shared internal chrome and styles
│   ├── utils/                      # Shared utilities (shouldForwardProp)
│   └── index.ts                    # Public API barrel
├── dist/                           # Built output (gitignored)
├── tsup.config.ts                  # Bundle config
└── package.json

Component catalog

Categories match Storybook (*.stories.tsx / Overview.mdx <Meta title>): General, Data Display, Feedback, Form, Navigation, Layout.

General

Data Display

Feedback

Form

The barrel also exports lower-level primitives (TextInput, TextArea, Select, Checkbox, Radio, Switch, Hint, Label) for advanced use — prefer the field components below in product code.

Navigation

Layout

Dependencies

Styling conventions

• CSS Modules: each component owns its styles in a colocated index.module.css; no utility classes in component source. See docs/agents/styling.md.
• Design tokens for all visual values — never hardcode hex colors, pixel sizes, or font values.

Documentation

• Storybook: Every component has a Playground.stories.tsx and an Overview.mdx next to its source in libraries/ui/src/{ComponentName}/
• Overview.mdx: Comprehensive documentation with props, patterns, dos/don'ts, and known exceptions
• AGENTS.md: Agent-oriented API reference — see AGENTS.md

Consumers

• Apps: apps/web (primary), apps/blog, apps/nutrition-blog, apps/website, apps/design-system (Storybook host)
• Libraries: libraries/shared-components (@serenis/shared-components), libraries/ui-deprecated (legacy — prefer @serenis/ui)

Build

Bundled with tsup into ESM + CJS + TypeScript declarations. Workspace dependencies are externalized.

License

PolyForm Noncommercial 1.0.0 — see LICENSE for the full text.