@sehgaltech/psui

v1.0.5

Published

a month ago

A scalable and customizable UI library built with Tailwind CSS v4, TypeScript, and React

0High
0Medium
0Low

sehgaltech

purvisehgal5

ui-library react typescript tailwindcss components design-system

PSUI

A scalable and customizable UI library built with Tailwind CSS v4, TypeScript, and React.

📚 Documentation | 📝 Changelog

Features

🎨 Tailwind CSS v4 - Modern CSS-first configuration with @theme blocks
📦 TypeScript - Full type safety and excellent developer experience
⚡ tsup - Fast and efficient builds with ESM/CJS dual output
📚 Documentation - Custom interactive component documentation using Vite
🧪 Vitest - Fast unit testing with React Testing Library
🎯 Tree-shakeable - Optimized bundle size with side-effect free exports
🎨 Customizable - Easy theme customization via CSS variables

Installation

npm install @sehgaltech/psui
# or
yarn add @sehgaltech/psui
# or
pnpm add @sehgaltech/psui

Usage

Basic Setup

Import the library styles in your application's main CSS file or entry point:

// In your main CSS file (e.g., index.css or app.css)
@import '@sehgaltech/psui/styles';

OR in your JavaScript/TypeScript entry file:

// In your main entry file (e.g., main.tsx or index.tsx)
import './index.css'; // This initializes Tailwind and scans psui
import '@sehgaltech/psui/styles'; // This provides the colors/themes for psui

Note: Make sure your build tool supports Tailwind CSS v4. If you're using Vite, install @tailwindcss/vite plugin:

npm install -D @tailwindcss/vite

Then add it to your vite.config.ts:

import tailwindcss from '@tailwindcss/vite';

export default {
  plugins: [tailwindcss()],
};

Use components in your React application:

import { Button } from '@sehgaltech/psui';

function App() {
  return (
    <div>
      <Button variant="solid" type="primary" size="md">
        Click me
      </Button>
    </div>
  );
}

Button Component

The Button component supports multiple types, variants, sizes, and states:

import { Button } from '@sehgaltech/psui';

// Types (colors)
<Button type="primary">Primary</Button>
<Button type="secondary">Secondary</Button>
<Button type="success">Success</Button>
<Button type="danger">Danger</Button>
<Button type="warning">Warning</Button>
<Button type="info">Info</Button>
<Button type="ghost">Ghost</Button>

// Variants (styles)
<Button variant="solid">Solid (default)</Button>
<Button variant="outlined">Outlined</Button>
<Button variant="dashed">Dashed</Button>
<Button variant="text">Text</Button>
<Button variant="link">Link</Button>

// Sizes
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

// States & Features
<Button loading>Loading...</Button>
<Button disabled>Disabled</Button>
<Button fullWidth>Full Width</Button>
<Button success>Success State</Button>
<Button startIcon={<YourIcon />}>With Icon</Button>

Themes

PSUI ships with two themes: Winter (light) and Starlight (dark). Both use OKLCH colors and semantic tokens (base, primary, secondary, accent, neutral, info, success, warning, error).

Switching themes

Set data-theme on a root element (e.g. <html> or a wrapper):

// Light (default)
<html data-theme="winter">

// Dark
<html data-theme="starlight">

You can switch at runtime:

document.documentElement.setAttribute('data-theme', 'starlight');

Theme tokens

Colors: base-100, base-200, base-300, base-content, primary, primary-content, secondary, secondary-content, accent, accent-content, neutral, neutral-content, info, info-content, success, success-content, warning, warning-content, error, error-content
Radius: --radius-selector, --radius-field, --radius-box
Sizes: --size-selector, --size-field
Border: --border-width

Customization

Override theme variables for a given theme:

[data-theme="winter"] {
  --theme-primary: oklch(70% 0.12 260);
}

Development

Prerequisites

Node.js 18+
npm, yarn, or pnpm

Setup

# Install dependencies
npm install

# Start development build in watch mode
npm run dev

# Run documentation site locally
cd docs && npm run dev

# Run tests
npm test

# Type check
npm run type-check

# Build library
npm run build

Project Structure

psui/
├── src/
│   ├── components/       # React components
│   │   ├── Button/
│   │   └── index.ts
│   ├── styles/           # Tailwind CSS styles
│   │   ├── base.css      # Tailwind import
│   │   └── theme.css     # Theme tokens
│   ├── types/            # TypeScript types
│   ├── utils/            # Shared utilities
│   └── index.ts          # Main entry point
├── docs/                 # Custom Vite React documentation site
└── dist/                 # Build output

Adding New Components

Create component directory in src/components/:

mkdir src/components/MyComponent

Create component file:

// src/components/MyComponent/MyComponent.tsx
import { forwardRef } from 'react';
import type { ComponentProps } from '../../types';

export interface MyComponentProps extends ComponentProps<'div'> {
  // Your props
}

export const MyComponent = forwardRef<HTMLDivElement, MyComponentProps>(
  ({ className, ...props }, ref) => {
    return <div ref={ref} className={className} {...props} />;
  }
);

MyComponent.displayName = 'MyComponent';

Export from component index:

// src/components/MyComponent/index.ts
export { MyComponent } from './MyComponent';
export type { MyComponentProps } from './MyComponent';

Export from main components index:

// src/components/index.ts
export { MyComponent } from './MyComponent';
export type { MyComponentProps } from './MyComponent';

Export from main library entry:

// src/index.ts
export { MyComponent } from './components';
export type { MyComponentProps } from './components';

Create a documentation page in docs/src/pages/MyComponentPage.tsx and add it to the routing in docs/src/App.tsx.

Building and Publishing

Build

npm run build

This generates:

dist/index.js - CommonJS bundle
dist/index.mjs - ES Module bundle
dist/index.d.ts - TypeScript declarations
dist/styles.css - Compiled CSS

Publishing

Update version in package.json
Build the library: npm run build
Publish to npm: npm publish

Deployment (Documentation)

Deploy the custom component documentation site (docs/) to Vercel so others can browse the library online.

Prerequisites

Project pushed to GitHub, GitLab, or Bitbucket
Vercel account

Steps

Deploy via Vercel

In Vercel: Add New Project → import your repository.
Configure the project:
- Framework Preset: Vite
- Root Directory: docs
- Build Command: npm run build
- Output Directory: dist
- Install Command: npm install
Deploy. The published URL will serve your custom Vite React documentation site.

TypeScript Support

PSUI is written in TypeScript and provides full type definitions. All components export their prop types for use in your applications:

import type { ButtonProps } from '@sehgaltech/psui';

const MyButton: React.FC<ButtonProps> = (props) => {
  // Type-safe component
};

Browser Support

Safari 16.4+
Chrome 111+
Firefox 128+

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

PSUI

Features

Installation

Usage

Basic Setup

Button Component

Themes

Switching themes

Theme tokens

Customization

Development

Prerequisites

Setup

Project Structure

Adding New Components

Building and Publishing

Build

Publishing

Deployment (Documentation)

Prerequisites

Steps

TypeScript Support

Browser Support

License

Contributing