npm package: @mladjo/shared-components
Description: Mladjo atomic design system — shared React + TypeScript components
Latest version: 0.3.3

# @mladjo/shared-components

Atomic design system for Mladjo projects — React + TypeScript, published as an npm package.

## Stack

| Layer | Tool |
|-------|------|
| Components | React 18 + TypeScript 5 |
| Build / bundle | Vite 5 (library mode) |
| Type checking | `tsc` |
| Storybook | Storybook 8 + `@storybook/react-vite` |
| Unit tests | Vitest + `@testing-library/react` |
| Linting | ESLint 8 + `eslint-plugin-jsx-a11y` |
| Formatting | Prettier |
| Accessibility | WCAG 2.2 AA (built-in, enforced by lint + tests + Storybook a11y) |

## Getting started

```bash
cd mladjo-shared-components
npm install
```

### Development

```bash
npm run storybook     # Storybook dev server on :6006
npm run test:watch    # Vitest in watch mode
```

### Quality checks

```bash
npm run typecheck     # tsc --noEmit
npm run lint          # ESLint
npm run format:check  # Prettier
npm test              # Vitest run (single pass)
npm run test:coverage # Coverage report
```

### Build

```bash
npm run build         # Outputs to dist/
```

---

## Using in a Next.js project

```bash
npm install @mladjo/shared-components
```

**Import the CSS tokens once** at the application root:

```tsx
// app/layout.tsx  (App Router)
import '@mladjo/shared-components/styles';
```

Then use components anywhere:

```tsx
import { Button } from '@mladjo/shared-components';

export default function Page() {
  return (
    <Button variant="primary" onClick={() => console.log('clicked')}>
      Get started
    </Button>
  );
}
```

---

## Project structure

```
mladjo-shared-components/
├── .storybook/           Storybook configuration
├── docs/
│   ├── WCAG.md           WCAG 2.2 compliance guide for contributors
│   └── DESIGN_TOKENS.md  Token usage guide
├── src/
│   ├── atoms/            Atomic level — smallest building blocks
│   │   └── Button/
│   │       ├── Button.tsx
│   │       ├── Button.module.css
│   │       ├── Button.test.tsx
│   │       ├── Button.stories.tsx
│   │       └── index.ts
│   ├── styles/
│   │   ├── tokens.css    CSS custom properties (design tokens)
│   │   └── reset.css     Minimal CSS reset
│   ├── tokens/           TypeScript design token objects
│   │   ├── colors.ts
│   │   ├── spacing.ts
│   │   ├── typography.ts
│   │   └── index.ts
│   ├── index.ts          Package public API
│   ├── test-setup.ts     Vitest / jest-dom global setup
│   └── vite-env.d.ts     Vite type references
├── .eslintrc.cjs
├── .prettierrc
├── tsconfig.json
├── tsconfig.build.json   Excludes tests & stories from type emission
├── vite.config.ts
└── vitest.config.ts
```

---

## Adding a new component

1. Create a folder under the correct atomic level:
   ```
   src/atoms/MyComponent/
   src/molecules/MyComposite/
   src/organisms/MySection/
   ```

2. Add these files:
   - `MyComponent.tsx` — component implementation
   - `MyComponent.module.css` — styles using `var(--token-*)` custom properties
   - `MyComponent.test.tsx` — unit tests (aim for ≥ 80 % branch coverage)
   - `MyComponent.stories.tsx` — Storybook stories with `autodocs` tag
   - `index.ts` — re-exports

3. Work through **[docs/WCAG.md](./docs/WCAG.md)** checklist before merging.

4. Export from `src/atoms/index.ts` (or molecules/organisms) and then `src/index.ts`.

---

## Accessibility

This design system targets **WCAG 2.2 Level AA** for every component.
Read [`docs/WCAG.md`](./docs/WCAG.md) for the full contributor guide.

Accessibility is enforced at three levels:

- **Lint time** — `eslint-plugin-jsx-a11y` catches missing `alt`, invalid ARIA, missing keyboard handlers.
- **Test time** — Tests assert correct `aria-*` attributes, focus behaviour, and keyboard interaction.
- **Story time** — `@storybook/addon-a11y` runs axe-core on every story and surfaces violations.

---

## Design tokens

See [`docs/DESIGN_TOKENS.md`](./docs/DESIGN_TOKENS.md) for the full token reference.

Tokens exist as both CSS custom properties (`src/styles/tokens.css`) and TypeScript
objects (`src/tokens/`). Import the CSS file at app root; use the TS objects when
you need values in JavaScript.