---
name: typo3-astryx
description: Use when installing, configuring, extending, or styling the TYPO3 Astryx extension, including Content Blocks, Fluid components, StyleX tokens and recipes, themes, or consuming-site overrides. Pair with typo3-stylex for generic StyleX Connector and Vite setup or repair.
license: CC-BY-4.0
compatibility: For TYPO3 projects that use Astryx. Confirm the installed Astryx, TYPO3, PHP, StyleX Connector, and build-tool versions and constraints in the target project before changing or building anything.
---

# TYPO3 Astryx

## Outcome

Make a source-backed change to Astryx or the consuming TYPO3 project, with correct package ownership, configuration, StyleX source, asset entrypoint, and focused verification. This skill owns Astryx-specific decisions. Use the companion `typo3-stylex` skill for generic StyleX Connector and Vite pipeline installation, repair, and diagnostics.

## Workflow

1. **Discover the actual project and package boundaries.** Read applicable `AGENTS.md` and repository instructions. Find the Composer project root from its `composer.json` and lockfile; run Composer, TYPO3, and frontend commands from the root that owns those dependencies. Find the Astryx package by its Composer package name (`skom/typo3-astryx`) and confirm its actual source path and installed version. It may be a checked-out path repository, a package under `vendor/`, or another project-specific location.

   Find the consuming sitepackage or application package from the project's Composer repositories/installed packages and TYPO3 configuration, rather than inferring its name or location. A project may have multiple sitepackages or product packages. Use the one that owns the requested branding, templates, entrypoints, or Site Set activation. Keep extension-owned reusable behavior in Astryx and site/product-specific behavior in the actual consumer package.

   Read the manuals shipped with the installed Astryx version when present. Look for its Installation, Configuration, Styling, and CSS/entrypoint documentation under `<astryx-extension-root>/Documentation/`; exact filenames can vary by version. Inspect the package's `composer.json`, Site Set, entrypoint registry, build configuration, token registry, and relevant source when documentation is missing or disagrees with the code. Project-level design-system guidance is useful when present, but is not required for this workflow.

   Use these paths relative to `<astryx-extension-root>` as a discovery map; confirm each path against the actual package version:

   | Extension path | Responsibility |
   | --- | --- |
   | `Classes/` | Reusable PHP commands, configuration, data processors, and ViewHelpers |
   | `Configuration/Sets/` | Reusable Site Set settings, TypoScript, and Page TSconfig |
   | `Configuration/TCA/`, `Configuration/RTE/`, `Configuration/Fluid/` | TYPO3 editor fields, CKEditor presets, and native Fluid component registration |
   | `ContentBlocks/ContentElements/<name>/` | One block's configuration, frontend/backend templates, translations, published assets, and private source |
   | `Resources/Private/Components/`, `Partials/`, `Templates/`, `PageView/` | Native Fluid components and shared rendering structures |
   | `Resources/Private/JavaScript/StyleX/` | Shared token families, themes, and reusable recipes |
   | `Resources/Private/CSS/` | CSS entrypoints, generated bridges, and narrowly justified browser/editor CSS |
   | `Resources/Public/` | Generated distributable assets and manifests |
   | `Build/` | Token/theme bridge, build configuration, finite recipe contracts, and verifiers |
   | `Documentation/` | User and developer manuals |

   Completion: identify the Composer root, Astryx source/package root, relevant consumer package (if any), installed versions, active asset-delivery mode, and authoritative manual/source for the change.

2. **Install or configure Astryx using the target project's actual constraints.** Check the root Composer manifest and lockfile, installed package version, and Astryx package constraints before changing dependencies. Use the project's existing package manager, lockfiles, runtime and container workflow (for example DDEV only when the project uses it). Do not create a second `vendor/` or `node_modules/` inside the extension.

   Check the installed package metadata and installation manual for dependencies, supported TYPO3/PHP versions, Site Set identity, schema steps, and asset-delivery options; do not copy version requirements from another project or an older Astryx release. Activate the Astryx Site Set through the project's actual site configuration or sitepackage according to the manual, then apply schema changes and flush caches when required.

   Astryx releases may conflict with Fluid Styled Content (FSC) because Astryx can replace its rendering. Confirm the installed release's Composer conflict and migration support before proposing a transition. If an FSC migration is requested, inspect the supported CType mapping and limitations, plan dependency and TypoScript/Site Set changes together, and keep the migration read-only/dry-run by default. Never apply a production data migration without explicit user authorization and the release manual's backup, rehearsal, and reporting prerequisites.

   Use packaged extension assets when they meet the project's needs. Enable Vite delivery only when the consuming project has a working integration for Astryx's registered entrypoints. Use `typo3-stylex` for missing generic connector/Vite wiring. Load one Astryx frontend delivery path, as required by the installed release.

   Read the installed release's configuration manual for theme/mode settings, page fields, inheritance, visitor preferences, and template override contracts; verify actual setting names and defaults in source before changing them.

   Completion: dependencies and activation match the requested setup, migrations are bounded to documented support, schema/cache steps are clear, and the chosen asset-delivery path is explicit.

3. **Route each style change to its owner and author StyleX first.** Paths in the table are relative to the Astryx extension root unless marked otherwise. The named token files are common source locations; confirm the installed package's token registry and imports before editing, and follow the corresponding family or nearest existing pattern if a release uses different filenames.

   | Change | Authored source to inspect/use |
   | --- | --- |
   | Semantic colors | `Resources/Private/JavaScript/StyleX/tokens/` color token family and token registry |
   | Category or code colors | Corresponding category/code token family when present |
   | Typography, spacing, layout, shape, shadow, or motion | Matching semantic token family under `StyleX/tokens/` |
   | Themeable component contract | Component token family under `StyleX/tokens/components/`, if provided |
   | Built-in theme values | Theme source modules under `StyleX/themes/` |
   | Reusable Fluid component or page chrome | Shared recipes under `StyleX/components/` |
   | Styling consumed only by one Content Block | That block's private source directory (commonly `ContentBlocks/ContentElements/<name>/src/`) |
   | Site/product-only styling | The actual consumer package's authored StyleX sources and registered entrypoint, if its build supports them |
   | Arbitrary rich-text descendants or external editor DOM | Existing narrowly scoped CSS integration (for example extension `Resources/Private/CSS/prose.css`) when StyleX cannot reliably target the generated markup |

   **Token rules:** use `stylex.defineVars` for shared values that need to vary by theme, mode, or runtime scope. Use compile-time constants only for values that are deliberately fixed. Keep token families grouped by semantic role and update the package's token registry and all build/import paths that consume it. Name tokens for their meaning, not their current hex value, theme, mode, or incidental declaration. In Astryx's public custom-property contract, follow the installed package's namespace and lowercase kebab-case convention (commonly `--astryx-...`), for example `--astryx-color-text-primary`. Keep theme and mode out of token names. Reference exported StyleX variables from recipes; do not duplicate public custom-property strings inside StyleX recipes. Tokenize a value when it is reused or is a deliberate theming contract; keep one-off values local to the recipe.

   **Recipe rules:** use StyleX recipes for controlled component layout, color, typography, spacing, states, responsive behavior, and variants. Use finite static keys and the installed Astryx `ax:recipe`/manifest contract where applicable. Keep the recipe module, Fluid arguments, ViewHelper validation, finite recipe registry, and entrypoint imports synchronized when keys or options change. Put reusable native-component recipes in the shared extension source; put styling used only by one Content Block in that block's source. Keep source basenames unique when the connector/build adapter exposes basename aliases. Import each module from the entrypoint that renders its classes. Never hard-code generated atomic class names.

   **CSS boundary:** avoid hand-authored CSS for ordinary component styling. A block-specific selector or convenience is not by itself a reason to add CSS. Prefer tokens and StyleX recipes. Keep hand-authored CSS only for a documented browser, editor, or markup integration that the installed StyleX compiler and Fluid rendering path cannot express or reliably apply—for example, arbitrary CKEditor/prose descendants, font-face declarations, a required reset, or a native pseudo-element/external-library DOM selector. Keep exceptions small and scoped, consume existing tokens, and link the source stylesheet through the documented entrypoint. Treat generated CSS as build output; do not edit generated theme bridges, bundles, or manifests by hand. An import aggregator is not a place for component rules.

   Completion: values and recipes live in their owning package, are imported by the entrypoint that needs them, and use keys resolved by the installed manifest/ViewHelper contract. Any authored CSS has a specific technical reason documented at its source.

4. **Change themes as a coordinated source/runtime contract.** Keep theme identity separate from color mode. Inspect the installed theme modules, token registry, resolver/allowlist, page field choices, labels, settings, editor/preview integration, generated bridge, and manuals before changing a theme. Use mode-aware values when only light/dark appearance changes; introduce a new theme identity only when it represents a supported, reusable design system choice rather than one consuming site's brand.

   For a new or changed built-in theme, update the corresponding source overrides, theme registry, imports, TYPO3 allowlists/settings/labels, documentation, and any provenance records required by the package. Override semantic roles rather than copying entire token families. Ensure each nested theme boundary receives all required token values through the package's supported bridge/runtime mechanism, including RTE and backend preview scopes where applicable. Regenerate generated theme artifacts with the documented script and build the paired CSS/manifest outputs together. Review both supported modes, nested theme boundaries, frontend, editor, and preview contexts affected by the change.

   For a site-specific brand variation, prefer a site-owned StyleX theme/recipe and existing semantic contracts if the consuming integration supports them. Do not copy Astryx token modules into the consumer package or add an Astryx-wide theme for a one-site need. If a project cannot express the desired brand variation through a supported StyleX scope, document the limitation and follow the extension's documented override contract.

   Completion: source, registration, TYPO3 settings, generated bridge, runtime scopes, and documentation agree; theme identity remains independent from mode.

5. **Build and verify through the discovered project setup.** Run commands from the Composer/frontend project root that owns the dependencies. Derive build commands and order from the installed Astryx manual, its actual extension root, and the consuming project's `package.json`, Vite configuration, and entrypoint registry. Do not assume DDEV, a source-checkout directory such as `packages/`, a fixed sitepackage name, or a project-specific script.

   When changing tokens or themes, run the package's documented bridge/generation step before the build stages that consume its generated files. Then run the relevant extension asset build and, when site assets or Vite manifests are affected, the consuming project's build. Use the installed package's ownership/artifact verifiers and TYPO3 validation commands when available. For manifest changes, validate the changed key. For Content Block schema/template changes, use the project's Content Blocks lint and relevant Fluid checks. Select focused rendering or browser checks for the behavior affected. Never hand-edit generated bundles, manifests, checksums, theme bridges, or generated token indexes.

   If Astryx is only available as an installed/vendor package, do not edit dependency files in place. Locate its source checkout or follow the project's established fork/patch workflow so changes remain reproducible.

   Completion: relevant build/audit commands pass, matching assets and manifests are generated together, and affected output is checked or any unavailable check is reported precisely.

## Safety and ownership

- Do not apply content migrations or alter production data without explicit authorization and the installed release's documented backup/rehearsal/report workflow.
- Treat generated files as disposable output; edit authored sources and rerun the documented build.
- Keep reusable Astryx behavior in the extension and product branding in the actual consuming package. Do not modify installed dependencies in place.
- Follow the requested scope; do not expand a documentation or style change into unrelated extension coverage or migrations.

## Related workflows

- Read the project's applicable design-system guide when present for local source routing and build order; treat the installed package's manuals and source as authoritative.
- For generic StyleX Connector/Vite installation, repair, manifests, and integrations, use the companion `typo3-stylex` skill.
- For Content Block schemas/templates/previews that change alongside styling, use the relevant TYPO3 Content Blocks workflow skill.