Add focal point documentation to media library page

[markkaylor]

Description

Updates the documentation for the Media Library to include the new focal point feature

Related issue(s)/PR(s)

More information about the feature on this PR

strapi/strapi#25267

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
documentation	Ready	Preview, Comment	Jan 30, 2026 2:27pm

[markkaylor]

Looking into the broken links causing the build to fail done

[pwizla]

The PR looks great, @markkaylor!

As an experiment, I passed it through new AI-based tools I'm developing to analyze compliance to our 12 rules and also to check the structure/outline.
Here's the detailed report generated.

I'm fully aligned with it, except maybe about splitting Step 4. I think in our case it's perfectly acceptable to frame it as you did (what the bot calls "Option C").

I'll do these fixes myself:

• typos
• adding a short intro sentence

and then I'll approve the PR, and merge it next Wednesday. 🫡

(Thanks for fixing the broken link which prevented the build, by the way. Another upcoming tool I'm developing will detect and fix this soon 🤓)

---

Documentation Review Report

File: docusaurus/docs/cms/features/media-library.md
PR: #2930
Workflow: Full Review (Outline Checker → UX Analyzer → Style Checker)
Date: 2026-01-30

---

Summary

Check	Errors	Warnings	Suggestions
Structure (Outline Checker)	0	0	0
UX (UX Analyzer)	0	0	1
Style (12 Rules)	2	1	0
Total	2	1	1

Suggestions

[suggestion] UX — Consider adding a brief intro sentence

Issue: The section jumps directly into steps without explaining what a focal point is or why a user would want one.

Current:

#### Adding a focal point

Click on the edit...

Suggested improvement:

#### Adding a focal point
A focal point ensures the most important part of an image remains visible when the image is cropped or resized in different contexts.

Click on the edit...

Impact: Low — the feature is intuitive enough, but a one-sentence intro would help users understand the value before following the steps.

---

3. Style Issues (Style Checker)

[error] Section "Adding a focal point" > Step 4 — Typo

Found: "...to abandaon changes and exit focal point mode."

Issue: Typo — "abandaon" should be "abandon".

Suggestion:

Alternatively, click the cancel <Icon name="x" classes="ph-bold" /> button to abandon changes and exit focal point mode.

---

[error] Section "Adding a focal point" > Step 5 — Typo

Found: "...to reset the focal point to the center of the iamge."

Issue: Typo — "iamge" should be "image".

Suggestion:

Click the reset <Icon name="arrows-counter-clockwise" classes="ph-bold" /> button to reset the focal point to the center of the image.

---

[warning] Section "Adding a focal point" > Step 4 — Rule 7: One step = one action

Found: "Click the check <Icon name="check" classes="ph-bold" /> button to validate the new focal point. Alternatively, click the cancel <Icon name="x" classes="ph-bold" /> button to abandon changes and exit focal point mode."

Issue: This step contains two distinct actions (validate OR cancel). While they are alternatives, combining them in one step can cause confusion when users are following the procedure.

Suggestion: Split into two separate steps or restructure:

Option A — Split steps:

4. Click the check <Icon name="check" classes="ph-bold" /> button to validate the new focal point.
5. Alternatively, to discard changes, click the cancel <Icon name="x" classes="ph-bold" /> button to exit focal point mode without saving.
6. Click the reset...
7. Click **Finish**...

Option B — Use a note/tip callout:

4. Click the check <Icon name="check" classes="ph-bold" /> button to validate the new focal point.
:::tip

To discard changes, click the cancel <Icon name="x" classes="ph-bold" /> button instead.

:::

Click the reset...

Option C — Keep as-is (acceptable): If the team prefers to keep alternative actions together for brevity, this is a minor deviation and can be accepted. The current phrasing with "Alternatively" does signal the optional nature.

---

Recommended Fixes (by priority)

1. [error] Fix typo: "abandaon" → "abandon" (Step 4)
2. [error] Fix typo: "iamge" → "image" (Step 5)
3. [warning] Consider splitting Step 4 into separate steps for validate/cancel actions, or use a callout for the alternative
4. [suggestion] Add a brief intro sentence explaining what a focal point is and why it's useful

---

Assets Updated

The PR also updates two screenshots:

• media-library_asset-details.png
• media-library_asset-details_DARK.png

✅ Screenshot updates are appropriate to reflect the new focal point button in the UI.

[pwizla]

Looking great, thank you!