Skip to content

netresearch/typo3-docs-skill / skills/typo3-docs

typo3-docs

Flagged

Use when TYPO3 extension documentation has to render on docs.typo3.org, which builds a manual from Documentation/guides.xml and reads no Settings.cfg (a single README.rst serves an extension too small for one): when an extension has no documentation yet, or when creating, editing or reviewing Documentation/*.rst, guides.xml, README.md or XLF translations, rendering docs with Docker, TYPO3 RST directives, screenshots, or XLIFF 2-space indentation (TYPO3 v14+).

FileKindSize
SKILL.mdskill md5.9 KB
assets/AGENTS.mdmarkdown11.7 KB
assets/guides.xml.distother1.8 KB
checkpoints.yamlconfig43.1 KB
evals/evals.jsonconfig23.1 KB
references/architecture-decision-records.mdmarkdown6.6 KB
references/asset-templates-guide.mdmarkdown2.8 KB
references/canonical-sources.mdmarkdown6.2 KB
references/code-structure-elements.mdmarkdown7.4 KB
references/coding-guidelines.mdmarkdown7.1 KB
references/content-directives.mdmarkdown7.6 KB
references/documentation-coverage-analysis.mdmarkdown7.6 KB
references/documentation-quality-checks.mdmarkdown3.5 KB
references/extraction-patterns.mdmarkdown23.3 KB
references/file-structure.mdmarkdown7.0 KB
references/guides-xml.mdmarkdown15.9 KB
references/intercept-deployment.mdmarkdown12.5 KB
references/render-guides-development.mdmarkdown8.8 KB
references/rendering.mdmarkdown17.3 KB
references/rst-syntax.mdmarkdown10.5 KB
references/screenshots.mdmarkdown13.1 KB
references/scripts-guide.mdmarkdown3.1 KB
references/text-roles-inline-code.mdmarkdown2.5 KB
references/typo3-directives.mdmarkdown16.0 KB
references/typo3-extension-architecture.mdmarkdown17.4 KB
references/upstream-docs-contribution.mdmarkdown7.5 KB
scripts/add-agents-md.shexecutablescript2.2 KB
scripts/analyze-docs.shexecutablescript12.0 KB
scripts/check-adr-coverage.shexecutablescript778 B
scripts/check-changelog-version-coverage.shexecutablescript1.7 KB
scripts/check-confval-completeness.shexecutablescript2.1 KB
scripts/check-guides-xml-schema.shexecutablescript4.0 KB
scripts/check-guides-xml-version-sync.shexecutablescript1.9 KB
scripts/check-required-doc-sections.shexecutablescript1.6 KB
scripts/check-rst-substitutions-resolve.shexecutablescript5.4 KB
scripts/check-screenshot-freshness.shexecutablescript2.5 KB
scripts/check-settings-documented.shexecutablescript1.5 KB
scripts/check-ui-surface-screenshots.shexecutablescript2.8 KB
scripts/check-untranslated-fluid-strings.shexecutablescript1.6 KB
scripts/check-version-match.shexecutablescript624 B
scripts/extract-all.shexecutablescript4.1 KB
scripts/extract-build-configs.shexecutablescript2.8 KB
scripts/extract-composer.shexecutablescript1.9 KB
scripts/extract-extension-config.shexecutablescript5.0 KB
scripts/extract-php.shexecutablescript5.1 KB
scripts/extract-project-files.shexecutablescript2.0 KB
scripts/extract-repo-metadata.shexecutablescript4.7 KB
scripts/extraction-dir.shexecutablescript1.7 KB
scripts/json-string.shscript921 B
scripts/render_docs.shexecutablescript1.0 KB
scripts/validate_docs.shexecutablescript6.2 KB
scripts/validate_headings.pyexecutablescript4.4 KB

references/screenshots.md

View on GitHub
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->

# Screenshots Reference

Creating and inserting screenshots in TYPO3 documentation. Canonical source:
[Guidelines for images](https://docs.typo3.org/permalink/h2document:guidelines-for-images)
`[upstream]` — on conflict the live manual wins.

**Read the canonical page for the rules themselves**: when a screenshot is
necessary, the accepted formats, the 1400 × 1050 target, the ≥1440 capture
viewport, and the backend `iframe`/`fullPage` behaviour are all stated there.
The last two arrived upstream on 2026-08-15 and were `[regression]` knowledge
here until then. What this file keeps is what upstream does not give you: which
subjects are worth a screenshot at all, the executable recipe, the NR
deviations, and the tell that says you got it wrong.

## When to Add Screenshots

Upstream states the necessity rule; the two lists below are this skill's
judgement about which subjects earn one.

### Screenshots ARE Appropriate For

- **Backend module interfaces** - Show where to find settings
- **Configuration screens** - Extension configuration, site settings
- **Complex UI workflows** - Multi-step processes that are hard to describe
- **Form configurations** - TCA forms, FlexForm settings
- **Visual results** - Frontend output that demonstrates a feature
- **Error messages** - Help users identify specific error states

### Screenshots Are NOT Needed For

- Simple button clicks or menu selections (use `:guilabel:` instead)
- Code that can be shown in code blocks
- Standard TYPO3 interfaces that haven't changed
- Information easily conveyed in text

## Image Requirements

Formats and dimensions are `[upstream]` — PNG or AVIF for bitmaps, SVG for
vector graphics, 1400 × 1050 for a full page. Only the deviation is ours:

| Deviation | Rule |
|---|---|
| Screenshot format | PNG **preferred** for consistency across NR extensions; AVIF is allowed upstream and stays allowed here `[NR policy]` (soft) |

Crop to the relevant portion rather than shipping a whole page — as small as
practical while the surrounding context is still recognisable.

### Capture Viewport

The rules are `[upstream]`; this is how to execute them.

```js
// Playwright (the Playwright MCP exposes this as browser_resize, same dimensions)
await page.setViewportSize({ width: 1440, height: 1050 });
```

Don't shrink the window to crop — crop the captured file.

For a tall module view (a config form *and* its result in one shot), raise the
viewport height rather than reaching for `fullPage`:

```js
// Capture config + output together: tall viewport, NOT fullPage.
await page.setViewportSize({ width: 1440, height: 1750 });
await page.screenshot({ path: 'Documentation/Images/Usage/ModuleRun.png' }); // no fullPage
```

**The tell:** measure the result afterwards. A file exactly as tall as the
viewport you set — 1050 px from the first recipe, where the second was meant to
give you 1750 — means the capture stopped at the outer frame and the module's
lower content is missing. Upstream states the behaviour; the height check is
what tells you it happened to *this* screenshot, and it is the reason the
mistake was ever noticed.

### File Location `[NR policy]`

Store images under `Documentation/Images/`, organized by section
(`Images/Configuration/…`, `Images/Usage/…`, CamelCase filenames). Note:
upstream examples use `/_Images/`; both work — this skill deliberately picks
`Documentation/Images/` for consistency across NR extensions (checkpoint
TD-12).

## TYPO3 Backend Setup and Screenshot Container

Backend settings (light mode, modern look, default installation on a
Composer-based latest LTS or dev-main, `j.doe` user) and the
`linawolf/typo3-screenshots` container incl. extension installation and
reset:
[Guidelines for images](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Advanced/GuidelinesForImages.html)
and
[Screenshot container](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ScreenshotContainer/Index.html)
`[upstream]`.

## RST Image Directives, CSS Classes, Zoom

`image`/`figure` syntax (`:alt:` required; `:width:`, `:scale:`, `:class:`,
`:align:`, `:target:`), the theme CSS classes (`with-shadow`, `with-border`,
`float-left`, `float-right`) and the four zoom modes (`lightbox`, `gallery`,
`inline`, `lens` with `:gallery:`, `:zoom-indicator:`, `:zoom-factor:`,
render-guides 0.36.0+, keyboard/ARIA/reduced-motion support):
[Images](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Graphics/Images.html)
and
[Image zoom](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Graphics/ImageZoom.html)
`[upstream]`. House default (`[NR policy]`): `:zoom: lightbox` +
`:class: with-border with-shadow` on screenshots.

## Annotations

When annotating screenshots with boxes, arrows, or numbers:

### Contrast Requirements

Use sufficient contrast to ensure annotations are visible:
- Across different devices and screens
- For readers with color vision differences
- Against varying background colors in the screenshot

### Recommended Annotation Colors `[NR policy]`

House palette — not a TYPO3 convention (the manual prescribes no annotation
colors; `#FF8700` is the TYPO3 brand orange used by choice):

| Element | Color | Hex |
|---------|-------|-----|
| Highlight boxes | TYPO3 brand orange | `#FF8700` |
| Arrows/lines | Dark gray | `#333333` |
| Numbers/labels | White on dark background | `#FFFFFF` on `#333333` |

### Annotation Tools

- **macOS**: Preview, Skitch, CleanShot X
- **Windows**: Snagit, Greenshot, ShareX
- **Linux**: Flameshot, Shutter
- **Cross-platform**: GIMP, Inkscape (for SVG)

## Alt Text Guidelines

Alt text is **required** for all images. Write descriptive alt text that:

1. **Describes what the image shows** - Not just "screenshot"
2. **Includes key information visible in the image** - Field names, values shown
3. **Is concise but complete** - Typically 10-30 words

### Examples

```rst
.. Bad alt text:
.. image:: screenshot.png
   :alt: Screenshot

.. Good alt text:
.. image:: /Images/Configuration/VaultSettings.png
   :alt: Extension configuration showing Master Key Path field set to /var/secrets/master.key
```

## Suggesting Screenshots in Documentation

When writing documentation, suggest screenshots for:

1. **New features** - Visual introduction helps users understand
2. **Configuration screens** - Show where settings are located
3. **Complex workflows** - Multi-step processes benefit from visuals
4. **Before/after comparisons** - Show the result of configuration changes
5. **Error states** - Help users identify problems

### Template Comment for Missing Screenshots

```rst
.. todo::
   Add screenshot of the backend module showing the secret list view.
   Dimensions: 1400x1050 or cropped to relevant area.
   Settings: Light mode, j.doe user, clean installation.
```

## Pre-Commit Checklist for Screenshots

1. ✅ **Format**: PNG (or AVIF) for all screenshots
2. ✅ **Dimensions**: 1400x1050 or appropriately cropped
3. ✅ **Backend setup**: Light mode, modern look, j.doe user
4. ✅ **Alt text**: Descriptive alt text provided
5. ✅ **File location**: Stored in `Documentation/Images/` with proper organization
6. ✅ **File naming**: CamelCase, descriptive names (e.g., `ExtensionSettings.png`)
7. ✅ **Annotations**: Sufficient contrast for accessibility
8. ✅ **Necessity**: Screenshot genuinely adds value vs. text description

## Diagrams: commit SVG, not PNG

A screenshot records a UI you do not control. A **diagram** is authored, and the
tradeoffs are the opposite ones.

Commit diagrams as SVG:

- It is text, so a reviewer sees the change in the diff instead of a binary
  blob swap. A wrong label is caught in review rather than shipped.
- It scales, and the same file serves every viewport.
- No build step and no generator dependency for the SVG itself. Two distinct
  PlantUML facts, do not conflate them: a `.. code-block:: plantuml` is not a
  diagram — there is no `plantuml` *highlighter*, and every render emits
  `Language "plantuml" is not available to highlight code`. The `.. uml::`
  *directive* however IS officially rendered (PlantUML is integrated into the
  toolchain — see
  [Diagrams](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Graphics/Diagrams.html)).
  Hand-authored SVG remains preferable where reviewable diffs matter.

```rst
..  figure:: /Images/diagram-streaming-flow.svg
    :alt: Streaming: the prompt is screened, the budget is checked, and each
        chunk passes a redaction window before the Generator yields it.
    :class: with-border

    Request path down the left, chunk path back up the right.
```

`render-guides` copies referenced images to `Images/` in the output tree, not to
`_images/` — check there when verifying that a figure resolved:

```bash
docker run --rm --user $(id -u):$(id -g) -v "$(pwd)":/project -w /project \
  ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress
find Documentation-GENERATED-temp -name 'diagram-*.svg'
grep -oh 'diagram-[a-z-]*\.svg' Documentation-GENERATED-temp/**/*.html | sort -u
```

Two things worth doing while authoring:

- **Put an `aria-label` on the `<svg>` as well as the `:alt:` on the figure.**
  The `:alt:` serves the RST; the `aria-label` travels with the file if it is
  ever embedded elsewhere.
- **Trace the diagram against the code before drawing it.** A diagram is a claim
  about how the system works, and it ages exactly like a hand-maintained count.
  Drawing a CI pipeline from the workflow file rather than from memory is what
  surfaces that a required check never runs; drawing a streaming path from the
  service rather than from the feature description is what surfaces the
  redaction window nobody had documented.

**Open the render and read it — "the file exists" is not verification.** Three
defects in one set of eight diagrams were invisible in the source and in a file
listing, and each was found by looking at the output: an arrow leaving the wrong
box (a *skipped* task cannot *fail*), a heading centred vertically straight
through three hand-placed lines, and an arrow whose colour had no `<marker>`
defined — that one renders headless in a browser and crashes cairosvg, so a
browser check alone would have passed it.

**Measure text against its shape rather than eyeballing it.** Overflow is the
failure that survives review, because a diagram with one word poking out of a box
still looks like a diagram. In a browser, compare each `<text>` element's
`getBBox()` against the rect that should contain it:

```javascript
for (const t of svg.querySelectorAll('text')) {
  const b = t.getBBox();              // compare against the enclosing <rect>
  if (b.x + b.width > box.x + box.width) console.log('overflow:', t.textContent);
}
```

**And when that check reports nothing, make it fail once before believing it.**
Feed it a deliberately overlong string and watch it flag that. A detector that
finds nothing because it is broken is indistinguishable from a clean result — the
same reason a `grep` returning `0` is first a suspect query, not a finding.

**If the SVGs are generated, prove the committed file is what the generator
emits.** Re-run it over a clean checkout and require `git status --porcelain` to
be empty. Otherwise the script has quietly stopped being the source and the next
person edits the one that is not read.

Keep light-on-dark legibility in mind: a page is rendered in both themes, and an
`<img>` does not inherit `currentColor`. A neutral card with explicit fills
reads acceptably on both; a diagram drawn in pure black on transparent does not.

## References

- **Guidelines for Images:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Advanced/GuidelinesForImages.html
- **Screenshot Container:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ScreenshotContainer/Index.html

## Theme-change screenshots (render-guides): file:// is unstyled, control the comparison

- The rendered output links `theme.css` with `crossorigin="anonymous"` — Chrome **blocks the stylesheet under `file://`** (CORS), so a `file://` screenshot is completely unstyled. Serve the output over HTTP (`python3 -m http.server`) and shoot `http://localhost:…`.
- For a true before/after on CSS-only changes, reuse the SAME output HTML and swap in the old stylesheet (`git show origin/main:…/theme.css`) — the HTML doesn't change. Neutralize sticky/fixed nav before element shots (`position: static`).
- The theme CSS is a **committed build artifact** (`npm run build` in `packages/typo3-docs-theme`, or `npm run build:css` for the stylesheet alone → `resources/public/css/theme.css`) — rebuild it in the same commit as the SCSS change; CI's `check-built-assets` fails when the committed output differs from a fresh build. Keep the diff surgical (`git diff --stat`).
- Computed-style dumps flap on two non-differences: custom-property **enumeration order** (compare property→value dicts, never serialized strings) and load-timing noise (rerun the SAME variant twice; a property that flaps there is noise). Trust controlled pixel comparison — 12/12 pairs were 0-pixel identical while string dumps "differed".
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall