Merge branch 'development' of https://github.com/mendix/docs into development

Author: MarkvanMents

.claude/skills/docs-alt-text/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: docs-alt-text
+description: Generates W3C-compliant alt text for images in documentation pages. Analyzes each image's purpose and adds descriptive alt text for informative images or empty alt for decorative images, improving accessibility and SEO.
+user-invocable: true
+disable-model-invocation: false
+---
+
+> **Accessibility skill:** Generates alt text following W3C/WCAG 2.1 guidelines. Analyzes actual image content plus context to create concise, meaningful descriptions.
+
+## Workflow
+
+Follow this order for each image:
+
+1. **STEP 1 - View the image file** (REQUIRED)
+   - Extract image src path from figure shortcode
+   - Convert path: `src="/attachments/path/file.png"` → `static/attachments/path/file.png`
+   - Use Read tool to view the actual image
+   - Understand what the image shows BEFORE reading context
+
+2. **STEP 2 - Read surrounding context**
+   - Read the heading, preceding/following text, list item, or numbered step
+   - Understand the image's purpose within the documentation
+   - Consider if context + image together make the image informative or decorative
+
+3. **STEP 3 - Determine if informative or decorative**
+   - **Technical docs assumption:** Images are informative unless obviously decorative
+   - **Informative:** Images that convey information → write descriptive alt text
+   - **Decorative:** Images where the information is already given in adjacent text, or pure visual styling with no informational value → use `alt=""`
+
+4. **STEP 4 - Generate alt text**
+   - **If decorative, use `alt=""`.** Never omit the alt attribute entirely.
+   - **If informative, generate descriptive alt text:**
+      - Focus on the information the image communicates, not what it looks like
+      - Give the most concise description possible
+      - Maximum 30 words (flag complex images needing longer descriptions for body text)
+      - Don't include "screenshot of", "image of", or "picture of" (screen readers already announce it's an image)
+      - Use Mendix terminology
+      - Avoid redundancy with nearby text
+      - **Based on surrounding context:**
+         - In a procedure: emphasize the action/element relevant to the step (e.g., "Download button in Registration dialog")
+         - Showing UI elements: name the relevant elements (e.g., "Properties pane")
+         - Showing structure or relationships: describe what entities/components are connected (e.g., "Domain model with Customer and Order entities connected by one-to-many association")
+         - Showing logic or process flow: describe what the flow accomplishes (e.g., "Microflow that retrieves FileDocument list and updates encryption keys")
+
+5. **STEP 5 - Edit the figure shortcode**
+   - Use Edit tool to add/update only the `alt` attribute
+   - Preserve all other attributes: `class`, `width`, `max-width`, `link`
+   - Maintain exact indentation and spacing
+
+## Special Cases
+
+- **Images in numbered lists:** Common in procedures—describe the procedural step shown
+- **Before/after sequences:** Describe what changed or the state shown
+- **Existing alt text:** May update if it's empty, generic, or poor quality (e.g., `alt=""`, `alt="button"`, `alt="before"`)
+- **File format icons:** Use format name (e.g., "PDF", "ZIP", "Word document")
+- **Complex diagrams:** If needs >30 words, flag to user and suggest adding description to body text
+
+## What NOT to do
+
+- Don't modify `src` path or attributes other than `alt`
+- Don't change surrounding text or document structure
+- Don't process images outside the determined scope
+- Don't generate alt text based solely on filename—always view the image first
+
+## After Processing
+
+Report summary:
+- How many images processed
+- How many updated
+
+**Always suggest user review:** Recommend that the user review the images themselves to confirm alt text accuracy, as AI-generated descriptions may miss important nuances or context-specific details.

.claude/skills/docs-polish/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: docs-polish
-description: Proofreads a single documentation page and improves clarity, readability, and word choice without changing meaning or reorganizing structure. Simplifies complex sentences, applies style guide standards, and converts passive voice to active voice. Use when the user wants to polish, improve language and clarity, make more readable, check style guide compliance, or clean up documentation while preserving its structure.
+description: Applies style guide standards to a documentation page without changing meaning or reorganizing structure. This includes fixing grammar, improving clarity and readability, simplifying complex sentences, using active voice, and standardizing terminology and formatting. Use when the user wants to polish, check style guide compliance, improve language, or clean up documentation while preserving its structure.
 user-invocable: true
 disable-model-invocation: false
 ---
 
-> **Skill progression:** This does everything `/docs-proofread` does plus clarity improvements and style guide enforcement. If only grammar and spelling fixes are needed, use `/docs-proofread`. For deeper reorganization, suggest `/docs-enhance`.
+> **Skill progression:** This does everything `/docs-proofread` does plus style guide enforcement including clarity improvements. If only grammar and spelling fixes are needed, use `/docs-proofread`. For deeper reorganization, suggest `/docs-enhance`. If missing alt text is found, suggest `/docs-alt-text`.
 
 Improve clarity and readability without changing meaning, structure, or paragraph order:
 
 **docs-polish should**:
 * Read Mendix style guides first (in parallel): `grammar-formatting.md`, `terminology.md`, and `product-naming-guide.md` from `/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/`
 * Fix all spelling, grammar, and punctuation errors
-* Add missing alt text to images (use simple, factual descriptions)
+* Check all figure shortcodes for missing alt text. If the alt text parameter is missing, insert `alt=""` as a placeholder.
 * Ensure required front matter fields are present (title, url, description) and make descriptions concise and action-oriented
 * Fix broken Markdown syntax
 * Fix capitalization and terminology inconsistencies
@@ -24,10 +24,15 @@ Improve clarity and readability without changing meaning, structure, or paragrap
 * Apply Mendix style guide standards (overrides the Microsoft Writing Style Guide)
 * Apply Microsoft Writing Style Guide standards, unless they conflict with the Mendix style guide standards
 
+**After completing edits**:
+* Report what was changed in a concise summary
+* If any images were found with missing or empty alt text, state "I found [N] image(s) with missing alt text. Consider running `/docs-alt-text` to generate alt text."
+
 **docs-polish should NOT**:
 * Move paragraphs or restructure sections (that's `/docs-enhance`)
 * Change technical meaning or accuracy
 * Significantly increase document length
+* Generate alt text for images
 * Change command syntax, code identifiers, variable names, placeholders, or any other text that appears in code formatting (inline backticks or code blocks). Code-formatted text represents literal technical content that must remain unchanged. If you notice an issue with code-formatted text, flag it in the chat but don't edit it directly.
 
 Every edit should serve a clear purpose in making the text easier to read, scan, and understand.

content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md

@@ -51,11 +51,12 @@ Do not modify `.claude/settings.json` or other files in the `.claude/` directory
 This repository includes custom Claude Code skills optimized for documentation work:
 
 * `/docs-proofread` - Checks spelling, grammar, punctuation, and basic Markdown formatting
-* `/docs-polish` - Improves clarity, readability, and word choice without changing meaning
+* `/docs-polish` - Applies the Mendix style guide and improves clarity, readability, and word choice without changing meaning
 * `/docs-enhance` - Performs comprehensive editing including reorganization, restructuring, and stronger phrasing
-* `/docs-review` - Analyzes documentation and generates suggestions for improvements
 * `/docs-add` - Adds new content to an existing page while preserving original structure
-* `/docs-pr-review` - Reviews all changes in the PR rather than just a single document
+* `/docs-review` - Analyzes a page and generates suggestions for improvements without making any edits
+* `/docs-pr-review` - Reviews all changes in a PR rather than just a single document
+* `/docs-alt-text` - Suggests W3C-compliant alt text for images on a page
 
 These skills are available to all contributors using Claude Code with this repository.