https://github.com/shalomormsby/opencosmos-ui
An AI-fluent component library that's lovable by design. Contains accessible React components, 3 runtime themes, user-controlled motion system. TypeScript-first design system built on Radix UI, Tailwind CSS, and Framer Motion.
https://github.com/shalomormsby/opencosmos-ui
ai-assisted-development ai-native-design ai-native-development component-library design design-system full-stack human-centered-design product-design
Last synced: 2 months ago
JSON representation
An AI-fluent component library that's lovable by design. Contains accessible React components, 3 runtime themes, user-controlled motion system. TypeScript-first design system built on Radix UI, Tailwind CSS, and Framer Motion.
- Host: GitHub
- URL: https://github.com/shalomormsby/opencosmos-ui
- Owner: shalomormsby
- License: mit
- Created: 2026-02-17T00:45:33.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T03:19:07.000Z (3 months ago)
- Last Synced: 2026-04-12T03:27:22.929Z (3 months ago)
- Topics: ai-assisted-development, ai-native-design, ai-native-development, component-library, design, design-system, full-stack, human-centered-design, product-design
- Language: TypeScript
- Homepage: https://thesage.dev
- Size: 2.41 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# OpenCosmos UI
> **Lovable by Design** — 92 accessible React components, 3 runtime-switchable themes, user-controlled motion system, and a philosophy-driven design system built for modern product teams.
[](https://www.npmjs.com/package/@opencosmos/ui)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://react.dev/)
## Overview
The OpenCosmos UI is a production-ready design system that proves human-centered design through architecture, not just claims. With 100 carefully crafted components organized by functional purpose, three distinct themes with runtime switching, and a motion system that respects user accessibility needs, it's built for teams that prioritize developer experience, user agency, and code quality.
**What's included:**
- **92 Components** across 11 functional categories (actions, forms, navigation, overlays, feedback, data-display, layout, features, backgrounds, cursor, motion)
- **3 Runtime Themes** — Studio (professional), Terra (organic), Volt (electric) — each with light and dark modes
- **User-Controlled Motion** — Intensity slider (0-10 scale) with automatic system preference sync
- **Customizer Feature** — User control made tangible, with theme switching, motion tuning, and localStorage persistence
- **Design Tokens** — Colors, typography, spacing, and motion curves defined as code
- **TypeScript-First** — Strict mode, complete type definitions, exports for all subpaths
- **Accessibility First** — WCAG AA contrast, keyboard navigation, screen reader support, motion preferences respected
- **MIT Licensed** — Open source, tree-shakeable, subpath exports for optimal bundle sizes
---
## Quick Start
### Installation
```bash
npm install @opencosmos/ui
# or
pnpm add @opencosmos/ui
```
### Basic Setup
Wrap your app root with the required providers:
```tsx
import { ThemeProvider, TooltipProvider } from '@opencosmos/ui/providers'
import { Toaster } from '@opencosmos/ui'
import '@opencosmos/ui/globals.css'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
)
}
```
### Your First Component
```tsx
import { Button, Card, CardContent, CardHeader, CardTitle } from '@opencosmos/ui'
export function MyComponent() {
return (
Welcome
console.log('Clicked!')}>Get Started
)
}
```
---
## Packages
| Package | Description |
|---------|-------------|
| [`@opencosmos/ui`](https://www.npmjs.com/package/@opencosmos/ui) | 100 components, providers, hooks, theme system |
| [`@opencosmos/tokens`](https://www.npmjs.com/package/@opencosmos/tokens) | Design tokens (colors, typography, spacing, motion) |
| [`@opencosmos/mcp`](https://www.npmjs.com/package/@opencosmos/mcp) | MCP server for AI-assisted component discovery |
### Subpath Exports
Include only what you need:
```tsx
import { Form, FormField, FormItem } from '@opencosmos/ui/forms'
import { DatePicker, Calendar } from '@opencosmos/ui/dates'
import { DataTable } from '@opencosmos/ui/tables'
import { DragDrop } from '@opencosmos/ui/dnd'
import { WarpBackground, OrbBackground } from '@opencosmos/ui/webgl'
import { useMotionPreference, useTheme } from '@opencosmos/ui/hooks'
import { ThemeProvider } from '@opencosmos/ui/providers'
import { cn } from '@opencosmos/ui/utils'
import { spacing } from '@opencosmos/ui/tokens'
```
---
## Themes
Three distinct themes, switchable at runtime via CSS variables (no recompilation):
| Theme | Personality | Use Case |
|-------|------------|----------|
| **Studio** | Professional, balanced, modern | SaaS, developer tools, enterprise |
| **Terra** | Calm, organic, warm earth tones | Wellbeing, design, lifestyle |
| **Volt** | Bold, electric, high contrast | Gaming, dev tools, high-energy brands |
All themes support light and dark modes with WCAG AA contrast ratios.
```tsx
import { useTheme } from '@opencosmos/ui/hooks'
function ThemeSwitcher() {
const { theme, setTheme, mode, setMode } = useTheme()
return (
<>
setTheme('studio')}>Studio
setTheme('terra')}>Terra
setTheme('volt')}>Volt
>
)
}
```
---
## Motion System
Every animation respects user preferences automatically:
```tsx
import { useMotionPreference } from '@opencosmos/ui/hooks'
import { motion } from 'framer-motion'
function AnimatedCard() {
const { shouldAnimate, scale } = useMotionPreference()
return (
Content
)
}
```
- **Intensity Slider (0-10)** — Users control animation intensity
- **System Sync** — Respects `prefers-reduced-motion` automatically
- **Theme-Aware** — Duration and easing curves vary by theme
- **Zero Animation Mode** — Intensity 0 = instant state changes
---
## Eject — Own Your Components
Need to deeply customize a component? Eject it into your project:
```bash
npx @opencosmos/ui eject Button
npx @opencosmos/ui eject Dialog --dir components/sage
npx @opencosmos/ui eject --list
```
The CLI copies component source with imports automatically rewritten. Ejected components still work with Sage themes and CSS variables.
Also available via:
- **Web UI** — Eject button on every component page at [opencosmos.ai/studio](https://opencosmos.ai/studio)
- **MCP** — `eject_component` tool returns transformed source for AI assistants
- **API** — `GET /api/eject/{component}` returns JSON with source and dependencies
---
## OpenCosmos Studio
Interactive documentation at [opencosmos.ai/studio](https://opencosmos.ai/studio):
- Component explorer with live prop controls
- Token gallery across all themes
- Copy-paste ready code examples
- **Eject button** on every component page — copy or download source for full customization
- Accessibility guidelines per component
- AI discovery endpoints (`/.well-known/ai-plugin.json`, `/docs/api.json`)
---
## Development
### Prerequisites
- Node.js 24+ (see `.nvmrc`)
- pnpm 8.15.0+
### Setup
```bash
git clone
cd opencosmos-ui
pnpm install
```
### Commands
```bash
pnpm dev # Start dev server (Studio)
pnpm build # Build all packages and apps
pnpm build --filter @opencosmos/ui # Build specific package
pnpm --filter @opencosmos/ui test # Run tests (156 tests, 30 files)
pnpm lint # Lint all
pnpm typecheck # TypeScript checks
```
### Releasing
```bash
pnpm changeset # Create a changeset
pnpm version-packages # Version packages
pnpm release # Build and publish to NPM
```
### File Structure
```
opencosmos-ui/
├── packages/
│ ├── ui/ # @opencosmos/ui — Component library
│ │ ├── src/components/ # 100 components by functional category
│ │ ├── src/hooks/ # useTheme, useMotionPreference
│ │ ├── src/providers/ # ThemeProvider, TooltipProvider
│ │ └── src/lib/ # Utilities, stores
│ ├── tokens/ # @opencosmos/tokens — Design tokens
│ └── mcp/ # @opencosmos/mcp — MCP server
├── apps/
│ └── web/ # OpenCosmos Studio (opencosmos.ai/studio)
├── docs/ # Documentation
├── DESIGN-PHILOSOPHY.md # The North Star
└── turbo.json # Turborepo task orchestration
```
---
## Architecture
### Functional Organization
Components organized by **purpose** (not atomic hierarchy):
`actions/` `forms/` `navigation/` `overlays/` `feedback/` `data-display/` `layout/` `features/` `backgrounds/` `cursor/` `motion/`
### Styling
CSS variables enable runtime theme switching. All components use semantic tokens:
```tsx
// Theme-aware (correct)
// Hardcoded (incorrect)
```
### State Management
- **Zustand** — Theme, motion, customizer state with localStorage persistence
- **React Context** — Provider hierarchy for theme injection
- **react-hook-form** — Form state management
---
## Tech Stack
| Layer | Technology |
|-------|-----------|
| Framework | React 19, Next.js 16 (App Router) |
| Language | TypeScript 5 (strict mode) |
| Styling | Tailwind CSS 3 |
| Animation | Framer Motion 12 |
| UI Primitives | Radix UI |
| State | Zustand 5 |
| Build | tsup 8 (ESM + CJS) |
| Testing | Vitest + Testing Library |
| Monorepo | Turborepo + pnpm workspaces |
---
## Contributing
1. Read [DESIGN-PHILOSOPHY.md](./DESIGN-PHILOSOPHY.md) first
2. Follow functional organization patterns
3. Ensure accessibility (WCAG AA, keyboard nav, motion preferences)
4. Include tests for new components
5. Use `pnpm changeset` for versioning
---
## License
MIT