@brona22/superwaddle

v1.0.0

Published

2 months ago

A collection of reusable React components

0High
0Medium
0Low

brona22

react components ui typescript design-system

Super Waddle Components

A production-ready React component library built with TypeScript, featuring accessible, themeable components with comprehensive documentation and testing.

✅ READY TO PUBLISH: PUBLICATION_READY.md - All quality gates passed, all tests passing, verified ready for npm publish

✨ Features

🎯 TypeScript - Full type safety with TypeScript support
🎨 Themeable - CSS custom properties (design tokens) for easy theming
♿ Accessible - WCAG compliant components tested with jest-axe
📦 Tree-shakeable - Optimized bundle with ESM and CJS support
📚 Documented - Interactive documentation with Storybook
🧪 Tested - Comprehensive test coverage with Vitest + React Testing Library
🔧 Developer Experience - ESLint, Prettier, and Husky for code quality

📦 Installation

npm install superwaddle

🚀 Quick Start

import { Button, Card, Header, ThemeProvider } from 'superwaddle';

function App() {
  return (
    <ThemeProvider>
      <Header 
        title="My App" 
        subtitle="Built with Super Waddle"
      />
      <Card
        title="Welcome"
        content="Get started with our component library"
        footer={
          <Button variant="primary" onClick={() => console.log('Clicked!')}>
            Get Started
          </Button>
        }
      />
    </ThemeProvider>
  );
}

🧩 Components

Button

A customizable button component with multiple variants.

Props:

children: ReactNode - Button content
variant?: 'primary' | 'secondary' - Visual style (default: 'primary')
disabled?: boolean - Disable the button
className?: string - Additional CSS classes
Extends all standard HTML button attributes

Example:

import { Button } from 'superwaddle';

<Button variant="primary" onClick={handleClick}>
  Click Me
</Button>

<Button variant="secondary" disabled>
  Disabled Button
</Button>

Card

A versatile card component for displaying content.

Props:

title?: string - Card title
content?: string - Main content text
footer?: ReactNode - Footer content (often used for actions)
className?: string - Additional CSS classes

Example:

import { Card, Button } from 'superwaddle';

<Card
  title="Card Title"
  content="This is the card content."
  footer={
    <Button variant="primary">Action</Button>
  }
/>

Header

A header component with title and optional subtitle.

Props:

title: string - Main header title (required)
subtitle?: string - Optional subtitle text
className?: string - Additional CSS classes

Example:

import { Header } from 'superwaddle';

<Header 
  title="Super Waddle" 
  subtitle="A React Component Library"
/>

ThemeProvider

A wrapper component that provides theme context.

Props:

children: ReactNode - Child components

Example:

import { ThemeProvider } from 'superwaddle/theme';

<ThemeProvider>
  <YourApp />
</ThemeProvider>

🎨 Theming

The library uses CSS custom properties for theming. All design tokens use the --sw-* prefix.

Available Design Tokens

/* Colors */
--sw-color-primary: #007bff;
--sw-color-secondary: #6c757d;
--sw-color-background: #ffffff;
--sw-color-text-primary: #333333;

/* Spacing */
--sw-spacing-sm: 8px;
--sw-spacing-md: 16px;
--sw-spacing-lg: 20px;

/* Typography */
--sw-font-size-base: 16px;
--sw-font-size-lg: 18px;

/* Border Radius */
--sw-radius-sm: 4px;
--sw-radius-md: 8px;

/* Shadows */
--sw-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.1);
--sw-shadow-md: 0 2px 4px rgba(0, 0, 0, 0.1);

/* Transitions */
--sw-transition-fast: 150ms ease-in-out;
--sw-transition-base: 250ms ease-in-out;

Customizing Theme

Override CSS variables in your own stylesheet:

:root {
  --sw-color-primary: #ff6b6b;
  --sw-color-secondary: #4ecdc4;
  --sw-spacing-md: 20px;
}

🛠️ Development

Prerequisites

Node.js >= 18
npm >= 9

Setup

# Install dependencies
npm install

# Start development server
npm run dev

# Run Storybook
npm run storybook

Available Scripts

# Development
npm run dev              # Start Vite dev server
npm run storybook        # Start Storybook

# Building
npm run build            # Build the library
npm run build-storybook  # Build Storybook

# Testing
npm run test             # Run tests
npm run test:watch       # Run tests in watch mode
npm run test:ui          # Open Vitest UI
npm run test:coverage    # Generate coverage report

# Code Quality
npm run lint             # Run ESLint
npm run lint:fix         # Fix ESLint errors
npm run format           # Format code with Prettier
npm run format:check     # Check formatting
npm run typecheck        # Run TypeScript type checking

🎯 Start Here: Execution Resources

Ready to ship SuperWaddle? Use these resources to execute the complete 50-step launch plan:

WEEK1_EXECUTION_CHECKLIST.md - This week's daily action items (npm publish, announce, first customer calls)
EXECUTION_STATUS.md - 50-week launch plan tracker with revenue projections and all milestones

Weekly execution plan: Publish to npm → Announce launch → Get first customers → Build partnerships → Scale to $100k+ ARR

📚 Complete Documentation Hub

Interactive Component Docs

Storybook (Public): https://bronero-ai.github.io/super-waddle/ - Interactive component explorer with code examples
Storybook (Local): npm run storybook then open http://localhost:6006

Core Reference

API_REFERENCE.md - Complete API for all components, props, and theme tokens
ADVANCED_THEMING.md - Advanced customization patterns, color modes, dynamic themes

For Development Teams

STARTER_TEMPLATE.md - 10-minute quick start guide for new projects
MIGRATION_CHECKLIST.md - Integration steps for existing projects (6-step process)
DEPLOYMENT_GUIDE.md - Deploy to Next.js, Vite, Netlify, Vercel, AWS, Azure, Kubernetes

Troubleshooting & Help

TROUBLESHOOTING.md - Common issues and solutions (setup, styling, performance, accessibility)
FAQ.md - Frequently asked questions (installation, usage, licensing, support)

Brand & Operations

BRAND_GUIDELINES.md - Logo usage, color palette, typography, do's and don'ts
COMPONENT_ROADMAP.md - Planned components (Input, Modal, Tabs, etc.), voting system

🧪 Testing

The library uses Vitest with React Testing Library and jest-axe for comprehensive testing:

# Run all tests
npm run test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

All components include:

Unit tests for functionality
Accessibility tests with jest-axe
User interaction tests

🏗️ Project Structure

superwaddle/
├── src/
│   ├── components/           # Component source files
│   │   ├── Button.tsx
│   │   ├── Button.css
│   │   ├── Button.test.tsx
│   │   ├── Button.stories.tsx
│   │   ├── Card.tsx
│   │   ├── Card.css
│   │   ├── Card.test.tsx
│   │   ├── Card.stories.tsx
│   │   ├── Header.tsx
│   │   ├── Header.css
│   │   ├── Header.test.tsx
│   │   ├── Header.stories.tsx
│   │   └── index.ts
│   ├── theme/                # Theme and styling
│   │   ├── ThemeProvider.tsx
│   │   ├── tokens.css
│   │   └── index.ts
│   ├── tests/                # Test utilities
│   │   └── setup.ts
│   ├── App.tsx               # Demo app
│   └── main.tsx              # Demo entry point
├── .storybook/               # Storybook config
├── dist/                     # Build output
├── tsconfig.json             # TypeScript config
├── tsup.config.ts            # Build config
├── vitest.config.ts          # Test config
├── eslint.config.js          # ESLint config
├── .prettierrc               # Prettier config
└── package.json

💳 Pricing & Commercial

Superwaddle is dual-licensed: MIT for open-source use and a paid commercial license for production or proprietary use.

Pricing Options

PRICING.md - Tier overview (Team $999/year, Enterprise $4,999+/year, custom per-project pricing)
ENTERPRISE_FEATURES.md - Enterprise SLA, custom development, white-label options

Commercial Terms & Licensing

MIT License (open-source): LICENSE.md
Commercial License (production use): COMMERCIAL_LICENSE.md

For Organizations

CUSTOMER_SUCCESS.md - Onboarding, support tiers, success metrics, training resources
PARTNERSHIPS.md - Reseller program (25-35% commission), integration partnerships, component authors
MONITORING_GUIDE.md - Analytics, performance metrics, usage tracking
REVENUE_OPERATIONS.md - Pricing strategy, revenue forecasting, customer economics (internal reference)

🚀 Publication & Sales

Publish & Launch

NPM_PUBLICATION_GUIDE.md - Step-by-step npm publishing (generate tokens, set secrets, verify installation)
LAUNCH_ANNOUNCEMENT.md - Launch templates for Twitter, LinkedIn, Product Hunt, GitHub, Dev.to, HN, email

Sales & Customer Acquisition

CUSTOMER_TRACKING.md - Revenue tracking spreadsheet, MRR/ARR formulas, customer metrics dashboard
CUSTOMER_ONBOARDING.md - Day-by-day onboarding plan (Week 1-4 checkpoints, success metrics)
PARTNER_RECRUITMENT.md - Reseller recruitment emails, partner one-pagers, agreements, enablement checklist

Internal Validation (Steps 31-35)

PILOT_CUSTOMER_PROGRAM.md - Internal & external pilot program (2-week validation, case study creation, feedback compilation)

Growth & Expansion (Steps 36-40)

GROWTH_AND_EXPANSION.md - Partner recruitment campaigns, v1.1 component roadmap, release cadence, community engagement, KPIs

Revenue Optimization (Steps 41-45)

REVENUE_OPTIMIZATION.md - Stripe integration, subscription management, pricing optimization, customer financial operations, churn prevention

Scale & Sustainability (Steps 46-50)

SCALE_AND_SUSTAINABILITY.md - Year 1-2 revenue targets (to $250k+ ARR), team scaling, product roadmap, industry recognition, long-term vision

Revenue Optimization (Steps 41-45)

REVENUE_OPTIMIZATION.md - Stripe integration, subscription management, pricing optimization, customer financial operations, churn prevention

Scale & Sustainability (Steps 46-50)

SCALE_AND_SUSTAINABILITY.md - Year 1-2 revenue targets (to $250k+ ARR), team scaling, product roadmap, industry recognition, long-term vision

🤝 Contributing

Contributions are welcome! The project includes:

Pre-commit hooks with Husky and lint-staged
Automated linting and formatting
Type checking with TypeScript
Comprehensive test coverage requirements

Make sure all tests pass and code is properly formatted before submitting PRs.

💬 Support & Community

Get Help

Community (Free): GitHub Discussions - Q&A and feature requests
Bug Reports: GitHub Issues - Report bugs and issues
Team Support: [email protected] (24-48h response, paid tier)
Enterprise Support: [email protected] (4h SLA, Enterprise tier)

📋 Quick Links

| Resource | Purpose | Audience | |----------|---------|----------| | Storybook | Interactive component docs | Everyone | | API_REFERENCE.md | Complete API reference | Developers | | STARTER_TEMPLATE.md | 10-minute setup | New users | | ADVANCED_THEMING.md | Custom theming patterns | Advanced users | | DEPLOYMENT_GUIDE.md | Deployment instructions | DevOps/Deployment engineers | | TROUBLESHOOTING.md | Common issues & fixes | Anyone with issues | | FAQ.md | Frequently asked questions | Everyone | | PARTNERSHIPS.md | Reseller/partner program | Agencies & Partners | | CUSTOMER_SUCCESS.md | Support & onboarding | Customers | | COMPONENT_ROADMAP.md | Upcoming components | Product planning | | NPM_PUBLICATION_GUIDE.md | Publish to npm | DevOps/Release engineers | | LAUNCH_ANNOUNCEMENT.md | Launch templates | Marketing/Communications | | CUSTOMER_TRACKING.md | Revenue dashboard | Finance/Operations | | CUSTOMER_ONBOARDING.md | Onboarding checklist | Customer success/Sales | | PARTNER_RECRUITMENT.md | Partner recruitment | Business development |

🚀 Getting Started

Fastest path to production:

Read STARTER_TEMPLATE.md (10 minutes)
Install: npm install superwaddle
Wrap app with ThemeProvider
Import components: import { Button, Card } from 'superwaddle'
See DEPLOYMENT_GUIDE.md for your platform

Already have a project?

Read MIGRATION_CHECKLIST.md (6-step integration)
Replace components one by one
Test in your build pipeline
Deploy when ready

Questions?

Check FAQ.md for common questions
Search Discussions
Try TROUBLESHOOTING.md
Open a GitHub Issue if stuck

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Super Waddle Components

✨ Features

📦 Installation

🚀 Quick Start

🧩 Components

Button

Card

Header

ThemeProvider

🎨 Theming

Available Design Tokens

Customizing Theme

🛠️ Development

Prerequisites

Setup

Available Scripts

🎯 Start Here: Execution Resources

📚 Complete Documentation Hub

Interactive Component Docs

Core Reference

For Development Teams

Troubleshooting & Help

Brand & Operations

🧪 Testing

🏗️ Project Structure

💳 Pricing & Commercial

Pricing Options

Commercial Terms & Licensing

For Organizations

🚀 Publication & Sales

Publish & Launch

Sales & Customer Acquisition

Internal Validation (Steps 31-35)

Growth & Expansion (Steps 36-40)

Revenue Optimization (Steps 41-45)

Scale & Sustainability (Steps 46-50)

Revenue Optimization (Steps 41-45)

Scale & Sustainability (Steps 46-50)

🤝 Contributing

💬 Support & Community

Get Help

See Also

📋 Quick Links

🚀 Getting Started