@stolution/ui

v1.1.0

Published

3 months ago

Stolution's Material-UI based component library for PWA-first applications

0High
0Medium
0Low

stolution

@stolution/ui

Stolution's Material-UI based component library for PWA-first applications

A comprehensive, production-ready UI component library built on Material-UI with Stolution branding and PWA-first responsive design.

Features

✨ Stolution Branding - Cyan Teal primary (#0891B2) and Emerald Green secondary (#10B981) color scheme
🎨 Material Design 3 - Modern, accessible components following Google's design system
📱 PWA-First - Mobile-optimized with 44×44px minimum touch targets (WCAG 2.1)
♿ Accessible - WCAG 2.1 AA compliant with comprehensive ARIA support
🌓 Dark Mode - Built-in light/dark theme support
⚡ Next.js Ready - Full SSR/SSG support for SEO optimization
🎯 TypeScript - Full type safety with comprehensive type definitions
📦 Tree-Shakable - Optimized bundle size with ESM support
🧪 Well-Tested - Comprehensive unit tests and Storybook documentation
🎨 Custom Variants - "Soft" button variant with alpha backgrounds

Installation

npm install @stolution/ui
# or
yarn add @stolution/ui
# or
pnpm add @stolution/ui

Peer Dependencies

The library requires these peer dependencies (auto-installed in most cases):

npm install @mui/material @mui/icons-material @emotion/react @emotion/styled react react-dom

Quick Start

1. Wrap your app with `StolutionThemeProvider`

Next.js App Router (app/layout.tsx)

import { StolutionThemeProvider } from '@stolution/ui';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <StolutionThemeProvider mode="light">
          {children}
        </StolutionThemeProvider>
      </body>
    </html>
  );
}

Next.js Pages Router (_app.tsx)

import { StolutionThemeProvider } from '@stolution/ui';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <StolutionThemeProvider mode="light">
      <Component {...pageProps} />
    </StolutionThemeProvider>
  );
}

2. Use Components

import { Button, Card, CardContent, Typography } from '@stolution/ui';

export default function HomePage() {
  return (
    <Card>
      <CardContent>
        <Typography variant="h4" gutterBottom>
          Welcome to Stolution
        </Typography>
        <Typography variant="body1" color="text.secondary" paragraph>
          Build modern, accessible web applications with our PWA-first component library.
        </Typography>
        <Button variant="contained" color="primary">
          Get Started
        </Button>
        <Button variant="soft" color="secondary" sx={{ ml: 2 }}>
          Learn More
        </Button>
      </CardContent>
    </Card>
  );
}

Core Components

Inputs

Button - Material button with custom "soft" variant
TextField, Select, Autocomplete - Form inputs
Checkbox, Radio, Switch - Selection controls

Data Display

Typography - Text with consistent styling
Avatar, Badge, Chip - Visual elements
Table, List - Data presentation

Surfaces

Card - Content containers
Paper - Elevated surfaces

Layout

Box, Container, Grid, Stack - Layout primitives

Feedback

Alert, Dialog, Snackbar - User notifications

Navigation

Drawer, Menu, Tabs, Breadcrumbs - Navigation components

See full component list →

Custom Features

"Soft" Button Variant

A unique Stolution variant with colored text on alpha background:

<Button variant="soft" color="primary">
  Soft Button
</Button>

Responsive Hooks

import { useResponsive } from '@stolution/ui';

function MyComponent() {
  const { isMobile, isTablet, isDesktop, isPortrait } = useResponsive();

  return (
    <div>
      {isMobile && <MobileView />}
      {isTablet && <TabletView />}
      {isDesktop && <DesktopView />}
    </div>
  );
}

Platform Detection (for analytics)

import { usePlatform } from '@stolution/ui';

function MyComponent() {
  const { isIOS, isAndroid, isStandalone } = usePlatform();

  // Use for analytics, NOT for changing UI
  useEffect(() => {
    analytics.track('page_view', { 
      platform: isIOS ? 'ios' : isAndroid ? 'android' : 'desktop',
      isPWA: isStandalone 
    });
  }, []);

  return <div>Consistent UI across all platforms</div>;
}

PWA Configuration

Next.js with next-pwa

npm install next-pwa

// next.config.js
const withPWA = require('next-pwa')({
  dest: 'public',
  register: true,
  skipWaiting: true,
});

module.exports = withPWA({
  reactStrictMode: true,
});

PWA Manifest (public/manifest.json)

{
  "name": "Your Stolution App",
  "short_name": "Stolution",
  "theme_color": "#0891B2",
  "background_color": "#ffffff",
  "display": "standalone",
  "orientation": "portrait-primary",
  "scope": "/",
  "start_url": "/",
  "icons": [
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

Theming

Custom Theme

import { createStolutionTheme } from '@stolution/ui';
import { ThemeProvider } from '@mui/material/styles';

const customTheme = createStolutionTheme('light');

// Extend with your own customizations
const myTheme = {
  ...customTheme,
  components: {
    ...customTheme.components,
    MuiButton: {
      styleOverrides: {
        root: {
          borderRadius: 16, // More rounded buttons
        },
      },
    },
  },
};

function App() {
  return (
    <ThemeProvider theme={myTheme}>
      {/* Your app */}
    </ThemeProvider>
  );
}

Dark Mode

import { useState } from 'react';
import { StolutionThemeProvider } from '@stolution/ui';

function App() {
  const [mode, setMode] = useState<'light' | 'dark'>('light');

  const toggleMode = () => {
    setMode(mode === 'light' ? 'dark' : 'light');
  };

  return (
    <StolutionThemeProvider mode={mode}>
      <button onClick={toggleMode}>Toggle Theme</button>
      {/* Your app */}
    </StolutionThemeProvider>
  );
}

Design Tokens

Colors

// Primary - Cyan Teal
primary.main: '#0891B2'
primary.light: '#67E8F9'
primary.dark: '#0E7490'

// Secondary - Emerald Green
secondary.main: '#10B981'
secondary.light: '#A7F3D0'
secondary.dark: '#059669'

Typography

h1: 2.5rem (40px)
h2: 2rem (32px)
h3: 1.5rem (24px)
body1: 1rem (16px)
body2: 0.875rem (14px)

Spacing

theme.spacing(1) = 8px
theme.spacing(2) = 16px
theme.spacing(3) = 24px

Breakpoints

xs: 0px      // Mobile portrait
sm: 600px    // Mobile landscape
md: 900px    // Tablet portrait
lg: 1200px   // Desktop
xl: 1536px   // Large desktop

Browser Support

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+
Mobile Safari (iOS 14+)
Chrome Mobile (Android 5+)

License

Contributing

Contributions are welcome! Please read our contributing guidelines first.

Links

Made with ❤️ by the Stolution Team

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@stolution/ui

Features

Installation

Peer Dependencies

Quick Start

1. Wrap your app with StolutionThemeProvider

Next.js App Router (app/layout.tsx)

Next.js Pages Router (_app.tsx)

2. Use Components

Core Components

Inputs

Data Display

Surfaces

Layout

Feedback

Navigation

Custom Features

"Soft" Button Variant

Responsive Hooks

Platform Detection (for analytics)

PWA Configuration

Next.js with next-pwa

PWA Manifest (public/manifest.json)

Theming

Custom Theme

Dark Mode

Design Tokens

Colors

Typography

Spacing

Breakpoints

Browser Support

License

Contributing

Links

1. Wrap your app with `StolutionThemeProvider`