npm package: @sphere-crm/ui
Description: UI component library for Sphere CRM - Bank Respublika
Author: Bank Respublika
Latest version: 0.1.6

# Sphere UI

Sphere UI is the React/TypeScript component library used across Sphere CRM. The goal is to ship a consistent design system that developers can drop into any React (or Next.js) app, with sensible defaults that still allow heavy customization. The current repository already exposes foundational building blocks such as `Button`, `Loader`, and the shared icon set, and the final version will contain many more components built with the same standards.

## Key Features

- **Typed React components** that target React 18+ and React 19 without workarounds.
- **Design tokens and SCSS variables** so that designers can evolve the brand system without rewriting components.
- **Tree-shakeable build** generated through Vite and TypeScript to keep bundles lean.
- **Icon library** with reusable SVG components for common CRM actions.
- **Future-ready architecture** for adding new inputs, layouts, and complex widgets as the design system grows.

## Installation

Install the package plus its peer dependencies:

```bash
npm install @sphere-crm/ui react react-dom @mui/material @emotion/react @emotion/styled react-to-print
```

If you use another package manager, swap `npm install` for `pnpm add` or `yarn add`.

## Usage

Import the styles once near the root of your application and pull in the components you need:

```tsx
import '@sphere-crm/ui/styles.css'
import { Button } from '@sphere-crm/ui'

function Example() {
  return (
    <Button size="md" tone="primary" onClick={() => console.log('clicked')}>
      Create deal
    </Button>
  )
}
```

### Customizing Tokens

Every component reads from the shared SCSS variables in `src/styles/variables.scss`. Override them inside your app to align with your brand palette:

```scss
:root {
  --sphere-color-primary: #0052cc;
  --sphere-color-primary-hover: #003d99;
  --sphere-radius-md: 8px;
}
```

More tokens (spacing, typography, motion) will be documented as the component catalog grows.

## Available Components

| Category   | Components                               | Notes                                   |
|------------|-------------------------------------------|-----------------------------------------|
| Actions    | `Button`                                  | Variants, sizes, loading states         |
| Feedback   | `Loader` (`Circle`, `Linear`)             | Works standalone or inline              |
| Visuals    | `icons/*`                                 | 170+ SVG icons tailored for CRM flows   |

> Roadmap: inputs, tables, dashboards, printable templates, and layout primitives will follow the same API patterns so migrations remain easy.

## Local Development

```bash
npm install
npm run dev      # story playground via Vite dev server
npm run build    # type-check + library build
npm run preview  # serve the production build locally
```

The build step runs `tsc` followed by `vite build` to emit both ESM and CJS bundles plus `.d.ts` files in `dist/`.

## Contribution Workflow

1. **Create a component folder** inside `src/components` and keep logic functional + typed.
2. **Co-locate styles** via SCSS modules and share tokens through `src/styles/variables.scss`.
3. **Export the component** through `src/index.ts` so it becomes part of the published bundle.
4. **Add usage docs** to this README (or the future docs site) so consumers know the props and patterns.

Please open a PR with design references whenever you add a new component. The maintainers will help ensure consistency and accessibility (focus rings, keyboard navigation, ARIA attributes, etc.).

## License

MIT © Bank Respublika. Reach out to the Sphere CRM platform team for access questions or to request early design assets.