@peak-security-suite/ui-elements

UI design system and React components for the Peak Security Suite and extended applications, built with TypeScript and Tailwind CSS.

⚠️ Pre-1.0 Development Notice This library is under active development. Component interfaces and APIs may introduce breaking changes in minor version updates (0.x) as we refine the design system. We recommend pinning to specific versions and reviewing changelogs before updating until we reach version 1.0.

Installation

npm install @peak-security-suite/ui-elements --save

# Install peer dependencies if not already present
npm install react react-dom

Usage

import {
  ThemeProvider,
  Button,
  ThemeColor,
  Badge,
  Icon,
  Typography,
} from "@peak-security-suite/ui-elements";
import { mdiAccount } from "@mdi/js";

function App() {
  return (
    <ThemeProvider fontFamily="Outfit, sans-serif">
      <div>
        <Typography.H1>Welcome</Typography.H1>
        <Button color={ThemeColor.primary}>Click me</Button>
        <Badge content={5}>
          <Icon path={mdiAccount} />
        </Badge>
      </div>
    </ThemeProvider>
  );
}

Project Setup

Build Integration Options

Choose your build integration approach:

Option 1: Source + Tailwind v4 (Recommended)

Requires a modern build system (Vite, Webpack, etc.)

Import components directly from source and set up Tailwind v4 in your host application:

// Import from source (default export)
import { Button } from "@peak-security-suite/ui-elements";

/* In your main CSS file */
@import "@peak-security-suite/ui-elements/src/tailwind.css";

// vite.config.js
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [tailwindcss()],
});

Option 2: Pre-built Bundle

Use this option if you don't use Tailwind CSS in your project or prefer not to bundle source code:

// Import pre-built styles
import "@peak-security-suite/ui-elements/styles";

// Import from dist
import { Button } from "@peak-security-suite/ui-elements/dist";

Font Setup

The host application is responsible for providing fonts. Install and import your preferred font family:

npm install @fontsource/outfit  # or your preferred font

/* In your main CSS file */
@import "@fontsource/outfit/400.css";
@import "@fontsource/outfit/500.css";
@import "@fontsource/outfit/600.css";

/* ThemeProvider handles font family dynamically */
<ThemeProvider fontFamily="Outfit, sans-serif">
  {/* Your app components */}
</ThemeProvider>

Icon Setup

SVG Paths (Recommended for Performance)

import { Icon } from "@peak-security-suite/ui-elements";
import { mdiAccount, mdiEmail } from "@mdi/js";

<Icon path={mdiAccount} />;

Named Icons (Required for Icon Localization)

Install the icon font if you need named icons or localization features:

npm install @mdi/font

/* In your main CSS file */
@import "@mdi/font/css/materialdesignicons.min.css";

<Icon name="account" />  {/* Uses mdi-account class */}

Note: You can use both approaches together. Icon font is required if you use the localization system's icon features.

Documentation

For detailed component documentation and examples, refer to the Storybook documentation and AI Docs.

TypeScript Support

Comprehensive type definitions work in both TypeScript and JavaScript projects:

TypeScript:

import {
  Button,
  ButtonVariant,
  ThemeColor,
} from "@peak-security-suite/ui-elements";

<Button
  variant={ButtonVariant.primary} // Enum autocomplete
  themeColor={ThemeColor.success} // Type-safe colors
  onClick={(e) => console.log(e)} // Event handlers
>
  Click me
</Button>;

JavaScript with JSDoc:

/**
 * @param {import('@peak-security-suite/ui-elements').ButtonProps} props
 */
export const MyButton = ({ variant, color, children }) => {
  return (
    <Button variant={variant} color={color}>
      {children}
    </Button>
  );
};

Benefits:

• Autocomplete - IntelliSense in both TS and JS projects
• Type Safety - Catch errors at compile time (TS) or in IDE (JS)
• Refactoring - Safe renames and changes across your codebase
• Documentation - Prop types serve as inline documentation

Requirements

• React 18.2.0+
• React DOM 18.2.0+
• TypeScript 4.0+ (optional but recommended)

Publishing

For maintainers publishing to npm:

# Test the publish (dry run)
yarn release:dry

# Publish to npm
yarn release

The package will automatically build before publishing via the prepare script.

License

MIT