unich-ui-kit-web

v0.2.8

Published

a year ago

Mantine theme configuration and provider for Unich UI Kit

0High
0Medium
0Low

twan-unich

react nextjs ui-kit mantine server-components typescript ui-library

Unich UI Kit for Mantine

A comprehensive theme customization system for Mantine UI, featuring a carefully crafted color system based on your brand colors.

Features

🎨 Complete color system with semantic colors
🌓 Light and dark mode support
🧩 Multiple theme variants (brand, blue, gray)
🔄 Easily extendable for custom themes
📦 Ready-to-use components with theme integration
🌈 OKLCH color space for better color representation
📱 Fully responsive and mobile-friendly
⚡ Compatible with Next.js App Router and React Server Components

Installation

npm install unich-ui-kit-web @mantine/core @mantine/hooks

Usage

Basic Usage

Wrap your application with the ThemeProvider component:

import { ThemeProvider } from 'unich-ui-kit-web';

function App() {
  return (
    <ThemeProvider>
      <YourApp />
    </ThemeProvider>
  );
}

Theme Variants

Choose from multiple theme variants:

// Orange primary (brand default)
<ThemeProvider variant="brand">
  <YourApp />
</ThemeProvider>

// Blue primary
<ThemeProvider variant="blue">
  <YourApp />
</ThemeProvider>

// Neutral gray primary
<ThemeProvider variant="gray">
  <YourApp />
</ThemeProvider>

// Dark mode (combine with Mantine's colorScheme)
<ThemeProvider variant="darkBrand">
  <YourApp />
</ThemeProvider>

Theme Customization

Extend the theme with custom overrides:

import { ThemeProvider, extendTheme } from 'unich-ui-kit-web';

const customTheme = extendTheme({
  primaryColor: 'orange',
  defaultRadius: 'lg',
  // Add your custom overrides here
});

function App() {
  return (
    <ThemeProvider themeOverrides={customTheme}>
      <YourApp />
    </ThemeProvider>
  );
}

Brand Colors

The theme is built around the following brand colors:

Primary Orange (#FF990A): Main color from the brand logo
Blue Accent (#0A85FF): Secondary accent color
Light Neutral (#ECECEC): Light background and text on dark surfaces
Dark (#171717): Dark background for contrast
Semantic Colors: Success (green), Error (red), Warning (yellow)

Color System

Each color comes with 11 shades (50-950), giving you a comprehensive system:

import { baseColors, semanticColors } from 'unich-ui-kit-web';

// Access base colors
const primaryOrange = baseColors.orange[500]; // #FF990A
const lightBg = baseColors.neutral[50]; // #ECECEC
const darkBg = baseColors.neutral[950]; // #171717

// Access semantic colors
const primaryAction = semanticColors.primary[500]; // Orange
const error = semanticColors.error[500]; // Red
const pageBg = semanticColors.background.page; // Light background

Helper Functions

import { getSemanticColor, getThemeColor } from 'unich-ui-kit-web';

// Get a semantic color
const errorColor = getSemanticColor('error', 500);

// Get a theme color in a component
function MyComponent({ theme }) {
  const primary = getThemeColor(theme, 'primary', 500);
  // ...
}

Tailwind CSS Integration

The package includes Tailwind CSS compatible color definitions for projects using Tailwind:

/* In your CSS */
@import 'unich-ui-kit-web/tailwind-colors.css';

Development

Scripts

npm run build: Build the package
npm run generate:colors: Generate the color system
npm run generate:palette: Generate color palettes

License

MIT

Next.js Server Components Compatibility

This UI kit is compatible with Next.js App Router and React Server Components. The components are marked with the 'use client' directive, making them safe to use in both client and server contexts.

For Next.js App Router projects, we recommend using the special NextThemeProvider component which is optimized for Next.js:

// app/layout.tsx
import { NextThemeProvider } from 'unich-ui-kit-web';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <NextThemeProvider withColorSchemeScript />
      </head>
      <body>
        <NextThemeProvider variant="brand" colorScheme="light">
          {children}
        </NextThemeProvider>
      </body>
    </html>
  );
}

The NextThemeProvider component:

Properly handles both the Mantine color scheme script and provider
Works correctly with Next.js App Router's server components
Can be used in both head and body sections of your layout
Prevents the "MantineProvider was not found" error by using a safe mounting strategy

Troubleshooting: MantineProvider not found error

If you encounter the error: "MantineProvider was not found in component tree", ensure that:

You're using the NextThemeProvider instead of the regular ThemeProvider in your Next.js App Router project
The provider is placed in the root layout of your application
The provider wraps all components that use Mantine

For more complex applications, you can also customize the provider behavior:

<NextThemeProvider
  variant="brand"
  colorScheme="dark"
  forceRender={true} // Controls initial SSR rendering
  themeOverrides={{
    // Your custom theme options
    primaryColor: 'blue',
  }}
>
  {children}
</NextThemeProvider>