For a theme-local installation, run vendor/bin/theme-json from the theme root.
For a global installation, add Composer's global binary directory to your shell's
PATH. Check installation and run list
with the executable you installed.
The current generator requires some development branches. Allow those dependencies explicitly in the installing Composer project, choose a generator version containing the features you use, and commit your lockfile. A theme's Composer settings do not configure a separate global Composer installation. See installation.
init imports existing JSON files. It does not create theme.json when missing,
and it skips entrypoints that already exist. Start a new configuration using the
quick start. Run init from the theme root;
it does not accept --path.
Check for theme.json.php or a *.json.php file under styles/. Other supporting
PHP files are not entrypoints. Run from the theme root or supply dump --path=….
An empty scan can exit successfully without generating a file; check that the
expected outputs exist when scripting builds.
The destination theme needs a readable root style.css containing Theme Name:.
For a non-current directory, use dump --path=/path/to/theme. This requirement
applies to JSON generation; standalone scss export does not require it.
Check the namespace, declaration, and Autoload directory.
Attribute paths are relative to their entrypoint; the --autoload flag is
relative to the working directory and overrides attributes. Remove duplicate
declarations. A configured but invalid directory fails rather than falling back
to Composer. Put work needing those classes inside the callable, after metadata
can be inspected.
Pipeline classes must implement ConfiguratorInterface and define
__invoke(ThemeJson $themeJson): void. Plain invokable classes are not enough.
Use an explicit configured instance for dependencies that cannot be resolved
automatically. See configurators.
Register presets before using them. Use the type key (fontSize.body), not the
JSON collection name (fontSizes.body). Block keys include their block scope.
Missing plain keys pass through literally; missing placeholders throw. Generic
root writes do not register objects in the preset collection. See presets.
Choose unique paths within each type and scope. Avoid registering a common palette and then another palette with the same slugs in one output. Do not use a custom path as both a scalar and a parent group. Each variation has a separate collection; configure only the presets its build needs.
Every entrypoint builds independently. Root autoload directories are shared, but root configuration is not executed for a selected variation. Use shared configurators explicitly in the relevant files.
Without a selector argument, use declarations and nested rules starting with &.
With a selector argument, every input selector must belong to that scope. .card-title
and .card_title are independent classes, not descendants of .card. Keep scoped
at-rules out of block CSS; write complete global rules instead.
See custom CSS.
Opt an already fluid size out with the preset's false fluid argument. Choose
either global boolean fluid configuration or its object options; do not configure
both alternatives. See typography.
dump exports SCSS only with a ScssOutput attribute or --scss. Check whether
--no-scss suppressed it. Root SCSS attributes are not inherited by variations.
Each selected entrypoint must target a distinct output file. File symlink outputs
are rejected. Standalone scss --check compares with its input JSON, so regenerate
JSON first when the PHP source changed. See SCSS export.
The current validate command prints schema errors without reliably failing the
process. dump --validate does not run validation. Use a separate validator with
a chosen schema and a failing exit status for CI gates. See the CLI reference.
The command caches Gutenberg's schema as theme.schema.json, refreshing it after
a week or with --force. Check network access, PHP URL stream support, and write
permissions. The cached schema is independent of your entrypoint's $schema URL.
Replace THEME_JSON_VERSION with an installable tag or branch. Check THEME_PATH,
the root entrypoint, and whether repository rules permit the workflow token to
push. Existing workflow copies are not updated automatically. See GitHub Actions.
Check ownership and write access for the destination and its parent directory. Run generation as the user who owns the project. Avoid fixing a theme permission problem by running the generator as root. Review the reported destination before changing project permissions.