Typo3 Icon14

TYPO3 v14 Icon Modernizer

Source: https://github.com/dirnbauer/webconsulting-skills

Prefer live TYPO3 v14 references over bundled snapshots. Use the official Icon API

docs for registration rules and the TYPO3.Icons catalog for the current Core SVG

language. Use the local reference files only to keep this skill concise.

What this skill is for

Use this skill to:

• migrate legacy extension icons to TYPO3 v14
• design new custom icons that fit the TYPO3 v14 backend
• update Configuration/Icons.php and all icon consumers
• keep module, plugin, record, action, and extension icons distinct

Do not invent a second icon system for the extension. Work with the icon identifiers, file names, and render contexts that already exist in the codebase.

Workflow

1. Inventory existing icon files and registrations. 2. Classify each icon by type and render context. 3. Infer the icon meaning from module names, TCA, plugin config, and current SVGs. 4. If the meaning is still unclear, ask one focused question: what should this icon communicate? 5. Load live TYPO3 v14 references for the matching icon family. See references/live-sources.md. 6. Redraw or modernize the SVG in the correct TYPO3 v14 style. 7. Update Configuration/Icons.php and every iconIdentifier / pluginIcon / typeicon_classes consumer. 8. Verify the icon in its real backend context and clear TYPO3 cache plus browser local storage if the old SVG still appears.

Start With Meaning, Not Shapes

When the user asks for new icons, first capture or infer:

• which identifiers or files need to exist
• what each icon represents
• whether several icons should form a visual family
• whether one icon is the parent and others are sub-variants

If the repository already makes the meaning obvious, proceed without stopping. If not, ask for a short mapping such as:

• module-myext -> "main module for editorial planning"
• record-myext-campaign -> "campaign record"
• plugin-myext-list -> "frontend list plugin"

The user can describe usage, not geometry. Translate usage into icon semantics.

Source Of Truth

Use sources in this order:

1. Official TYPO3 Icon API docs for registration, providers, and migration: Icon API 2. Live TYPO3.Icons catalog for current Core SVG references: TYPO3.Icons 3. If the working TYPO3 instance has EXT:styleguide, inspect the real backend rendering there as a runtime check 4. Only fall back to local reference notes in this skill when live sources are unavailable

Prefer loading the current Core icons when needed. Do not ship copies of Core icons into an extension unless the user explicitly wants vendored assets or the environment is offline.

Respect The Icon Type

Always match the render size and visual density of the icon type you are editing. Do not force a 64x64 module composition into a 16x16 record or action icon.

Minimal TYPO3 v14 SVG Rules

• transparent background only
• primary geometry uses currentColor
• accent geometry uses var(--icon-color-accent, #ff8700)
• remove hardcoded white, black, gray, and legacy brand-color backgrounds
• keep markup minimal: xmlns plus viewBox only unless a provider truly needs more
• preserve the semantic shape from the existing icon whenever possible
• for module-* and Extension.svg: prefer strong silhouettes, a 4px stroke on the

64x64 canvas (renders 2px at 32x32), and .4 opacity for depth fills when needed

• for 16x16 icons: reduce details aggressively; two clear ideas beat five tiny ones

See references/design-notes.md for the visual rules and anti-patterns.

Light And Dark Mode Are Non-Negotiable

TYPO3 v14 ships auto / light / dark color scheme switching in the backend (introduced as a Core feature in v13.3, carried into v14). Every custom icon must render correctly in both schemes. There is no separate "dark icon" file — the same SVG is used.

The two CSS tokens that the Core ships on :root (from TYPO3.Icons/assets/scss/icons.scss) are:

:root {
    --icon-color-primary: currentColor;
    --icon-color-accent: #ff8700;
}

How to stay compatible with both schemes:

• Use currentColor (or var(--icon-color-primary, currentColor)) for the primary

silhouette. It inherits the surrounding text color, which flips automatically when the user switches color scheme.

• Use var(--icon-color-accent, #ff8700) for the accent. TYPO3 orange #ff8700 is the

same fallback in both schemes because orange has sufficient contrast on both light and dark backend surfaces. Do not replace it with a scheme-specific hex — themes that want a different accent override the CSS variable, not the fallback.

• Never hardcode fill="#000", fill="#333", fill="#fff", fill="white", or

fill="black". Any one of these vanishes on one of the two backgrounds.

• Never draw a solid background rectangle behind the icon. The backend surface color

must show through so the scheme flip works.

• Opacity-based depth (opacity=".4" on top of currentColor) is safe because the

base tone flips with the scheme.

• Do not depend on prefers-color-scheme media queries inside the SVG. The Core drives

the scheme via an attribute on the root element, and relying on prefers-color-scheme will miss manual switches from the User Settings dropdown.

Verify every icon in both schemes before shipping (see Verification below).

Registration Rules

Register icons in Configuration/Icons.php. TYPO3 v14 requires this and no longer allows registration in ext_localconf.php.

<?php

declare(strict_types=1);

use TYPO3\CMS\Core\Imaging\IconProvider\SvgIconProvider;

return [
    'module-myext' => [
        'provider' => SvgIconProvider::class,
        'source' => 'EXT:my_extension/Resources/Public/Icons/module-myext.svg',
    ],
    'record-myext-item' => [
        'provider' => SvgIconProvider::class,
        'source' => 'EXT:my_extension/Resources/Public/Icons/record-myext-item.svg',
    ],
];

Update every consumer after the SVG is in place:

• Configuration/Backend/Modules.php -> iconIdentifier
• Configuration/TCA/*.php -> typeicon_classes, iconIdentifier
• Configuration/TCA/Overrides/*.php -> pluginIcon, page-type or folder icons

The official docs state that icons must be registered in the icon registry through Configuration/Icons.php, and that registration in ext_localconf.php is no longer possible in TYPO3 v14.

Migration Behavior

When legacy SVGs already exist:

• keep the existing identifier unless a rename is required
• modernize the current shape before replacing it with a completely new metaphor
• keep file paths stable where possible to reduce config churn
• verify every updated icon against the icon type it belongs to

Use references/migration-steps.md for the checklist.

Verification

Before finishing:

• verify the file path matches the registered source
• verify the icon type uses the correct viewBox
• verify there is no solid background layer
• verify all consumers point to the intended identifier
• verify the icon remains readable at its real render size
• verify the icon works in both light and dark backend schemes — switch via the

user dropdown at the top right or User Settings, and check the icon in its real render context (module menu, content wizard, list module, TCA icons)

• confirm no hardcoded #000, #333, #fff, white, or black fills remain
• clear TYPO3 caches and browser local storage if rendering looks stale

References

• references/live-sources.md: live TYPO3 v14 sources, catalog

URLs, and fetch patterns

• references/design-notes.md: visual rules, icon-family

guidance, and common mistakes

• references/migration-steps.md: migration checklist

Source: https://github.com/dirnbauer/webconsulting-skills

TYPO3 v14 Icon Design Notes

Core visual rules

• No background rectangle or full-canvas fill.
• Use currentColor for the primary geometry.
• Use var(--icon-color-accent, #ff8700) for accent geometry.
• Keep SVG markup minimal.
• Preserve the icon's meaning even when the drawing changes.

Light and dark mode

TYPO3 v14 backend supports auto / light / dark color schemes. The same SVG must work in both. The TYPO3.Icons package defines the tokens on :root as:

--icon-color-primary: currentColor;
--icon-color-accent: #ff8700;

Guidance:

• currentColor inherits the surrounding text color, so the silhouette flips with

the scheme automatically — this is why you must never hardcode black or white.

• #ff8700 (TYPO3 orange) stays the same in both schemes. Orange has sufficient

contrast against the light and dark backend surfaces. Do not introduce a second scheme-specific accent hex; theme authors override the CSS variable if they want a different color.

• Opacity-based depth layered on top of currentColor is safe.
• Do not rely on prefers-color-scheme media queries inside the SVG; the Core

drives the scheme via an attribute on the root element, and manual switches from User Settings would be missed.

Match the Core icon family

Pick references from the Core family that matches the job:

Custom extension icons should feel native to TYPO3 v14, but they should still represent the extension's own concepts. Do not copy a Core icon verbatim unless the extension is intentionally reusing the exact same meaning.

Module icon rules

Module icons render large in source SVG terms but small in the backend menu. Keep them simple:

• viewBox="0 0 64 64"
• strong silhouette
• 4px stroke width on the 64x64 canvas when using outlined shapes (renders 2px at 32x32)
• .4 opacity for depth fills when needed
• one clear accent strategy, not several competing accents

Accent strategies that work well:

1. background companion shape 2. inner detail 3. outer ring or border

Small icon rules

Plugin, record, and action icons usually render at 16px.

• Keep the viewBox consistent with the Core icon family you are matching.
• Remove tiny decorative details.
• Prefer one primary metaphor plus one accent at most.
• Avoid module-style multi-layer compositions in 16x16 icons.

Common mistakes

TYPO3 v14 Live Icon Sources

Use these live sources first when you need the current TYPO3 v14 icon language.

1. Official Icon API docs

Source: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Icon/Index.html

Use this for:

• Configuration/Icons.php
• allowed icon providers
• icon usage in PHP, Fluid, and JavaScript
• TYPO3 v14 migration rules away from ext_localconf.php

Key points from the docs:

• TYPO3 v14 requires custom icons to be registered in Configuration/Icons.php
• TYPO3 v14 no longer allows registering icons in ext_localconf.php
• TYPO3 Core icons can be browsed via the TYPO3.Icons catalog

2. TYPO3.Icons live catalog

Catalog root: https://typo3.github.io/TYPO3.Icons/

Category pages:

• module: https://typo3.github.io/TYPO3.Icons/icons/module.html
• actions: https://typo3.github.io/TYPO3.Icons/icons/actions.html
• content: https://typo3.github.io/TYPO3.Icons/icons/content.html
• default: https://typo3.github.io/TYPO3.Icons/icons/default.html
• apps: https://typo3.github.io/TYPO3.Icons/icons/apps.html
• mimetypes: https://typo3.github.io/TYPO3.Icons/icons/mimetypes.html
• overlay: https://typo3.github.io/TYPO3.Icons/icons/overlay.html
• status: https://typo3.github.io/TYPO3.Icons/icons/status.html

Use the matching category for the icon type you are designing. For example:

• module-* and Extension.svg -> module
• actions-* -> actions
• plugin-* -> usually content, default, or apps
• record-* -> usually default, apps, mimetypes, overlay, or status

3. Individual icon URL patterns

Preview page:

https://typo3.github.io/TYPO3.Icons/icons/{set}/{identifier}.html

Example:

https://typo3.github.io/TYPO3.Icons/icons/module/module-styleguide.html

Direct SVG download:

https://typo3.github.io/TYPO3.Icons/dist/svgs/{set}/{identifier}.svg

Example:

https://typo3.github.io/TYPO3.Icons/dist/svgs/module/module-styleguide.svg

Prefer the live catalog page first because it shows identifier, preview, inline markup, and download link together.

4. EXT:styleguide as runtime validation

If the working TYPO3 instance has EXT:styleguide, use it to validate how icons behave in the real backend theme and color scheme.

Use EXT:styleguide for:

• checking module-icon readability in the backend navigation
• checking how currentColor and --icon-color-accent behave in context
• validating that an icon family feels like TYPO3 v14 rather than an isolated SVG

Do not depend on EXT:styleguide as the only source of truth. The primary source for current Core icons is still TYPO3.Icons.

5. Local fallback

If the project already contains @typo3/icons, you can read the shipped SVGs directly from the package instead of fetching them from the web.

Typical local package path:

node_modules/@typo3/icons/dist/svgs/

Prefer this only when it already exists in the project or when network access is unavailable.

TYPO3 Icon Migration Checklist

Use this checklist when updating existing extension icons.

1. Inventory

• [ ] Read the current SVG files
• [ ] Read Configuration/Icons.php
• [ ] Read Configuration/Backend/Modules.php
• [ ] Read relevant TCA and TCA override files

2. Classify

• [ ] Assign every icon to one type: module, extension, plugin, record, or action
• [ ] Confirm the render context and expected viewBox
• [ ] Keep existing identifiers unless there is a good reason to rename them

3. Capture meaning

• [ ] Infer the semantic meaning from module names, record names, plugin names, and old SVGs
• [ ] If the meaning is not obvious, ask the user what the icon should communicate
• [ ] For icon families, note which icon is the parent and which are sub-variants

4. Load references

• [ ] Load the matching live Core icon family from TYPO3.Icons
• [ ] Check the official Icon API docs for registration details
• [ ] If available, validate the look in EXT:styleguide

5. Redraw

• [ ] Remove solid legacy backgrounds
• [ ] Replace hardcoded white/black/gray with currentColor
• [ ] Use var(--icon-color-accent, #ff8700) for accent geometry
• [ ] Confirm no #fff, #000, #333, white, or black fills remain
• [ ] Simplify shapes until they are readable at the real render size
• [ ] Keep module icons and 16x16 icons visually appropriate for their type

6. Register and wire up

• [ ] Register the icon in Configuration/Icons.php
• [ ] Update iconIdentifier in Configuration/Backend/Modules.php if needed
• [ ] Update pluginIcon, typeicon_classes, and related references
• [ ] Remove legacy registration from ext_localconf.php

7. Verify

• [ ] Confirm the SVG file path matches the registered source
• [ ] Confirm the icon has the intended viewBox
• [ ] Confirm the icon is readable in its real backend context
• [ ] Switch the backend color scheme and confirm the icon works in both

light and dark mode (top-right user dropdown or User Settings)

• [ ] Clear TYPO3 caches and browser local storage if stale icons still appear