What is Vulcan Neo?

Vulcan Neo is a Neomorphism (Soft UI) design system for React applications. It provides beautiful, accessible components with the signature soft shadow effects that make neomorphic design distinctive.

Key Features

• 70+ Components - From buttons to charts, everything you need
• Accessible - WCAG AA compliant with 4.5:1+ contrast ratios
• Dark Mode - Full light and dark theme support
• TypeScript - Complete type definitions included
• Tree-Shakable - Import only what you need
• Zero Dependencies - Only peer depends on React

Quick Start

For Developers

Prerequisites

• Node.js 24+
• npm, yarn, or pnpm
• React 19+

Installation

# npm
npm install @slashui/vulcan-neo

# yarn
yarn add @slashui/vulcan-neo

# pnpm
pnpm add @slashui/vulcan-neo

Basic Usage

import { Surface, Button, Card } from '@slashui/vulcan-neo';
import '@slashui/vulcan-neo/styles';

function App() {
  return (
    <Surface theme="light">
      <Card>
        <h2>Welcome to Vulcan Neo</h2>
        <Button variant="convex">Get Started</Button>
      </Card>
    </Surface>
  );
}

For Non-Technical Users

If you're new to development, follow these steps:

Step 1: Install Node.js

1. Go to nodejs.org
2. Download the LTS version (recommended)
3. Run the installer and follow the prompts
4. Restart your computer

Step 2: Create a New Project

Open Terminal (Mac) or Command Prompt (Windows) and run:

# Create a new React project
npx create-react-app my-app
cd my-app

# Install Vulcan Neo
npm install @slashui/vulcan-neo

Step 3: Start Building

Open the project in your code editor (we recommend VS Code) and edit src/App.js:

import { Surface, Button } from '@slashui/vulcan-neo';
import '@slashui/vulcan-neo/styles';

function App() {
  return (
    <Surface theme="light" style={{ padding: '20px', minHeight: '100vh' }}>
      <h1>My First Neomorphic App</h1>
      <Button variant="convex">Click Me!</Button>
    </Surface>
  );
}

export default App;

Run npm start to see your app!

Components

Atoms (Basic Building Blocks)

| Component | Description | | ------------- | ----------------------------------------- | | Surface | Theme provider and background container | | Button | Convex, concave, and flat button variants | | InsetField | Text input with inset neomorphic styling | | Switch | Toggle switch control | | Checkbox | Checkbox input | | Radio | Radio button input | | Badge | Status indicator | | Avatar | User avatar with status | | IconButton | Icon-only button | | Slider | Range slider | | ProgressBar | Progress indicator |

Molecules (Composed Components)

| Component | Description | | ---------- | ----------------------------------------- | | Card | Content container with header/body/footer | | Select | Dropdown select input | | Dropdown | Generic dropdown menu | | Tabs | Tabbed navigation | | Modal | Dialog/modal overlay | | Tooltip | Hover tooltips | | Alert | Alert messages | | Table | Data tables |

Organisms (Complex Components)

| Component | Description | | ------------------- | -------------------------- | | HeaderNavigation | App header with navigation | | SidebarNavigation | Sidebar menu | | Pagination | Page navigation | | Calendar | Date calendar | | DatePicker | Date input with calendar | | FileUploader | File upload interface | | CommandMenu | Command palette (⌘K) |

Marketing Sections

| Component | Description | | -------------------- | --------------------- | | HeroSection | Hero/landing section | | FeaturesSection | Feature highlights | | PricingSection | Pricing tables | | TestimonialSection | Customer testimonials | | CTASection | Call-to-action | | FAQSection | FAQ accordion | | Footer | Site footer |

Charts

| Component | Description | | ----------- | ---------------- | | LineChart | Line/area charts | | BarChart | Bar charts | | PieChart | Pie/donut charts |

Templates

| Component | Description | | ----------- | --------------- | | ErrorPage | 404/error pages |

View all components in Storybook →

Design Standards

Neomorphism Principles

Vulcan Neo follows these core neomorphism design principles:

1. Light Source (135°)

All shadows are cast as if light comes from the top-left at 135°:

• Light shadow: top-left
• Dark shadow: bottom-right

2. Soft Backgrounds

Never use pure white or black. Our default backgrounds:

• Light theme: #E0E5EC
• Dark theme: #292D32

3. Elevation States

Three elevation levels for depth:

• Low: Subtle, for backgrounds
• Mid: Default for interactive elements
• High: Prominent, for focused states

Typography Standards

We use accessible typography optimized for soft UI backgrounds:

| Scale | Size | Weight | Use | | -------- | ------- | -------------- | --------------- | | Display | 39-76px | Bold (700) | Hero headlines | | Headline | 20-31px | Semibold (600) | Section headers | | Title | 14-20px | Medium (500) | Titles | | Body | 14-18px | Regular (400) | Content | | Label | 11-14px | Medium (500) | UI labels |

Font Stack:

• Display: Poppins
• Body: Inter
• Code: JetBrains Mono

Accessibility

All components meet WCAG AA standards:

• Text contrast: 4.5:1 minimum (8.2:1 for primary text)
• Focus indicators on all interactive elements
• Keyboard navigation support
• Screen reader compatible
• Reduced motion support

Color System

| Role | Light | Dark | Use | | --------- | --------- | --------- | --------------- | | Primary | #6C5CE7 | #6C5CE7 | Actions, links | | Secondary | #00CEC9 | #00CEC9 | Accents | | Success | #00B894 | #00B894 | Positive states | | Warning | #FDCB6E | #FDCB6E | Warnings | | Error | #E17055 | #E17055 | Errors |

Theming

Using Themes

Wrap your app with Surface to apply a theme:

import { Surface } from '@slashui/vulcan-neo';

// Light theme (default)
<Surface theme="light">
  <App />
</Surface>

// Dark theme
<Surface theme="dark">
  <App />
</Surface>

CSS Variables

All design tokens are available as CSS variables:

/* Colors */
--neo-color-primary: #6c5ce7;
--neo-color-secondary: #00cec9;
--neo-bg: #e0e5ec;
--neo-text: #2d3436;

/* Shadows */
--neo-shadow-light: rgba(255, 255, 255, 0.8);
--neo-shadow-dark: rgba(163, 177, 198, 0.6);

/* Typography */
--neo-font-family: 'Inter', sans-serif;
--neo-font-body-md: 16px;

/* Spacing */
--neo-space-md: 16px;
--neo-radius-md: 20px;

/* Motion */
--neo-transition-normal: 200ms cubic-bezier(0.2, 0, 0, 1);

Custom Theming

Override CSS variables to customize:

:root {
  --neo-color-primary: #your-brand-color;
  --neo-bg-light: #your-light-bg;
}

Development Setup

Clone and Install

git clone https://github.com/Slash-ui/vulcan-neo.git
cd vulcan-neo
yarn install

Available Scripts

| Command | Description | | ---------------------- | ------------------------------ | | yarn dev | Start development server | | yarn build | Build the library | | yarn test | Run tests | | yarn test:coverage | Run tests with coverage | | yarn storybook | Start Storybook dev server | | yarn build-storybook | Build Storybook for deployment | | yarn lint | Run ESLint | | yarn format | Format code with Prettier |

Project Structure

vulcan-neo/
├── src/
│   ├── components/       # All components
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.module.css
│   │   │   ├── Button.stories.tsx
│   │   │   └── index.ts
│   │   └── ...
│   ├── stories/          # Storybook documentation
│   │   └── foundation/  # Design system docs
│   ├── styles/
│   │   └── tokens.css    # Design tokens
│   └── index.ts          # Main exports
├── .github/
│   └── workflows/        # CI/CD pipelines
├── .storybook/           # Storybook config
└── dist/                 # Build output

Contributing

We welcome contributions! Here's how to get started:

Quick Contribution Guide

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR-USERNAME/vulcan-neo.git
3. Create a branch: git checkout -b feature/amazing-feature
4. Make changes and commit: git commit -m 'Add amazing feature'
5. Push: git push origin feature/amazing-feature
6. Open a Pull Request

Reporting Issues

Found a bug? Have a feature request?

Open an issue →

Please include:

• Clear description of the issue
• Steps to reproduce (for bugs)
• Expected vs actual behavior
• Screenshots if applicable
• Environment details (OS, browser, React version)

Development Guidelines

• Follow the existing code style
• Write tests for new components
• Update Storybook stories
• Ensure accessibility compliance
• Keep bundle size minimal

See CONTRIBUTING.md for detailed guidelines.

Browser Support

| Browser | Version | | ------- | --------------- | | Chrome | Last 2 versions | | Firefox | Last 2 versions | | Safari | Last 2 versions | | Edge | Last 2 versions |

FAQ

Yes! Vulcan Neo works with Next.js. For App Router, use 'use client' directive:

'use client';
import { Surface, Button } from '@slashui/vulcan-neo';

Override CSS variables in your global styles:

:root {
  --neo-color-primary: #your-color;
}

Yes! All components meet WCAG AA standards with 4.5:1+ contrast ratios, keyboard navigation, and screen reader support.

The full library is ~80KB gzipped. With tree-shaking, you only pay for what you import.

Links

• Website
• Documentation (Storybook)
• npm Package
• GitHub Repository
• Issue Tracker
• Changelog

License

MIT © Slash UI