npm package: @noizt/ui
Description: Noizt design system — dark premium UI component library
Author: Noizt
Latest version: 1.3.0

<p align="center">
  <img src="https://res.cloudinary.com/noiztbander/image/upload/v1774888806/branding/2024_logo_name_white_wmfanl.png" alt="Noiztbander Logo" width="400" />
</p>

# @noizt/ui

A premium UI component library for the **Noiztbander** ecosystem, featuring two distinct themes: **Dark (Sci-Fi Noir)** and **Lux (Apple-inspired Light)**.

## Vision

Designed by **Erick Ureña**, this design system provides a high-contrast, motion-rich experience for all projects related to the Noiztbander brand—from professional portfolios and art showrooms to high-end apparel ecommerce.

The system is built on principles of **scarcity, atmospheric motion, and pure contrast**, ensuring that every digital product feels like a premium artifact.

## Features

- 🌙 **Dark Theme (Sci-Fi Noir)**: Pure black aesthetic optimized for OLED displays with vibrant purple/blue accents.
- ☀️ **Lux Theme (Apple-inspired)**: Clean, bright light theme with subtle depth and premium feel.
- ⚡ **Motion-First**: Energetic spring transitions calibrated for luxury storytelling.
- 🛠 **Custom Typography**: Integrated with Outward fonts for high-impact creative titles.
- 🎨 **Scalable**: Used across portfolios, showrooms, and ecommerce storefronts.
- ♿ **Accessible**: Focus states, reduced motion support, and WCAG contrast compliance.

## Installation

```bash
npm install @noizt/ui
```

## Usage

### 1. Import Global Styles

Import the global tokens in your application:

```tsx
import '@noizt/ui/styles'
```

### 2. Theme Switching

The design system supports two themes:

- **Dark** (`data-theme="dark"`) - Sci-Fi Noir aesthetic
- **Lux** (`data-theme="lux"`) - Apple-inspired light theme

#### Programmatic Theme Control

```tsx
import { setTheme, getTheme, initTheme, useTheme } from '@noizt/ui/theme'

// Initialize theme from localStorage or system preference
initTheme()

// Set a specific theme
setTheme('lux') // or 'dark'

// Get current theme
const current = getTheme() // 'dark' | 'lux'
```

#### React Hook

```tsx
import { ThemeProvider, useTheme } from '@noizt/ui/theme'

function App() {
  return (
    <ThemeProvider>
      <ThemeToggle />
    </ThemeProvider>
  )
}

function ThemeToggle() {
  const { theme, setTheme, toggleTheme, isDark, isLux } = useTheme()

  return (
    <button onClick={toggleTheme}>
      Current: {theme} ({isDark ? 'Dark' : 'Lux'})
    </button>
  )
}
```

#### Manual HTML Attribute

Set the `data-theme` attribute on your root element:

```tsx
// Enable Lux theme
document.documentElement.setAttribute('data-theme', 'lux')

// Switch back to Dark
document.documentElement.setAttribute('data-theme', 'dark')
```

### 3. Use Brand Components

```tsx
import { Button, Card, Icon, SideBar } from '@noizt/ui'

export function Showcase() {
  return (
    <Card variant="glass">
      <h1 style={{ fontFamily: 'var(--font-display)' }}>Latest Drop</h1>
      <Button variant="gradient">Explore Collection</Button>
      <Button variant="frost">Apple-style Button</Button>
      <SideBar />
    </Card>
  )
}
```

## Development

### Storybook & Branding

We use [Storybook v10](https://storybook.js.org/) with a custom **Noizt Branding** theme:

```bash
npm run storybook # Launch the branded dev environment
```

- **Staging URL**: [ui-staging.noiztbander.com](https://ui-staging.noiztbander.com) (Updated from `develop`)
- **Production URL**: [ui.noiztbander.com](https://ui.noiztbander.com) (Updated from `main` via tags)

## Releasing & Deployment

We use an automated pipeline for versioning and multi-environment deployment.

### 1. Release Cycle (Automation)

We use [release-please](https://github.com/googleapis/release-please) based on **Conventional Commits**:

1. **Commit changes**: Use `feat:`, `fix:`, `chore:`, or `refactor:`.
2. **Push to `main`**: This triggers the robot to create/update a **Release PR**.
3. **Merge the Release PR**: This finalizes the release by:
   - Creating a **GitHub Tag** (e.g., `v1.2.0`).
   - Generating the `CHANGELOG.md`.
   - **Triggering Production Deploy** to Cloudflare and **NPM Publish**.

### 2. Deployment Strategy

#### 🟢 Staging & Previews (`deploy-staging.yml`)

- **Pull Requests to `develop`**: Every PR generates a **private Preview URL**. You'll find the link in the "View deployment" button within the PR checks.
- **Push to `develop`**: Updates the persistent staging site at [ui-staging.noiztbander.com](https://ui-staging.noiztbander.com).

#### 🚀 Production (`deploy-production.yml`)

- **Tags (`vX.X.X`)**: Only stable tags pushed from `main` trigger the production deployment.
- **Official Site**: Always reflects the latest stable version at [ui.noiztbander.com](https://ui.noiztbander.com).

## Credits

- **Design & Creative Direction**: Erick Ureña
- **Engineering**: Noizt Team

## License

MIT