Add taking-screenshots skill for standardized documentation screenshots (#333)

This skill provides guidance for taking and updating UI screenshots across Auth0 documentation sites (main, auth4genai, ui) with consistent viewport settings, file paths, Playwright MCP usage, and accessible alt text.

Author: btiernay

.claude/skills/taking-screenshots/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: taking-screenshots
+description: Provides a consistent, reproducible workflow for creating, updating, and maintaining screenshots in the Auth0 docs-v2 monorepo. Use when capturing or modifying screenshots for Mintlify pages, Auth0 Dashboard interfaces, or UI surfaces within main, auth4genai, or ui. Ensures correct formatting, accessibility, alt text, paths, viewport, file size, cropping rules, and Playwright MCP usage.
+---
+
+# Taking screenshots for docs-v2
+
+Use this skill when capturing or updating screenshots that will be committed to `docs-v2`. It defines when screenshots add value, how they must be formatted, how to capture them reproducibly, where to store them, and how to handle alt text and accessibility.
+
+## When to use
+
+Use this skill when:
+
+- A screenshot helps clarify a complex UI step or validates that the reader is in the correct place.
+- A UI region has multiple interdependent settings and is hard to describe concisely in text.
+- A Mintlify preview or Auth0 Dashboard interface needs visual confirmation to reduce ambiguity.
+- An existing screenshot in `docs-v2` is out of date due to UI changes.
+
+## When NOT to use
+
+Do not use this skill for:
+
+- Conceptual diagrams, flowcharts, or visuals that should be vector graphics.
+- Decorative or aesthetic images.
+- One off internal exploration screenshots that will not be committed to `docs-v2`.
+- Third party applications or websites.
+- Cases where clear text instructions are enough and the screenshot would only duplicate the text.
+
+## Standard workflow
+
+For most tasks, follow this workflow. Only open reference files if you need additional detail.
+
+1. Decide if the screenshot is additive
+    - Confirm that the screenshot will reduce ambiguity or cognitive load, not just restate the text.
+    - Users must still be able to complete tasks using text alone.
+
+2. Reach the correct UI state
+    - Open the right Mintlify preview or Auth0 Dashboard view.
+    - Reproduce the exact page, tab, filters, and selections described in the doc.
+    - Use safe, generic, non sensitive values.
+
+3. Use a stable viewport and browser
+    - Use Chrome.
+    - Use a viewport of `1200 × 900`.
+    - Do not include browser chrome, URL bar, tabs, or OS UI.
+    - No device emulation unless explicitly required.
+
+4. Stabilize the UI
+    - Wait for loading indicators, skeletons, and animations to finish.
+    - Dismiss banners, toasts, or modals unless they are part of the documented behavior.
+    - Confirm that visible labels match the current UI text.
+
+5. Capture a focused region
+    - Capture only the relevant panel, section, or modal, plus minimal surrounding context to confirm location.
+    - Avoid full dashboard windows and unnecessary whitespace.
+    - For modals, capture only the modal, not the background.
+
+6. Apply required formatting
+    - Add a `1px` centered border with color `#CCCCCC`.
+    - Do not add shadows or decorative effects.
+    - Use highlight color `#0099CC` only when it clarifies a specific control or region.
+    - Capture at `1200px` width, keep outputs at no more than `1500px`.
+    - Use PNG format for screenshots.
+
+7. Save and name the file
+    - Use the appropriate path for the workspace (main, auth4genai, or ui).
+    - Use lowercase, hyphen separated, descriptive filenames.
+    - Do not include dates, version numbers, or author initials.
+
+8. Provide alt text and verify
+    - Write concise, purpose driven alt text that describes the UI state and product area, not the image mechanics.
+    - Confirm there are no sensitive values.
+    - Make sure the page text does not depend on the screenshot as the only source of information.
+
+9. Prefer Playwright MCP when possible
+    - For reproducible captures, use Playwright MCP to open the preview, reach the correct state, and take an element screenshot that follows the same viewport and formatting rules.
+
+## Quick reference
+
+| Task | Reference |
+|------|-----------|
+| Detailed inclusion and alt text rules | [reference/alt-text-and-accessibility.md](reference/alt-text-and-accessibility.md) |
+| Full capture and formatting workflow | [reference/screenshot-workflow.md](reference/screenshot-workflow.md) |
+| Deterministic captures using Playwright MCP | [reference/playwright-mcp-usage.md](reference/playwright-mcp-usage.md) |
+| Repo paths and filename patterns | [reference/repo-paths-and-filenames.md](reference/repo-paths-and-filenames.md) |
+| Auth0 Dashboard specifics | [reference/dashboard-sources.md](reference/dashboard-sources.md) |
+
+## Common mistakes
+
+| Mistake | Fix |
+|--------|-----|
+| Including browser chrome or OS UI | Capture only the app region in a `1200 × 900` viewport |
+| Using screenshots where text is sufficient | Replace the screenshot with clear step by step instructions |
+| Using screenshots of third party UIs | Remove or replace with text, unless explicitly approved and necessary |
+| Out of date UI labels | Recapture the screenshot and update surrounding text to match |
+| Missing or generic alt text | Write concise, task oriented alt text that names the product area and view |
+| Including loaders, transient modals, or toasts | Wait for a stable UI state before capture |

.claude/skills/taking-screenshots/reference/alt-text-and-accessibility.md

@@ -0,0 +1,76 @@
+# Screenshot inclusion and accessibility
+
+This file defines when screenshots should be included, how to minimize accessibility and localization burden, and how to write alt text. For basic decisions, see `SKILL.md`. Use this file when you need more detailed guidance or examples.
+
+## 1. When screenshots add value
+
+Include a screenshot when it does at least one of the following:
+
+- Reassures the user that they are in the correct UI location.
+- Calls attention to a specific region or control within a complex UI.
+- Supports an example that is hard to visualize from text alone.
+- Shows a configuration screen with multiple interdependent settings.
+- Serves as a first interface verification screenshot for a new section or product area.
+
+Use an additive approach. The screenshot should reduce ambiguity or cognitive load, not just repeat the text.
+
+## 2. When NOT to include screenshots
+
+Avoid screenshots when:
+
+- Text instructions alone can fully convey the step without confusion.
+- The screenshot provides no additional technical information beyond what is already described.
+- The user is likely to have the application open beside the docs and can see the referenced UI directly.
+- The screenshot is used mainly as decoration or to break up long text.
+- It duplicates exactly what is described in text, especially step by step instructions.
+- It tries to verify every small step instead of the overall state.
+- The UI changes frequently, making it hard to keep screenshots accurate.
+
+Screenshots can slow reading, may confuse users if mistaken for live UI, and increase maintenance cost.
+
+## 3. Accessibility considerations
+
+- Every screenshot requires alt text.
+- Alt text must stay in sync with the image and with the current UI.
+- Localization multiplies maintenance cost for both image and text.
+- Screenshots should never be the only source of information for a task.
+- Users with disabilities must be able to complete tasks using text alone.
+
+Design the doc so that removing the screenshot would not prevent a user from succeeding.
+
+## 4. Localization considerations
+
+- Each screenshot adds translation overhead.
+- Alt text must be translated along with the rest of the content.
+- Avoid embedding critical text inside images. When possible, rely on UI labels and body text instead of annotations rendered into the screenshot.
+
+Only introduce new screenshots when they clearly improve comprehension enough to justify ongoing translation cost.
+
+## 5. Alt text rules
+
+Alt text must:
+
+- Describe the purpose of the screenshot and the UI state, not the image itself.
+- Indicate product area and UI section.
+- Use sentence case.
+- Use Auth0 terminology accurately and consistently.
+
+Good examples:
+
+- `Auth0 Dashboard Application Settings view showing Allowed Callback URLs field`
+- `Auth0 Tenant Settings General tab with support email, logo, and session settings`
+- `Docs UI quickstart card grid on the Get Started page`
+
+Avoid:
+
+- Generic text such as `screenshot` or `image of the UI`.
+- Repeating captions or surrounding body text word for word.
+- Describing every visual detail or pixel level layout.
+
+## 6. Information placement
+
+- Body text explains what the user must do and why.
+- The screenshot clarifies or validates a complex UI state or set of controls.
+- Alt text provides a brief textual stand in for the screenshot.
+
+If a step references content that appears only in the screenshot, move that information into the body text so that screen reader users and translated versions are not dependent on the image alone.

.claude/skills/taking-screenshots/reference/dashboard-sources.md

@@ -0,0 +1,52 @@
+# Auth0 Dashboard sources
+
+Use this file when you need more detail about Auth0 Dashboard views. For general workflow and formatting, see `reference/screenshot-workflow.md`.
+
+### Navigation clarity in text
+
+In the documentation text:
+
+- State the full navigation path in terms of the Dashboard hierarchy.
+- For example: `Auth0 Dashboard > Applications > Applications > Settings`.
+
+This ensures users can reach the correct view even without the screenshot.
+
+### Navigation clarity in screenshots
+
+In the screenshot:
+
+- Include only enough UI context to confirm the location, such as a panel title or breadcrumb.
+- Crop out:
+    - Browser window and chrome.
+    - Top navigation bar, unless it is directly relevant to the step.
+    - Left navigation bar, unless the doc is explicitly about navigation.
+
+The goal is to show the configuration or state the user cares about, plus minimal context to prove they are in the right place.
+
+### Data hygiene
+
+Use non sensitive values:
+
+- Example tenant names instead of production tenant identifiers.
+- Generic application names.
+- Fake email addresses such as `user@example.com`.
+
+Avoid:
+
+- Real user data.
+- Internal tenant names or identifiers.
+- Secrets, tokens, or internal URLs.
+
+### UI consistency
+
+- Use exact UI label text in both screenshots and body text.
+- If UI copy changes, update the screenshot and adjust the surrounding text to match.
+- Avoid highlighting controls that are not referenced in the instructions.
+
+## Third party UIs
+
+- Avoid screenshots of third party applications or websites whenever possible.
+- Do not include external branding, user data, or proprietary UI unless there is a specific approval and requirement.
+- Prefer concise text descriptions or vector diagrams for third party interactions.
+
+If a third party screenshot is unavoidable, treat it as an exception and follow internal review processes before adding it to `docs-v2`.

.claude/skills/taking-screenshots/reference/playwright-mcp-usage.md

@@ -0,0 +1,78 @@
+# Using Playwright MCP for deterministic screenshots
+
+Use Playwright MCP when you need consistent, reproducible captures or when UI states are hard to reach manually. It reuses the same viewport and formatting rules defined in `reference/screenshot-workflow.md`.
+
+## 1. Start the correct dev server
+
+Run the appropriate dev server:
+
+- In `main/`: `mint dev`
+- In `auth4genai/`: `mint dev`
+- In `ui/`: `npm run dev`
+
+Use the preview URL from the console output. Do not hardcode localhost ports if they can change.
+
+## 2. Apply the standard viewport
+
+When launching the browser in Playwright MCP:
+
+- Use the standard viewport `1200 × 900`.
+- Do not resize the window manually after launch.
+- Do not include browser chrome or OS UI in screenshots.
+
+Follow all cropping and formatting rules from `reference/screenshot-workflow.md`.
+
+## 3. Wait for stable selectors
+
+Before taking a screenshot:
+
+- Choose selectors that appear only when the main content is fully loaded.
+- Prefer selectors that represent the primary content region, not transient placeholders.
+- Avoid selectors that match skeleton states, loading spinners, or transient banners.
+
+Examples of good selectors:
+
+- Main content containers
+- Stable header or breadcrumb elements that exist only after load
+- Key form sections for configuration pages
+
+## 4. Interact to reach the documented state
+
+Use Playwright interactions to reach the UI state described in the doc:
+
+- Click tabs, accordions, and toggles.
+- Apply filters or sorting.
+- Scroll to the relevant section.
+
+If the path to reach the state is non obvious, describe it briefly in the PR description so others can reproduce it.
+
+## 5. Capture the screenshot
+
+Prefer element screenshots:
+
+- Take an element screenshot of the main content region or specific panel you are documenting.
+- Use full viewport screenshots only when necessary, for example when showing page level layout that is relevant to the doc.
+
+Save screenshots using repo relative paths:
+
+- `auth4genai/img/...`
+- `main/docs/img/...`
+- `main/docs/images/...`
+- `ui/src/assets/screenshots/...`
+- `ui/public/screenshots/...`
+
+File naming and formatting must follow the rules in:
+
+- `reference/repo-paths-and-filenames.md`
+- `reference/screenshot-workflow.md`
+
+## 6. Inspect and iterate
+
+After capture:
+
+- Verify the screenshot matches the state described in the doc.
+- Confirm no transient UI, loaders, or toasts are visible.
+- Check that the element boundaries provide enough context without extra noise.
+- Re capture if cropping, whitespace, or context is insufficient.
+
+When you find a stable selector and pattern that works well, keep using it for future captures of the same page to minimize visual drift over time.

.claude/skills/taking-screenshots/reference/repo-paths-and-filenames.md

@@ -0,0 +1,70 @@
+# Repo paths and filenames
+
+Use this file as the single source of truth for screenshot locations and naming patterns. Other docs only refer to it.
+
+## Auth0 for AI docs (`auth4genai/`)
+
+Store shared screenshots in:
+
+- `auth4genai/img/...`
+
+Group by site structure when helpful:
+
+- `auth4genai/img/get-started/...`
+- `auth4genai/img/how-tos/...`
+- `auth4genai/img/integrations/...`
+
+Use descriptive filenames, for example:
+
+- `auth4genai-user-authentication-login-screen.png`
+
+## Main docs (`main/docs/`)
+
+Use:
+
+- `main/docs/img/...` (preferred)
+- `main/docs/images/...` (when that pattern is already used nearby)
+
+Group by product area where possible:
+
+- `main/docs/img/authenticate/...`
+- `main/docs/img/manage-users/...`
+
+Examples:
+
+- `main/docs/img/authenticate/universal-login-settings.png`
+
+## UI workspace (`ui/`)
+
+Use:
+
+- `ui/src/assets/screenshots/...` for bundled assets
+- `ui/public/screenshots/...` for static assets
+
+Examples:
+
+- `ui/src/assets/screenshots/pr-template-preview.png`
+
+## File naming rules
+
+- Lowercase only.
+- Hyphen separated.
+- Descriptive of purpose and UI area.
+
+Patterns:
+
+- `[product]-[area]-[view-state].png`
+- `[site]-[section]-[focus].png`
+
+Avoid:
+
+- Generic names such as `image1.png` or `screenshot.png`.
+- Dates or version numbers.
+- Author initials or personal tags.
+
+## Format
+
+- PNG for screenshots.
+- SVG only for logos or icons, not for UI screenshots.
+
+If you need to replace an existing image with a new version, keep the filename and path the same whenever possible so that existing references remain valid.