@j3m-quantum/ui 0.8.2 → 0.8.4

package/README.md

@@ -1,13 +1,13 @@
 # @j3m-quantum/ui
 
-J3M Quantum UI - A themed component library based on shadcn/ui with J3M design tokens.
+J3M Quantum UI - A React component library with J3M design tokens.
 
 ## Features
 
 - **J3M Design Tokens** - Orange primary, neutral grays, pill-shaped buttons
 - **Dark Mode** - Full dark theme support via `.dark` class
 - **Glass Mode** - Frosted glass effects via `.theme-glass` class
-- **55+ Components** - All shadcn/ui components with J3M styling
+- **55+ Components** - Complete UI component library with J3M styling
 - **All-in-One** - Everything bundled, just install and use
 - **Smooth Animations** - Powered by tw-animate-css
 
@@ -179,6 +179,37 @@ export default defineConfig({
 })
 ```
 
+## Cursor Rules (AI Assistant)
+
+If your team uses Cursor or AI coding assistants, we provide ready-to-use rules to ensure consistent usage of the design system.
+
+See [`cursor-rules-for-consumers.md`](./cursor-rules-for-consumers.md) for:
+- Rules to copy into your project's `.cursor/rules` file
+- Quick setup guide for new projects
+- Complete component list
+
+This helps AI assistants understand how to use @j3m-quantum/ui correctly and avoid common mistakes.
+
+## Version Strategy
+
+We follow semantic versioning (semver):
+
+| Version Change | When to Use | Example |
+|----------------|-------------|---------|
+| **Patch** (0.8.1 → 0.8.2) | Bug fixes, small styling tweaks | Fix button hover color |
+| **Minor** (0.8.x → 0.9.0) | New components, new features (backward compatible) | Add new PlayerCanvas component |
+| **Major** (0.x.x → 1.0.0) | Breaking changes, API changes, removed components | Rename component props |
+
+### Updating
+
+To get the latest version:
+
+```bash
+npm update @j3m-quantum/ui
+# or
+npm install @j3m-quantum/ui@latest
+```
+
 ## License
 
 MIT

package/cursor-rules-for-consumers.md

@@ -0,0 +1,139 @@
+# J3M Quantum UI - Cursor Rules
+
+Copy the rules below to `.cursor/rules` in your project to help AI assistants use the J3M Design System correctly.
+
+---
+
+## Rules to Copy
+
+```markdown
+# J3M Design System Rules
+
+## Package Usage
+- This project uses @j3m-quantum/ui - a complete React component library with J3M styling
+- Import components directly: `import { Button, Card, Input } from '@j3m-quantum/ui'`
+- Do NOT use shadcn CLI to add components - everything is already bundled
+
+## CSS Import Order (Critical)
+The order in src/index.css must be:
+```css
+@import "tailwindcss";
+@import "tw-animate-css";           /* Required for animations */
+@import "@j3m-quantum/ui/styles";   /* J3M theme and tokens */
+```
+
+## Theme Modes
+- Dark mode: Add `dark` class to root element
+- Glass mode: Add `theme-glass` class to root element
+- Combined: `<div className="dark theme-glass">`
+
+## J3M Design Tokens
+- Primary: #F58446 (orange) - use `bg-primary`, `text-primary`
+- Destructive: #FB3748 (red) - use `bg-destructive`
+- Background: #FFFFFF - use `bg-background`
+- Foreground: #333333 - use `text-foreground`
+- Muted: #E8E8E8 - use `bg-muted`, `text-muted-foreground`
+- Radius: Components use pill shape (rounded-full) for buttons/inputs
+
+## DO
+- Import all components from @j3m-quantum/ui
+- Use Tailwind semantic classes: bg-primary, text-muted-foreground, bg-accent
+- Use CSS variables for custom styling: var(--primary), var(--background)
+- Check the component catalogue before building custom components
+
+## DON'T
+- Don't use shadcn CLI - components are already bundled
+- Don't override CSS variables unless approved by design system maintainer
+- Don't use arbitrary color values like bg-[#F58446] - use bg-primary
+- Don't recreate existing components - use what's in @j3m-quantum/ui
+- Don't modify component border-radius - pill shapes are intentional
+
+## Available Components (55+)
+Inputs: Button, ButtonGroup, Input, Textarea, Checkbox, RadioGroup, Switch, Slider, Select, NativeSelect, Toggle, ToggleGroup, ToolBarCanvas, PlayerCanvas, Form, Label
+
+Display: Card, Table, Badge, Avatar, Separator, Skeleton, Accordion, Tabs, Calendar, Carousel, Chart, AspectRatio, Empty, Item, Kbd
+
+Feedback: Alert, AlertDialog, Progress, Tooltip, Sonner (Toast), Spinner
+
+Navigation: Breadcrumb, Pagination, Command, DropdownMenu, Menubar, NavigationMenu, ContextMenu
+
+Overlay: Dialog, Drawer, Sheet, Popover, HoverCard
+
+Layout: ScrollArea, Collapsible, Resizable, Sidebar, Section
+
+## Requesting Changes
+Need a new component or styling change? Don't build it locally.
+Contact the design system maintainer to request additions or modifications.
+This ensures consistency across all J3M applications.
+```
+
+---
+
+## Quick Setup for New Projects
+
+### 1. Create Project
+```bash
+npm create vite@latest my-app -- --template react-ts
+cd my-app
+npm install
+```
+
+### 2. Add Dependencies
+```bash
+npm add -D tailwindcss @tailwindcss/vite
+npm install @j3m-quantum/ui tw-animate-css
+```
+
+### 3. Configure Vite
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+})
+```
+
+### 4. Setup CSS
+```css
+/* src/index.css */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@j3m-quantum/ui/styles";
+```
+
+### 5. Add Cursor Rules
+Create `.cursor/rules` in your project root and paste the rules from above.
+
+### 6. Use Components
+```tsx
+import { Button, Card, CardHeader, CardTitle, CardContent, Input } from '@j3m-quantum/ui'
+
+function App() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Welcome</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Input placeholder="Enter your name" />
+        <Button>Submit</Button>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+---
+
+## Updating the Package
+
+To get the latest components and styling:
+
+```bash
+npm update @j3m-quantum/ui
+# or
+npm install @j3m-quantum/ui@latest
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@j3m-quantum/ui",
-  "version": "0.8.2",
-  "description": "J3M UI Component Library - themed shadcn/ui components with design tokens",
+  "version": "0.8.4",
+  "description": "J3M UI Component Library - React components with J3M design tokens",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -21,7 +21,8 @@
     "./styles/*": "./dist/styles/*"
   },
   "files": [
-    "dist"
+    "dist",
+    "cursor-rules-for-consumers.md"
   ],
   "scripts": {
     "build": "tsup && npm run copy-styles",