Skip to content

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. Add searchable terms that describe meaning rather than appearance. 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.

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 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.