@bizapps/ui 1.0.0

package/README.md

@@ -0,0 +1,331 @@
+# @bizapps/design-system-testing
+
+A React component library built for TCCE CRM applications. Provides reusable, consistent UI components built with React, TypeScript, and Tailwind CSS v4.
+
+---
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Setup](#setup)
+- [Usage](#usage)
+- [Available Components](#available-components)
+- [Design Tokens](#design-tokens)
+- [Contributing](#contributing)
+- [Publishing a New Version](#publishing-a-new-version)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Requirements
+
+Your project must have the following installed before using this library:
+
+| Package             | Version |
+| ------------------- | ------- |
+| `react`             | ^19     |
+| `react-dom`         | ^19     |
+| `tailwindcss`       | ^4      |
+| `@tailwindcss/vite` | ^4      |
+
+> **Note:** `shadcn`, `tw-animate-css`, and font packages are already bundled inside the library's CSS. You do **not** need to install them separately.
+
+---
+
+## Installation
+
+```bash
+pnpm add @bizapps/design-system-testing
+```
+
+---
+
+## Setup
+
+### 1. Configure Vite
+
+Add the Tailwind CSS plugin to your `vite.config.ts`:
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+    plugins: [react(), tailwindcss()],
+});
+```
+
+### 2. Import the styles
+
+In your main CSS file (e.g. `src/index.css`), add these two lines **in this order**:
+
+```css
+@import 'tailwindcss';
+@import '@bizapps/design-system-testing/styles';
+```
+
+> **Important:** `tailwindcss` must come **before** the library styles so that Tailwind's base layer is available when the library's theme tokens are applied.
+
+### 3. Import the CSS in your entry point
+
+Make sure your `src/main.tsx` imports the CSS file:
+
+```tsx
+import './index.css';
+```
+
+That's it. No further configuration is needed.
+
+---
+
+## Usage
+
+Import components directly from the package:
+
+```tsx
+import { Button } from '@bizapps/design-system-testing';
+
+function App() {
+    return (
+        <Button variant='primary' size='md'>
+            Click me
+        </Button>
+    );
+}
+```
+
+---
+
+## Available Components
+
+### Button
+
+```tsx
+import { Button } from '@bizapps/design-system-testing';
+```
+
+#### Props
+
+| Prop        | Type                                                           | Default     | Description                               |
+| ----------- | -------------------------------------------------------------- | ----------- | ----------------------------------------- |
+| `variant`   | `'primary' \| 'secondary' \| 'cancel' \| 'outline' \| 'ghost'` | `'primary'` | Visual style of the button                |
+| `size`      | `'sm' \| 'md' \| 'lg' \| 'icon-sm'`                            | `'md'`      | Size of the button                        |
+| `isLoading` | `boolean`                                                      | `false`     | Shows a loading state                     |
+| `disabled`  | `boolean`                                                      | `false`     | Disables the button                       |
+| `asChild`   | `boolean`                                                      | `false`     | Renders as child element (via Radix Slot) |
+
+#### Examples
+
+```tsx
+// Variants
+<Button variant="primary">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="cancel">Cancel</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="ghost">Ghost</Button>
+
+// Sizes
+<Button size="sm">Small</Button>
+<Button size="md">Medium</Button>
+<Button size="lg">Large</Button>
+
+// States
+<Button disabled>Disabled</Button>
+<Button isLoading>Loading...</Button>
+
+// As a link (using asChild)
+<Button asChild variant="primary">
+  <a href="/dashboard">Go to Dashboard</a>
+</Button>
+```
+
+---
+
+## Design Tokens
+
+The library exposes a full set of CSS custom properties (design tokens) that you can use directly in your project's styles. These are injected globally when you import the library styles.
+
+### Colors
+
+```css
+/* Brand */
+--color-main-blue-primary: #22205f;
+--color-main-orange-primary: #f66a24;
+--color-main-grey: #605f60;
+
+/* Semantic */
+--color-main-positive-state: #01d42f;   /* success */
+--color-main-warning-state: #ea3a3d;    /* error/danger */
+--color-main-yellow-primary: #faca4a;   /* warning */
+
+/* Scales: dark, light, blue, red, orange, yellow, green, purple */
+/* Each scale goes from 100 (lightest) to 1000 (darkest) */
+--color-blue-100 through --color-blue-1000
+--color-green-100 through --color-green-1000
+/* ...etc */
+```
+
+### Border Radius
+
+```css
+--border-radius-button: 1.875rem;
+--border-radius-secondary-button: 0.625rem;
+--border-radius-card: 1.25rem;
+--border-radius-article: 0.875rem;
+--border-radius-outline: 0.5rem;
+```
+
+### Shadows
+
+```css
+--shadow-black-card
+--shadow-hover-black-card
+--shadow-black-button
+--shadow-hover-black-button
+--shadow-hover-orange-button
+```
+
+### Typography
+
+The library includes the following fonts, loaded automatically:
+
+- **Inter Variable** — primary UI font (`--font-sans`)
+- **Dax** — brand heading font
+- **Helvetica Neue** — secondary font
+
+### Using tokens in your CSS
+
+```css
+.my-card {
+    background: var(--color-main-white);
+    border-radius: var(--border-radius-card);
+    box-shadow: var(--shadow-black-card);
+}
+
+.my-card:hover {
+    box-shadow: var(--shadow-hover-black-card);
+}
+```
+
+### Using tokens in Tailwind classes
+
+The tokens are also registered as Tailwind theme values, so you can use them as utility classes:
+
+```tsx
+<div className='bg-main-blue-primary text-main-white rounded-card shadow-black-card'>Hello</div>
+```
+
+---
+
+## Contributing
+
+### Local Development
+
+```bash
+# Clone the repo
+git clone <repository-url>
+cd tcce-design-system
+
+# Install dependencies
+pnpm install
+
+# Start Storybook (recommended)
+pnpm storybook
+# → http://localhost:6006
+
+# OR start Vite dev server
+pnpm dev
+# → http://localhost:5173
+```
+
+### Adding a New Component
+
+1. Create the component folder under `src/components/ui/ComponentName/`
+2. Build the component following the existing `Button` pattern
+3. Export it from `src/main.ts`
+4. Add a Storybook story under `src/stories/`
+
+### Code Quality
+
+```bash
+pnpm lint          # check for lint errors
+pnpm lint:fix      # auto-fix lint errors
+pnpm format        # format with Prettier
+pnpm type-check    # TypeScript check without building
+```
+
+---
+
+## Publishing a New Version
+
+1. Make your changes and commit them:
+
+```bash
+git add -A
+git commit -m "feat: description of changes"
+```
+
+2. Update the version in `package.json` following [semver](https://semver.org/):
+    - `patch` (0.4.x) → bug fixes
+    - `minor` (0.x.0) → new components or features
+    - `major` (x.0.0) → breaking changes
+
+3. Build the library:
+
+```bash
+pnpm build
+```
+
+4. Publish to npm:
+
+```bash
+npm publish --access public
+```
+
+> Use `npm publish` (not `pnpm publish`) to avoid branch and git-state validation errors from pnpm.
+
+---
+
+## Troubleshooting
+
+### Styles not applying
+
+Make sure the import order in your CSS file is correct — `tailwindcss` must come first:
+
+```css
+@import 'tailwindcss'; /* ✅ first */
+@import '@bizapps/design-system-testing/styles'; /* ✅ second */
+```
+
+### `Cannot resolve './tokens.css'` or similar errors
+
+This means you're using an older version of the package (0.4.0 or 0.4.1). Update to the latest version:
+
+```bash
+pnpm add @bizapps/design-system-testing@latest
+```
+
+### `Scope not found` on publish
+
+The npm scope `@bizapps` belongs to the `bizapps` npm user account. Make sure you're logged in as that user:
+
+```bash
+npm whoami       # should return: bizapps
+npm login        # if not logged in
+```
+
+### pnpm `minimumReleaseAge` policy error
+
+If pnpm blocks installation of a recently published version, run:
+
+```bash
+pnpm config set minimum-release-age 0 --location project
+```
+
+---
+
+## License
+
+MIT — BizAppsTotal &lt;bizapps@tcce.biz&gt;