ppods-mini

A minimal design system with atomic tokens and theming, built with React and TypeScript.

Features

• 🎨 Atomic Design Tokens - Consistent spacing, colors, typography, and more
• 🎯 Component Library - Pre-built Button, Card, Badge, and Banner components
• 🌙 Theme System - Light theme with CSS custom properties
• 📦 TypeScript Support - Full type definitions included
• 🚀 Tree Shakeable - Import only what you need
• 💅 CSS-in-JS - Styled with CSS custom properties
• ⚡ Zero Dependencies - Only requires React as peer dependency

Installation

npm install ppods-mini

Peer Dependencies

npm install react react-dom

Quick Start

For AI Agents: See USAGE.md for detailed instructions and examples.

1. Import the CSS

Import the CSS file in your app's entry point:

import 'ppods-mini/styles';

2. Use Components

import { Button, Card, Badge, Banner } from 'ppods-mini';

function App() {
  return (
    <div>
      <Button variant="primary" size="medium">
        Click me
      </Button>
      
      <Card border shadow>
        <Card.Header>Card Title</Card.Header>
        <Card.Body>Card content goes here</Card.Body>
      </Card>
      
      <Badge variant="success" type="expressive">
        Success
      </Badge>
      
      <Banner variant="info" heading="Information">
        This is an informational banner
      </Banner>
    </div>
  );
}

3. Initialize Theme (Optional)

The theme is automatically initialized when you import the package, but you can also manually control it:

import { initializeTheme, applyLightTheme } from 'ppods-mini';

// Initialize theme
initializeTheme();

// Or apply theme to specific element
applyLightTheme(document.getElementById('my-app'));

Components

Button

import { Button } from 'ppods-mini';

<Button 
  variant="primary" // primary | secondary | tertiary | outline | overlay
  size="medium"     // small | medium | large
  loading={false}
  success={false}
  inverse={false}
  iconLeft={<Icon />}
  iconRight={<Icon />}
  iconOnly={<Icon />}
>
  Button Text
</Button>

Card

import { Card } from 'ppods-mini';

<Card 
  variant="default" // default | fill
  border={true}
  shadow={true}
  interactive={false}
>
  <Card.Header>Header Content</Card.Header>
  <Card.Body>Body Content</Card.Body>
  <Card.Footer>Footer Content</Card.Footer>
</Card>

Badge

import { Badge } from 'ppods-mini';

<Badge 
  variant="neutral"    // critical | warning | success | neutral | feature | overlay | highlight
  type="expressive"    // expressive | functional
  size="large"         // small | large
  iconLeft={<Icon />}
  iconRight={<Icon />}
>
  Badge Text
</Badge>

Banner

import { Banner } from 'ppods-mini';

<Banner 
  variant="info"        // critical | warning | feature | info
  type="functional"     // functional | expressive
  interactive={false}
  square={false}
  icon={<Icon />}
  heading="Banner Title"
  action={<Button>Action</Button>}
>
  Banner description text
</Banner>

Theme System

The design system uses CSS custom properties for theming. All theme variables are automatically applied to the :root element.

Available Theme Functions

import { 
  lightTheme,           // Theme object with all CSS variables
  applyLightTheme,      // Apply theme to an element
  getLightThemeCSS,     // Get CSS string for Shadow DOM
  getLightThemeRootCSS, // Get CSS string for :root
  getDistributionCSS,   // Get complete CSS for distribution
  initializeTheme       // Initialize theme system
} from 'ppods-mini';

Custom Theme Variables

You can override any theme variable in your CSS:

:root {
  --color-button-background: #your-color;
  --color-button-text: #your-text-color;
  --spacing-button-padding-medium: 16px 32px;
}

Design Tokens

The design system includes a comprehensive set of design tokens:

import { 
  colors,      // Color palette
  spacing,     // Spacing scale
  fontSizes,   // Typography scale
  fontWeights, // Font weights
  shadows,     // Shadow tokens
  borderRadius,// Border radius tokens
  // ... and more
} from 'ppods-mini';

TypeScript Support

Full TypeScript support is included with comprehensive type definitions:

import { ButtonProps, CardProps, BadgeProps, BannerProps } from 'ppods-mini';

const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for details about changes in each version.

Made with ❤️ by the ppods-mini team