Poesis

EPFL Intranet React UI component library — a themed, accessible component kit built with React, TypeScript, and Tailwind CSS v4.

Features

• 30+ components — buttons, inputs, cards, dialogs, toasts, tables, navigation shells, and more
• EPFL design tokens — colors, typography, spacing, shadows, and radii baked into Tailwind's @theme
• Dark mode — light / dark themes with a single .dark class toggle and useTheme hook
• i18n ready — built-in EN/FR support via react-i18next, with a useLanguage hook and LanguageSwitcher component
• CSS auto-injection — styles are embedded in the JS bundle; no separate stylesheet import needed
• Fully typed — TypeScript declarations ship with the package
• Storybook — every component has interactive stories with accessibility checks

Installation

npm install poesis

Peer dependencies

Poesis expects the following packages in your project:

| Package | Version | Required | | ----------------------- | ---------------------- | -------- | | react | ^18.0.0 \|\| ^19.0.0 | yes | | react-dom | ^18.0.0 \|\| ^19.0.0 | yes | | @floating-ui/react | ^0.27.0 | yes | | i18next | ^25.0.0 | yes | | react-i18next | ^16.0.0 | yes | | react-bootstrap-icons | ^1.11.0 | optional | | react-router-dom | ^6.0.0 \|\| ^7.0.0 | optional | | react-select | ^5.0.0 | optional |

Quick start

import { Button, Card, Alert, initTheme, ToastProvider } from "poesis";

// Initialise theme once at app startup
initTheme();

function App() {
    return (
        <ToastProvider>
            <Card header="Dashboard">
                <Alert variant="info">Welcome back!</Alert>
                <Button variant="primary">Get Started</Button>
            </Card>
        </ToastProvider>
    );
}

No CSS import is needed — styles are injected automatically when you import any component.

Components

Primitives

Button · IconButton · Badge · Avatar · Spinner

Form Controls

Input · Textarea · Select · Checkbox · Switch · RadioGroup

Data Display

Card · Table · DescriptionList · EmptyState

Feedback

Alert · Dialog · ConfirmDialog · ToastProvider / useToast

Layout

PageShell · TopNav · SideNav · BurgerDrawer

Overlays & Navigation

DropdownMenu · Popover · Tooltip · Tabs

Theme & i18n

ThemeToggle · LanguageSwitcher

Hooks

| Hook | Description | | ------------- | ------------------------------------------------ | | useTheme | Current theme (light / dark) and toggle/set | | initTheme | Initialise theme from localStorage / system pref | | useLanguage | Current language (en / fr) and toggle/set | | useAuth | Access the authenticated user and role setter | | useToast | Imperatively add/remove toast notifications |

Theme utilities

• epflSelectTheme — drop-in react-select theme using EPFL design tokens
• epflSelectClassNames — Tailwind-based classNames config for react-select

Development

Prerequisites

• Node.js 24 (see .nvmrc)
• npm

Scripts

# Install dependencies
npm install

# Start Storybook (development)
npm run storybook

# Build the library (dist/poesis.js + type declarations)
npm run build

# Build Storybook as a static site
npm run build-storybook

# Lint with ESLint
npm run lint

# Format with Prettier (4-space indent)
npm run format

# Check formatting (CI)
npm run format:check

# Build + run integration tests
npm run test:integration

Project structure

├── src/
│   ├── components/
│   │   ├── ui/             # Primitives, form controls, overlays
│   │   ├── layout/         # PageShell, TopNav, SideNav, BurgerDrawer
│   │   ├── data-display/   # Card, Table, DescriptionList, EmptyState
│   │   └── feedback/       # Alert, Dialog, ConfirmDialog, Toast
│   ├── hooks/              # useTheme, useLanguage, useAuth
│   ├── theme/              # react-select theme utilities
│   ├── i18n/               # i18next config + EN/FR translation files
│   ├── stories/            # Storybook stories
│   ├── pages/              # Demo app placeholder pages
│   ├── routes/             # Route config + role types
│   ├── lib.ts              # Library entry point (public API)
│   └── index.css           # Tailwind v4 @theme + design tokens
├── integration-tests/      # Consumer-simulation integration tests
├── .storybook/             # Storybook configuration
├── vite.config.ts          # Vite lib mode + Tailwind + Storybook tests
├── tsconfig.lib.json       # TypeScript config for .d.ts generation
├── PLAN.md                 # Implementation plan & phase tracker
└── STYLING.md              # Full design system specification

Building the library

npm run build

This runs two steps:

1. Vite builds src/lib.ts into dist/poesis.js (ESM, with CSS injected into JS)
2. TypeScript emits declaration files into dist/ (lib.d.ts + per-component .d.ts)

Integration tests

A separate test project in integration-tests/ imports from the built dist/ exactly like a real consumer would. It renders components in a headless Chromium browser via Vitest + Playwright and verifies exports, DOM output, CSS injection, accessibility attributes, and component composition.

npm run test:integration

See integration-tests/README.md for details.

Design system

The full design system specification — colors, typography, spacing, shadows, theming strategy, layout architecture, and component inventory — is documented in STYLING.md.

Authors

• Andrii Babarytskyi
• Juan Convers

Assisted by Claude Opus 4.6

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.