@j3m-quantum/ui 1.12.1 → 2.1.0

package/README.md

@@ -32,6 +32,16 @@ npm install @j3m-quantum/ui tw-animate-css
 
 That's it! All dependencies (Radix UI, lucide-react, etc.) are bundled with the package.
 
+### Set Up AI Assistance (Recommended)
+
+If you use Cursor or AI coding assistants, run this to ensure AI uses the correct components:
+
+```bash
+npx @j3m-quantum/ui init
+```
+
+This creates cursor rules so AI assistants know about all components and use them correctly instead of creating new files.
+
 ## Quick Start
 
 ### 1. Setup Vite + Tailwind
@@ -527,16 +537,71 @@ Make sure to add `glass-context` class to Cards containing interactive component
 </Card>
 ```
 
-## Cursor Rules (AI Assistant)
+## CLI Commands
+
+The package includes a CLI to help with setup and discovery.
+
+### Initialize AI Assistance (Recommended)
+
+Run this after installing to set up Cursor/AI assistant rules:
+
+```bash
+npx @j3m-quantum/ui init
+```
+
+This creates `.cursor/rules/j3m-quantum.md` with:
+- Complete component list with import statements
+- Figma layer name → component mappings
+- Usage guidelines and patterns
+- Instructions for AI to use package components (not create new ones)
+
+### List Available Components
+
+```bash
+npx @j3m-quantum/ui list
+
+# Filter by category
+npx @j3m-quantum/ui list --category blocks
+npx @j3m-quantum/ui list --category inputs
+```
+
+### Check Setup
+
+Validate your project configuration:
+
+```bash
+npx @j3m-quantum/ui doctor
+```
+
+This checks:
+- Package installation
+- CSS import order
+- Cursor rules configuration
+- Required dependencies
+
+## AI Assistant Integration
+
+If your team uses Cursor, Copilot, or other AI coding assistants:
+
+1. **Run `npx @j3m-quantum/ui init`** - This is the most important step
+2. The AI will now:
+   - Use components from `@j3m-quantum/ui` instead of creating new files
+   - Know all 60+ available components
+   - Map Figma layer names to correct components
+   - Follow J3M styling guidelines
+
+### Figma MCP Integration
 
-If your team uses Cursor or AI coding assistants, we provide ready-to-use rules to ensure consistent usage of the design system.
+The cursor rules include a Figma layer → component mapping table. When your Figma MCP suggests a design element, the AI will automatically use the correct package component:
 
-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
+| Figma Layer | Package Component |
+|-------------|------------------|
+| "Button", "CTA" | `Button` |
+| "Card", "Panel" | `Card` |
+| "Planning Grid" | `PlanningTable` |
+| "Dialog", "Modal" | `Dialog` |
 
-This helps AI assistants understand how to use @j3m-quantum/ui correctly and avoid common mistakes.
+See [`cursor-rules-for-consumers.md`](./cursor-rules-for-consumers.md) for the complete mapping.
 
 ## Version Strategy
 

package/cursor-rules-for-consumers.md

@@ -205,7 +205,14 @@ npm add -D tailwindcss @tailwindcss/vite
 npm install @j3m-quantum/ui tw-animate-css
 ```
 
-### 3. Configure Vite
+### 3. Set Up AI Assistance (Important!)
+```bash
+npx @j3m-quantum/ui init
+```
+
+This automatically creates the cursor rules so AI assistants use the correct components.
+
+### 4. Configure Vite
 ```typescript
 // vite.config.ts
 import { defineConfig } from 'vite'
@@ -217,7 +224,7 @@ export default defineConfig({
 })
 ```
 
-### 4. Setup CSS
+### 5. Setup CSS
 ```css
 /* src/index.css */
 @import "tailwindcss";
@@ -225,19 +232,9 @@ export default defineConfig({
 @import "@j3m-quantum/ui/styles";
 ```
 
-### 5. Add Cursor Rules
-Create `.cursor/rules` or `.cursorrules` in your project root and paste the rules from above.
-
-### 6. Setup App Root
-```tsx
-// src/App.tsx
-function App() {
-  return (
-    <div className="j3m-app-bg min-h-screen">
-      {/* Your app content */}
-    </div>
-  )
-}
+### 6. Verify Setup
+```bash
+npx @j3m-quantum/ui doctor
 ```
 
 ### 7. Use Components
@@ -271,6 +268,16 @@ function App() {
 
 ---
 
+## CLI Commands
+
+```bash
+npx @j3m-quantum/ui init      # Set up cursor rules for AI assistance
+npx @j3m-quantum/ui list      # List all available components
+npx @j3m-quantum/ui doctor    # Check if setup is correct
+```
+
+---
+
 ## Updating the Package
 
 To get the latest components and styling:
@@ -280,3 +287,5 @@ npm update @j3m-quantum/ui
 # or
 npm install @j3m-quantum/ui@latest
 ```
+
+After updating, you may want to re-run `npx @j3m-quantum/ui init` to get the latest cursor rules.