Minutemailer Kit

A comprehensive React UI library and design system built for Minutemailer. Built on top of shadcn/ui and Tailwind CSS, this kit provides utilities, icons, state management, and components for building consistent user interfaces.

Installation

npm install @minutemailer/kit
Copy

Usage

The kit exports four main modules:

Utils

import {
    strToDate,
    zeroPad,
    replacePlaceholders,
    choice,
    capitalize,
    objToQuery,
} from '@minutemailer/kit/utils';
Copy

Icons

import { Alert, Arrow, Check, Close } from '@minutemailer/kit/icons';
Copy

Store (Global State Management)

import { createStore, getStore, useSelector } from '@minutemailer/kit/store';

// Create a store
const userStore = createStore('user', { name: '', email: '' }, (state, action) => {
  switch (action.type) {
    case 'SET_NAME':
      return { ...state, name: action.value };
    default:
      return state;
  }
});

// Use in React components
function UserProfile() {
  const name = useSelector('user', state => state.name);
  return <div>{name}</div>;
}
Copy

State Machine

import { createMachine } from '@minutemailer/kit/state';

const machine = createMachine(
    {
        IDLE: { on: { START: 'LOADING' } },
        LOADING: { on: { SUCCESS: 'IDLE', ERROR: 'ERROR' } },
        ERROR: { on: { RETRY: 'LOADING' } },
    },
    {
        START: (context) => ({ ...context, loading: true }),
        SUCCESS: (context) => ({ ...context, loading: false }),
    },
    { loading: false },
);
Copy

Development

Setup

git clone <repository-url>
cd kit
npm install
Copy

Available Scripts

• npm start - Start Storybook development server
• npm test - Run tests
• npm run build - Build the library
• npm run icons:build - Generate icon components from SVG files
• npm run docs - Generate documentation

Building Icons

Place SVG files in resources/icons/ and run:

npm run icons:build
Copy

This will generate React components in src/icons/ using SVGR.

Design System

Built with:

• shadcn/ui - Component foundation
• Tailwind CSS v4 - Utility-first styling
• Lucide React - Icon system
• Radix UI - Accessible primitives

Notes:

• Keep component folder names lowercase and component files in PascalCase where applicable.
• Prefer colocating styles/types with the component in the same folder.
• Follow existing patterns for props naming and accessibility.

Adding New Components

Follow this workflow when introducing a new UI component to the kit:

1. Add from shadcn registry

   • Use the shadcn/ui registry to scaffold the base component and any required primitives.
   • Keep the generated file/folder structure consistent with existing components under src/components/ui.
   • If the component requires additional Radix primitives or utilities, include them in the same PR.

2. Create a Storybook story in the category WIP

   • Add a new story file under src/stories and set title to start with WIP/, for example: title: 'WIP/Button'.
   • Include a minimal playground story that demonstrates the component’s states, variants, and interactions.
   • Ensure stories render with our Storybook preview and theming (see .storybook/preview.tsx).

3. Theme it

   • Apply Minutemailer theme tokens and Tailwind classes so the component matches our design language.
   • Verify light/dark modes, focus states, hover/active states, and disabled styles.
   • Align spacing, radius, typography, and color usage with existing components.

4. Move to category UI once ready

   • After review and sign-off, change the Storybook title from WIP/... to UI/... and adjust the file if needed.
   • Remove any temporary props or experimental flags before promoting.
   • Update any related docs or examples.

License

MIT

Contributing

This library is built specifically for Minutemailer's design system. For contributions, please follow the existing patterns and ensure all changes maintain consistency with the Minutemailer brand.