@springernature/atoms

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

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

npm install @springernature/atoms

Dependencies

This package includes the following dependencies:

{
  "@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

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

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

Using Components

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

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

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

Beta Theme

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

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

Gamma Theme

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:

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.

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

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

Scripts

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

Code of Conduct

This project adheres to the Code of Conduct. By participating, you are expected to uphold this code.

Changelog

See CHANGELOG.md for version history and migration guides.

License

ISC License - see LICENSE file for details.

Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support