Kratos UI Kit

A lightweight React component library with Material-UI-style theming, Emotion-based styling, and precise CSS specificity hierarchy.

🎯 Key Features

• Material-UI-style createTheme - Complete theming system with deep customization
• CSS Specificity Hierarchy - Theme → makeStyles → Inline → !important
• Emotion Integration - Pure CSS-in-JS with @emotion/css
• makeStyles Utility - Dynamic styling with theme and props
• Storybook Documentation - Interactive examples and documentation

📦 Installation

npm install kratos-ui-kit

🚀 Quick Start

Basic Usage

import React from 'react';
import { Button, ThemeProvider, createTheme } from 'kratos-ui-kit';

// Create a custom theme
const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' },
    secondary: { main: '#dc004e' },
  },
});

function App() {
  return (
    <ThemeProvider theme={theme}>
      <Button variant="contained" color="primary">
        Click me
      </Button>
    </ThemeProvider>
  );
}

🎨 Theming System

createTheme Function

The createTheme function creates a complete theme object with default values and allows deep customization:

import { createTheme } from 'kratos-ui-kit';

const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
      light: '#42a5f5',
      dark: '#1565c0',
      contrastText: '#ffffff',
    },
    secondary: {
      main: '#dc004e',
      light: '#ff5983',
      dark: '#9a0036',
      contrastText: '#ffffff',
    },
    danger: {
      main: '#d32f2f',
      light: '#ef5350',
      dark: '#c62828',
      contrastText: '#ffffff',
    },
  },
  typography: {
    fontFamily: '"Roboto", "Helvetica", "Arial", sans-serif',
    h1: {
      fontSize: '2.5rem',
      fontWeight: 300,
    },
  },
  spacing: 8,
  shape: {
    borderRadius: 4,
  },
  components: {
    Button: {
      styleOverrides: {
        root: {
          textTransform: 'none',
        },
        contained: {
          boxShadow: '0 2px 4px rgba(0,0,0,0.2)',
        },
      },
    },
  },
});

Advanced Theme Customization

// Component-specific overrides
const themeWithComponents = createTheme({
  palette: {
    primary: { main: '#1976d2' },
    secondary: { main: '#dc004e' },
  },
  components: {
    Button: {
      styleOverrides: {
        root: {
          textTransform: 'none',
          borderRadius: 8,
          fontWeight: '600',
        },
        contained: {
          boxShadow: '0 4px 8px rgba(0,0,0,0.3)',
        },
        outlined: {
          borderWidth: 2,
        },
      },
    },
  },
});

🎨 Styling with makeStyles

Basic Usage

import { Button, makeStyles } from 'kratos-ui-kit';

const useStyles = makeStyles({
  customButton: {
    backgroundColor: 'orange',
    color: 'white',
    borderRadius: '8px',
    padding: '10px 20px',
    fontSize: '14px',
    fontWeight: '600',
  },
});

function App() {
  const classes = useStyles();
  
  return (
    <Button className={classes.customButton}>
      Custom Styled Button
    </Button>
  );
}

⚠️ Important: ThemeProvider Requirement

makeStyles requires ThemeProvider when using theme values:

import { Button, makeStyles, ThemeProvider, createTheme } from 'kratos-ui-kit';

// ✅ Correct usage in consuming app
const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' },
    secondary: { main: '#dc004e' },
  },
});

const MyComponent = () => {
  const useStyles = makeStyles((theme) => ({
    root: {
      border: `1px solid ${theme.palette.primary.main}`,
      backgroundColor: theme.palette.secondary.main,
    }
  }));

  const classes = useStyles(); // ✅ Works because it's inside ThemeProvider

  return (
    <Button className={classes.root}>
      My Button
    </Button>
  );
};

function App() {
  return (
    <ThemeProvider theme={theme}>
      <MyComponent /> {/* ✅ ThemeProvider wrapper required */}
    </ThemeProvider>
  );
}

// ❌ Wrong usage (will cause error)
const MyComponent = () => {
  const useStyles = makeStyles((theme) => ({
    root: { /* styles */ }
  }));

  const classes = useStyles(); // ❌ Error: useTheme must be used within a ThemeProvider

  return (
    <Button className={classes.root}>
      My Button
    </Button>
  );
};

function App() {
  return (
    <div>
      <MyComponent /> {/* ❌ No ThemeProvider wrapper */}
    </div>
  );
}

Function Pattern (Recommended)

const useStyles = makeStyles((theme) => ({
  root: {
    border: '2px solid red',
    backgroundColor: '#ff6b6b',
    color: 'white',
    borderRadius: '20px',
    '&:hover': {
      backgroundColor: '#ff5252',
      transform: 'scale(1.05)',
    }
  }
}));

Theme Integration

const useStyles = makeStyles({
  themedButton: (theme, props) => ({
    backgroundColor: theme.palette.primary.main,
    color: theme.palette.primary.contrastText,
    borderRadius: theme.shape.borderRadius,
    padding: `${theme.spacing * 2}px ${theme.spacing * 3}px`,
    '&:hover': {
      backgroundColor: theme.palette.primary.dark,
    }
  }),
});

Using Theme Values in CSS Properties

// ✅ Correct syntax for theme values
const useStyles = makeStyles((theme) => ({
  root: {
    border: `1px solid ${theme.palette.primary.main}`, // Template literal syntax
    color: 'black',
    backgroundColor: theme.palette.secondary.main, // Direct theme access
    padding: `${theme.spacing * 2}px ${theme.spacing * 3}px`,
    borderRadius: `${theme.shape.borderRadius}px`,
    '&:hover': {
      backgroundColor: theme.palette.primary.dark,
      color: theme.palette.primary.contrastText,
    }
  },
}));

// ❌ Wrong syntax
const useStyles = makeStyles((theme) => ({
  root: {
    border: '1px solid theme.palette.primary.main', // Missing template literal
    color: 'black',
  },
}));

Key Points for Theme Integration:

• Template Literals: Use backticks (`) and ${} for theme values in strings
• Direct Access: Use theme properties directly for CSS values
• Spelling: Make sure to spell "palette" correctly
• Theme Structure: theme.palette.primary.main, theme.palette.secondary.main, etc.

🎯 CSS Specificity Hierarchy

The component follows this CSS specificity order (from lowest to highest priority):

1. Theme styles (lowest priority) - Applied via Emotion CSS
2. makeStyles classes (medium priority) - Override theme styles with !important
3. Inline styles (high priority) - Override makeStyles classes
4. !important classes (highest priority) - Override everything

Example Hierarchy Test

import { Button, makeStyles } from 'kratos-ui-kit';

const useStyles = makeStyles((theme) => ({
  root: {
    border: '1px solid red',  // Will override theme border
    backgroundColor: 'orange',  // Will override theme background
  }
}));

function App() {
  const classes = useStyles();
  
  return (
    <div>
      {/* Theme styles only */}
      <Button variant="contained" color="primary">Theme Button</Button>
      
      {/* makeStyles override */}
      <Button className={classes.root}>Custom Button</Button>
      
      {/* Inline styles override */}
      <Button 
        className={classes.root}
        style={{ backgroundColor: 'red' }}
      >
        Inline Override
      </Button>
    </div>
  );
}

Using Styles Outside Components

makeStyles with theme requires React context, but here are alternatives:

// ✅ Approach 1: Styles Factory Function
const createStyles = (theme) => ({
  root: {
    border: `1px solid ${theme.palette.primary.main}`,
    backgroundColor: theme.palette.secondary.main,
    padding: '10px 20px',
    borderRadius: '4px',
  }
});

const useCustomStyles = () => {
  const theme = useTheme(); // Must be inside component
  return createStyles(theme);
};

const MyComponent = () => {
  const styles = useCustomStyles();
  const classes = makeStyles(styles)();
  
  return <Button className={classes.root}>My Button</Button>;
};

// ✅ Approach 2: Static Styles (No Theme)
const staticStyles = {
  root: {
    border: '1px solid #1976d2', // Hardcoded values
    backgroundColor: '#dc004e',
    padding: '10px 20px',
    borderRadius: '4px',
  }
};

const MyComponent = () => {
  const classes = makeStyles(staticStyles)();
  
  return <Button className={classes.root}>My Button</Button>;
};

// ❌ This won't work
const useStyles = makeStyles((theme) => ({
  root: { /* styles */ }
}));
const classes = useStyles(); // Error: useTheme must be used within a ThemeProvider

📋 API Reference

Button Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | - | Button content | | variant | 'contained' | 'outlined' | 'contained' | Button variant | | color | 'primary' | 'secondary' | 'danger' | 'primary' | Color theme | | size | 'small' | 'medium' | 'large' | 'medium' | Button size | | bg | string | - | Custom background color | | style | object | - | Inline styles | | className | string | - | Additional CSS classes | | ...otherProps | - | - | All other button props |

makeStyles API

const useStyles = makeStyles(styles, options);

// styles can be:
// 1. Object: { root: { ... } }
// 2. Function: (theme) => ({ root: { ... } })

// options:
// - addImportantToConsumer: boolean (default: true)

createTheme API

const theme = createTheme(options);

// options can include:
// - palette: Color palette configuration
// - typography: Font and text styles
// - spacing: Base spacing unit
// - shape: Border radius and shadows
// - components: Component-specific overrides

Helper Functions

• mergeClasses(...classNames) - Merges multiple class names with proper specificity

🎨 Theme Structure

The theme object follows this structure:

{
  palette: {
    primary: { main, light, dark, contrastText },
    secondary: { main, light, dark, contrastText },
    danger: { main, light, dark, contrastText },
    text: { primary, secondary },
    background: { default, paper },
  },
  typography: {
    fontFamily, fontSize, fontWeightLight, fontWeightRegular,
    fontWeightMedium, fontWeightBold,
    h1, h2, h3, h4, h5, h6, body1, body2, button,
  },
  spacing: 8,
  shape: { borderRadius },
  breakpoints: { values: { xs, sm, md, lg, xl } },
  components: { Button: { styleOverrides } },
}

📚 Storybook

View all components and examples in Storybook:

Local Development

npm run storybook

Online Demo

🌐 Live Storybook: https://khadirpatan.github.io/kratos-ui-kit

Available stories:

• Default - Interactive button with controls
• Variants - All button variants (contained, link, outlined)
• Size - Button size examples
• BlueTheme - Blue professional theme
• GreenTheme - Green modern theme
• MakeStyles - CSS specificity examples with different properties

🛠️ Development

# Install dependencies
npm install

# Start Storybook locally
npm run storybook

# Build the package
npm run build

# Build Storybook for deployment
npm run build-storybook

# Deploy Storybook to GitHub Pages
npm run deploy-storybook

📦 Package Contents

• Button - Flexible button component with CSS specificity hierarchy
• ThemeProvider - React context provider for theme management
• createTheme - Material-UI-style theme creation function
• makeStyles - Dynamic CSS-in-JS utility with theme integration
• useTheme - Hook to access current theme

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

Version: 1.0.39
React: 16.8+
License: MIT
CSS-in-JS: Emotion