{"id":47933703,"url":"https://github.com/shalomormsby/opencosmos-ui","last_synced_at":"2026-04-26T16:02:04.706Z","repository":{"id":338928904,"uuid":"1159631451","full_name":"shalomormsby/opencosmos-ui","owner":"shalomormsby","description":"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.","archived":false,"fork":false,"pushed_at":"2026-04-12T03:19:07.000Z","size":2529,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-12T03:27:22.929Z","etag":null,"topics":["ai-assisted-development","ai-native-design","ai-native-development","component-library","design","design-system","full-stack","human-centered-design","product-design"],"latest_commit_sha":null,"homepage":"https://thesage.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shalomormsby.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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":"2026-02-17T00:45:33.000Z","updated_at":"2026-04-12T03:17:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shalomormsby/opencosmos-ui","commit_stats":null,"previous_names":["shalomormsby/sage-design-engine","shalomormsby/opencosmos-ui"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/shalomormsby/opencosmos-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shalomormsby%2Fopencosmos-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shalomormsby%2Fopencosmos-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shalomormsby%2Fopencosmos-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shalomormsby%2Fopencosmos-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shalomormsby","download_url":"https://codeload.github.com/shalomormsby/opencosmos-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shalomormsby%2Fopencosmos-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31705574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-12T05:11:36.334Z","status":"ssl_error","status_checked_at":"2026-04-12T05:11:27.332Z","response_time":58,"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":["ai-assisted-development","ai-native-design","ai-native-development","component-library","design","design-system","full-stack","human-centered-design","product-design"],"created_at":"2026-04-04T07:30:52.811Z","updated_at":"2026-04-12T06:04:38.239Z","avatar_url":"https://github.com/shalomormsby.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenCosmos UI\n\n\u003e **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.\n\n[![npm version](https://img.shields.io/npm/v/@opencosmos/ui.svg?style=flat-square)](https://www.npmjs.com/package/@opencosmos/ui)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue.svg)](https://www.typescriptlang.org/)\n[![React](https://img.shields.io/badge/React-19-blue.svg)](https://react.dev/)\n\n## Overview\n\nThe 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.\n\n**What's included:**\n\n- **92 Components** across 11 functional categories (actions, forms, navigation, overlays, feedback, data-display, layout, features, backgrounds, cursor, motion)\n- **3 Runtime Themes** — Studio (professional), Terra (organic), Volt (electric) — each with light and dark modes\n- **User-Controlled Motion** — Intensity slider (0-10 scale) with automatic system preference sync\n- **Customizer Feature** — User control made tangible, with theme switching, motion tuning, and localStorage persistence\n- **Design Tokens** — Colors, typography, spacing, and motion curves defined as code\n- **TypeScript-First** — Strict mode, complete type definitions, exports for all subpaths\n- **Accessibility First** — WCAG AA contrast, keyboard navigation, screen reader support, motion preferences respected\n- **MIT Licensed** — Open source, tree-shakeable, subpath exports for optimal bundle sizes\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\nnpm install @opencosmos/ui\n# or\npnpm add @opencosmos/ui\n```\n\n### Basic Setup\n\nWrap your app root with the required providers:\n\n```tsx\nimport { ThemeProvider, TooltipProvider } from '@opencosmos/ui/providers'\nimport { Toaster } from '@opencosmos/ui'\nimport '@opencosmos/ui/globals.css'\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n  return (\n    \u003cThemeProvider defaultTheme=\"studio\" defaultMode=\"system\"\u003e\n      \u003cTooltipProvider\u003e\n        {children}\n        \u003cToaster /\u003e\n      \u003c/TooltipProvider\u003e\n    \u003c/ThemeProvider\u003e\n  )\n}\n```\n\n### Your First Component\n\n```tsx\nimport { Button, Card, CardContent, CardHeader, CardTitle } from '@opencosmos/ui'\n\nexport function MyComponent() {\n  return (\n    \u003cCard\u003e\n      \u003cCardHeader\u003e\n        \u003cCardTitle\u003eWelcome\u003c/CardTitle\u003e\n      \u003c/CardHeader\u003e\n      \u003cCardContent\u003e\n        \u003cButton onClick={() =\u003e console.log('Clicked!')}\u003eGet Started\u003c/Button\u003e\n      \u003c/CardContent\u003e\n    \u003c/Card\u003e\n  )\n}\n```\n\n---\n\n## Packages\n\n| Package | Description |\n|---------|-------------|\n| [`@opencosmos/ui`](https://www.npmjs.com/package/@opencosmos/ui) | 100 components, providers, hooks, theme system |\n| [`@opencosmos/tokens`](https://www.npmjs.com/package/@opencosmos/tokens) | Design tokens (colors, typography, spacing, motion) |\n| [`@opencosmos/mcp`](https://www.npmjs.com/package/@opencosmos/mcp) | MCP server for AI-assisted component discovery |\n\n### Subpath Exports\n\nInclude only what you need:\n\n```tsx\nimport { Form, FormField, FormItem } from '@opencosmos/ui/forms'\nimport { DatePicker, Calendar } from '@opencosmos/ui/dates'\nimport { DataTable } from '@opencosmos/ui/tables'\nimport { DragDrop } from '@opencosmos/ui/dnd'\nimport { WarpBackground, OrbBackground } from '@opencosmos/ui/webgl'\nimport { useMotionPreference, useTheme } from '@opencosmos/ui/hooks'\nimport { ThemeProvider } from '@opencosmos/ui/providers'\nimport { cn } from '@opencosmos/ui/utils'\nimport { spacing } from '@opencosmos/ui/tokens'\n```\n\n---\n\n## Themes\n\nThree distinct themes, switchable at runtime via CSS variables (no recompilation):\n\n| Theme | Personality | Use Case |\n|-------|------------|----------|\n| **Studio** | Professional, balanced, modern | SaaS, developer tools, enterprise |\n| **Terra** | Calm, organic, warm earth tones | Wellbeing, design, lifestyle |\n| **Volt** | Bold, electric, high contrast | Gaming, dev tools, high-energy brands |\n\nAll themes support light and dark modes with WCAG AA contrast ratios.\n\n```tsx\nimport { useTheme } from '@opencosmos/ui/hooks'\n\nfunction ThemeSwitcher() {\n  const { theme, setTheme, mode, setMode } = useTheme()\n  return (\n    \u003c\u003e\n      \u003cbutton onClick={() =\u003e setTheme('studio')}\u003eStudio\u003c/button\u003e\n      \u003cbutton onClick={() =\u003e setTheme('terra')}\u003eTerra\u003c/button\u003e\n      \u003cbutton onClick={() =\u003e setTheme('volt')}\u003eVolt\u003c/button\u003e\n    \u003c/\u003e\n  )\n}\n```\n\n---\n\n## Motion System\n\nEvery animation respects user preferences automatically:\n\n```tsx\nimport { useMotionPreference } from '@opencosmos/ui/hooks'\nimport { motion } from 'framer-motion'\n\nfunction AnimatedCard() {\n  const { shouldAnimate, scale } = useMotionPreference()\n  return (\n    \u003cmotion.div\n      animate={{ opacity: 1, y: shouldAnimate ? 20 : 0 }}\n      transition={{ duration: shouldAnimate ? 0.3 : 0 }}\n    \u003e\n      Content\n    \u003c/motion.div\u003e\n  )\n}\n```\n\n- **Intensity Slider (0-10)** — Users control animation intensity\n- **System Sync** — Respects `prefers-reduced-motion` automatically\n- **Theme-Aware** — Duration and easing curves vary by theme\n- **Zero Animation Mode** — Intensity 0 = instant state changes\n\n---\n\n## Eject — Own Your Components\n\nNeed to deeply customize a component? Eject it into your project:\n\n```bash\nnpx @opencosmos/ui eject Button\nnpx @opencosmos/ui eject Dialog --dir components/sage\nnpx @opencosmos/ui eject --list\n```\n\nThe CLI copies component source with imports automatically rewritten. Ejected components still work with Sage themes and CSS variables.\n\nAlso available via:\n- **Web UI** — Eject button on every component page at [opencosmos.ai/studio](https://opencosmos.ai/studio)\n- **MCP** — `eject_component` tool returns transformed source for AI assistants\n- **API** — `GET /api/eject/{component}` returns JSON with source and dependencies\n\n---\n\n## OpenCosmos Studio\n\nInteractive documentation at [opencosmos.ai/studio](https://opencosmos.ai/studio):\n\n- Component explorer with live prop controls\n- Token gallery across all themes\n- Copy-paste ready code examples\n- **Eject button** on every component page — copy or download source for full customization\n- Accessibility guidelines per component\n- AI discovery endpoints (`/.well-known/ai-plugin.json`, `/docs/api.json`)\n\n---\n\n## Development\n\n### Prerequisites\n\n- Node.js 24+ (see `.nvmrc`)\n- pnpm 8.15.0+\n\n### Setup\n\n```bash\ngit clone \u003crepo-url\u003e\ncd opencosmos-ui\npnpm install\n```\n\n### Commands\n\n```bash\npnpm dev                          # Start dev server (Studio)\npnpm build                        # Build all packages and apps\npnpm build --filter @opencosmos/ui   # Build specific package\npnpm --filter @opencosmos/ui test    # Run tests (156 tests, 30 files)\npnpm lint                         # Lint all\npnpm typecheck                    # TypeScript checks\n```\n\n### Releasing\n\n```bash\npnpm changeset                    # Create a changeset\npnpm version-packages             # Version packages\npnpm release                      # Build and publish to NPM\n```\n\n### File Structure\n\n```\nopencosmos-ui/\n├── packages/\n│   ├── ui/                    # @opencosmos/ui — Component library\n│   │   ├── src/components/    # 100 components by functional category\n│   │   ├── src/hooks/         # useTheme, useMotionPreference\n│   │   ├── src/providers/     # ThemeProvider, TooltipProvider\n│   │   └── src/lib/           # Utilities, stores\n│   ├── tokens/                # @opencosmos/tokens — Design tokens\n│   └── mcp/                   # @opencosmos/mcp — MCP server\n├── apps/\n│   └── web/                   # OpenCosmos Studio (opencosmos.ai/studio)\n├── docs/                      # Documentation\n├── DESIGN-PHILOSOPHY.md       # The North Star\n└── turbo.json                 # Turborepo task orchestration\n```\n\n---\n\n## Architecture\n\n### Functional Organization\n\nComponents organized by **purpose** (not atomic hierarchy):\n\n`actions/` `forms/` `navigation/` `overlays/` `feedback/` `data-display/` `layout/` `features/` `backgrounds/` `cursor/` `motion/`\n\n### Styling\n\nCSS variables enable runtime theme switching. All components use semantic tokens:\n\n```tsx\n// Theme-aware (correct)\n\u003cdiv className=\"bg-background text-foreground border-border\"\u003e\n\n// Hardcoded (incorrect)\n\u003cdiv className=\"bg-white text-black border-gray-200\"\u003e\n```\n\n### State Management\n\n- **Zustand** — Theme, motion, customizer state with localStorage persistence\n- **React Context** — Provider hierarchy for theme injection\n- **react-hook-form** — Form state management\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|-----------|\n| Framework | React 19, Next.js 16 (App Router) |\n| Language | TypeScript 5 (strict mode) |\n| Styling | Tailwind CSS 3 |\n| Animation | Framer Motion 12 |\n| UI Primitives | Radix UI |\n| State | Zustand 5 |\n| Build | tsup 8 (ESM + CJS) |\n| Testing | Vitest + Testing Library |\n| Monorepo | Turborepo + pnpm workspaces |\n\n---\n\n## Contributing\n\n1. Read [DESIGN-PHILOSOPHY.md](./DESIGN-PHILOSOPHY.md) first\n2. Follow functional organization patterns\n3. Ensure accessibility (WCAG AA, keyboard nav, motion preferences)\n4. Include tests for new components\n5. Use `pnpm changeset` for versioning\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshalomormsby%2Fopencosmos-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshalomormsby%2Fopencosmos-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshalomormsby%2Fopencosmos-ui/lists"}