Contributing icon changes

A successful icon change solves a specific interface problem while still looking like part of the TYPO3 set. Work from the source SVG, use the established construction rules and validate the generated asset in context before opening a pull request.

Visual language

Search the library before drawing. An existing identifier may already express the intended action, object or status, and reusing it keeps interfaces predictable. If an existing drawing needs refinement, preserve its identifier unless the meaning itself changes; identifiers are an API used by TYPO3 Core and extensions.

Compare nearby icons in the same category, then read the relevant guidance for action and overlay icons or module icons. The canvas, protective space, stroke weight and use of currentColor should be deliberate rather than corrected after export.

Edit the source, not the output

Source SVGs live under src/<category>/<identifier>.svg. The folder places the icon in its category and the filename becomes its public identifier. Files under dist/ are generated by the icon build and must not be treated as the authoring source.

Keep SVG markup small and portable. Use the correct viewBox, avoid embedded raster images and editor-specific metadata, and use currentColor where the icon should inherit its context. Module accent elements follow the dedicated module-icon guidance.

Metadata and compatibility

Matching YAML files under meta/<category>/ hold aliases, tags and version history. When an identifier replaces an older name, an alias can preserve discovery and compatibility; do not remove an identifier casually once it has shipped.

Version history is generated from Git tags. Review it as release data, not as a substitute for the commit history. Compatibility across TYPO3 branches depends on the package version in which the identifier first appears.

Tags

Tags are what the search finds an icon by, next to its identifier and its aliases. Every word of a query has to appear in one of them, so a tag is only useful if it is a word somebody would type when looking for the icon. Give every icon three to eight tags, drawn from three kinds:

What the icon depicts: trash can, clock, flag, chain.
What it stands for in TYPO3, in TYPO3's own terms: deleted records, scheduler task, page tree, backend layout.
Synonyms people type for the same thing: delete and remove, settings and configuration.

Write tags in English and in lowercase. A phrase such as broken link is a single tag. Leave out words the identifier already contains; it is searched anyway. Use the same words as the icons around it for the same concept, so a search for delete finds every icon that deletes. npm run verify checks the count, the case and the words of the identifier, and CI runs it on every push.

alias: []
tags:
  - trash
  - bin
  - deleted records
  - restore
  - undelete

Build and inspect the result

Install dependencies once, then rebuild the distributed icon assets:

npm ci
npm run icons-build

Build the site when the generated preview matters to the review. Inspect the normal, disabled and inverse contexts supported by the category, and judge the icon at its real rendered size—not only enlarged in an SVG editor.

npm run site-build
npm run site-serve

Pull-request checklist

The identifier and category describe the icon's meaning.
The metadata file carries three to eight tags that follow the tag rules.
The SVG follows the correct grid and remains legible at its intended size.
Colors and directionality behave correctly in supported contexts.
Generated assets were rebuilt and inspected.
The pull request explains the interface need and includes useful previews.