@superbuilders/incept-renderer 0.1.7 → 0.1.11

package/README.md

@@ -439,13 +439,35 @@ interface ValidateResult {
 
 ## Theming
 
-The package includes two built-in themes and supports custom themes via CSS variables.
+The package includes two built-in themes and supports custom themes via CSS variables. **You are not required to use the built-in styles** — you can fully customize the appearance to match your application's design system.
+
+### Required CSS Imports
+
+Import the base theme CSS in your app's root layout or global styles:
+
+```tsx
+// In your layout.tsx or globals.css
+import "@superbuilders/incept-renderer/styles/themes.css"
+```
 
 ### Built-in Themes
 
 #### Duolingo (Default)
 
-Clean, friendly design inspired by Duolingo's learning interface.
+Clean, friendly design inspired by Duolingo's learning interface with a vibrant color palette.
+
+**For the complete Duolingo experience**, import the Duolingo theme CSS which includes:
+- Full Duolingo color palette (owl green, macaw blue, cardinal red, etc.)
+- Rounded square choice indicators (A, B, C, D)
+- Filled checkboxes with inset gap effect
+- HTML content styling (lists, typography)
+- Dark mode support
+
+```tsx
+// In your layout.tsx or globals.css
+import "@superbuilders/incept-renderer/styles/themes.css"
+import "@superbuilders/incept-renderer/styles/duolingo.css"  // Full Duolingo styling
+```
 
 ```tsx
 <QTIRenderer theme="duolingo" ... />
@@ -461,19 +483,200 @@ Bold, high-contrast design with thick borders and sharp shadows.
 
 ### Custom Themes
 
-Create your own theme by overriding CSS variables:
+Create your own theme by defining CSS variables for `[data-qti-theme="your-theme-name"]` in your stylesheet, then pass that theme name to the `QTIRenderer` component.
+
+```tsx
+<QTIRenderer theme="my-custom-theme" ... />
+```
+
+### CSS Variables Reference
+
+Below is the **complete list of CSS variables** you can override when creating a custom theme. All variables are optional — any variable you don't define will fall back to the default value.
+
+#### Container Variables
+
+Controls the main question container/card appearance.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-container-bg` | Background color of the container | `var(--background, #ffffff)` |
+| `--qti-container-border` | Border color of the container | `var(--border, #e5e5e5)` |
+| `--qti-container-border-width` | Border thickness | `2px` |
+| `--qti-container-radius` | Border radius (rounded corners) | `var(--radius, 0.5rem)` |
+| `--qti-container-shadow` | Box shadow | `none` |
+
+#### Typography Variables
+
+Controls fonts and text styling throughout the renderer.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-font-family` | Font family for all QTI text | `inherit` |
+| `--qti-font-weight` | Base font weight | `500` |
+| `--qti-tracking` | Letter spacing | `normal` |
+
+#### Choice Variables
+
+Controls the appearance of answer choices (radio buttons, checkboxes).
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-choice-bg` | Default background of choices | `var(--background, #ffffff)` |
+| `--qti-choice-border` | Default border color of choices | `var(--accent, #f4f4f5)` |
+| `--qti-choice-hover-bg` | Background on hover | `var(--muted, #f4f4f5)` |
+| `--qti-choice-selected-bg` | Background when selected | `oklch(0.9 0.1 220 / 0.3)` |
+| `--qti-choice-selected-border` | Border when selected | `oklch(0.6 0.2 250)` |
+| `--qti-choice-correct-bg` | Background for correct answers | `oklch(0.9 0.15 140 / 0.3)` |
+| `--qti-choice-correct-border` | Border for correct answers | `#22c55e` |
+| `--qti-choice-incorrect-bg` | Background for incorrect answers | `oklch(0.9 0.1 25 / 0.3)` |
+| `--qti-choice-incorrect-border` | Border for incorrect answers | `#ef4444` |
+
+#### Button Variables
+
+Controls the appearance of buttons (if using the QTI button classes).
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-button-bg` | Button background color | `var(--primary, #18181b)` |
+| `--qti-button-text` | Button text color | `var(--primary-foreground, #ffffff)` |
+| `--qti-button-border` | Button border color | `var(--primary, #18181b)` |
+| `--qti-button-shadow` | Button box shadow | `none` |
+| `--qti-button-radius` | Button border radius | `var(--radius, 0.5rem)` |
+| `--qti-button-font-weight` | Button font weight | `700` |
+
+#### Feedback Variables
+
+Controls the appearance of feedback messages shown after validation.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-feedback-bg` | Feedback container background | `var(--background, #ffffff)` |
+| `--qti-feedback-border` | Feedback container border | `var(--border, #e5e5e5)` |
+| `--qti-feedback-correct-text` | Text color for correct feedback | `#22c55e` |
+| `--qti-feedback-correct-icon-bg` | Icon background for correct | `#22c55e` |
+| `--qti-feedback-incorrect-text` | Text color for incorrect feedback | `#ef4444` |
+| `--qti-feedback-incorrect-icon-bg` | Icon background for incorrect | `#ef4444` |
+
+#### Input Variables (Text Entry, Textarea, Dropdowns)
+
+Controls the appearance of text input fields, textareas, and select/dropdown elements.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-input-bg` | Input background color | `var(--background, #ffffff)` |
+| `--qti-input-border` | Input border color | `var(--border, #e5e5e5)` |
+| `--qti-input-border-width` | Input border thickness | `2px` |
+| `--qti-input-radius` | Input border radius | `var(--radius, 0.5rem)` |
+| `--qti-input-shadow` | Input box shadow | `none` |
+| `--qti-input-focus-border` | Border color when focused | `var(--ring, #2563eb)` |
+| `--qti-input-focus-shadow` | Box shadow when focused | `0 0 0 2px rgba(37, 99, 235, 0.2)` |
+| `--qti-input-correct-border` | Border for correct text answers | `#22c55e` |
+| `--qti-input-incorrect-border` | Border for incorrect text answers | `#ef4444` |
+
+#### Choice Indicator Variables (Radio/Checkbox Circles)
+
+Controls the appearance of the radio button and checkbox indicators.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-indicator-size` | Size of the indicator | `1.5rem` |
+| `--qti-indicator-bg` | Default background | `var(--background, #ffffff)` |
+| `--qti-indicator-border` | Default border color | `var(--border, #d4d4d8)` |
+| `--qti-indicator-border-width` | Border thickness | `2px` |
+| `--qti-indicator-radius` | Border radius (use `9999px` for circles, `0` for squares) | `9999px` |
+| `--qti-indicator-checked-bg` | Background when checked | `var(--primary, #18181b)` |
+| `--qti-indicator-checked-border` | Border when checked | `var(--primary, #18181b)` |
+| `--qti-indicator-checked-text` | Checkmark/dot color | `var(--primary-foreground, #ffffff)` |
+
+#### Progress Bar Variables
+
+Controls the appearance of progress indicators.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-progress-bg` | Progress bar background (empty part) | `var(--muted, #f4f4f5)` |
+| `--qti-progress-fill` | Progress bar fill color | `var(--primary, #18181b)` |
+| `--qti-progress-height` | Height of the progress bar | `0.5rem` |
+| `--qti-progress-radius` | Border radius | `var(--radius, 0.5rem)` |
+| `--qti-progress-border` | Border color | `transparent` |
+| `--qti-progress-border-width` | Border thickness | `0px` |
+
+#### Content Variables (Question Text, Prompts)
+
+Controls the appearance of HTML content (question text, prompts, instructions).
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-content-font-size` | Font size for content | `1.125rem` |
+| `--qti-content-line-height` | Line height for content | `1.625` |
+| `--qti-content-font-weight` | Font weight for content | `500` |
+
+#### Image Grid Variables
+
+Controls the layout of image-based choice interactions.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-grid-gap` | Gap between grid items | `1rem` |
+| `--qti-image-card-min-height` | Minimum height of image cards | `180px` |
+| `--qti-image-card-padding` | Padding inside image cards | `1rem` |
+| `--qti-image-max-height` | Maximum height of images | `160px` |
+
+#### Order Interaction Variables (Drag-and-Drop Sorting)
+
+Controls the appearance of the order interaction container that holds draggable items.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-order-container-bg` | Container background | `var(--muted, #f4f4f5)` |
+| `--qti-order-container-border` | Container border color | `transparent` |
+| `--qti-order-container-border-width` | Container border thickness | `2px` |
+| `--qti-order-container-radius` | Container border radius | `0.75rem` |
+| `--qti-order-container-padding` | Container padding | `1rem` |
+| `--qti-order-container-gap` | Gap between drag items | `0.5rem` |
+| `--qti-order-container-correct-bg` | Background when correct | `oklch(0.9 0.15 140 / 0.2)` |
+| `--qti-order-container-correct-border` | Border when correct | `#22c55e` |
+| `--qti-order-container-incorrect-bg` | Background when incorrect | `oklch(0.9 0.1 25 / 0.2)` |
+| `--qti-order-container-incorrect-border` | Border when incorrect | `#ef4444` |
+
+#### Order Item Variables (Drag Tokens)
+
+Controls the appearance of individual draggable items/tokens.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--qti-order-item-bg` | Item background | `var(--background, #ffffff)` |
+| `--qti-order-item-border` | Item border color | `var(--border, #e5e5e5)` |
+| `--qti-order-item-border-width` | Item border thickness | `1px` |
+| `--qti-order-item-radius` | Item border radius | `0.5rem` |
+| `--qti-order-item-padding` | Item padding | `1rem` |
+| `--qti-order-item-shadow` | Item box shadow | `0 1px 2px rgba(0, 0, 0, 0.05)` |
+| `--qti-order-item-hover-border` | Border on hover | `oklch(0.6 0.2 250)` |
+| `--qti-order-item-hover-shadow` | Shadow on hover | `0 4px 6px rgba(0, 0, 0, 0.1)` |
+| `--qti-order-item-dragging-border` | Border while dragging | `oklch(0.6 0.2 250)` |
+| `--qti-order-item-dragging-shadow` | Shadow while dragging | `0 8px 16px rgba(0, 0, 0, 0.15)` |
+| `--qti-order-item-handle-color` | Drag handle icon color | `var(--muted-foreground, #71717a)` |
+
+### Complete Custom Theme Example
+
+Here's a complete example defining all variables for a custom theme:
 
 ```css
-/* In your globals.css */
+/* In your globals.css or styles file */
 [data-qti-theme="my-custom-theme"] {
-  /* Container styling */
+  /* ========== Container ========== */
   --qti-container-bg: #ffffff;
   --qti-container-border: #e0e0e0;
   --qti-container-border-width: 1px;
   --qti-container-radius: 12px;
   --qti-container-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
 
-  /* Choice styling */
+  /* ========== Typography ========== */
+  --qti-font-family: "Inter", system-ui, sans-serif;
+  --qti-font-weight: 400;
+  --qti-tracking: normal;
+
+  /* ========== Choices (Radio/Checkbox Cards) ========== */
   --qti-choice-bg: #f8f8f8;
   --qti-choice-border: #d0d0d0;
   --qti-choice-hover-bg: #f0f0f0;
@@ -484,30 +687,151 @@ Create your own theme by overriding CSS variables:
   --qti-choice-incorrect-bg: #ffebee;
   --qti-choice-incorrect-border: #f44336;
 
-  /* Button styling */
+  /* ========== Buttons ========== */
   --qti-button-bg: #2196f3;
   --qti-button-text: #ffffff;
   --qti-button-border: transparent;
   --qti-button-shadow: none;
+  --qti-button-radius: 8px;
+  --qti-button-font-weight: 600;
 
-  /* Typography */
-  --qti-font-family: system-ui, sans-serif;
-  --qti-font-weight: 400;
-
-  /* Feedback styling */
+  /* ========== Feedback Messages ========== */
   --qti-feedback-bg: #ffffff;
   --qti-feedback-border: #e0e0e0;
   --qti-feedback-correct-text: #2e7d32;
+  --qti-feedback-correct-icon-bg: #4caf50;
   --qti-feedback-incorrect-text: #c62828;
+  --qti-feedback-incorrect-icon-bg: #f44336;
+
+  /* ========== Text Inputs / Textareas / Dropdowns ========== */
+  --qti-input-bg: #ffffff;
+  --qti-input-border: #d0d0d0;
+  --qti-input-border-width: 1px;
+  --qti-input-radius: 8px;
+  --qti-input-shadow: none;
+  --qti-input-focus-border: #2196f3;
+  --qti-input-focus-shadow: 0 0 0 3px rgba(33, 150, 243, 0.2);
+  --qti-input-correct-border: #4caf50;
+  --qti-input-incorrect-border: #f44336;
+
+  /* ========== Choice Indicators (Radio/Checkbox Circles) ========== */
+  --qti-indicator-size: 1.5rem;
+  --qti-indicator-bg: #ffffff;
+  --qti-indicator-border: #d0d0d0;
+  --qti-indicator-border-width: 2px;
+  --qti-indicator-radius: 9999px; /* Use 0 for square checkboxes */
+  --qti-indicator-checked-bg: #2196f3;
+  --qti-indicator-checked-border: #2196f3;
+  --qti-indicator-checked-text: #ffffff;
+
+  /* ========== Progress Bar ========== */
+  --qti-progress-bg: #e0e0e0;
+  --qti-progress-fill: #2196f3;
+  --qti-progress-height: 8px;
+  --qti-progress-radius: 4px;
+  --qti-progress-border: transparent;
+  --qti-progress-border-width: 0;
+
+  /* ========== Content (Question Text) ========== */
+  --qti-content-font-size: 1.125rem;
+  --qti-content-line-height: 1.6;
+  --qti-content-font-weight: 400;
+
+  /* ========== Image Grids ========== */
+  --qti-grid-gap: 1rem;
+  --qti-image-card-min-height: 180px;
+  --qti-image-card-padding: 1rem;
+  --qti-image-max-height: 160px;
+
+  /* ========== Order Interaction (Drag-and-Drop Container) ========== */
+  --qti-order-container-bg: #f5f5f5;
+  --qti-order-container-border: #e0e0e0;
+  --qti-order-container-border-width: 1px;
+  --qti-order-container-radius: 12px;
+  --qti-order-container-padding: 1rem;
+  --qti-order-container-gap: 0.75rem;
+  --qti-order-container-correct-bg: rgba(76, 175, 80, 0.15);
+  --qti-order-container-correct-border: #4caf50;
+  --qti-order-container-incorrect-bg: rgba(244, 67, 54, 0.15);
+  --qti-order-container-incorrect-border: #f44336;
+
+  /* ========== Order Items (Drag Tokens) ========== */
+  --qti-order-item-bg: #ffffff;
+  --qti-order-item-border: #e0e0e0;
+  --qti-order-item-border-width: 1px;
+  --qti-order-item-radius: 8px;
+  --qti-order-item-padding: 1rem;
+  --qti-order-item-shadow: 0 2px 4px rgba(0, 0, 0, 0.08);
+  --qti-order-item-hover-border: #2196f3;
+  --qti-order-item-hover-shadow: 0 4px 8px rgba(0, 0, 0, 0.12);
+  --qti-order-item-dragging-border: #2196f3;
+  --qti-order-item-dragging-shadow: 0 8px 16px rgba(0, 0, 0, 0.2);
+  --qti-order-item-handle-color: #9e9e9e;
+}
+
+/* Optional: Dark mode support for your custom theme */
+.dark[data-qti-theme="my-custom-theme"],
+[data-qti-theme="my-custom-theme"] .dark {
+  /* Container */
+  --qti-container-bg: #1a1a1a;
+  --qti-container-border: #333333;
+  
+  /* Choices */
+  --qti-choice-bg: #252525;
+  --qti-choice-border: #444444;
+  --qti-choice-hover-bg: #333333;
+  --qti-choice-selected-bg: rgba(33, 150, 243, 0.2);
+  --qti-choice-selected-border: #2196f3;
+  --qti-choice-correct-bg: rgba(76, 175, 80, 0.2);
+  --qti-choice-incorrect-bg: rgba(244, 67, 54, 0.2);
+  
+  /* Feedback */
+  --qti-feedback-bg: #1a1a1a;
+  --qti-feedback-border: #333333;
+  
+  /* Inputs */
+  --qti-input-bg: #252525;
+  --qti-input-border: #444444;
+  
+  /* Indicators */
+  --qti-indicator-bg: #252525;
+  --qti-indicator-border: #444444;
+  
+  /* Progress */
+  --qti-progress-bg: #333333;
+
+  /* Order Interaction */
+  --qti-order-container-bg: #252525;
+  --qti-order-container-border: #444444;
+  --qti-order-container-correct-bg: rgba(76, 175, 80, 0.2);
+  --qti-order-container-incorrect-bg: rgba(244, 67, 54, 0.2);
+  
+  /* Order Items */
+  --qti-order-item-bg: #1a1a1a;
+  --qti-order-item-border: #444444;
+  --qti-order-item-handle-color: #888888;
 }
 ```
 
-Then use it:
+Then use your custom theme:
 
 ```tsx
 <QTIRenderer theme="my-custom-theme" ... />
 ```
 
+### Partial Overrides
+
+You don't need to define all variables. You can create a theme that only overrides specific values:
+
+```css
+/* Minimal custom theme - only changes colors */
+[data-qti-theme="brand-colors"] {
+  --qti-choice-selected-bg: #your-brand-color-light;
+  --qti-choice-selected-border: #your-brand-color;
+  --qti-button-bg: #your-brand-color;
+}
+```
+
 ---
 
 ## Complete Examples