npm package: @prosync_solutions/ui
Description: Prosync Design System - Vue 3 component library with design tokens
Latest version: 0.3.0

# @prosync_solutions/ui · Prosync Design System

Vue 3 component library and design token system. Phase 1 ships a focused set of 11 Tier 1 components to get your project started quickly.

[![Storybook](https://img.shields.io/badge/Storybook-Live%20Docs-ff4785?style=for-the-badge&logo=storybook&logoColor=white)](https://prosync-ui-kit-7139f.web.app/)
[![npm](https://img.shields.io/npm/v/@prosync_solutions/ui?style=for-the-badge&color=03439a)](https://www.npmjs.com/package/@prosync_solutions/ui)

> 📖 **[View Live Storybook →](https://prosync-ui-kit-7139f.web.app/)**
> Browse all components, design tokens, usage guidelines, and interactive examples.

---

## Installation

```bash
npm install @prosync_solutions/ui @phosphor-icons/vue
```

**Peer dependencies:** `vue >=3.3.0` · `@phosphor-icons/vue >=2.0.0`

---

## Requirements

| Requirement                                                         | Version    | Notes                                                           |
| ------------------------------------------------------------------- | ---------- | --------------------------------------------------------------- |
| [Vue](https://vuejs.org/)                                           | `>= 3.3.0` | Peer dependency — must be installed in your project             |
| [@phosphor-icons/vue](https://github.com/phosphor-icons/vue)        | `>= 2.0.0` | Peer dependency — used for icons inside components              |
| [Tailwind CSS](https://tailwindcss.com/)                            | **v4**     | Required for styles to work — uses `@layer base` internally     |
| [@tailwindcss/vite](https://tailwindcss.com/docs/installation/vite) | `>= 4.0.0` | Required Vite plugin to process Tailwind v4                     |
| [Vite](https://vitejs.dev/)                                         | `>= 5.0.0` | Recommended bundler (the library is built and tested with Vite) |
| TypeScript                                                          | `>= 5.0`   | Optional — full `.d.ts` types are included                      |

### Tailwind CSS v4 Setup

This library uses Tailwind CSS v4 **internally**. Your consumer project must also have Tailwind v4 configured, or you will see this build error:

```
@layer base is used but no matching @tailwind base directive is present.
```

**Install Tailwind v4:**

```bash
npm install -D tailwindcss @tailwindcss/vite
```

**Add to `vite.config.ts`:**

```ts
import tailwindcss from "@tailwindcss/vite";

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

**Add to your main CSS file (e.g. `src/style.css`):**

```css
@import "tailwindcss";
```

> ℹ️ Tailwind v4 does **not** use `tailwind.config.js` or `postcss.config.js`. Configuration is handled entirely through the Vite plugin and your CSS file.

---

## Quick Start

Import only the components you need from the Tier 1 sub-path:

```ts
// main.ts
import { createApp } from "vue";
import "@prosync_solutions/ui/style.css"; // design tokens + Tailwind utilities
import App from "./App.vue";

createApp(App).mount("#app");
```

```vue
<!-- Any component -->
<script setup>
import { ProButton, ProInput, ProTag } from "@prosync_solutions/ui/tier1";
</script>

<template>
  <ProInput v-model="name" label="Full Name" placeholder="Enter name" />
  <ProButton variant="primary">Submit</ProButton>
  <ProTag variant="success">Active</ProTag>
</template>
```

### Global Registration (optional)

```ts
import ProsyncUITier1 from "@prosync_solutions/ui/tier1";
import "@prosync_solutions/ui/style.css";

app.use(ProsyncUITier1);
```

---

## Phase 1 — Tier 1 Components

| Component     | Description                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------- |
| `ProButton`   | 5 variants · 3 sizes · loading state                                                        |
| `ProInput`    | Text input with built-in label, required asterisk, info tooltip, and AI-extracted indicator |
| `ProSelect`   | Dropdown with normalized options                                                            |
| `ProTextarea` | Multi-line input with configurable rows                                                     |
| `ProTag`      | Status badge — `secondary / success / info / warn / error / attention`                      |
| `ProCard`     | Flexible content container                                                                  |
| `ProModal`    | Dialog overlay — sm / md / lg / xl / full                                                   |
| `ProToast`    | Notification toast — information / success / warn / error                                   |
| `ProAvatar`   | User avatar — xs / sm / md / lg / xl sizes                                                  |
| `ProDivider`  | Horizontal or vertical separator                                                            |
| `ProSpinner`  | Animated loading spinner                                                                    |

---

## Full Component Library

All 28 components ship with the main `@prosync_solutions/ui` import path.

### Form & Input

| Component     | Description                                                                        |
| ------------- | ---------------------------------------------------------------------------------- |
| `ProButton`   | 5 variants · 3 sizes · loading state                                               |
| `ProInput`    | Text input with label, required asterisk, info tooltip, and AI-extracted indicator |
| `ProSelect`   | Dropdown select with normalized option list                                        |
| `ProTextarea` | Multi-line input with configurable rows                                            |

### Display & Feedback

| Component          | Description                                                               |
| ------------------ | ------------------------------------------------------------------------- |
| `ProTag`           | Status badge in 6 variants with optional `status` prop for auto-mapping   |
| `ProCard`          | Flexible content container with configurable padding                      |
| `ProBanner`        | Informational banner for alerts and announcements                         |
| `ProModal`         | Dialog overlay — sm / md / lg / xl / full sizes                           |
| `ProDrawer`        | Slide-in panel from the right edge                                        |
| `ProToast`         | Notification toast — information / success / warn / error                 |
| `ProTooltip`       | Hover tooltip for additional context                                      |
| `ProAvatar`        | User avatar with xs / sm / md / lg / xl sizes, image or initials fallback |
| `ProSpinner`       | Animated loading spinner                                                  |
| `ProSkeleton`      | Skeleton loading placeholder                                              |
| `ProEmpty`         | Empty state illustration and message                                      |
| `ProStatisticCard` | KPI / metric card with label and value                                    |

### Layout & Navigation

| Component        | Description                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------- |
| `ProSidebar`     | Collapsible navigation sidebar with toggle, localStorage persistence, logo and footer slots |
| `ProSidebarItem` | Individual sidebar nav item with active state, tooltip, and nested children                 |
| `ProTopbar`      | Top navigation bar with slots for search, actions, and user menu                            |
| `ProPageHeader`  | Page-level header with title, breadcrumb, and action slots                                  |
| `ProBreadcrumbs` | Breadcrumb navigation trail                                                                 |
| `ProMenu`        | Floating context / dropdown menu                                                            |
| `ProTabs`        | Tab bar with slotted panel content                                                          |
| `ProPagination`  | Page navigation controls                                                                    |
| `ProDivider`     | Horizontal or vertical visual separator                                                     |

### Data

| Component      | Description                     |
| -------------- | ------------------------------- |
| `ProTable`     | Data table container            |
| `ProTableRow`  | Table row with slot-based cells |
| `ProTableCell` | Individual table cell           |

---

## Design Tokens

Tokens are available as CSS custom properties under the `--pds-` prefix.

```css
/* Import raw tokens only (no Tailwind required) */
@import "@prosync_solutions/ui/tokens-tier1";
```

### Tier 1 Token Reference

| Token                        | Value        | Usage                           |
| ---------------------------- | ------------ | ------------------------------- |
| `--pds-brand-primary`        | `#03439a`    | Buttons, focus rings, links     |
| `--pds-brand-primary-strong` | `#02367b`    | Button hover                    |
| `--pds-text-body`            | `#1d293d`    | Default body text               |
| `--pds-text-placeholder`     | `#62748e`    | Input placeholder               |
| `--pds-text-error`           | `#c10007`    | Validation error messages       |
| `--pds-surface-sub-bg`       | `#ffffff`    | Input / card background         |
| `--pds-surface-error`        | `#ffe2e2`    | Error input tint / error tag bg |
| `--pds-border`               | `#e5e7eb`    | Default input border            |
| `--pds-radius-button`        | `6px`        | Buttons, inputs, tags           |
| `--pds-radius-card`          | `12px`       | Cards, containers               |
| `--pds-font-family`          | `Montserrat` | All text                        |
| `--pds-button-height-md`     | `40px`       | Default button height           |
| `--pds-input-height-md`      | `40px`       | Default input height            |

Full token reference: [`src/styles/tokens.json`](./src/styles/tokens.json) · [`src/styles/tokens-tier1.css`](./src/styles/tokens-tier1.css)

---

## Package Exports

| Import path                          | Contents                     |
| ------------------------------------ | ---------------------------- |
| `@prosync_solutions/ui`              | All 28 components            |
| `@prosync_solutions/ui/tier1`        | 11 Tier 1 components + types |
| `@prosync_solutions/ui/style.css`    | Full design token stylesheet |
| `@prosync_solutions/ui/tier1.css`    | Tier 1 token stylesheet      |
| `@prosync_solutions/ui/tokens`       | Raw `tokens.json`            |
| `@prosync_solutions/ui/tokens-tier1` | Raw Tier 1 CSS token file    |

---

## Development

```bash
npm install          # install dependencies
npm run storybook    # component preview at http://localhost:6006
npm run build        # build the library to dist/
```

> 🌐 **Hosted Storybook:** [https://prosync-ui-kit-7139f.web.app/](https://prosync-ui-kit-7139f.web.app/)

---

## License

MIT © Prosync