css-app-ui

Shared React UI library used across CSS Operations services.

The package provides:

• reusable UI components
• app-shell primitives (Layout, TopNav, ErrorBoundary)
• toast state hooks/helpers
• a shared Tailwind configuration and design tokens

Installation

npm install css-app-ui

Peer dependencies:

• react >= 16.8.0
• react-dom >= 16.8.0

Quick Start

1. Import package styles once in your app entry.
2. Wire shared Tailwind config.
3. Use components from the root package export.

// src/main.tsx (or equivalent)
import 'css-app-ui/styles';

// tailwind.config.ts
import type { Config } from 'tailwindcss';
import { tailwindConfig } from 'css-app-ui/tailwind-config';

export default {
  ...tailwindConfig,
  content: [
    './index.html',
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/css-app-ui/dist/**/*.js',
  ],
} satisfies Config;

import { Button, Card, Input, Layout } from 'css-app-ui';

export function Example() {
  return (
    <Layout mode="sidebar" sidebar={() => <aside />}>
      <Card className="p-4 space-y-3">
        <Input placeholder="Email" />
        <Button>Submit</Button>
      </Card>
    </Layout>
  );
}

Styling Model

The package supports two styling entrypoints:

• css-app-ui/styles: full component styles and tokens (recommended)
• css-app-ui/variables: token variables only

Use variables only when your host app owns all Tailwind layers and you only need the shared tokens.

API Surface

Primary export:

• css-app-ui

Subpath exports:

• css-app-ui/styles
• css-app-ui/variables
• css-app-ui/tailwind-config

Notable utilities:

• cn(...classes)
• useToast() and toast (success, error, warning, info, dismiss)
• useIsMobile()
• Layout, TopNav, useTopNavPadding, ErrorBoundary
• Toaster (Radix toast renderer)
• SonnerToaster and sonnerToast (Sonner renderer and helper)

Component Catalog

For a practical, grouped component reference with usage notes, see:

• docs/components.md

This file is included in the published package for local installs.

Common Integration Notes

• Ensure your build includes PostCSS with Tailwind and Autoprefixer.
• Add node_modules/css-app-ui/dist/**/*.js to Tailwind content so utility classes inside library components are not purged.
• Mount one toast renderer in your app root:
  • <Toaster /> for Radix toast stack
  • or <SonnerToaster /> for Sonner toasts
• Layout is a discriminated union:
  • mode="sidebar" requires sidebar
  • mode="topnav" requires navItems, currentPath, and onNavigate

Development

npm run type-check
npm run build

Changelog

See CHANGELOG.md.

License

MIT