@j3m-quantum/ui 0.8.3 → 0.9.0

package/README.md

@@ -2,6 +2,12 @@
 
 J3M Quantum UI - A React component library with J3M design tokens.
 
+## Requirements
+
+- **React** >= 18
+- **Tailwind CSS v4** (required - not compatible with v3)
+- **tw-animate-css** >= 1.0.0
+
 ## Features
 
 - **J3M Design Tokens** - Orange primary, neutral grays, pill-shaped buttons
@@ -179,6 +185,17 @@ 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):

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
+```