npm package: @protonradio/proton-ui
Description: ![](./.readme.gif)
Latest version: 0.12.0

# ProtonUI

![](./.readme.gif)

```
npm run storybook
```

## Installation

### Prerequisites

1. Ensure you have access to `@protonradio/proton-ui` [npm package](https://www.npmjs.com/package/@protonradio/proton-ui)
2. Login using `npm login`

### Install

```bash
npm install @protonradio/proton-ui --save
```

### Project Structure

TODO: Explain project structure after treeshaking efforts have concluded

### Setup ThemeProvider

Wrap your application with the `ThemeProvider` to enable theming:

```jsx
import { ThemeProvider, THEMES } from "@protonradio/proton-ui";

function MyApp({ Component, pageProps }) {
  return (
    <ThemeProvider theme={THEMES.DARK}>
      <Component {...pageProps} />
    </ThemeProvider>
  );
}
```

### Custom Color Palettes

Each theme has a `ProtonPalette` with colors tailored for UI design. Palettes are made up of `ProtonColorScale`s that have shades from super_light to super_dark:

- **Primary Scale**
- **Secondary Scale**
- **Brand Colors** [Partial ProtonColorScale]
- **Gray Scale**
- **Semantic Colors**
  - Success
  - Warning
  - Error

When you pass a custom palette to the ThemeProvider, these five scales are updated with colors based on the background image you gave it. This is useful for designing UIs around individual releases, labels and artists. All generated scales are designed with accessibility in mind, ensuring proper contrast ratios and visual hierarchy.

To generate a new palette, use the `usePalette` hook:

```jsx
import { ThemeProvider, usePalette, THEMES } from "@protonradio/proton-ui";

function AppWithCustomPalette(props) {
  const customPalette = usePalette(
    `https://example.com/${props.imgUrl}.jpg`,
    THEMES.DARK
  );

  return (
    <ThemeProvider theme={THEMES.DARK} palette={customPalette}>
      <YourApp />
    </ThemeProvider>
  );
}
```

## Best Styling Practices

Components use standardized _control_ variables defined in the theme config stylesheets for consistent styling across the design system:

```typescript
export interface ProtonStyleSheet {
  "--proton-control__background-color": string;
  "--proton-control__background-color-light": string;
  "--proton-control__text-color": string;
  "--proton-control__title-color": string;
  "--proton-control__border-color": string;
  "--proton-control__shadow-color": string;
  // ... etc
```

These control variables unify the styling system while powering theme-specific CSS customization, and follow the pattern `--proton-control__{style}-{property}`:

```css
.myComponent {
  background-color: var(--proton-control__background-color);
}
```

For more advanced theme overrides we utilize the theme class names. The `ThemeProvider` applies the appropriate theme class to its container, making it available to all child components. Theme class names follow the pattern `proton-ui__theme--{themeName}`:

```css
.proton-ui__theme--dark .myComponent[active] {
  background-color: var(--proton-color__primary-light);
}
```

Palettes can also be accessed in JSX via the `useTheme` hook for more advanced use cases:

```jsx
import { useTheme } from "@protonradio/proton-ui";

function MyComponent() {
  const { palette } = useTheme();

  // Prefer CSS selectors over programmatic styling
  return <Icon color={palette.BRAND.PRIMARY} />;
}
```

## Publishing Updates to NPM

We follow semantic versioning and use automated CI/CD for releases:

**For Beta Releases (Testing):**

```bash
npm run build
npm run publish-beta  # Automated versioning with beta tag
```

**For Production Releases:**

```bash
npm run build
npm version <patch|minor|major>  # Semantic versioning
npm publish
```

**Best Practices:**

- Always publish beta releases first for testing across platforms
- Test on all supported environments before production release
- Use semantic versioning (patch for bug fixes, minor for features, major for breaking changes)
- Our GitHub Actions [NPM Version](https://github.com/protonradio/proton-ui/actions/workflows/npm_release.yml) tool automatically handles versioning and deployment workflows

## Recommended Reading

- https://www.gabe.pizza/notes-on-component-libraries/