@serenis/ui

Main UI component library for the Serenis design system. Provides reusable React components with Storybook documentation, design-token integration, and accessibility support. Built with styled-components on top of @serenis/cdk layout primitives.

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

import { SPACING_MD, SPACING_SM } from '@serenis/design-tokens'
import { Button, Card, Text } from '@serenis/ui'
;<Card $p={SPACING_MD} $gap={SPACING_SM}>
  <Text as="h2" kind="h2">
    Session details
  </Text>
  <Text kind="paragraph" colorName="neutral-80">
    Your next session is scheduled for tomorrow.
  </Text>
  <Button kind="primary">Confirm</Button>
</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 (14 exports)
│   │   ├── TextField/
│   │   ├── TextAreaField/
│   │   ├── SelectField/
│   │   ├── PasswordField/
│   │   ├── Autocomplete/
│   │   ├── Checkbox/
│   │   ├── CheckboxButton/
│   │   ├── Radio/
│   │   ├── RadioButton/
│   │   └── ...
│   ├── FileUploadField/            # Drag-and-drop upload (re-exported from barrel; not under Form/)
│   ├── 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

| Component | Description | | --------- | ---------------------------------------------------------- | | Button | Primary interactive element — actions, submits, navigation | | Text | Typographic primitive — all visible text passes through it |

Data Display

| Component | Description | | ---------------- | --------------------------------------------------------------------- | | Accordion | Expandable section with trigger and collapsible content | | AccordionList | Convenience wrapper that renders multiple Accordions | | Avatar | Circular image with name-based acronym fallback | | Badge | Numeric or dot indicator for notifications | | Card | Foundational surface with elevation, outline, and background variants | | Chip | Status/label pill with icon and kind-based coloring | | Pill | Minimal bordered capsule for tags | | Quote | Semantic blockquote with left border accent | | Suggestion | Contextual note with role="note" and colored left border | | Tabs | Tabbed interface with WAI-ARIA tabs pattern and overflow | | SegmentedControl | Pill-style tab switcher for 2–5 options | | Tile | Card with icon, title, description, and action slot | | Timeline | Vertical timeline with icon circles and connectors | | Modal | Centered dialog with drag-to-dismiss, focus trap, compound API | | Drawer | Slide-in panel (bottom on mobile, right on desktop), compound API | | BottomSheet | Mobile bottom sheet with multi-step heights, drag-to-resize | | Popover | Click-triggered floating content anchored to a reference element | | Tooltip | Hover/focus-triggered floating info anchored to a reference element |

Feedback

| Component | Description | | --------- | ------------------------------------------------------------------- | | Alert | Status banner with role="alert", icon, and action slot | | Loader | SVG spinner with prefers-reduced-motion support | | Skeleton | Loading placeholder with shimmer animation and typography alignment |

Form

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

| Component | Description | | --------------- | ------------------------------------------------------- | | TextField | Text input with floating label, hint/error, ARIA wiring | | TextAreaField | Multi-line variant of TextField | | SelectField | Native select with floating label and hint/error | | PasswordField | TextField with visibility toggle | | Autocomplete | TextField with floating suggestions dropdown | | CheckboxButton | Card-style checkbox with label and hint | | RadioButton | Card-style radio with label and hint | | FileUploadField | Drag-and-drop file upload with react-dropzone |

Navigation

| Component | Description | | ---------------- | -------------------------------------------------------- | | Link | Styled anchor for inline text links | | NavigationButton | List-item button for menus and action lists | | BottomBar | Fixed-position mobile bottom navigation bar | | Breadcrumbs | Navigation breadcrumb trail with chevron separators | | SideBar | Collapsible sidebar navigation | | SideBarItem | Navigation item for SideBar (wraps NavigationButton) | | SideBarUser | User avatar + name/email display for SideBar bottom slot | | TopBar | Sticky header with logo and back navigation | | TopBarBack | Back link with chevron icon for TopBar's back slot |

Layout

| Component | Description | | --------- | ---------------------------------- | | Divider | Horizontal/vertical separator line |

Dependencies

| Dependency | Role | | -------------------------------------- | -------------------------------------------------------------------------- | | @serenis/cdk | Layout primitives (Flex, Pressable, PositionFixed, etc.) | | @serenis/design-tokens | Colors, spacing, typography, elevation, border radius | | @serenis/icons | Icon components for Button, Alert, Accordion, etc. | | @serenis/hooks | Shared React hooks | | @serenis/numbers, @serenis/strings | Formatting utilities | | styled-components | CSS-in-JS (uses @sanity/styled-components fork) | | @floating-ui/react | Positioning for Popover, Tooltip, Modal, Drawer, BottomSheet, Autocomplete | | framer-motion | Animations for Modal, BottomSheet | | react-dropzone | File upload for FileUploadField |

Styling conventions

• $ prefix for props passed to styled-components that are styling-only (prevents DOM forwarding): $kind, $backgroundColorName, $gap, etc.
• Design tokens for all visual values — never hardcode hex colors, pixel sizes, or font values.
• shouldForwardProp from @emotion/is-prop-valid for the Text component to control DOM forwarding.

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.