Skip to content

Cursor Rules

Jump to bottom
Brad Johnson edited this page Aug 11, 2025 · 3 revisions

Cursor Rules

Below is usage info on the initial round of .mdc rules (found in .cursor/rules/* for our project. These are built on widely available training materials, PRs, GH discussions and tons of trial and error. Use the phrases below to get the most out of these rules automatically.

This is a living idea that will change fast, and isn't perfect. Feel free to give feedback, bring new ideas and open a PR with updated info, new best practices or corrections as you find them.

mdc logic

Explicit phrase-triggered

  • "Write my tests" → Unit Testing Standards: Unit test patterns, mocking, coverage thresholds, anti-patterns, setup.
  • "Generate Nala tests", "Write E2E tests", "Nala tests" → Nala E2E Test Generation Standards: Playwright-style E2E test scaffolds for blocks/pages, a11y/perf/responsive patterns.
  • "code review" (you can also share a diff or PR URL) → Express-Milo Code Review Standards: Full multi-rule checklist and required review format; enforces performance, structure, a11y, file-size limits, mocks in tests.
  • "create block", "new block", "optimize block", "block development" → Express-Milo Block Patterns: Author-first block design, standard init(el) pattern, resilient selectors, performance-by-phase.

Performance-triggered (keywords: "performance", "Lighthouse", "PageSpeed", "Core Web Vitals", "LCP", "CLS", "INP", "TBT", "render-blocking", "slow", "optimize load")

  • AEM Three-Phase Loading (E-L-D): Enforce E/L/D assignment, first-section-only in Phase E, <100KB budget, single origin.
  • AEM Franklin Loading Phases: Raw → Decorated → Loaded; perf wins in phases 1-2.
  • CSS Render-Blocking Diagnosis: Primary diagnostic for slow LCP/white screen; fix CSS loading order.
  • Lighthouse Performance Troubleshooting: Practical fixes to hit 97–100 scores; LCP targeting, CLS prevention, testing tips.
  • Resource Loading Strategy: Strict E/L/D resource budgets; fonts after LCP; no early preconnect.
  • Lazy Loading Implementation: IntersectionObserver patterns, timeouts, cleanup; Phase D third-party delay.
  • Image Optimization Requirements: Phase-aware image handling, eager LCP image with fetchpriority, bandwidth budgeting, responsive sources.
  • Core Web Vitals Standards: End-to-end CWV targets and enforcement; progressive enhancement patterns.

Conditional triage

  • Mentions like "PageSpeed 75", "score < 90" → Express-Milo Performance Diagnosis: Decision tree that prioritizes CSS render-blocking fixes and E/L/D alignment.

Structure/decorations (often paired with block work or perf work)

  • "block decoration", "decorate", "transformation" → AEM EDS Transformation Patterns: Don’t bypass 3-phase; build LCP structure first, enhance later.
  • "sections", "metadata", "markup architecture" → AEM Markup, Sections, and Blocks Architecture: Authoring hierarchy, section metadata, block JS/CSS scoping.

Always-on (applies to every query implicitly)

  • DOM Structure Preservation: Final DOM must remain identical post-optimization (classes/order/attrs).
  • DOM Manipulation Best Practices: Use createTag, batch DOM ops, avoid innerHTML, phase-aware building.
  • Event Handling Performance: Minimal Phase E handlers, throttle/debounce, passive listeners, cleanup.
Clone this wiki locally