npm package: @freshclinics/ui
Description: Welcome to Fresh UI, a design system crafted for FreshClinics to help build consistent, visually appealing, and user-friendly interfaces.
Latest version: 2.0.4

# Fresh UI - Design System

Welcome to Fresh UI, a design system crafted for FreshClinics to help build consistent, visually appealing, and user-friendly interfaces.

## Table of Contents

- [Introduction](#introduction)
- [Installation](#installation)
- [Tech Stack](#tech-stack)
- [Getting Started](#getting-started)
- [Available Components](#available-components)
- [CSS Architecture](#css-architecture)
- [Scripts](#scripts)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [Publishing to NPM](#publishing-to-npm)

## Introduction

Fresh UI is a comprehensive collection of atomic and reusable components and style guidelines, designed to provide consistency and scalability across FreshClinics applications. This design system simplifies UI development, ensuring a cohesive and intuitive user experience across all projects.

## Installation

To install Fresh UI, you can use either npm or yarn:

```bash
npm install @freshclinics/ui
```

or

```bash
yarn add @freshclinics/ui
```

## Tech Stack

- React 19
- TypeScript
- Tailwind CSS 4
- Shadcn UI

## Getting Started

After installing Fresh UI, import the components you need and start integrating them into your app:

```javascript
import { Button, Card } from '@freshclinics/ui';

const App = () => (
  <div>
    <Card>
      <Button>Click Me</Button>
    </Card>
  </div>
);
```

Each component comes with its own set of customizable props, making it easy to adjust functionality and styling according to your application's requirements.

## Available Components

Fresh UI includes a wide range of components to cover most common UI needs, including:

- **Buttons** - for primary and secondary actions
- **Cards** - for displaying grouped content
- **Modals** - for dialogs and overlays
- **Forms** - with consistent input styling
- **Alerts** - for notifications and status messages
- And more...

For a comprehensive list of components, their APIs, and examples, check the [Fresh UI documentation](https://example.com/docs).

## CSS Architecture

The design system uses a structured approach to CSS organization:

- **global.css** - Contains base styles, CSS resets, and non-semantic variables
- **theme.css** - Defines all semantic color tokens using OKLCH color space
- **styles.css** - Main entry point that imports all necessary style files

### Semantic Color Tokens

All colors in the design system are organized as semantic tokens in `theme.css`, categorized as:

- **Text Colors** - For typography (`--color-text-primary`, `--color-text-secondary`, etc.)
- **Icon Colors** - For SVG and icon elements
- **Fill Colors** - For backgrounds and surfaces
- **Stroke Colors** - For borders and outlines

Always use these semantic tokens instead of hard-coded color values to ensure consistency.

## Scripts

```bash
# CSS Build
pnpm build       # Compile CSS for production
pnpm dev         # Compile CSS and watch for changes

# Code Quality
pnpm lint        # Check for linting issues
pnpm lint:fix    # Fix linting issues automatically
pnpm format      # Check formatting
pnpm format:fix  # Fix formatting issues automatically

# Testing
pnpm test        # Run tests
pnpm test:watch  # Run tests in watch mode
```

## Documentation

Visit the [Fresh UI Documentation](https://example.com/docs) for detailed information on each component, including examples, usage guidelines, and best practices.

## Contributing

We welcome contributions to improve Fresh UI! To get started:

1. Clone the repository.
2. Install dependencies with `npm install` or `yarn`.
3. Create a new branch for your feature or bug fix.
4. Make your changes and ensure they are properly documented.
5. Submit a pull request for review.


## Publishing to NPM

To publish a new version of Fresh UI, follow these steps:

1. Update the version number in `package.json` as appropriate.
2. Run the build script to compile the package:
   ```bash
   npm run build
   ```
3. Log in to your NPM account:
   ```bash
   npm login
   ```
4. Publish the package to NPM:
   ```bash
   npm publish
   ```

   You can increment the version as needed:
   ```bash
   npm version patch # or minor/major
   ```