npm package: @malovey/rogue-ui
Description: A neumorphic design system merging tactical, data-heavy interfaces with soft, tactile aesthetics. Simplicity by default, Complexity on demand.
Author: system-errors
Latest version: 1.1.0

# Rogue UI

A neumorphic design system merging tactical, data-heavy interfaces with soft, tactile aesthetics.

> **Simplicity by default. Complexity on demand.**

---

## Philosophy

Rogue UI embraces the neumorphic paradigm—surfaces that appear to extrude from or indent into the background, creating depth through light and shadow rather than flat colors or harsh borders.

**Core Principles:**

- **Tactile Depth** — Components feel physically present, responding to interaction with realistic shadow transitions
- **Restrained Palette** — Neutral grays with a single teal accent (`#14b8a6`) to guide focus
- **Motion with Purpose** — Spring physics animations that feel natural, not decorative
- **Accessibility First** — WCAG-compliant focus states, keyboard navigation, and ARIA support

---

## Design Tokens

### Colors

| Token | Dark | Light |
|-------|------|-------|
| Surface | `#4a4a4a` | `#e8e8e8` |
| Accent | `#14b8a6` | `#0d9488` |
| Text Primary | `rgba(255,255,255,0.95)` | `#1f2937` |

### Shadows

Neumorphic shadows use dual light sources—a highlight from top-left and shadow from bottom-right:

```css
/* Raised (resting state) */
--rogue-shadow-raised: 
  8px 8px 16px -2px rgba(0,0,0,0.3),
  -8px -8px 16px -2px rgba(255,255,255,0.15);

/* Sunken (pressed state) */
--rogue-shadow-sunken: 
  inset 8px 8px 16px -2px rgba(0,0,0,0.3),
  inset -8px -8px 16px -2px rgba(255,255,255,0.15);
```

### Typography

**Inter** — Clean, geometric sans-serif optimized for UI.

| Weight | Usage |
|--------|-------|
| 400 | Body text |
| 500 | Labels, buttons |
| 600 | Headings |
| 700 | Emphasis |

### Motion

Spring-based animations via Framer Motion:

| Preset | Stiffness | Damping | Use Case |
|--------|-----------|---------|----------|
| `stiff` | 400 | 30 | Quick micro-interactions |
| `bouncy` | 300 | 20 | Playful feedback |
| `soft` | 200 | 25 | Smooth transitions |

---

## Components

| Component | Description |
|-----------|-------------|
| `RogueButton` | Neumorphic button with variants, loading states, tooltips |
| `RogueCard` | Neumorphic card container with header, body, footer sections |
| `RogueToggleGroup` | Segmented control with smooth selection indicator |
| `RogueSwitch` | Toggle switch with raised thumb and sunken track |
| `RogueBarChart` | Animated bar chart with hover effects and stat badges |
| `RogueInput` | Text input with sunken appearance, label, and error states |
| `RogueTextarea` | Multi-line text input with auto-resize and character count |
| `RogueBadge` | Badge/tag component for status indicators and labels |
| `RogueCheckbox` | Checkbox with indeterminate state and labeled variant |
| `RogueSelect` | Dropdown select with groups, search, and custom styling |
| `RogueSlider` | Range slider with single/dual thumbs and value display |
| `RogueProgress` | Progress bar with determinate and indeterminate states |
| `RogueAvatar` | Avatar with image/fallback and group stacking support |
| `RogueTooltip` | Tooltip with multiple positions and rich content support |
| `RoguePopover` | Popover for contextual menus and rich interactive content |
| `RogueTabs` | Tabbed interface with animated selection indicator |
| `RogueModal` | Modal dialog with header, body, footer composition |
| `RogueCalendar` | Date calendar with month navigation and date highlighting |
| `RogueSkeleton` | Loading placeholders for text, avatars, cards, and more |
| `RogueDropdownMenu` | Context menus and action menus with keyboard support |
| `RogueAlert` | Inline alerts for info, success, warning, and error states |
| `RogueToast` | Toast notifications with provider and useToast hook |
| `RogueAccordion` | Collapsible content sections with single/multiple modes |
| `RogueBreadcrumb` | Navigation hierarchy with customizable separators |
| `RogueNumberInput` | Numeric input with stepper buttons and min/max |
| `RogueRadioGroup` | Single-select radio option groups |

---

## Installation

```bash
npm install @malovey/rogue-ui
# or
yarn add @malovey/rogue-ui
# or
pnpm add @malovey/rogue-ui
```

### Peer Dependencies

Rogue UI requires React 18 or 19:

```bash
npm install react react-dom
```

---

## Quick Start

```tsx
import { RogueButton } from '@malovey/rogue-ui';
import '@malovey/rogue-ui/styles.css';

function App() {
  return (
    <div className="rogue-surface" data-theme="dark">
      <RogueButton variant="accent">Get Started</RogueButton>
    </div>
  );
}
```

### Import Styles

**Important:** You must import the CSS file in your app's entry point:

```tsx
// In your main.tsx, App.tsx, or _app.tsx
import '@malovey/rogue-ui/styles.css';
```

### Theming

Apply themes via `data-theme` attribute or `.rogue-light` class:

```html
<!-- Dark (default) -->
<div class="rogue-surface">...</div>

<!-- Light -->
<div class="rogue-surface" data-theme="light">...</div>
```

### Using Toast Notifications

Wrap your app with `RogueToastProvider` for toast support:

```tsx
import { RogueToastProvider, useToast, RogueButton } from '@malovey/rogue-ui';
import '@malovey/rogue-ui/styles.css';

function App() {
  return (
    <RogueToastProvider>
      <MyComponent />
    </RogueToastProvider>
  );
}

function MyComponent() {
  const { toast } = useToast();
  
  return (
    <RogueButton onClick={() => toast({ title: 'Hello!', variant: 'success' })}>
      Show Toast
    </RogueButton>
  );
}
```

### Using Tooltips

Wrap components with `RogueTooltipProvider` for tooltips:

```tsx
import { RogueTooltipProvider, RogueTooltip, RogueButton } from '@malovey/rogue-ui';

function App() {
  return (
    <RogueTooltipProvider>
      <RogueTooltip content="Click me!">
        <RogueButton>Hover me</RogueButton>
      </RogueTooltip>
    </RogueTooltipProvider>
  );
}
```

---

## Development

```bash
npm run dev          # Start dev server
npm run storybook    # Component playground
npm run test         # Run tests
npm run lint         # ESLint
npm run format       # Prettier
npm run build        # Production build
```

---

## Publishing

```bash
# Build the package
npm run build

# Publish to npm
npm publish
```

---

## License

MIT