@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

cd mladjo-shared-components
npm install

Development

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

Quality checks

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

npm run build         # Outputs to dist/

Using in a Next.js project

npm install @mladjo/shared-components

Import the CSS tokens once at the application root:

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

Then use components anywhere:

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 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 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 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.