Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .Jules/palette.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.