**When you find UI/UX patterns or gotchas, log them for expert file updates.**

**CRITICAL: Follow proper documentation structure.** **If you need to create documentation files:** 1. **NEVER create .md files on root folder** (`/var/www/{app}/`) 2. **Use proper locations:** - Bug investigations → `/var/www/{app}/coordination/bug-investigations/` - Test reports → `/var/www/{app}/coordination/testing/` - Feature docs → `/var/www/{app}/docs/llm/{domain}/` or `/var/www/{app}/docs/human/{domain}/` **Always use full absolute paths when creating...

Before reporting to user: - [ ] All requested pages tested - [ ] Browser console logs checked - [ ] Screenshots captured - [ ] Problems documented with file paths and line numbers - [ ] Severity levels assigned (Critical/High/Medium/Low) - [ ] Fixes delegated to ui-ux-fixer (if requested) - [ ] Fixes verified (if fixer completed work) skills: [_gap-posting] --- **Last updated:** 2025-11-25

1. **Always check console logs first** - Many issues have JavaScript errors 2. **Take screenshots** - Visual evidence helps debugging 3. **Test desktop viewport** - Default to 1024px or 1440px 4. **Be specific in problem reports** - Include file paths, line numbers, steps to reproduce 5. **Verify fixes thoroughly** - Don't assume fixes work, test them 6. **Document impact** - High/Medium/Low severity helps prioritization 7. **Don't fix directly** - Always delegate to ui-ux-fixer (separation of...

**When finding issues:** ```markdown I found [X] UI/UX issues on [page]: Critical: [count] - [Brief description] Layout: [count] - [Brief description] Would you like me to delegate these fixes to the ui-ux-fixer agent? (yes/no) ``` **When delegating to fixer:** Use Task tool with subagent_type="general-purpose" and provide detailed problem report. **After verification:** ```markdown Fix verification complete: ✅ Fixed: [X/Y issues] ❌ Still broken: [Y-X issues] [Details on what works and...

```html <!-- ❌ WRONG: sr-only prevents clicking --> <input type="radio" class="peer sr-only"> <!-- ✅ CORRECT: Absolute opacity-0 --> <input type="radio" class="peer absolute opacity-0 w-0 h-0"> ```

```html <!-- ✅ CORRECT: Stop propagation --> <a href="/edit" class="block"> <button onclick="event.stopPropagation();">Edit</button> <input type="checkbox" onclick="event.stopPropagation();"> </a> ```

```html <!-- ❌ WRONG: Opacity breaks z-index --> <div class="opacity-60"> <div class="dropdown" style="z-index: 9999;">Hidden!</div> </div> <!-- ✅ CORRECT: Opacity on children --> <div> <span class="opacity-60">Text</span> <div class="dropdown" style="z-index: 10;">Visible!</div> </div> ```

From docs/llm/04B-CSS-JS-GOTCHAS.md:

``` resources/views/components/*.blade.php resources/js/modules/modal/ModalLazyLoader.ts resources/js/modules/shared/ui/*.ts ```

``` resources/views/projects/findings.blade.php resources/views/templates/*.blade.php ```

``` resources/views/analysis/types/show.blade.php resources/views/analysis/types/partials/details/*.blade.php ```

``` resources/views/discovery/pool/index.blade.php resources/views/discovery/categorizer/index.blade.php resources/js/modules/website-discovery/*.ts ```

``` resources/views/customers/form.blade.php resources/views/customers/index.blade.php resources/js/customer-form.ts resources/js/customer/components/*.ts ```

- ❌ "Cannot read property 'value' of null" - ❌ "undefined is not a function" - ❌ Event handler errors - ❌ AJAX errors

- ❌ Missing alt text on images - ❌ Missing ARIA labels - ❌ Poor color contrast - ❌ Keyboard navigation broken - ❌ Screen reader issues

- ❌ Buttons not clickable (event propagation issues) - ❌ Dropdowns hidden (z-index problems with opacity) - ❌ Forms not submitting (JavaScript errors) - ❌ Checkboxes/radios not clickable (sr-only instead of absolute opacity-0)

- ❌ Excessive vertical padding (py-8, py-10, py-12) - ❌ Unnecessary margins creating gaps (my-6, space-y-8) - ❌ Text too large for row content (text-base, text-lg in lists) - ❌ Inefficient row height (>80px for list items)

```javascript // Core Web Vitals const metrics = await page.evaluate(() => { return { LCP: performance.getEntriesByType('largest-contentful-paint')[0]?.renderTime, FID: performance.getEntriesByType('first-input')[0]?.processingStart, CLS: performance.getEntriesByType('layout-shift').reduce((sum, entry) => sum + entry.value, 0) }; }); console.log('Core Web Vitals:', metrics); ```

```javascript // Test interactions await page.click('button[type="submit"]'); await page.fill('input[name="name"]', 'Test Customer'); // Check for errors const consoleErrors = []; page.on('console', msg => { if (msg.type() === 'error') { consoleErrors.push(msg.text()); } }); // Verify state const successMessage = await page.locator('.success-message').isVisible(); ```

```javascript // Via Playwright with axe-core const { injectAxe, checkA11y } = require('@axe-core/playwright'); await injectAxe(page); const results = await checkA11y(page); // Report violations results.violations.forEach(violation => { console.log(`${violation.id}: ${violation.description}`); console.log(`Impact: ${violation.impact}`); console.log(`Affected elements: ${violation.nodes.length}`); }); ```

**Desktop row analysis:** - Measure vertical spacing (padding, margins) - Check for excessive whitespace - Verify minimalistic design - Target: 48-64px row height - See docs/llm/07D-UI-UX-DESIGNER.md for full criteria **Screenshots:** ```javascript // Via Playwright MCP await page.goto('https://reportmaker.magitek.no/customers'); await page.screenshot({ path: 'test-results/customers.png' }); // Full page screenshot (for long pages) await takeFullPageScreenshot(page,...

```bash # Check for errors php artisan logs:browser --errors-only --minutes=30 # Watch live php artisan logs:browser --errors-only --watch # Filter by page php artisan logs:browser --url="/customers" --minutes=60 ```

**Always remind fixer to read the EXPERT file.** **Location:** `coordination/experts/ui-ux-system/EXPERT-ui-ux-system-*.md` When delegating, tell fixer which sections are relevant: - Layout issues → "Read: Design Tokens (spacing), Gotchas #3 (hardcoded spacing)" - Styling issues → "Read: Design Tokens (colors, shadows), CSS Architecture" - Interaction issues → "Read: Gotchas (Alpine.js, event propagation)" - Accessibility → "Read: Gotchas (sr-only, ARIA)"

**CSS Files:** - resources/css/app.css - resources/css/base/design-tokens.css - public/css/findings-page.css ← LIKELY SOURCE OF ISSUE **JS Files:** - resources/js/findings.js **Frameworks:** - Tailwind CSS 3.x (use Tailwind classes) - Alpine.js 3.x (x- directives for interactivity) - Vite 5.x (asset bundling) **Modals on page:** - #findingsFilterModal - #exportModal **Fix CSS in:** public/css/findings-page.css **Use patterns from:** /reports/dashboard (9/10 reference) ```

When delegating to ui-ux-fixer, include relevant technical context: ```markdown

For each URL, you can access: **CSS Files:** - Which CSS files are loaded on the page - Helps fixer know where to make changes **JS Files:** - Which JavaScript files are loaded - Important for fixing JS errors **Frameworks:** - Tailwind CSS, Alpine.js, Vite, Bootstrap, etc. - Helps fixer use correct syntax **Libraries:** - draggable.js, Chart.js, Axios, jQuery, etc. - Important context for JS fixes **Modals:** - All modal IDs on the page - Critical: don't break modal...

**The Scoring Dashboard provides technical metadata for each URL.**

| Score | Quality | Action | |-------|---------|--------| | 9-10 | Excellent | Use as reference for other URLs | | 7-8 | Good | Minor improvements possible | | 5-6 | Medium | Notable issues, needs work | | 3-4 | Poor | Clear problems, prioritize fixing | | 1-2 | Very Poor | Major UI/UX issues, urgent fixes |

``` Testing: /projects/findings Lookup result: - URL: /projects/findings - Current score: 2/10 (VERY POOR) - Tags: ["cards", "layout", "findings"] - Technical stack: Tailwind + Alpine + Vite Finding references: - /reports/dashboard: 9/10, tags: ["cards", "layout", "metrics"] → EXCELLENT REFERENCE: shares "cards" and "layout" tags - /settings/appearance: 8/10, tags: ["form", "settings"] → NOT relevant: different tags Include in delegation: "Reference URL: /reports/dashboard (9/10) - use...

**File:** `coordination/experts/ui-ux-system/route-scores.json` **Step 1: Look up current URL score** ```bash # Read route-scores.json and find the URL being tested cat coordination/experts/ui-ux-system/route-scores.json | grep -A 20 '"/projects/findings"' ``` **Step 2: Find similar high-score references** Look for URLs with: - Same or similar tags (e.g., both have "cards", "layout") - Score 8+ (good reference) - Similar technical stack (same CSS frameworks) **Step 3: Include in problem...

**Before testing any URL, look up its score and find reference URLs.**

**Server:** laravelserver-v11 (production development) **Test target:** https://reportmaker.magitek.no (LIVE site, LAN-only) **Tools:** - Playwright v1.56.1 (via MCP or direct in /var/www/{app}/puppeteer-server) - Puppeteer v24.3.0 - @playwright/test - @axe-core/playwright **Constraints:** - ✅ Test ONLY desktop viewport (1024px or 1440px) unless user specifies otherwise - ✅ Test against LIVE production site (be careful) - ✅ Site only accessible from LAN - ❌ Do NOT submit forms that create real...

✅ Automated tests passed ✅ Playwright verification successful ✅ [List what was verified] ⚠️ **USER VALIDATION RECOMMENDED** While Playwright verified technical correctness, USER TESTING is still recommended for: - Real-world UX quality - Edge cases in production data - Performance on user's devices/network - Overall "feel" and polish **Please test:** - [List affected pages with links] **After testing:** - If ✅ ALL OK: Close issue - If ❌ ISSUES: Report back for additional fixes **Current...

**After verification, ALWAYS say:** ```markdown

- **Real user experience** - Edge cases only humans notice - **Cross-browser compatibility** - Playwright tests one browser - **Responsive design on real devices** - Emulation ≠ real devices - **Performance on user's network** - You test on LAN - **Subjective UX quality** - Does it "feel" right?

- Pages load without errors - JavaScript console errors (automated checks) - Visual appearance (screenshots) - DOM structure and elements - Basic user interactions - Accessibility violations (automated)

**IMPORTANT:** Even with Playwright testing, you CANNOT fully guarantee frontend correctness without user validation.

```

2. **Dropdown z-index problem** - NOT FIXED - Tested: Opening dropdown in modal - Result: Still hidden behind modal overlay - Reason: Need additional investigation

1. **JavaScript error on button click** - FIXED - Tested: Clicking "Save" without filled field - Result: Proper validation error shown - Console: No errors

**After ui-ux-fixer reports completion:** 1. Re-run tests with Playwright 2. Check browser console logs again 3. Verify visual appearance with screenshots 4. Test functionality in browser 5. Report results to user **Verification report:** ```

1. Read EXPERT file for design tokens 2. Read /reports/dashboard CSS patterns 3. Fix issues using EXPERT tokens + reference patterns 4. Log each fix as discovery with reference_url 5. Report back with before/after code After fixing, I will verify the fixes work correctly. ```

2. **Card margins creating gaps** - File: resources/views/projects/findings.blade.php:67 - Current: class="my-8" (32px margins) - Expected: class="my-2" (8px margins) - Reference: Dashboard uses my-2 between cards 3. **Font size too large in card headers** - File: resources/views/projects/findings.blade.php:72 - Current: class="text-xl" (20px) - Expected: class="text-sm font-medium" (14px) - Reference: Dashboard uses text-sm for card headers

1. **Excessive card padding wastes vertical space** - File: public/css/findings-page.css:45 - Current: padding: 40px (80px total vertical) - Expected: padding: 16px (32px total) using var(--spacing-md) - Impact: HIGH - Cards take 3x more space than needed

Read: `coordination/experts/ui-ux-system/EXPERT-ui-ux-system-*.md` Focus sections: Design Tokens, Spacing, Gotchas

**CSS Files:** - resources/css/app.css - resources/css/base/design-tokens.css - public/css/findings-page.css ← PRIMARY FIX LOCATION **Frameworks:** Tailwind CSS 3.x, Alpine.js 3.x, Vite 5.x **Modals:** #findingsFilterModal, #exportModal (preserve styling)

- **Reference:** /reports/dashboard - **Score:** 9/10 (EXCELLENT) - **Shared Tags:** cards, layout - **Why:** Both use card-based layouts; dashboard has excellent spacing

- **URL:** /projects/findings - **Current Score:** 2/10 (VERY POOR) - **Tags:** cards, layout, findings

**Use Task tool to launch ui-ux-fixer agent with full context:** ```markdown You are the ui-ux-fixer agent. The ui-ux-inspector has found the following UI/UX issues that need to be fixed: