npm package: @muzammil2003/atoms-design-system
Description: A lightweight, utility-first design system with atoms- prefixed classes
Author: Muzammil
Latest version: 1.0.2

# Atoms Design System

A lightweight, utility-first CSS design system with JavaScript utilities. All classes are prefixed with `atoms-` to prevent conflicts with your existing CSS.

## Features

✨ **Utility-First** - Compose designs directly in your markup  
🎨 **Complete Color Palette** - Primary, secondary, success, danger, warning, info, and grayscale colors  
📐 **Spacing System** - Consistent margin and padding utilities  
🔤 **Typography** - Headings, text sizes, and font weights  
🎯 **Components** - Pre-styled buttons and labels  
🎭 **CSS Variables** - Easy theming and customization  
📦 **Zero Dependencies** - Pure CSS, tiny JavaScript API  
⚡ **Small Bundle Size** - Optimized for production

## Installation

### Via npm

```bash
npm install @your-username/atoms-design-system
```

### Via CDN

```html
<!-- CSS -->
<link rel="stylesheet" href="https://unpkg.com/@your-username/atoms-design-system/dist/atoms.css">

<!-- JavaScript (optional) -->
<script src="https://unpkg.com/@your-username/atoms-design-system/dist/atoms.js"></script>
```

## Usage

### CSS Only

Simply include the CSS file in your HTML:

```html
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="node_modules/@your-username/atoms-design-system/dist/atoms.css">
</head>
<body>
  <button class="atoms-btn atoms-btn-primary">Click Me</button>
</body>
</html>
```

### With JavaScript

```javascript
import Atoms from '@your-username/atoms-design-system';

// Initialize (optional)
Atoms.init();

// Customize theme
Atoms.theme.setPrimaryColor('#ff6b6b');
Atoms.theme.setSecondaryColor('#4ecdc4');

// Or apply multiple theme variables at once
Atoms.theme.applyTheme({
  primary: '#ff6b6b',
  secondary: '#4ecdc4',
  success: '#95e1d3',
});

// Get CSS variable value
const primaryColor = Atoms.getCSSVar('primary');
console.log(primaryColor);
```

### With Webpack/Bundlers

```javascript
// Import CSS and JS
import '@your-username/atoms-design-system/dist/atoms.css';
import Atoms from '@your-username/atoms-design-system';

// Now use the classes in your components
```

## Documentation

### Spacing

#### Margin

All margin utilities follow the pattern `atoms-m{side}-{size}`:

- **Sides**: `t` (top), `b` (bottom), `l` (left), `r` (right), `x` (horizontal), `y` (vertical), or no side for all
- **Sizes**: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `8`, `10`, `12`, `16`, `20`, `auto`

```html
<div class="atoms-m-4">Margin on all sides</div>
<div class="atoms-mt-2">Margin top only</div>
<div class="atoms-mx-auto">Centered horizontally</div>
<div class="atoms-my-6">Margin top and bottom</div>
```

#### Padding

All padding utilities follow the pattern `atoms-p{side}-{size}`:

```html
<div class="atoms-p-4">Padding on all sides</div>
<div class="atoms-pt-2">Padding top only</div>
<div class="atoms-px-6">Padding left and right</div>
<div class="atoms-py-3">Padding top and bottom</div>
```

### Typography

#### Headings

```html
<h1 class="atoms-h1">Heading 1</h1>
<h2 class="atoms-h2">Heading 2</h2>
<h3 class="atoms-h3">Heading 3</h3>
<h4 class="atoms-h4">Heading 4</h4>
<h5 class="atoms-h5">Heading 5</h5>
<h6 class="atoms-h6">Heading 6</h6>
```

#### Text Sizes

```html
<p class="atoms-text-xs">Extra small text</p>
<p class="atoms-text-sm">Small text</p>
<p class="atoms-text-base">Base text</p>
<p class="atoms-text-lg">Large text</p>
<p class="atoms-text-xl">Extra large text</p>
<p class="atoms-text-2xl">2X large text</p>
<p class="atoms-text-3xl">3X large text</p>
```

#### Font Weights

```html
<p class="atoms-font-light">Light weight</p>
<p class="atoms-font-normal">Normal weight</p>
<p class="atoms-font-medium">Medium weight</p>
<p class="atoms-font-semibold">Semibold weight</p>
<p class="atoms-font-bold">Bold weight</p>
```

#### Text Alignment

```html
<p class="atoms-text-left">Left aligned</p>
<p class="atoms-text-center">Center aligned</p>
<p class="atoms-text-right">Right aligned</p>
```

### Colors

#### Text Colors

```html
<p class="atoms-text-primary">Primary text</p>
<p class="atoms-text-secondary">Secondary text</p>
<p class="atoms-text-success">Success text</p>
<p class="atoms-text-danger">Danger text</p>
<p class="atoms-text-warning">Warning text</p>
<p class="atoms-text-info">Info text</p>
<p class="atoms-text-gray-500">Gray text</p>
```

#### Background Colors

```html
<div class="atoms-bg-primary">Primary background</div>
<div class="atoms-bg-secondary">Secondary background</div>
<div class="atoms-bg-success">Success background</div>
<div class="atoms-bg-danger">Danger background</div>
<div class="atoms-bg-gray-100">Gray background</div>
```

### Buttons

#### Basic Buttons

```html
<button class="atoms-btn atoms-btn-primary">Primary</button>
<button class="atoms-btn atoms-btn-secondary">Secondary</button>
<button class="atoms-btn atoms-btn-success">Success</button>
<button class="atoms-btn atoms-btn-danger">Danger</button>
<button class="atoms-btn atoms-btn-warning">Warning</button>
<button class="atoms-btn atoms-btn-info">Info</button>
```

#### Outline Buttons

```html
<button class="atoms-btn atoms-btn-outline-primary">Primary Outline</button>
<button class="atoms-btn atoms-btn-outline-secondary">Secondary Outline</button>
```

#### Button Sizes

```html
<button class="atoms-btn atoms-btn-primary atoms-btn-sm">Small</button>
<button class="atoms-btn atoms-btn-primary">Default</button>
<button class="atoms-btn atoms-btn-primary atoms-btn-lg">Large</button>
```

#### Full Width Button

```html
<button class="atoms-btn atoms-btn-primary atoms-btn-block">Full Width</button>
```

### Labels/Badges

```html
<span class="atoms-label atoms-label-primary">Primary</span>
<span class="atoms-label atoms-label-success">Success</span>
<span class="atoms-label atoms-label-danger">Danger</span>

<!-- Sizes -->
<span class="atoms-label atoms-label-primary atoms-label-sm">Small</span>
<span class="atoms-label atoms-label-primary">Default</span>
<span class="atoms-label atoms-label-primary atoms-label-lg">Large</span>

<!-- Pill style -->
<span class="atoms-label atoms-label-primary atoms-label-pill">Pill Badge</span>
```

### Layout Utilities

#### Display

```html
<div class="atoms-d-none">Hidden</div>
<div class="atoms-d-block">Block</div>
<div class="atoms-d-inline">Inline</div>
<div class="atoms-d-inline-block">Inline Block</div>
<div class="atoms-d-flex">Flex Container</div>
```

#### Flexbox

```html
<!-- Flex container with center alignment -->
<div class="atoms-d-flex atoms-justify-center atoms-align-center atoms-gap-4">
  <div>Item 1</div>
  <div>Item 2</div>
</div>

<!-- Flex row with space between -->
<div class="atoms-d-flex atoms-justify-between">
  <div>Left</div>
  <div>Right</div>
</div>

<!-- Flex column -->
<div class="atoms-d-flex atoms-flex-column atoms-gap-2">
  <div>Top</div>
  <div>Bottom</div>
</div>
```

### Other Utilities

#### Border Radius

```html
<div class="atoms-rounded-none">No radius</div>
<div class="atoms-rounded-sm">Small radius</div>
<div class="atoms-rounded-md">Medium radius</div>
<div class="atoms-rounded-lg">Large radius</div>
<div class="atoms-rounded-full">Full radius</div>
```

#### Shadows

```html
<div class="atoms-shadow-sm">Small shadow</div>
<div class="atoms-shadow-md">Medium shadow</div>
<div class="atoms-shadow-lg">Large shadow</div>
```

#### Width

```html
<div class="atoms-w-full">Full width</div>
<div class="atoms-w-auto">Auto width</div>
```

## Customization

### CSS Variables

All colors and values are defined as CSS variables in the `:root` selector. You can override them:

```css
:root {
  --atoms-primary: #your-color;
  --atoms-secondary: #your-color;
  --atoms-spacing-4: 1.5rem;
  /* etc. */
}
```

### JavaScript Theme API

```javascript
import Atoms from '@your-username/atoms-design-system';

// Change individual colors
Atoms.theme.setPrimaryColor('#ff6b6b');

// Apply complete theme
Atoms.theme.applyTheme({
  primary: '#ff6b6b',
  secondary: '#4ecdc4',
  success: '#95e1d3',
  danger: '#f38181',
  warning: '#ffd93d',
  info: '#6bcf7f',
});

// Access any CSS variable
const spacing = Atoms.getCSSVar('spacing-4');

// Set any CSS variable
Atoms.setCSSVar('spacing-4', '1.5rem');
```

## Examples

### Card Component

```html
<div class="atoms-bg-white atoms-shadow-lg atoms-rounded-lg atoms-p-6">
  <h3 class="atoms-h4 atoms-mb-2">Card Title</h3>
  <p class="atoms-text-gray-600 atoms-mb-4">
    Card description text goes here.
  </p>
  <div class="atoms-d-flex atoms-gap-2 atoms-mb-4">
    <span class="atoms-label atoms-label-primary atoms-label-sm">Tag 1</span>
    <span class="atoms-label atoms-label-secondary atoms-label-sm">Tag 2</span>
  </div>
  <button class="atoms-btn atoms-btn-primary atoms-btn-block">Action</button>
</div>
```

### Hero Section

```html
<section class="atoms-text-center atoms-py-20 atoms-bg-gray-50">
  <h1 class="atoms-h1 atoms-mb-4">Welcome to Our Site</h1>
  <p class="atoms-text-xl atoms-text-gray-600 atoms-mb-6">
    Build amazing things with Atoms Design System
  </p>
  <div class="atoms-d-flex atoms-justify-center atoms-gap-3">
    <button class="atoms-btn atoms-btn-primary atoms-btn-lg">Get Started</button>
    <button class="atoms-btn atoms-btn-outline-primary atoms-btn-lg">Learn More</button>
  </div>
</section>
```

## Development

### Setup

```bash
# Install dependencies
npm install

# Build for production
npm run build

# Development mode with watch
npm run dev

# Start dev server with live reload
npm run serve
```

### Project Structure

```
atoms-design-system/
├── src/
│   ├── atoms.css          # Main CSS file
│   └── index.js           # JavaScript API
├── example/
│   └── index.html         # Demo page
├── dist/                  # Built files (generated)
│   ├── atoms.css
│   └── atoms.js
├── webpack.config.js      # Webpack configuration
├── package.json
└── README.md
```

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - feel free to use this in your projects!

## Publishing to npm

Before publishing, update your `package.json`:

1. Change `@your-username/atoms-design-system` to your npm username
2. Update the `author` field
3. Ensure you're logged in to npm: `npm login`
4. Build the project: `npm run build`
5. Publish: `npm publish --access public`

```bash
# Login to npm
npm login

# Build the project
npm run build

# Publish (first time, use --access public for scoped packages)
npm publish --access public

# For updates, bump version first
npm version patch  # or minor, or major
npm publish
```

## Credits

Created with ❤️ for the developer community.

---

**Happy coding with Atoms! 🚀**