devtronic 1.2.2 → 1.2.4

package/templates/addons/design-best-practices/reference/color-and-contrast.md

@@ -0,0 +1,146 @@
+# Color & Contrast Reference
+
+Guide to building functional, accessible color palettes for frontend interfaces.
+
+---
+
+## OKLCH Color Space
+
+OKLCH (Oklab Lightness, Chroma, Hue) provides perceptually uniform color manipulation:
+
+```css
+/* oklch(lightness chroma hue) */
+--accent: oklch(0.65 0.2 250);        /* Vivid blue */
+--accent-light: oklch(0.85 0.1 250);  /* Same hue, lighter */
+--accent-dark: oklch(0.45 0.2 250);   /* Same hue, darker */
+```
+
+**Why OKLCH over HSL:**
+- Perceptually uniform lightness (50% L in HSL varies wildly across hues)
+- Easier to create harmonious palettes
+- Better for dark mode transformations (adjust L only)
+- Chroma channel controls saturation more predictably
+
+---
+
+## Palette Construction
+
+### Step 1: Neutrals First
+
+Build the neutral palette before any color:
+
+```
+Near-white:  oklch(0.98 0.005 [warm/cool hue])
+Light gray:  oklch(0.92 0.005 [same hue])
+Mid gray:    oklch(0.70 0.005 [same hue])
+Dark gray:   oklch(0.40 0.01 [same hue])
+Near-black:  oklch(0.15 0.01 [same hue])
+```
+
+Slightly warm (hue ~80) or cool (hue ~250) — never pure neutral gray.
+
+### Step 2: Functional Colors
+
+```
+Error:    oklch(0.55 0.2 25)    /* Red family */
+Warning:  oklch(0.70 0.15 80)   /* Amber family */
+Success:  oklch(0.60 0.15 150)  /* Green family */
+Info:     oklch(0.60 0.15 240)  /* Blue family */
+```
+
+### Step 3: Accent (One Strong Color)
+
+- Pick one accent color for primary actions and emphasis
+- Generate 3-5 shades (lighter for backgrounds, darker for text)
+- One intense color moment is stronger than five
+
+### The 60-30-10 Rule
+
+- **60%** — Dominant (background, surfaces)
+- **30%** — Secondary (cards, text, supporting elements)
+- **10%** — Accent (CTAs, active states, highlights)
+
+---
+
+## WCAG Contrast Requirements
+
+### Minimum Ratios
+
+| Text Size | Level AA | Level AAA |
+|-----------|----------|-----------|
+| Body text (<18px, <14px bold) | 4.5:1 | 7:1 |
+| Large text (≥18px, ≥14px bold) | 3:1 | 4.5:1 |
+| UI components & graphics | 3:1 | — |
+
+### Testing
+
+```css
+/* Check in DevTools: Elements → Computed → color */
+/* Or use: contrast-ratio.com, WebAIM contrast checker */
+```
+
+**Common traps:**
+- Light gray text on white (#999 on #fff = 2.8:1 — fails)
+- Colored text on colored background (check every combination)
+- Placeholder text (often too light)
+- Disabled states (still need 3:1 for the border/icon)
+
+---
+
+## Dark Mode
+
+### Strategy: Don't Invert — Remap
+
+```css
+/* Light mode */
+--bg: oklch(0.98 0.005 80);
+--text: oklch(0.15 0.01 80);
+--surface: oklch(0.95 0.005 80);
+
+/* Dark mode — not simple inversion */
+--bg: oklch(0.15 0.01 250);       /* Slightly cool */
+--text: oklch(0.92 0.005 250);    /* Not pure white */
+--surface: oklch(0.20 0.01 250);  /* Subtle elevation */
+```
+
+**Rules:**
+- Dark mode backgrounds should never be pure black (#000)
+- Reduce chroma slightly for dark mode (vivid colors are harsher on dark)
+- Use elevation (lighter surfaces) instead of shadows for depth
+- Accent colors may need lightness adjustment to maintain contrast
+
+---
+
+## Color Accessibility
+
+- Never use color alone to convey meaning (add icons, text, patterns)
+- Provide sufficient contrast between adjacent colors
+- Test with color blindness simulators (protanopia, deuteranopia, tritanopia)
+- Link text must be distinguishable from surrounding text (not just color — add underline)
+
+---
+
+## Practical Palette Template
+
+```css
+:root {
+  /* Neutrals */
+  --gray-50:  oklch(0.98 0.005 80);
+  --gray-100: oklch(0.95 0.005 80);
+  --gray-200: oklch(0.90 0.005 80);
+  --gray-400: oklch(0.70 0.005 80);
+  --gray-600: oklch(0.50 0.01 80);
+  --gray-800: oklch(0.25 0.01 80);
+  --gray-950: oklch(0.13 0.01 80);
+
+  /* Accent */
+  --accent-100: oklch(0.92 0.05 250);
+  --accent-500: oklch(0.60 0.20 250);
+  --accent-900: oklch(0.30 0.10 250);
+
+  /* Semantic */
+  --color-error: oklch(0.55 0.20 25);
+  --color-warning: oklch(0.70 0.15 80);
+  --color-success: oklch(0.60 0.15 150);
+}
+```

package/templates/addons/design-best-practices/reference/interaction-design.md

@@ -0,0 +1,208 @@
+# Interaction Design Reference
+
+Guide to interactive states, focus management, forms, and keyboard navigation.
+
+---
+
+## The 8 Interactive States
+
+Every interactive element should define these states:
+
+| State | Description | Visual Treatment |
+|-------|-------------|-----------------|
+| **Default** | Base appearance | Standard styling |
+| **Hover** | Mouse over (desktop) | Subtle background change, cursor: pointer |
+| **Focus** | Keyboard focused | Visible focus ring (2px+ offset) |
+| **Active** | Being pressed | Slight scale-down or color shift |
+| **Disabled** | Not available | Reduced opacity (0.5), cursor: not-allowed |
+| **Loading** | Processing action | Spinner or skeleton, disable re-click |
+| **Error** | Invalid state | Red border/text, error message |
+| **Success** | Completed action | Green check, confirmation message |
+
+### Implementation
+
+```css
+.button {
+  /* Default */
+  background: var(--accent-500);
+  color: white;
+  cursor: pointer;
+  transition: background 150ms ease-out;
+}
+
+.button:hover { background: var(--accent-600); }
+
+.button:focus-visible {
+  outline: 2px solid var(--accent-500);
+  outline-offset: 2px;
+}
+
+.button:active { transform: scale(0.98); }
+
+.button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+```
+
+---
+
+## Focus Management
+
+### Focus Rings
+
+```css
+/* Global focus style */
+:focus-visible {
+  outline: 2px solid var(--accent-500);
+  outline-offset: 2px;
+}
+
+/* Remove default outline only when using focus-visible */
+:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+**Rules:**
+- Focus rings must be visible on all backgrounds
+- Use `outline` not `box-shadow` (outlines respect `outline-offset` and don't affect layout)
+- Minimum 2px width, contrasting color
+- `focus-visible` only shows for keyboard navigation, not mouse clicks
+
+### Focus Trapping (Modals)
+
+```javascript
+// When modal opens:
+// 1. Move focus to first focusable element
+// 2. Trap Tab/Shift+Tab within modal
+// 3. Close on Escape
+// 4. Return focus to trigger element on close
+```
+
+### Focus Restoration
+
+After closing a modal, dropdown, or sidebar, return focus to the element that triggered it.
+
+---
+
+## Form Patterns
+
+### Labels
+
+- Every input needs a visible `<label>` (not just placeholder)
+- Labels above inputs (not beside — better for mobile and scanning)
+- Required fields: use `*` after label text + `aria-required="true"`
+
+### Validation
+
+```css
+/* Show errors on blur, not on type */
+.input:not(:focus):invalid {
+  border-color: var(--color-error);
+}
+
+.error-message {
+  color: var(--color-error);
+  font-size: 0.875rem;
+  margin-top: 4px;
+}
+```
+
+**Rules:**
+- Validate on blur (not on every keystroke)
+- Show error messages below the field, not in alerts/toasts
+- Don't clear the input on error — let users correct
+- Use `aria-describedby` to associate error messages with inputs
+- Provide positive feedback for complex fields (password strength)
+
+### Input Sizing
+
+- Text inputs: minimum width to fit expected content
+- Select/dropdown: wide enough for longest option
+- Textarea: show at least 3 lines by default
+- Touch targets: 44x44px minimum (48px recommended)
+
+---
+
+## Keyboard Navigation
+
+### Essential Patterns
+
+| Key | Action |
+|-----|--------|
+| Tab | Move to next focusable element |
+| Shift + Tab | Move to previous focusable element |
+| Enter / Space | Activate focused element |
+| Escape | Close overlay, cancel action |
+| Arrow keys | Navigate within components (tabs, menus, radio groups) |
+
+### Tab Order
+
+- Follow visual reading order (top-left to bottom-right for LTR)
+- Don't use `tabindex > 0` — rearranging tab order confuses users
+- Use `tabindex="-1"` for programmatically focusable elements
+- Use `tabindex="0"` to make non-interactive elements focusable (sparingly)
+
+### Skip Links
+
+```html
+<a href="#main-content" class="skip-link">Skip to main content</a>
+
+<style>
+.skip-link {
+  position: absolute;
+  left: -9999px;
+}
+.skip-link:focus {
+  position: fixed;
+  top: 8px;
+  left: 8px;
+  z-index: 999;
+}
+</style>
+```
+
+---
+
+## Loading States
+
+### Button Loading
+
+```html
+<button disabled aria-busy="true">
+  <span class="spinner" aria-hidden="true"></span>
+  Saving...
+</button>
+```
+
+- Disable the button to prevent double-clicks
+- Show a spinner inside the button (not replacing it)
+- Update button text to reflect action ("Save" → "Saving...")
+- Use `aria-busy="true"` for screen readers
+
+### Page/Section Loading
+
+1. **Skeleton screen** — preferred for known content layouts
+2. **Spinner** — for unknown content or short waits (<2s)
+3. **Progress bar** — for file uploads, multi-step processes
+4. **Optimistic UI** — show expected result immediately, rollback on failure
+
+---
+
+## Click/Touch Targets
+
+- Minimum 44x44px (WCAG 2.5.8)
+- Recommended 48x48px for primary actions
+- Minimum 8px gap between adjacent targets
+- Extend hit area with padding, not just visual size:
+
+```css
+.icon-button {
+  /* Visual size: 24px icon */
+  /* Hit area: 44px with padding */
+  padding: 10px;
+  margin: -10px; /* Prevent layout shift */
+}
+```

package/templates/addons/design-best-practices/reference/motion-design.md

@@ -0,0 +1,167 @@
+# Motion Design Reference
+
+Guide to animation, transitions, and motion in frontend interfaces.
+
+---
+
+## Duration Rules
+
+### The 100 / 300 / 500 Rule
+
+| Duration | Use Case | Example |
+|----------|----------|---------|
+| 100-150ms | Micro-interactions | Button press, toggle, hover state |
+| 200-300ms | Standard transitions | Panel open, tab switch, fade in |
+| 400-500ms | Complex animations | Page transition, modal entrance, list reorder |
+
+**Rules:**
+- Never exceed 500ms for UI transitions (feels sluggish)
+- Entrances can be slightly slower than exits (300ms in, 200ms out)
+- Content-shifting animations need to be fast (≤200ms) to avoid feeling broken
+
+---
+
+## Easing Curves
+
+### Standard Curves
+
+```css
+/* Entering the screen — starts fast, decelerates */
+--ease-out: cubic-bezier(0.0, 0.0, 0.2, 1.0);
+
+/* Leaving the screen — starts slow, accelerates */
+--ease-in: cubic-bezier(0.4, 0.0, 1.0, 1.0);
+
+/* Moving on screen — accelerates then decelerates */
+--ease-in-out: cubic-bezier(0.4, 0.0, 0.2, 1.0);
+
+/* Playful spring effect */
+--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1.0);
+```
+
+### When to Use Each
+
+| Curve | Use When |
+|-------|----------|
+| ease-out | Elements appearing, expanding, entering view |
+| ease-in | Elements disappearing, collapsing, leaving view |
+| ease-in-out | Elements moving position on screen |
+| spring | Toggles, switches, playful micro-interactions |
+| linear | Progress bars, continuous animations, opacity fades |
+
+---
+
+## Reduced Motion
+
+**Always respect `prefers-reduced-motion`:**
+
+```css
+/* Default: full animation */
+.element {
+  transition: transform 300ms var(--ease-out), opacity 300ms var(--ease-out);
+}
+
+/* Reduced motion: instant or minimal */
+@media (prefers-reduced-motion: reduce) {
+  .element {
+    transition: opacity 100ms linear;
+    /* Remove transform animations, keep opacity */
+  }
+
+  /* Disable all non-essential animations */
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+**What to keep in reduced motion:**
+- Opacity transitions (shorter duration)
+- Color changes
+- Essential state indicators
+
+**What to remove:**
+- Transform animations (slide, scale, rotate)
+- Parallax effects
+- Auto-playing animations
+- Decorative motion
+
+---
+
+## Perceived Performance
+
+Use motion to make loading feel faster:
+
+### Skeleton Screens
+
+```css
+.skeleton {
+  background: linear-gradient(
+    90deg,
+    oklch(0.92 0 0) 0%,
+    oklch(0.96 0 0) 50%,
+    oklch(0.92 0 0) 100%
+  );
+  background-size: 200% 100%;
+  animation: shimmer 1.5s ease-in-out infinite;
+}
+
+@keyframes shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+```
+
+### Progressive Loading
+
+1. Show skeleton layout immediately
+2. Fade in critical content first (text, primary actions)
+3. Load images/media progressively
+4. Animate list items in with staggered delay (50ms between items, max 5 items)
+
+---
+
+## Animation Patterns
+
+### Enter / Exit
+
+```css
+/* Fade up enter */
+@keyframes fadeUp {
+  from { opacity: 0; transform: translateY(8px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+/* Scale enter (modals, popovers) */
+@keyframes scaleIn {
+  from { opacity: 0; transform: scale(0.95); }
+  to { opacity: 1; transform: scale(1); }
+}
+```
+
+### Stagger
+
+```css
+.list-item {
+  animation: fadeUp 300ms var(--ease-out) both;
+}
+
+.list-item:nth-child(1) { animation-delay: 0ms; }
+.list-item:nth-child(2) { animation-delay: 50ms; }
+.list-item:nth-child(3) { animation-delay: 100ms; }
+/* Cap at 5 items — don't stagger infinitely */
+```
+
+---
+
+## Performance Guidelines
+
+- Animate only `transform` and `opacity` (GPU-accelerated, no layout recalc)
+- Avoid animating `width`, `height`, `top`, `left`, `margin`, `padding`
+- Use `will-change` sparingly and only on elements about to animate
+- Test on low-end devices — smooth on MacBook Pro ≠ smooth everywhere
+- Prefer CSS transitions/animations over JavaScript when possible

package/templates/addons/design-best-practices/reference/responsive-design.md

@@ -0,0 +1,180 @@
+# Responsive Design Reference
+
+Guide to mobile-first responsive design, breakpoints, and adaptive layouts.
+
+---
+
+## Mobile-First Approach
+
+Write base styles for mobile, then add complexity for larger screens:
+
+```css
+/* Base: mobile (320px+) */
+.grid { display: flex; flex-direction: column; gap: 16px; }
+
+/* Tablet (768px+) */
+@media (min-width: 768px) {
+  .grid { flex-direction: row; flex-wrap: wrap; }
+  .grid > * { flex: 1 1 calc(50% - 8px); }
+}
+
+/* Desktop (1024px+) */
+@media (min-width: 1024px) {
+  .grid > * { flex: 1 1 calc(33.333% - 11px); }
+}
+```
+
+**Why mobile-first:**
+- Forces you to prioritize content
+- Progressive enhancement is more robust than graceful degradation
+- Mobile CSS is simpler (fewer overrides needed)
+
+---
+
+## Content-Driven Breakpoints
+
+Don't use device-specific breakpoints. Break where the content breaks:
+
+```css
+/* Bad: targeting specific devices */
+@media (min-width: 375px) { }  /* iPhone */
+@media (min-width: 414px) { }  /* iPhone Plus */
+
+/* Good: where content needs it */
+@media (min-width: 40em) { }   /* ~640px — content gets cramped */
+@media (min-width: 52em) { }   /* ~832px — space for 2 columns */
+@media (min-width: 72em) { }   /* ~1152px — space for sidebar */
+```
+
+### Recommended Breakpoint Scale
+
+| Name | Width | Use Case |
+|------|-------|----------|
+| sm | 640px | Phone landscape, small tablet |
+| md | 768px | Tablet portrait, two-column |
+| lg | 1024px | Tablet landscape, small desktop |
+| xl | 1280px | Desktop |
+| 2xl | 1536px | Large desktop |
+
+---
+
+## Container Queries
+
+Use container queries for component-level responsive design:
+
+```css
+/* Define the container */
+.card-wrapper {
+  container-type: inline-size;
+  container-name: card;
+}
+
+/* Respond to container size, not viewport */
+@container card (min-width: 300px) {
+  .card { flex-direction: row; }
+}
+
+@container card (max-width: 299px) {
+  .card { flex-direction: column; }
+}
+```
+
+**When to use container queries vs media queries:**
+- **Container queries**: Reusable components that may be placed in different-width containers
+- **Media queries**: Page-level layout decisions (columns, navigation mode)
+
+---
+
+## Input Detection
+
+Adapt UI based on input method:
+
+```css
+/* Fine pointer (mouse) — smaller targets OK */
+@media (pointer: fine) {
+  .button { padding: 8px 16px; }
+}
+
+/* Coarse pointer (touch) — larger targets */
+@media (pointer: coarse) {
+  .button { padding: 12px 24px; min-height: 48px; }
+}
+
+/* Hover capability */
+@media (hover: hover) {
+  .card:hover { box-shadow: var(--shadow-md); }
+}
+
+@media (hover: none) {
+  /* Don't rely on hover states for mobile */
+}
+```
+
+---
+
+## Safe Areas
+
+Handle device-specific safe areas (notch, home indicator):
+
+```css
+/* iOS safe area insets */
+.app {
+  padding-top: env(safe-area-inset-top);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+}
+
+/* Fixed bottom navigation */
+.bottom-nav {
+  padding-bottom: calc(16px + env(safe-area-inset-bottom));
+}
+```
+
+---
+
+## Responsive Images
+
+```html
+<!-- srcset for resolution switching -->
+<img
+  src="image-400.jpg"
+  srcset="image-400.jpg 400w, image-800.jpg 800w, image-1200.jpg 1200w"
+  sizes="(min-width: 1024px) 33vw, (min-width: 768px) 50vw, 100vw"
+  alt="Description"
+  loading="lazy"
+/>
+```
+
+```css
+/* Responsive image defaults */
+img {
+  max-width: 100%;
+  height: auto;
+  display: block;
+}
+```
+
+---
+
+## Responsive Typography
+
+Use fluid type instead of breakpoint-based size changes:
+
+```css
+/* Better than @media jumps */
+h1 { font-size: clamp(1.75rem, 4vw + 1rem, 3.5rem); }
+body { font-size: clamp(1rem, 0.5vw + 0.875rem, 1.125rem); }
+```
+
+---
+
+## Testing Checklist
+
+- [ ] No horizontal scroll at any viewport width (320px minimum)
+- [ ] Touch targets ≥ 44x44px on mobile
+- [ ] Text readable without zooming on mobile
+- [ ] Navigation accessible on all screen sizes
+- [ ] Images scale appropriately
+- [ ] Forms usable on mobile (proper input types, no tiny fields)
+- [ ] Content priority matches viewport size (most important content visible first on mobile)