https://github.com/pglevy/propeller
https://github.com/pglevy/propeller
Last synced: 23 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/pglevy/propeller
- Owner: pglevy
- Created: 2025-12-16T22:36:22.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-03-06T18:52:48.000Z (3 months ago)
- Last Synced: 2026-03-06T19:28:45.608Z (3 months ago)
- Language: TypeScript
- Homepage: https://pglevy.github.io/propeller/
- Size: 1.06 MB
- Stars: 0
- Watchers: 0
- Forks: 1
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Propeller
A modern React component library built for conversational AI interfaces, featuring accessible primitives and domain-specific chat components.
## Overview
Propeller provides production-ready UI components with a focus on:
- **Accessibility-first design** - WCAG 2.1 AA compliant with automated testing
- **Composable architecture** - Build complex UIs from simple primitives
- **Theme flexibility** - CSS variable-based theming with light/dark mode
- **Developer experience** - TypeScript, Storybook documentation, and comprehensive testing
## Tech Stack
- **React 19** with TypeScript
- **Tailwind CSS v4** for styling with CSS variables
- **Radix UI** for accessible, unstyled primitives
- **Lucide React** for icons
- **Storybook v10** for component documentation and testing
- **Vitest** for unit and interaction testing
## Getting Started
### Prerequisites
- Node.js 18+ and npm
### Installation
```bash
npm install
```
### Development
```bash
# Start Storybook (primary development workflow)
npm run storybook
# Start Vite dev server (for quick component testing)
npm run dev
# Run tests
npm test
# Run linter
npm run lint
```
### Building
```bash
# Build library for npm
npm run build:lib
# Build Storybook (for local preview)
npm run build-storybook
# Build demo app
npm run build
```
**Note:** GitHub Pages automatically builds and deploys Storybook on push to main.
## Project Structure
```
src/
├── components/
│ ├── ui/ # Base UI primitives (Button, Input, Card, etc.)
│ ├── chat/ # Chat-specific components (ChatPanel, AgentSteps, etc.)
│ └── shared/ # Shared domain components
├── lib/ # Utilities (cn helper, etc.)
├── hooks/ # Custom React hooks
└── stories/ # Storybook demo pages
```
## Component Categories
### UI Primitives (`src/components/ui/`)
Foundational components built on Radix UI primitives:
- **Layout**: Card, Separator, Resizable, Sidebar
- **Forms**: Button, Input, Select, Checkbox, Radio, Switch, Slider
- **Navigation**: Tabs, Accordion, Navigation Menu, Breadcrumb
- **Feedback**: Alert, Toast, Progress, Spinner, Badge
- **Overlays**: Dialog, Popover, Tooltip, Dropdown Menu, Sheet
- **Data Display**: Table, Avatar, Carousel, Empty State
### Chat Components (`src/components/chat/`)
Specialized components for conversational interfaces:
- **ChatPanel** - Main chat container with message list
- **ChatInput** - Message input with send button
- **AgentSteps** - Display multi-step agent processes
- **TaskProgress** - Show task completion status
- **ChatFeedback** - Thumbs up/down feedback UI
- **ChatConfirmation** - Confirmation dialogs for actions
- **UserMessage** / **AssistantMessage** - Message bubbles
## Design Principles
### Accessibility
All components follow WCAG 2.1 AA standards:
- Semantic HTML and ARIA roles
- Keyboard navigation support
- Screen reader compatibility
- Color contrast compliance (4.5:1 minimum)
- Focus management
### Composition
Components are designed to be composed together:
```tsx
Title
Description
```
### Theming
Use semantic color tokens that adapt to light/dark mode:
```tsx
Muted text
Action
```
Available tokens: `background`, `foreground`, `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `border`, `input`, `ring`
## Documentation
- **Component Documentation**: Visit [https://pglevy.github.io/propeller/](https://pglevy.github.io/propeller/) or run `npm run storybook` locally
- **Agent Guidelines**: See [AGENTS.md](./AGENTS.md) for AI agent development patterns
- **Contributing**: See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines
- **Deployment**: See [DEPLOYMENT.md](./DEPLOYMENT.md) for deployment instructions
## Testing
Propeller uses Storybook's interaction testing and Vitest:
```bash
# Run all tests
npm test
# Run tests with UI
npm test:ui
# Run color palette enforcement tests
npm test:color
```
Coverage goals:
- Statements: 100%
- Branches: 85%+ (100% ideal)
- Functions: 100%
- Lines: 100%
## Contributing
We welcome contributions! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for:
- Code style and conventions
- Component development workflow
- Accessibility requirements
- Testing standards
- Pull request process
## License
[Add your license here]
## Acknowledgments
Built with patterns from [shadcn/ui](https://ui.shadcn.com) (New York style) and powered by [Radix UI](https://www.radix-ui.com) primitives.