diff --git a/.Jules/palette.md b/.Jules/palette.md index 51cdc939..7652ead3 100644 --- a/.Jules/palette.md +++ b/.Jules/palette.md @@ -42,12 +42,19 @@ ## 2026-03-25 - Avoid "these instructions" anti-pattern **Learning:** Using link text like "these instructions for..." creates a poor experience for screen reader users and those navigating out of context. The link text should be fully self-descriptive without needing surrounding context. **Action:** Always prefer updating the visible text of the link to be descriptive and human-readable (e.g., change `see [these instructions for matching MPI DLL files](...)` to `see the [CFD Online instructions for matching MPI DLL files](...)`). + ## 2026-04-02 - Accessible External Links **Learning:** When changing links to open in a new tab () to keep users in the application context, we MUST communicate this context shift to screen reader users by appending '(opens in a new tab)' to the `aria-label`. Additionally, `rel="noopener noreferrer"` is crucial for security. **Action:** For all future external links that open in a new tab, include `target="_blank"`, `rel="noopener noreferrer"`, and an `aria-label` warning for screen readers. + ## 2026-03-27 - Replace generic link text with specific descriptive visible text **Learning:** When changing links for accessibility, instead of using 'Learn more' and fixing it via an `aria-label`, updating the visible text itself to be fully descriptive (e.g., 'View Eddy3D Outdoor Documentation') provides a better experience for all users and guarantees WCAG 2.5.3 compliance. **Action:** Always prefer to update visible text to be self-descriptive instead of relying on `aria-label` attributes to patch generic link text. + +## 2025-04-13 - Lazy Loading Large Images +**Learning:** Found that large animated GIFs in the documentation can cause page load jank and impact performance for users on slower connections. +**Action:** Append `{ loading=lazy }` to large images and GIFs using the MkDocs `attr_list` extension to ensure they are lazy-loaded, improving initial page load times and overall performance. + ## 2026-04-12 - Lazy Loading Large Images **Learning:** Large GIFs in documentation can cause significant page jank and slow initial load times, negatively impacting the reading experience. **Action:** Use the MkDocs `attr_list` extension to append `{ loading=lazy }` to heavy media elements like animated GIFs.