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
• Installation
• Tech Stack
• Getting Started
• Available Components
• CSS Architecture
• Scripts
• Documentation
• Contributing
• 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:

npm install @freshclinics/ui

or

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:

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.

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

# 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 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:

   npm run build

3. Log in to your NPM account:

   npm login

4. Publish the package to NPM:

   npm publish

   You can increment the version as needed:

   npm version patch # or minor/major