ProtonUI

npm run storybook

Installation

Prerequisites

1. Ensure you have access to @protonradio/proton-ui npm package
2. Login using npm login

Install

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:

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 ProtonColorScales 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:

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:

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}:

.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}:

.proton-ui__theme--dark .myComponent[active] {
  background-color: var(--proton-control__interactive-color);
}

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

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):

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

For Production Releases:

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 tool automatically handles versioning and deployment workflows

Recommended Reading

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