TinyBigUI

Material Design 3 component library for React

A modern, accessible, and customizable React component library built with Material Design 3, TypeScript, and Tailwind CSS v4.

---

⚙️ Development Status

Released: v0.1.0 (2026-04-15)

Phase 1a (Button, IconButton, FAB) and Phase 1b (TextField, Checkbox, Switch, Radio, RadioGroup) are complete and published to npm.

Watch this repository to follow our progress!

---

✨ Features

• 🎨 Material Design 3 - Implements the latest MD3 design system with full token support
• ⚛️ React 18+ - Built for modern React with hooks and concurrent features
• 🎯 TypeScript First - 100% TypeScript with full type safety and IntelliSense
• 🌙 Dark Mode Built-in - Automatic system preference detection via prefers-color-scheme plus .dark / .light class overrides
• ♿ Accessibility - WCAG 2.1 AA compliant with comprehensive keyboard navigation
• 🎨 Tailwind CSS v4 - Powered by the latest Tailwind with utility-first styling
• 📦 Tree-shakable - Import only what you need, optimized bundle size
• 🧪 Well Tested - Comprehensive unit tests and component testing
• 🎭 Storybook - Interactive component documentation and testing
• 📚 TypeScript Declarations - Full type definitions included
• 🔧 Customizable - Easy theming and customization with CSS variables
• 🚀 Modern Build - ESM and CJS formats, optimized for all bundlers

---

🚀 Installation

npm install @tinybigui/react
# or
pnpm add @tinybigui/react
# or
yarn add @tinybigui/react

---

📖 Quick Start

import { Button } from "@tinybigui/react";
import "@tinybigui/react/styles.css";

function App() {
  return (
    <div>
      <Button variant="filled" color="primary">
        Click me
      </Button>
      <Button variant="outlined" color="secondary">
        Learn more
      </Button>
    </div>
  );
}

---

📦 Packages

This is a monorepo containing multiple packages:

Package	Description	Version	Status
@tinybigui/react	React components	0.1.0	Released
@tinybigui/tokens	Design tokens (CSS variables)	0.1.0	Released

---

🗺️ Roadmap

Phase 0: Foundation ✅

• Monorepo setup (pnpm workspaces)
• TypeScript configuration
• Build tooling (tsup, PostCSS)
• Tailwind CSS v4 integration
• Material Design 3 design tokens (120 tokens)
• Base utilities (color, typography, cn)
• Testing setup (Vitest + React Testing Library)
• Storybook 10 configuration
• Code quality tools (ESLint, Prettier, Husky, lint-staged)
• CI/CD (GitHub Actions)
• Documentation structure

Phase 1a: Core Buttons ✅

• Button component (53 tests)
• IconButton component (49 tests)
• FloatingActionButton (FAB) component (51 tests)
• Comprehensive tests
• Accessibility compliance

Phase 1b: Form Components ✅

• TextField component (56 tests)
• Checkbox component (49 tests)
• Radio component (47 tests)
• Switch component (50 tests)
• First npm release (v0.1.0) — released 2026-04-15

Phase 2: Layout & Navigation

• Card component
• Dialog component
• Drawer component
• Tabs component
• Navigation components
• Documentation site launch

Phase 3: Data Display

• Table component
• List component
• Chip component
• Badge component
• Tooltip component

Phase 4: Stable Release

• Performance optimization
• Bundle size optimization
• Comprehensive documentation
• Migration guides
• v1.0.0 stable release

---

🤝 Contributing

We welcome contributions! TinyBigUI is an open-source project and we're excited to build it with the community.

How to Contribute

1. Star the repo ⭐ - Show your support!
2. Report bugs 🐛 - Open an issue
3. Suggest features 💡 - Start a discussion
4. Submit PRs 🔧 - Help us build components!

Development Setup

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/tinybigui.git
cd tinybigui

# 2. Install dependencies (requires Node.js 18+ and pnpm 9+)
pnpm install

# 3. Start Storybook for development
pnpm storybook

# 4. Run tests
pnpm test

# 5. Build packages
pnpm build

# 6. Run linting
pnpm lint

# 7. Format code
pnpm format

Project Structure

tinybigui/
├── packages/
│   ├── react/          # React components
│   │   ├── src/
│   │   │   ├── components/
│   │   │   ├── utils/
│   │   │   └── index.ts
│   │   └── test/
│   └── tokens/         # Design tokens
│       └── src/
│           └── tokens.css
└── .github/
    └── workflows/      # CI/CD

Commit Convention

We use Conventional Commits:

feat: add new button component
fix: resolve focus ring issue
docs: update installation guide
style: format code with prettier
refactor: simplify color utilities
test: add button accessibility tests
chore: update dependencies

Code Quality

All contributions must pass:

• ✅ ESLint (no errors, zero warnings)
• ✅ Prettier (formatted code)
• ✅ TypeScript (no type errors)
• ✅ Tests (all passing)
• ✅ Build (successful compilation)

These are automatically checked via Git hooks and CI/CD.

---

🧪 Testing

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test -- --coverage

# Type check
pnpm typecheck

---

📚 Documentation

• GitHub Repository: github.com/buildinclicks/tinybigui
• Documentation Site: Coming soon at tinybigui.dev
• Storybook: Storybook 10 is set up — run pnpm storybook in packages/react to explore components locally
• QA Phases: See /.qa-phases for milestone tracking

---

🎯 Design Philosophy

TinyBigUI is built on these core principles:

1. Accessibility First - Every component is keyboard navigable and screen reader friendly
2. Type Safety - Full TypeScript support with no compromises
3. Performance - Optimized bundle sizes and runtime performance
4. Customization - Easy to theme and customize without fighting the library
5. Developer Experience - Clear APIs, great documentation, helpful error messages
6. Standards-Based - Follows Material Design 3 specifications faithfully
7. Modern Stack - Uses the latest stable versions of React, TypeScript, and Tailwind

---

🛠️ Tech Stack

• React 18.3+ - UI framework
• TypeScript 5.7+ - Type safety
• Tailwind CSS v4 - Styling framework
• Material Design 3 - Design system
• Vitest - Unit testing
• React Testing Library - Component testing
• Storybook 10 - Component development
• tsup - Build tool
• ESLint - Code linting
• Prettier - Code formatting
• pnpm - Package manager
• GitHub Actions - CI/CD

---

📄 License

MIT © buildinclicks

See LICENSE for details.

---

🙏 Acknowledgments

TinyBigUI stands on the shoulders of giants:

• Material Design 3 - Design system and guidelines
• Tailwind CSS - Utility-first CSS framework
• Radix UI - Inspiration for accessibility patterns
• Chakra UI - Inspiration for component API design
• Mantine - Inspiration for developer experience
• React - UI library
• TypeScript - Type system

Special thanks to all open-source contributors who make projects like this possible! 💙

---

Contributors

Thanks to all our contributors!

---

🌟 Show Your Support

If you like this project, please consider:

• ⭐ Starring the repository
• 👁️ Watching for updates
• 🐦 Sharing on social media
• 💬 Joining discussions
• 🔧 Contributing code or documentation

---

Built with ❤️ by buildinclicks

GitHub • Issues • Discussions