@qdesignsystems/design-system-core 0.1.4 → 0.1.6

package/AGENTS.md

@@ -0,0 +1,145 @@
+# Q Design System — AI Agent Rules
+
+## CRITICAL: Component Import Rule
+
+**NEVER install or use local shadcn/ui components (via `npx shadcn@latest add ...`).**
+**ALWAYS import components from `@qdesignsystems/design-system-core`.**
+
+This project uses a pre-built design system package. All components are already available — do not scaffold new ones.
+
+---
+
+## How to Import Components
+
+All components come from one package:
+
+```tsx
+import { Button, Card, Input, Badge, ... } from '@qdesignsystems/design-system-core';
+```
+
+### Base Components
+
+```tsx
+import {
+  // Layout
+  Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent, CardAction,
+
+  // Inputs
+  Button, Input, Textarea, Checkbox, RadioGroup, RadioGroupItem, Switch, Toggle,
+
+  // Display
+  Badge, Alert, AlertTitle, AlertDescription, Separator, Skeleton, Label,
+
+  // Navigation
+  Pagination, PaginationContent, PaginationLink, PaginationItem,
+  PaginationPrevious, PaginationNext, PaginationEllipsis,
+
+  // Overlay
+  Popover, PopoverTrigger, PopoverContent,
+  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem,
+  DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuGroup,
+
+  // Structure
+  Accordion, AccordionItem, AccordionTrigger, AccordionContent,
+  Collapsible, CollapsibleTrigger, CollapsibleContent,
+
+  // Form
+  Form, FormItem, FormLabel, FormControl, FormDescription, FormMessage, FormField,
+
+  // Sidebar
+  Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent,
+  SidebarGroupLabel, SidebarHeader, SidebarMenu, SidebarMenuButton,
+  SidebarMenuItem, SidebarProvider, SidebarTrigger, SidebarInset,
+
+  // Utilities
+  cn, ThemeProvider,
+} from '@qdesignsystems/design-system-core';
+```
+
+### Pre-built Composite Components
+
+These are ready-to-use demo components. Use them as-is or as a starting point:
+
+```tsx
+// Buttons
+import { Button14, Button16, Button17, Button19, Button20 } from '@qdesignsystems/design-system-core';
+
+// Button Groups
+import { ButtonGroup01, ButtonGroup02, ButtonGroup03 } from '@qdesignsystems/design-system-core';
+
+// Cards
+import { Card01, Card02, Card03, Card04, Card05, Card06, Card10, Card13, Card14 } from '@qdesignsystems/design-system-core';
+
+// Inputs
+import { Input01, Input02, Input03 /* ... up to Input46 */ } from '@qdesignsystems/design-system-core';
+
+// Badges
+import { Badge01, Badge02 /* ... up to Badge24 */ } from '@qdesignsystems/design-system-core';
+
+// Forms
+import { Form01, Form02, Form03 /* ... up to Form10 */ } from '@qdesignsystems/design-system-core';
+
+// Checkboxes
+import { Checkbox01, Checkbox02 /* ... up to Checkbox16 */ } from '@qdesignsystems/design-system-core';
+
+// Radio Groups
+import { RadioGroup01, RadioGroup02 /* ... up to RadioGroup13 */ } from '@qdesignsystems/design-system-core';
+
+// Dropdowns
+import { DropdownMenu01, DropdownMenu05, DropdownMenu08, DropdownMenu09 } from '@qdesignsystems/design-system-core';
+
+// Popovers
+import { Popover01, Popover02 /* ... up to Popover12 */ } from '@qdesignsystems/design-system-core';
+
+// Pagination
+import { Pagination01, Pagination02 /* ... up to Pagination15 */ } from '@qdesignsystems/design-system-core';
+
+// Calendars
+import { Calendar01, Calendar02 /* ... up to Calendar21 */ } from '@qdesignsystems/design-system-core';
+
+// Comboboxes
+import { Combobox01, Combobox02 /* ... up to Combobox12 */ } from '@qdesignsystems/design-system-core';
+
+// Data Tables
+import { DataTable01, DataTable02, DataTable03, DataTable05, DataTable07, DataTable08, DataTable09, DataTable13 } from '@qdesignsystems/design-system-core';
+
+// Collapsibles
+import { Collapsible01, Collapsible02 /* ... up to Collapsible09 */ } from '@qdesignsystems/design-system-core';
+
+// Toasts / Notifications
+import { Sonner01, Sonner02 /* ... up to Sonner20 */ } from '@qdesignsystems/design-system-core';
+```
+
+---
+
+## Rules
+
+1. **Never run `npx shadcn@latest add <component>`** — components already exist in the package
+2. **Never create files in `src/components/ui/`** — do not scaffold local shadcn components
+3. **Always import from `@qdesignsystems/design-system-core`**
+4. **Use Tailwind utility classes** for layout and spacing — the theme CSS variables are already loaded
+5. **Do not add a `:root { }` or `.dark { }` block** to any CSS file — this overrides the theme
+
+---
+
+## CSS Setup (must be correct)
+
+`src/main.tsx` must have these imports at the very top:
+
+```tsx
+import '@qdesignsystems/design-system-core/styles.css';
+import '@qdesignsystems/theme-myra/styles.css'; // or theme-q
+```
+
+`src/index.css` must NOT contain `:root { }` or `.dark { }` variable blocks. It should only contain:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  * { @apply border-border; }
+  body { @apply bg-background text-foreground; }
+}
+```

package/README.md

@@ -1,45 +1,99 @@
-# @q-designsystem/core
+# @qdesignsystems/design-system-core
 
-Core React component library built on shadcn/ui.
+Core component library for the Q Design System, built on shadcn/ui and Radix UI.
 
-## Installation
+---
+
+## Quick Setup
+
+### Step 1 — Install
+
+```bash
+# With the MYRA theme
+npm install @qdesignsystems/design-system-core@latest @qdesignsystems/theme-myra@latest
+
+# With the Q theme
+npm install @qdesignsystems/design-system-core@latest @qdesignsystems/theme-q@latest
+```
+
+### Step 2 — Run the init command
+
+The init command automatically patches your `index.css` and `main.tsx` for you:
 
 ```bash
-npm install @q-designsystem/core
+# For the MYRA theme
+npx qds-init --theme=myra
+
+# For the Q theme
+npx qds-init --theme=q
 ```
 
-## Usage
+This will:
+1. Remove the default `:root { }` and `.dark { }` CSS variable blocks from `src/index.css` (they override the theme if left in)
+2. Add the correct CSS imports to `src/main.tsx` in the right order
+
+### Step 3 — Done
+
+Your app now uses the Q Design System with the selected theme.
+
+---
+
+## Manual Setup
+
+If you prefer to set things up manually:
+
+### 1. Add imports to `src/main.tsx` (at the very top, before all other imports)
 
 ```tsx
-import { Button, ThemeProvider } from '@q-designsystem/core';
-import '@q-designsystem/core/styles';
-
-function App() {
-  return (
-    <ThemeProvider defaultTheme="light">
-      <Button>Click me</Button>
-    </ThemeProvider>
-  );
+import '@qdesignsystems/design-system-core/styles.css';
+import '@qdesignsystems/theme-myra/styles.css'; // or theme-q
+```
+
+### 2. Clean up `src/index.css`
+
+Remove the `:root { }` and `.dark { }` blocks that contain CSS variable declarations (lines like `--primary: ...`, `--background: ...`). These override the theme.
+
+Your `index.css` should contain only:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
 }
 ```
 
-## Components
+> **Why?** CSS follows "last one wins". The default `index.css` in a Vite/shadcn project contains hardcoded CSS variable values that override the theme package's variables. Removing them lets the theme apply correctly.
 
-All components are built on shadcn/ui and use CSS variables for theming.
+---
 
-### Button
+## Available Themes
+
+| Package | Description |
+|---|---|
+| `@qdesignsystems/theme-myra` | MYRA theme — blue primary, warm background |
+| `@qdesignsystems/theme-q` | Q theme — black primary, clean minimal |
+
+---
+
+## Import Order
+
+The import order in `main.tsx` matters:
 
 ```tsx
-import { Button } from '@q-designsystem/core';
-
-<Button variant="default">Default</Button>
-<Button variant="destructive">Destructive</Button>
-<Button variant="outline">Outline</Button>
-<Button variant="secondary">Secondary</Button>
-<Button variant="ghost">Ghost</Button>
-<Button variant="link">Link</Button>
-```
+// 1. Core styles (defines base variables)
+import '@qdesignsystems/design-system-core/styles.css';
 
-## Theming
+// 2. Theme styles (overrides base variables with theme values)
+import '@qdesignsystems/theme-myra/styles.css';
 
-Components use CSS variables that can be customized via themes. See `@q-designsystem/themes` for theme definitions.
+// 3. Your app styles (should NOT contain :root variable blocks)
+import './index.css';
+```

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@qdesignsystems/design-system-core",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
   "description": "Core component library built on shadcn/ui",
+  "bin": {
+    "qds-init": "./scripts/init.cjs"
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -24,7 +27,10 @@
     "**/*.css"
   ],
   "files": [
-    "dist"
+    "dist",
+    "scripts/init.cjs",
+    "README.md",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "tsup && node scripts/strip-css-sourcemap.cjs",

package/scripts/init.cjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const RESET = '\x1b[0m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+
+function log(color, symbol, msg) {
+  console.log(`${color}${symbol}${RESET} ${msg}`);
+}
+
+// ─── Resolve project root (where package.json lives) ─────────────────────────
+// When run via npx inside a project, cwd is the project root.
+const projectRoot = process.cwd();
+
+// ─── Detect theme from argv ───────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const themeArg = args.find(a => a.startsWith('--theme='));
+const theme = themeArg ? themeArg.replace('--theme=', '').toLowerCase() : null;
+
+const SUPPORTED_THEMES = ['myra', 'q'];
+
+console.log('');
+console.log(`${BOLD}${CYAN}Q Design System — Init${RESET}`);
+console.log('─'.repeat(40));
+
+if (theme && !SUPPORTED_THEMES.includes(theme)) {
+  log(RED, '✖', `Unknown theme "${theme}". Supported themes: ${SUPPORTED_THEMES.join(', ')}`);
+  process.exit(1);
+}
+
+// ─── 1. Patch index.css ───────────────────────────────────────────────────────
+const CSS_CANDIDATES = [
+  'src/index.css',
+  'src/App.css',
+  'src/globals.css',
+  'src/global.css',
+  'src/styles/index.css',
+  'src/styles/globals.css',
+];
+
+const CLEAN_CSS = `@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+`;
+
+// Regex that matches a :root { ... } or .dark { ... } block containing CSS vars
+const CSS_VAR_BLOCK_RE = /(?::root|\.dark)\s*\{[^}]*--[a-zA-Z][^}]*\}/gs;
+
+let cssPatched = false;
+for (const candidate of CSS_CANDIDATES) {
+  const cssPath = path.join(projectRoot, candidate);
+  if (fs.existsSync(cssPath)) {
+    const original = fs.readFileSync(cssPath, 'utf8');
+    if (CSS_VAR_BLOCK_RE.test(original)) {
+      // Remove :root and .dark CSS variable blocks, keep the rest
+      const patched = original.replace(CSS_VAR_BLOCK_RE, '').replace(/\n{3,}/g, '\n\n').trim();
+      // Ensure Tailwind directives are present
+      const hasTailwind = patched.includes('@tailwind base');
+      const final = hasTailwind ? patched + '\n' : CLEAN_CSS;
+      fs.writeFileSync(cssPath, final, 'utf8');
+      log(GREEN, '✔', `Removed CSS variable overrides from ${candidate}`);
+      cssPatched = true;
+    } else {
+      log(GREEN, '✔', `${candidate} looks clean — no CSS variable overrides found`);
+      cssPatched = true;
+    }
+    break;
+  }
+}
+
+if (!cssPatched) {
+  log(YELLOW, '⚠', 'Could not find index.css — please manually remove :root { } and .dark { } variable blocks');
+}
+
+// ─── 2. Patch main entry file ─────────────────────────────────────────────────
+const ENTRY_CANDIDATES = [
+  'src/main.tsx',
+  'src/main.ts',
+  'src/index.tsx',
+  'src/index.ts',
+  'src/main.jsx',
+  'src/index.jsx',
+];
+
+const CORE_IMPORT = `import '@qdesignsystems/design-system-core/styles.css';`;
+const THEME_IMPORT = theme ? `import '@qdesignsystems/theme-${theme}/styles.css';` : null;
+
+let entryPatched = false;
+for (const candidate of ENTRY_CANDIDATES) {
+  const entryPath = path.join(projectRoot, candidate);
+  if (fs.existsSync(entryPath)) {
+    let content = fs.readFileSync(entryPath, 'utf8');
+    let changed = false;
+
+    if (!content.includes(CORE_IMPORT)) {
+      content = CORE_IMPORT + '\n' + content;
+      changed = true;
+    }
+
+    if (THEME_IMPORT && !content.includes(THEME_IMPORT)) {
+      // Insert theme import right after core import
+      content = content.replace(CORE_IMPORT, CORE_IMPORT + '\n' + THEME_IMPORT);
+      changed = true;
+    }
+
+    if (changed) {
+      fs.writeFileSync(entryPath, content, 'utf8');
+      log(GREEN, '✔', `Added theme imports to ${candidate}`);
+    } else {
+      log(GREEN, '✔', `${candidate} already has the correct imports`);
+    }
+    entryPatched = true;
+    break;
+  }
+}
+
+if (!entryPatched) {
+  log(YELLOW, '⚠', 'Could not find main entry file — please add imports manually (see below)');
+}
+
+// ─── 3. Copy AGENTS.md to project root ───────────────────────────────────────
+// AGENTS.md tells AI assistants (Lovable, Cursor, etc.) to use our components
+const agentsSrc = path.join(__dirname, '..', 'AGENTS.md');
+const agentsDest = path.join(projectRoot, 'AGENTS.md');
+
+if (fs.existsSync(agentsSrc)) {
+  if (fs.existsSync(agentsDest)) {
+    log(GREEN, '✔', 'AGENTS.md already exists at project root');
+  } else {
+    fs.copyFileSync(agentsSrc, agentsDest);
+    log(GREEN, '✔', 'Copied AGENTS.md to project root (tells AI to use design system components)');
+  }
+} else {
+  log(YELLOW, '⚠', 'Could not find AGENTS.md in package — skipping');
+}
+
+// ─── 4. Summary ───────────────────────────────────────────────────────────────
+console.log('');
+console.log(`${BOLD}Setup complete!${RESET}`);
+console.log('');
+
+if (!theme) {
+  console.log(`${YELLOW}No theme specified. To apply a theme, run:${RESET}`);
+  console.log(`  npx @qdesignsystems/design-system-core init --theme=myra`);
+  console.log(`  npx @qdesignsystems/design-system-core init --theme=q`);
+  console.log('');
+  console.log('Then install the theme package:');
+  console.log('  npm install @qdesignsystems/theme-myra@latest');
+  console.log('  npm install @qdesignsystems/theme-q@latest');
+} else {
+  console.log(`${GREEN}Theme applied: ${theme.toUpperCase()}${RESET}`);
+  console.log('');
+  console.log('Make sure the theme package is installed:');
+  console.log(`  npm install @qdesignsystems/theme-${theme}@latest`);
+}
+console.log('');