Philosophy

Atman (आत्मन्) is a Sanskrit word meaning "essence," "soul," or "self." This design system embodies that philosophy — providing only essential components without unnecessary complexity.

• Essence over excess — Only essential components, no bloat
• Universal truth — Framework-agnostic, works everywhere
• Inner consistency — Coherent tokens and patterns throughout
• Accessible by default — WCAG AA compliance as baseline

Installation

npm install atman-ds

Quick Start

Import Styles

Include the design tokens in your HTML or import them in your CSS:

<!-- Via link tag -->
<link rel="stylesheet" href="node_modules/atman-ds/dist/tokens/index.css" />

Or import in your JavaScript/TypeScript:

import 'atman-ds';

Use Components

<!-- Button -->
<atman-button variant="primary">Click me</atman-button>
<atman-button variant="secondary">Secondary</atman-button>
<atman-button variant="ghost">Ghost</atman-button>

<!-- Input -->
<atman-input
  label="Email"
  type="email"
  placeholder="[email protected]"
></atman-input>

<!-- Card -->
<atman-card>
  <h3 slot="header">Card Title</h3>
  <p>Card content goes here.</p>
  <div slot="footer">
    <atman-button variant="primary">Action</atman-button>
  </div>
</atman-card>

<!-- Alert -->
<atman-alert variant="success" alert-title="Success!">
  Your changes have been saved.
</atman-alert>

With React

import 'atman-ds';

function App() {
  return (
    <div>
      <atman-button variant="primary" onClick={() => alert('Clicked!')}>
        Click me
      </atman-button>
    </div>
  );
}

With Vue

<template>
  <atman-button variant="primary" @click="handleClick">
    Click me
  </atman-button>
</template>

<script setup>
import 'atman-ds';

const handleClick = () => {
  alert('Clicked!');
};
</script>

Components

Primitives

| Component | Description | |-----------|-------------| | <atman-button> | Buttons with variants: primary, secondary, ghost, destructive | | <atman-badge> | Status indicators with color variants | | <atman-avatar> | User avatars with image, initials, or fallback | | <atman-icon> | Icon wrapper with Lucide icon support |

Form Controls

| Component | Description | |-----------|-------------| | <atman-input> | Text input with label, error states, prefix/suffix | | <atman-select> | Dropdown select with keyboard navigation | | <atman-checkbox> | Checkbox with indeterminate state | | <atman-radio> | Radio buttons with group support | | <atman-switch> | Toggle switch with label position options | | <atman-textarea> | Multiline text input with auto-resize and character count |

Feedback

| Component | Description | |-----------|-------------| | <atman-alert> | Alert messages with variants and dismissible option | | <atman-toast> | Toast notifications with auto-dismiss | | <atman-skeleton> | Loading placeholders | | <atman-tooltip> | Tooltips with placement options | | <atman-progress> | Progress bar (linear & circular) with indeterminate mode |

Layout

| Component | Description | |-----------|-------------| | <atman-card> | Container with header, body, and footer slots | | <atman-modal> | Modal dialogs with focus trap | | <atman-tabs> | Tabbed interface with keyboard navigation | | <atman-divider> | Visual separator with optional label |

Navigation

| Component | Description | |-----------|-------------| | <atman-breadcrumb> | Breadcrumb trail with link and current-page support | | <atman-pagination> | Page navigation with ellipsis for large ranges | | <atman-dropdown> | Dropdown menu with keyboard navigation and icon support |

Data Display

| Component | Description | |-----------|-------------| | <atman-accordion> | Collapsible sections with single or multiple expand modes | | <atman-table> | Data table with sorting, selection, striped rows, and empty/loading states |

Theming

Atman uses CSS Custom Properties for theming. Override tokens to customize the design system:

:root {
  /* Colors */
  --atman-color-primary: #111111;
  --atman-color-success: #1E8E3E;
  --atman-color-warning: #F9AB00;
  --atman-color-destructive: #D93025;

  /* Typography */
  --atman-font-family: 'Geist', sans-serif;
  --atman-font-size-md: 16px;

  /* Spacing */
  --atman-space-4: 16px;

  /* Border Radius */
  --atman-radius-md: 8px;
}

Dark Mode

Enable dark mode by adding data-theme="dark" to your document:

<html data-theme="dark">
  ...
</html>

Or toggle programmatically:

document.documentElement.setAttribute('data-theme', 'dark');

Design Tokens

| Category | Tokens | |----------|--------| | Colors | Primary, Success, Warning, Destructive, Neutral scale | | Spacing | 4px base unit (4, 8, 12, 16, 24, 32, 48, 64) | | Typography | Sizes (12-48px), Weights (400-700), Line heights | | Border Radius | sm (4px), md (8px), lg (12px), full (9999px) | | Shadows | sm, md, lg, xl | | Transitions | fast (150ms), normal (200ms), slow (300ms) |

Accessibility

Atman is built with WCAG AA compliance as a baseline. Every component includes:

• Keyboard navigation — Full keyboard support for all interactive elements
• Screen reader support — Proper ARIA attributes, roles, and live regions
• Focus management — Visible focus indicators, focus trapping in modals
• Color contrast — All text and UI elements meet minimum contrast ratios
• Reduced motion — Animations respect prefers-reduced-motion

See the Accessibility documentation in Storybook for per-component details and testing checklists.

Figma Integration

Atman tokens can be synced with Figma using the Tokens Studio plugin:

# Generate Tokens Studio compatible JSON
npm run export-tokens-studio

This creates src/tokens/tokens-studio.json with three token sets (global, light, dark) ready to import into Figma. See the Figma Integration Guide for setup instructions.

Browser Support

Atman supports all modern browsers (last 2 versions):

• Chrome
• Firefox
• Safari
• Edge

About

Atman was designed and built by Rafael Craice using Claude Code by Anthropic in an AI-assisted development approach where the human provides direction, vision, and quality control while the AI handles implementation details. The entire project was guided by a single project brief (atman.md), and every component, story, and accessibility fix was produced through this human-AI collaboration. Read the case study.

Documentation

• Landing Page — Project overview and showcase
• Storybook — Interactive component documentation
• Case Study — Project overview, design decisions, and learnings
• Figma Integration — Tokens Studio setup guide
• Accessibility — Accessibility audit and compliance details
• AI Guide — Reference for AI assistants working with the codebase
• GitHub — Source code and issues

Development

# Install dependencies
npm install

# Start Storybook for development
npm run storybook

# Build the library
npm run build

# Type check
npm run typecheck

# Build Storybook for deployment
npm run build-storybook

# Export tokens for Figma (Tokens Studio format)
npm run export-tokens-studio

AI-Assisted Development

Atman is built with AI-assisted development as a first-class workflow. The codebase includes structured onboarding for AI assistants:

• CLAUDE.md — Quick-start conventions and commands for AI sessions
• docs/ai-guide.md — Comprehensive component, token, and architecture reference

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see the LICENSE file for details.