@bizapps/design-system-testing 0.4.2 → 1.0.0

package/README.md

@@ -1,500 +1,331 @@
-# TCCE Design System
+# @bizapps/design-system-testing
 
-A React component library for the TCCE CRM applications. Provides reusable, consistent UI components built with React, TypeScript, Tailwind CSS, and styled-components.
+A React component library built for TCCE CRM applications. Provides reusable, consistent UI components built with React, TypeScript, and Tailwind CSS v4.
 
-## Overview
-
-This is a **component library** designed to ensure visual and functional consistency across all TCCE CRM frontend applications. It includes:
-
-- **50+ reusable components** (Button, Card, Dialog, Table, Forms, etc.)
-- **Design tokens** (colors, typography, spacing, shadows)
-- **Storybook documentation** for all components
-- **TypeScript support** with full type definitions
+---
 
 ## Table of Contents
 
-- [Prerequisites](#prerequisites)
-- [Quick Start](#quick-start)
-- [Project Structure](#project-structure)
-- [Development](#development)
-- [Building Components](#building-components)
-- [Code Quality](#code-quality)
-- [Testing Components](#testing-components)
-- [Publishing](#publishing)
+- [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)
 
 ---
 
-## Prerequisites
+## Requirements
 
-| Tool | Version | Notes |
-|------|---------|-------|
-| **Node.js** | v18+ | LTS recommended |
-| **pnpm** | v8+ | Package manager |
-| **Docker** | v20+ | Required for containerized development |
-| **Git** | Any | Version control |
+Your project must have the following installed before using this library:
 
-### Docker Network Prerequisite
+| Package             | Version |
+| ------------------- | ------- |
+| `react`             | ^19     |
+| `react-dom`         | ^19     |
+| `tailwindcss`       | ^4      |
+| `@tailwindcss/vite` | ^4      |
 
-If using Docker Compose, you must create the `tcce-network` network before starting the containers:
-
-```bash
-docker network create tcce-network
-```
+> **Note:** `shadcn`, `tw-animate-css`, and font packages are already bundled inside the library's CSS. You do **not** need to install them separately.
 
-**Important:** Always use `docker-compose.dev.yml` when running with Docker Compose.
+---
 
-### Installing pnpm
+## Installation
 
 ```bash
-npm install -g pnpm
+pnpm add @bizapps/design-system-testing
 ```
 
 ---
 
-## Quick Start
-
-### Local Development
+## Setup
 
-```bash
-# Clone the repository
-git clone <repository-url>
-cd tcce-design-system
+### 1. Configure Vite
 
-# Install dependencies
-pnpm install
+Add the Tailwind CSS plugin to your `vite.config.ts`:
 
-# Start Storybook (recommended for development)
-pnpm storybook
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
 
-# OR start Vite dev server
-pnpm dev
+export default defineConfig({
+    plugins: [react(), tailwindcss()],
+});
 ```
 
-**Access:**
-- Storybook: http://localhost:6006
-- Vite Dev: http://localhost:5173
+### 2. Import the styles
 
-### Using Docker (Recommended for Teams)
+In your main CSS file (e.g. `src/index.css`), add these two lines **in this order**:
 
-```bash
-docker compose -f docker-compose.dev.yml up
+```css
+@import 'tailwindcss';
+@import '@bizapps/design-system-testing/styles';
 ```
 
----
-
-## Project Structure
-
-```
-tcce-design-system/
-├── src/
-│   ├── components/           # All UI components
-│   │   ├── Badge/
-│   │   ├── Button/
-│   │   ├── Can/             # Authorization component
-│   │   ├── Card/
-│   │   ├── Divider/
-│   │   ├── Icon/
-│   │   ├── InfoLabel/
-│   │   ├── Spinner/
-│   │   ├── Stepper/
-│   │   ├── Typography/
-│   │   ├── Token/           # Design tokens showcase
-│   │   ├── forms/           # Form components
-│   │   │   ├── Checkbox/
-│   │   │   ├── FormField/
-│   │   │   ├── PinInput/
-│   │   │   ├── RadioInput/
-│   │   │   └── inputs/      # Input components
-│   │   ├── layout/          # Layout components
-│   │   ├── navigations/     # Navigation components
-│   │   ├── notifications/    # Toast & notifications
-│   │   ├── overlays/        # Dialog, Tooltip, etc.
-│   │   └── Table/           # Data tables
-│   ├── shared/
-│   │   ├── hooks/           # Shared React hooks
-│   │   ├── types/           # Global TypeScript types
-│   │   └── utils/           # Utility functions
-│   ├── globals.css          # Global styles
-│   ├── tokens.css           # Design tokens CSS
-│   └── main.ts              # Library entry point
-├── .storybook/              # Storybook configuration
-├── public/                  # Static assets (fonts, images)
-├── dist/                    # Build output (generated)
-├── package.json
-├── vite.config.ts
-├── tsconfig.json
-└── eslint.config.js
-```
+> **Important:** `tailwindcss` must come **before** the library styles so that Tailwind's base layer is available when the library's theme tokens are applied.
 
-### Component Structure
+### 3. Import the CSS in your entry point
 
-Each component follows this pattern:
+Make sure your `src/main.tsx` imports the CSS file:
 
-```
-ComponentName/
-├── ComponentName.tsx        # Main component
-├── ComponentName.types.ts  # TypeScript interfaces
-├── ComponentName.styles.ts # Styled-components styles
-├── ComponentName.stories.tsx # Storybook stories
-├── index.ts                # Barrel export
-└── components/             # Sub-components (if needed)
+```tsx
+import './index.css';
 ```
 
----
-
-## Development
+That's it. No further configuration is needed.
 
-### Available Scripts
+---
 
-| Command | Description |
-|---------|-------------|
-| `pnpm dev` | Start Vite development server |
-| `pnpm storybook` | Start Storybook (recommended) |
-| `pnpm build` | Build library for production |
-| `pnpm build-storybook` | Build static Storybook |
-| `pnpm preview` | Preview production build |
-| `pnpm lint` | Run ESLint |
-| `pnpm lint:fix` | Fix ESLint issues |
-| `pnpm format` | Format with Prettier |
+## Usage
 
-### Environment Variables
+Import components directly from the package:
 
-Create a `.env` file if needed (check `.env.example`):
+```tsx
+import { Button } from '@bizapps/design-system-testing';
 
-```bash
-# Not required for local development
+function App() {
+    return (
+        <Button variant='primary' size='md'>
+            Click me
+        </Button>
+    );
+}
 ```
 
 ---
 
-## Building Components
-
-### Creating a New Component
+## Available Components
 
-1. **Create the component folder:**
+### Button
 
-```bash
-src/components/controls/MyComponent/
+```tsx
+import { Button } from '@bizapps/design-system-testing';
 ```
 
-2. **Create files following the pattern:**
-
-```typescript
-// MyComponent.types.ts
-export interface MyComponentProps {
-  variant?: 'primary' | 'secondary';
-  // ... other props
-}
+#### 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>
 ```
 
-```typescript
-// MyComponent.tsx
-import type { MyComponentProps } from './MyComponent.types';
-import { StyledMyComponent } from './MyComponent.styles';
-
-export const MyComponent = ({ variant = 'primary', ...props }: MyComponentProps) => {
-  return <StyledMyComponent $variant={variant} {...props} />;
-};
-```
+---
 
-```typescript
-// MyComponent.styles.ts
-import styled from 'styled-components';
+## Design Tokens
 
-export const StyledMyComponent = styled.div<{ $variant: string }>`
-  /* Styles using Tailwind and styled-components */
-`;
-```
+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.
 
-```typescript
-// MyComponent.stories.tsx
-import type { Meta, StoryObj } from '@storybook/react';
-import { MyComponent } from './MyComponent';
-
-const meta = {
-  title: 'Controls/MyComponent',
-  component: MyComponent,
-  tags: ['autodocs'],
-} satisfies Meta<typeof MyComponent>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Primary: Story = {
-  args: {
-    variant: 'primary',
-  },
-};
-```
+### Colors
 
-```typescript
-// index.ts
-export * from './MyComponent';
-export * from './MyComponent.types';
-```
+```css
+/* Brand */
+--color-main-blue-primary: #22205f;
+--color-main-orange-primary: #f66a24;
+--color-main-grey: #605f60;
 
-3. **Export from main.ts:**
+/* Semantic */
+--color-main-positive-state: #01d42f;   /* success */
+--color-main-warning-state: #ea3a3d;    /* error/danger */
+--color-main-yellow-primary: #faca4a;   /* warning */
 
-```typescript
-// src/main.ts
-export * from './components/controls/MyComponent';
+/* 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 */
 ```
 
-4. **Run Storybook to test:**
+### Border Radius
 
-```bash
-pnpm storybook
+```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;
 ```
 
-### Component Patterns
+### Shadows
 
-- **Use styled-components** for component-specific styles
-- **Use Tailwind CSS** via `@apply` in styles
-- **Prefix styled-component props** with `$` (transient props)
-- **Always create TypeScript types** in `.types.ts` files
-- **Create Storybook stories** for documentation and testing
+```css
+--shadow-black-card
+--shadow-hover-black-card
+--shadow-black-button
+--shadow-hover-black-button
+--shadow-hover-orange-button
+```
 
----
+### Typography
 
-## Code Quality
+The library includes the following fonts, loaded automatically:
 
-### Linting & Formatting
+- **Inter Variable** — primary UI font (`--font-sans`)
+- **Dax** — brand heading font
+- **Helvetica Neue** — secondary font
 
-This project uses:
-- **ESLint** - Code linting
-- **Prettier** - Code formatting
-- **TypeScript** - Type safety
+### Using tokens in your CSS
 
-### Running Checks
+```css
+.my-card {
+    background: var(--color-main-white);
+    border-radius: var(--border-radius-card);
+    box-shadow: var(--shadow-black-card);
+}
 
-```bash
-# Lint
-pnpm lint
+.my-card:hover {
+    box-shadow: var(--shadow-hover-black-card);
+}
+```
 
-# Fix lint issues
-pnpm lint:fix
+### Using tokens in Tailwind classes
 
-# Format code
-pnpm format
+The tokens are also registered as Tailwind theme values, so you can use them as utility classes:
 
-# Type check
-pnpm build  # (includes tsc)
+```tsx
+<div className='bg-main-blue-primary text-main-white rounded-card shadow-black-card'>Hello</div>
 ```
 
-### Pre-commit Hooks
+---
 
-Ensure you run these before committing:
+## Contributing
+
+### Local Development
 
 ```bash
-pnpm lint:fix && pnpm format
-```
+# Clone the repo
+git clone <repository-url>
+cd tcce-design-system
 
-### ESLint Rules
+# Install dependencies
+pnpm install
 
-Key rules enforced:
-- React hooks dependencies must be correct
-- No unused variables
-- Prettier formatting required
+# Start Storybook (recommended)
+pnpm storybook
+# → http://localhost:6006
 
----
+# OR start Vite dev server
+pnpm dev
+# → http://localhost:5173
+```
 
-## Testing Components
+### Adding a New Component
 
-### Using Storybook
+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/`
 
-Storybook is the primary way to test components:
+### Code Quality
 
 ```bash
-pnpm storybook
-```
-
-- Browse components at http://localhost:6006
-- Use **Controls** panel to test props
-- Use **Actions** panel to see event handlers
-- Check **Accessibility** tab for a11y issues
-
-### Component Story Format
-
-Write stories following CSF (Component Story Format):
-
-```typescript
-// ComponentName.stories.tsx
-import type { Meta, StoryObj } from '@storybook/react';
-import { ComponentName } from './ComponentName';
-
-const meta = {
-  title: 'Category/ComponentName',
-  component: ComponentName,
-  parameters: {
-    layout: 'centered',
-  },
-  tags: ['autodocs'],
-  argTypes: {
-    variant: { control: 'select', options: ['primary', 'secondary'] },
-  },
-} satisfies Meta<typeof ComponentName>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Primary: Story = {
-  args: {
-    variant: 'primary',
-    label: 'Click me',
-  },
-};
-
-export const Secondary: Story = {
-  args: {
-    variant: 'secondary',
-    label: 'Cancel',
-  },
-};
+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
+## Publishing a New Version
 
-### Building for npm
+1. Make your changes and commit them:
 
 ```bash
-# Build the library
-pnpm build
-
-# Check dist folder
-ls dist/
+git add -A
+git commit -m "feat: description of changes"
 ```
 
-### Publish to npm
+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
 
-```bash
-# Login to npm
-npm login
+3. Build the library:
 
-# Publish
-npm publish
+```bash
+pnpm build
 ```
 
-The build outputs:
-- `dist/tcce-design-system-components.js` (ESM)
-- `dist/tcce-design-system-components.umd.cjs` (UMD)
-- `dist/tcce-design-system-components.css`
-- Type definitions via `vite-plugin-dts`
-
-### Consuming in Other Projects
+4. Publish to npm:
 
 ```bash
-# Install from npm (when published)
-pnpm add tcce-design-system
-
-# Or from local path
-pnpm add ../tcce-design-system
+npm publish --access public
 ```
 
-```typescript
-// Usage
-import { Button, Card } from 'tcce-design-system';
-import 'tcce-design-system/dist/tcce-design-system-components.css';
-```
+> Use `npm publish` (not `pnpm publish`) to avoid branch and git-state validation errors from pnpm.
 
 ---
 
-## Contributing
-
-### Workflow
-
-1. **Create a branch:**
-   ```bash
-   git checkout -b feature/component-name
-   ```
-
-2. **Make changes:**
-   - Follow component patterns
-   - Add Storybook stories
-   - Update types
-
-3. **Run quality checks:**
-   ```bash
-   pnpm lint:fix
-   pnpm format
-   pnpm build
-   ```
-
-4. **Commit and push:**
-   ```bash
-   git add .
-   git commit -m "feat: add new component"
-   git push origin feature/component-name
-   ```
-
-5. **Create Pull Request**
-
-### Coding Standards
+## Troubleshooting
 
-- Use **TypeScript** for everything
-- Use **styled-components** for styling
-- Use **Tailwind CSS** utilities via `@apply`
-- Follow existing component patterns
-- Write **stories** for all components
-- Use **transient props** (`$prop`) in styled-components
-- **No comments** unless absolutely necessary
+### Styles not applying
 
-### Versioning
+Make sure the import order in your CSS file is correct — `tailwindcss` must come first:
 
-This project uses [Semantic Versioning](https://semver.org/):
+```css
+@import 'tailwindcss'; /* ✅ first */
+@import '@bizapps/design-system-testing/styles'; /* ✅ second */
+```
 
-- **MAJOR**: Breaking changes
-- **MINOR**: New features (backward compatible)
-- **PATCH**: Bug fixes
+### `Cannot resolve './tokens.css'` or similar errors
 
-Update version in `package.json` before publishing.
+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
+```
 
-## Troubleshooting
+### `Scope not found` on publish
 
-### Common Issues
+The npm scope `@bizapps` belongs to the `bizapps` npm user account. Make sure you're logged in as that user:
 
-**Port already in use:**
 ```bash
-# Find and kill process on port 6006
-lsof -i :6006
-kill -9 <PID>
+npm whoami       # should return: bizapps
+npm login        # if not logged in
 ```
 
-**Dependencies issues:**
-```bash
-rm -rf node_modules
-pnpm install
-```
+### pnpm `minimumReleaseAge` policy error
 
-**Docker build fails:**
-```bash
-docker build --no-cache -t tcce-design-system .
-```
+If pnpm blocks installation of a recently published version, run:
 
-**TypeScript errors:**
 ```bash
-# Check for type errors
-npx tsc --noEmit
+pnpm config set minimum-release-age 0 --location project
 ```
 
-### Getting Help
-
-- Check Storybook docs: http://localhost:6006
-- Review existing component patterns
-- Contact: bizapps@tcce.biz
-
 ---
 
 ## License
 
-MIT License
-
-## Team
-
-- **Author:** BizAppsTotal <bizapps@tcce.biz>
-- **Version:** 0.3.24
+MIT — BizAppsTotal &lt;bizapps@tcce.biz&gt;