@springernature/atoms/README.md

React/Next JS components for Atom Elements

# @springernature/atoms

> A production-ready React/Nextjs component library built on Chakra UI v3 for Springer Nature applications.

[![npm version](https://img.shields.io/npm/v/npm)](https://badge.fury.io/js/%40springer%2Felements)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

## Features

- 🎨 **Two Built-in Themes**: Alpha and Beta design systems
- 🔧 **Fully Customizable**: Built on Chakra UI v3 with comprehensive theming
- 📱 **Responsive**: Mobile-first responsive design patterns
- ♿ **Accessible**: WCAG 2.1 compliant components
- 🚀 **Performance**: Tree-shakeable, optimized for production
- 📚 **TypeScript**: Full TypeScript support with strict typing
- 🧪 **Well Tested**: Comprehensive test coverage with Vitest
- 📖 **Documented**: Interactive Storybook documentation

## Installation

```bash
npm install @springernature/atoms
```

### Dependencies

This package includes the following dependencies:

```json
{
  "@chakra-ui/react": "^3.22.0",
  "@emotion/react": "^11.14.0",
  "next-themes": "^0.4.6",
  "react": "^19.1.0",
  "react-dom": "^19.1.0"
}
```

**Note**: Since React and React DOM are included as regular dependencies in this package, you don't need to install them separately. However, ensure your project uses compatible versions:

- **React**: `^19.1.0` or compatible
- **React DOM**: `^19.1.0` or compatible

The package automatically includes all necessary Chakra UI and Emotion dependencies, so no additional peer dependencies are required.

## Quick Start

### Basic Setup

```tsx
import { AtomsThemeProvider } from '@springernature/atoms';

function App() {
  return (
    <AtomsThemeProvider variant="alpha">
      <YourApp />
    </AtomsThemeProvider>
  );
}
```

### Using Components

```tsx
import { Button, Text, Box } from '@springernature/atoms';

function MyComponent() {
  return (
    <Box>
      <Text variant="heading">Welcome to Atom Elements</Text>
      <Button variant="solid" colorScheme="primary">
        Get Started
      </Button>
    </Box>
  );
}
```

## Theme Variants

### Alpha Theme

```tsx
import { AtomsThemeProvider } from '@springernature/atoms';

<AtomsThemeProvider variant="alpha">
  <App />
</AtomsThemeProvider>;
```

### Beta Theme

```tsx
import { AtomsThemeProvider } from '@springernature/atoms';

<AtomsThemeProvider variant="beta">
  <App />
</AtomsThemeProvider>;
```

### Gamma Theme

```tsx
import { AtomsThemeProvider } from '@springernature/atoms';

<AtomsThemeProvider variant="gamma">
  <App />
</AtomsThemeProvider>;
```

## Available Components

This library is **built on top of Chakra UI v3** and re-exports **all Chakra UI components** with enhanced Springer Nature Atoms theming and styling.

### Using Chakra UI Components

Since `@springernature/atoms` is built on Chakra UI, you can use **any Chakra UI component** directly from this package with your selected theme automatically applied:

```tsx
import {
  Button,
  Text,
  Box,
  Stack,
  Input,
  Modal,
  // ... any Chakra UI component
} from '@springernature/atoms';

function MyComponent() {
  return (
    <Box p={4}>
      <Stack spacing={4}>
        <Text variant="heading">All Chakra Components Available</Text>
        <Input placeholder="Chakra Input with Springer Nature Atoms theming" />
        <Button>Chakra Button with Springer Nature Atoms theming</Button>
      </Stack>
    </Box>
  );
}
```

**📚 Component Documentation**: For detailed usage, props, and examples of all available components, refer to the [Chakra UI Components Documentation](https://chakra-ui.com/docs/components/concepts/overview).

> **Note**: All Chakra UI components automatically inherit your selected Springer Nature Atoms theme (Alpha, Beta, or Gamma) when used through `@springernature/atoms`.

### Theme Systems

Pre-configured theme systems ready to use:

- `alphaSystem` - Alpha theme
- `betaSystem` - Beta theme
- `gammaSystem` - Gamma theme

### Theme Configurations

Raw theme configurations for customization:

- `alphaThemeConfig` - Alpha theme configuration
- `betaThemeConfig` - Beta theme configuration
- `gammaThemeConfig` - Gamma theme configuration

## Development

### Prerequisites

- Node.js 22+
- npm 10+

### Setup

```bash
git clone https://github.com/springer/elements.git
cd elements
npm install
```

### Scripts

```bash
npm run dev          # Start Storybook development server
npm run build        # Build the library
npm run test         # Run tests
npm run test:watch   # Run tests in watch mode
npm run lint         # Lint code
npm run type-check   # TypeScript type checking
npm run storybook    # Start Storybook
```

### Project Structure

```
src/
├── hooks/              # Custom hooks
├── providers/          # Theme providers
├── theme/              # Theme system
│   ├── foundations/    # Design tokens
│   ├── variants/       # Theme variants
│   └── system/         # Theme utilities
└── types/              # TypeScript definitions
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Code of Conduct

This project adheres to the [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and migration guides.

## License

ISC License - see [LICENSE](LICENSE) file for details.

## Support

- 📚 [Documentation](https://github.com/elements)
- 🐛 [Issue Tracker](https://github.com/springernature/springer-ui-elements/issues)
- 💬 [Discussions](https://github.com/springernature/springer-ui-elements/discussions)
- 📧 [Email Support](mailto:design-system@springer.com)

---

<p align="center">
  Made with ❤️ by the Springer Nature Team
</p>