{"id":34681478,"url":"https://github.com/pglevy/propeller","last_synced_at":"2026-05-25T12:34:47.880Z","repository":{"id":329649581,"uuid":"1117843963","full_name":"pglevy/propeller","owner":"pglevy","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-06T18:52:48.000Z","size":1116,"stargazers_count":0,"open_issues_count":9,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-06T19:28:45.608Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pglevy.github.io/propeller/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pglevy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-16T22:36:22.000Z","updated_at":"2026-03-06T18:52:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pglevy/propeller","commit_stats":null,"previous_names":["pglevy/propeller"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pglevy/propeller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pglevy%2Fpropeller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pglevy%2Fpropeller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pglevy%2Fpropeller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pglevy%2Fpropeller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pglevy","download_url":"https://codeload.github.com/pglevy/propeller/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pglevy%2Fpropeller/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33475742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T21:11:53.826Z","updated_at":"2026-05-25T12:34:47.874Z","avatar_url":"https://github.com/pglevy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Propeller\n\nA modern React component library built for conversational AI interfaces, featuring accessible primitives and domain-specific chat components.\n\n## Overview\n\nPropeller provides production-ready UI components with a focus on:\n\n- **Accessibility-first design** - WCAG 2.1 AA compliant with automated testing\n- **Composable architecture** - Build complex UIs from simple primitives\n- **Theme flexibility** - CSS variable-based theming with light/dark mode\n- **Developer experience** - TypeScript, Storybook documentation, and comprehensive testing\n\n## Tech Stack\n\n- **React 19** with TypeScript\n- **Tailwind CSS v4** for styling with CSS variables\n- **Radix UI** for accessible, unstyled primitives\n- **Lucide React** for icons\n- **Storybook v10** for component documentation and testing\n- **Vitest** for unit and interaction testing\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 18+ and npm\n\n### Installation\n\n```bash\nnpm install\n```\n\n### Development\n\n```bash\n# Start Storybook (primary development workflow)\nnpm run storybook\n\n# Start Vite dev server (for quick component testing)\nnpm run dev\n\n# Run tests\nnpm test\n\n# Run linter\nnpm run lint\n```\n\n### Building\n\n```bash\n# Build library for npm\nnpm run build:lib\n\n# Build Storybook (for local preview)\nnpm run build-storybook\n\n# Build demo app\nnpm run build\n```\n\n**Note:** GitHub Pages automatically builds and deploys Storybook on push to main.\n\n## Project Structure\n\n```\nsrc/\n├── components/\n│   ├── ui/           # Base UI primitives (Button, Input, Card, etc.)\n│   ├── chat/         # Chat-specific components (ChatPanel, AgentSteps, etc.)\n│   └── shared/       # Shared domain components\n├── lib/              # Utilities (cn helper, etc.)\n├── hooks/            # Custom React hooks\n└── stories/          # Storybook demo pages\n```\n\n## Component Categories\n\n### UI Primitives (`src/components/ui/`)\n\nFoundational components built on Radix UI primitives:\n\n- **Layout**: Card, Separator, Resizable, Sidebar\n- **Forms**: Button, Input, Select, Checkbox, Radio, Switch, Slider\n- **Navigation**: Tabs, Accordion, Navigation Menu, Breadcrumb\n- **Feedback**: Alert, Toast, Progress, Spinner, Badge\n- **Overlays**: Dialog, Popover, Tooltip, Dropdown Menu, Sheet\n- **Data Display**: Table, Avatar, Carousel, Empty State\n\n### Chat Components (`src/components/chat/`)\n\nSpecialized components for conversational interfaces:\n\n- **ChatPanel** - Main chat container with message list\n- **ChatInput** - Message input with send button\n- **AgentSteps** - Display multi-step agent processes\n- **TaskProgress** - Show task completion status\n- **ChatFeedback** - Thumbs up/down feedback UI\n- **ChatConfirmation** - Confirmation dialogs for actions\n- **UserMessage** / **AssistantMessage** - Message bubbles\n\n## Design Principles\n\n### Accessibility\n\nAll components follow WCAG 2.1 AA standards:\n\n- Semantic HTML and ARIA roles\n- Keyboard navigation support\n- Screen reader compatibility\n- Color contrast compliance (4.5:1 minimum)\n- Focus management\n\n### Composition\n\nComponents are designed to be composed together:\n\n```tsx\n\u003cItem\u003e\n  \u003cItemMedia\u003e\u003cIcon /\u003e\u003c/ItemMedia\u003e\n  \u003cItemContent\u003e\n    \u003cItemTitle\u003eTitle\u003c/ItemTitle\u003e\n    \u003cItemDescription\u003eDescription\u003c/ItemDescription\u003e\n  \u003c/ItemContent\u003e\n\u003c/Item\u003e\n```\n\n### Theming\n\nUse semantic color tokens that adapt to light/dark mode:\n\n```tsx\n\u003cdiv className=\"bg-background text-foreground\"\u003e\n  \u003cp className=\"text-muted-foreground\"\u003eMuted text\u003c/p\u003e\n  \u003cButton className=\"bg-primary text-primary-foreground\"\u003eAction\u003c/Button\u003e\n\u003c/div\u003e\n```\n\nAvailable tokens: `background`, `foreground`, `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `border`, `input`, `ring`\n\n## Documentation\n\n- **Component Documentation**: Visit [https://pglevy.github.io/propeller/](https://pglevy.github.io/propeller/) or run `npm run storybook` locally\n- **Agent Guidelines**: See [AGENTS.md](./AGENTS.md) for AI agent development patterns\n- **Contributing**: See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines\n- **Deployment**: See [DEPLOYMENT.md](./DEPLOYMENT.md) for deployment instructions\n\n## Testing\n\nPropeller uses Storybook's interaction testing and Vitest:\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests with UI\nnpm test:ui\n\n# Run color palette enforcement tests\nnpm test:color\n```\n\nCoverage goals:\n- Statements: 100%\n- Branches: 85%+ (100% ideal)\n- Functions: 100%\n- Lines: 100%\n\n## Contributing\n\nWe welcome contributions! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for:\n\n- Code style and conventions\n- Component development workflow\n- Accessibility requirements\n- Testing standards\n- Pull request process\n\n## License\n\n[Add your license here]\n\n## Acknowledgments\n\nBuilt with patterns from [shadcn/ui](https://ui.shadcn.com) (New York style) and powered by [Radix UI](https://www.radix-ui.com) primitives.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpglevy%2Fpropeller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpglevy%2Fpropeller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpglevy%2Fpropeller/lists"}