@atomic/ui (work-in-progress)

An atomic, CSS-first, user interface toolkit and library for building custom elements and user interfaces. Built on the web platform, Material Design 3 specifications, and the Lit library.

Monorepo Structure

This project is a monorepo managed with pnpm workspaces and Turborepo.

Package	Description
packages/ui	Core UI library — web components and CSS/SCSS design system
packages/ui-react	React wrappers for @atomic/ui components (via @lit/react)
packages/ui-next	Next.js wrappers for @atomic/ui components
apps/ui-site	Next.js demo and documentation site

Web Components

Component	Status
ez-appbar	✅ Active
ez-base	✅ Active (base class)
ez-button-surface	✅ Active
ez-field	✅ Active
ez-ripple	✅ Active
ez-shape	✅ Active
ez-badge	🚧 Planned
ez-button	🚧 Planned
ez-button-group	🚧 Planned
ez-card	🚧 Planned
ez-dialog	🚧 Planned
ez-divider	🚧 Planned
ez-input	🚧 Planned
ez-list	🚧 Planned
ez-typography	🚧 Planned

CSS / SCSS Modules

The library includes a Material Design 3 design system built with SCSS, covering:

• Base — reset, typography, spacing, elevation, motion, shape, state layers
• Theming — light, dark, and high-contrast Material Design 3 themes
• Components — button (filled, outlined, tonal, text, FAB, icon), card, badge, dialog, divider, field, fieldset, input (checkbox, radio, switch, range, color), list, table, form, shape, focus ring, and more

The compiled CSS is output to dist/css/index.min.css as part of the build.

React / Next.js Wrappers

Both @atomic/ui-react and @atomic/ui-next provide framework-specific wrappers for the following components:

• ez-appbar
• ez-button-surface
• ez-field
• ez-ripple

Development

Prerequisites

• Node.js v24+
• pnpm (package manager)
• Playwright (for Storybook interaction tests)

# Install dependencies
pnpm install

# Install Playwright browsers (required for tests)
pnpm exec playwright install --with-deps

Scripts

Command	Description
pnpm dev	Start development (Storybook + site)
pnpm build	Build all packages
pnpm build:lib	Build packages/ui only
pnpm test	Run tests
pnpm lint	Run ESLint and Stylelint
pnpm lintfix	Run ESLint and Stylelint with auto-fix
pnpm storybook	Start Storybook dev server
pnpm docs	Generate TypeDoc documentation
pnpm run new:element	Scaffold a new component

See root package.json and individual package package.json files for all available scripts.

Creating a New Component

pnpm run new:element

Generated components follow the ez-{name} naming convention. See ez-ripple and ez-field for reference patterns.

License

LGPL-3.0