SuperAPI AI Directory

ground-my-shopware

General & other

View repository

Updated 10-16 06:13

About this skill

Ground My Shopware

Shopware's Administration is a large design system wearing a thin Vue harness. Almost everything you need is already built — and almost nothing tells you when you have asked for it wrongly. A slot name that does not exist renders nothing. A wrong variant renders unstyled. A class you invented styles nothing. The build passes, the tests pass, and a merchant tells you the screen looks broken.

So this skill has one move, applied over and over: read the installed component before you write the markup that uses it.

The Prime Directive

No slot, prop, enum value, token, icon name, snippet key, or CSS assumption that you have not read in the installed source, at a file:line you can cite. Not remembered from training. Not inferred from a sibling component. Not copied from the online docs, which describe a different patch version than the one that will run.

Shopware moves fast and deprecates in place. A component that took #action in 6.4, sw-card in 6.5 and mt-card in 6.7 is the normal case, not the exception. Training-data memory of this framework is a hypothesis generator, never a source.

Nor is documentation — including Shopware's own. The framework ships an agent guide at administration/src/app/AGENTS.md whose styling example recommends var(--mt-spacing-4) and var(--mt-color-text-primary). Neither custom property is defined anywhere in the installed tree, so both declarations are dropped at runtime, and core itself carries a live instance of the same bug. Two greps prove it. If the authors' own guide does not survive contact with the source, nothing you remember will.

Hard rules

  1. Reuse before you build. Before writing a card, a grid, a picker, a definition list or a toolbar, check references/component-contracts.md for the component that already does it and the core file that demonstrates it. Copying a core screen's structure is the highest-value move available to you: it comes pre-styled, pre-tokenised, pre-accessible, and it survives upgrades.
  2. Silence is the enemy. These defects do not throw. Hunt them with the catalogue in references/silent-failures.md rather than waiting for an error or trusting a green build.
  3. Measure, do not eyeball. A layout diagnosis from source alone is a guess. The probes in references/measuring.md turn "looks cramped" into scrollWidth 902 vs clientWidth 623, which names the fix.
  4. Lock the contract into a test. An audit that lives only in a commit message gets re-broken next sprint. Patterns in references/contract-tests.md.
  5. Style with tokens you have grepped. Two different packages define them and the legacy palette still resolves, so "it renders" is not evidence you used the right one. See the token section of component-contracts.md.
  6. Never reach for !important. When an override loses, the cause is almost always a Meteor scoped style outranking you. First check whether the component published a custom property for what you are changing (--mt-card-content-padding, --mt-modal-width) — setting the variable beats fighting the selector. Otherwise win on specificity with an ancestor class you own, and leave a comment saying why the selector is longer than it looks like it needs to be.
  7. Know which generation you are on. 6.7 ships the legacy sw-* set and the Meteor mt-* set side by side, joined by nineteen shims that are all removed in 6.8. The two generations bind v-model differently, name variants differently, and render different DOM classes — and the shims hide every one of those differences until someone renames a tag. references/form-fields.md and references/version-deltas.md.
  8. Registered is not the same as installed. A Meteor component can sit in node_modules, read perfectly, and still render nothing because the Administration never registered it. Check vue.adapter.ts and app/component/index.ts, and check whether what you get is a Shopware wrapper rather than the library component — mt-card is.

Workflow

1. Locate the truth on disk

Paths differ per install; find them once and cite them from then on. The canonical layout, and the greps that confirm it, are at the top of references/component-contracts.md. Pin the version too — composer.lock or vendor/shopware/core/composer.json — because a contract answer is only true for a version.

Do that once per checkout, not once per question:

node scripts/contracts.mjs                 # walks up to the shop root by itself
node scripts/contracts.mjs --risk          # only what carries a derived warning
node scripts/contracts.mjs --component mt-card
node scripts/contracts.mjs --rank --uncovered   # what to document next

It indexes every component the installed Administration ships — around 385 of them in 6.7.13.1, against the fourteen this skill documents by hand — reading slots, props, required props, defaults, styled enums, component-local custom properties, scoped styles, wrappers and registration out of the source, each with a file:line. The index lands in .contracts/index.json, gitignored because it describes one checkout at one patch release.

It answers exactly the questions the prime directive forbids you to remember. "Which slots does this component declare" and "is this enum value styled" are lookups, not judgments — so they belong in a script, and every answer it gives is checkable in one grep. What it does not do is decide anything: enum values with no CSS rule is a review queue, because a behavioural prop like dateType correctly has no class. Read it, do not obey it.

It has no dependencies and needs no model — node:fs, node:path, node:url, and nothing else. No network, no API key, no node_modules. This matters: a skill that only works for users who have installed some other tool fails for most of them.

When you are the one extending this skill

--rank scores every component on the silent-failure signals above plus how many core files reach for it, and --uncovered drops the ones the prose already names. In 6.7.13.1 that leaves 227 components scored above zero and never mentioned — sw-entity-listing, sw-single-select, sw-multi-select, sw-pagination, sw-select-result and sw-inherit-wrapper at the top, all of which a plugin author reaches for and none of which has a contract here.

The ordering is deterministic on purpose. It is the same on every machine, it can be reviewed, and each row says which facts earned its score — so you can disagree with it and say why. Nothing about it waits on a model being available.

2. Read the contract for every component the screen touches

For each one, answer from source: which slots does it declare (exact spelling and case — headerRight is not header-right), which props are required, which enum values are actually styled, what does it do to layout and padding, and is it deprecated with a due date. Record the answers with file:line.

Three questions belong in that pass and are easy to skip:

  • Which component am I actually getting? mt-card in the Administration is a Shopware wrapper with a required position-identifier, not the component in node_modules. Check meteor-wrapper/ and the registration before you trust a prop list.
  • Is this enum real? Meteor's newer props are TypeScript unions, erased before a TwigJS template compiles. The runtime contract is whether the generated class has a rule in the built CSS.
  • Which binding does it want? mt-* takes v-model; the legacy set takes v-model:value; the shims take both and hide the mistake.

The first two are in component-contracts.md; the third is in references/form-fields.md.

3. Build on what you verified — and reuse the core screen that already does it

Never re-implement a layout primitive. The reuse table in component-contracts.md maps each thing you might need to the component that provides it and a core file that uses it well, because a working example answers questions a prop list cannot: where the padding comes from, which slot the grid belongs in, what the empty state looks like.

When you deviate, say why in a comment at the deviation. A future reader who finds variant="regular" with no explanation will "simplify" it back.

4. Measure the result in a logged-in Administration

Screenshot it, then dump the numbers: widths, overflow, computed padding, which rule won. Then read the console after a reload, so you are not diagnosing a stale error. If you have no session, say so and mark every layout claim UNVERIFIED — do not ask the user for credentials and do not type any.

5. Lock it in

Add or extend a contract spec so the defect cannot return. Shopware plugin repos usually have a Jest suite that reads templates off disk; that is the right place, and contract-tests.md has the assertions worth writing.

The five-minute version

When the task is small and you only need the greatest hits:

# 0. the whole component tree, as data — cheaper than any of the greps below
node scripts/contracts.mjs --component sw-data-grid

# 1. what version am I actually targeting?
grep -m1 '"version"' vendor/shopware/core/composer.json || grep -A2 '"name": "shopware/core"' composer.lock

# 2. does this slot exist? (the single most common silent defect)
grep -n '<slot' vendor/shopware/administration/Resources/app/administration/node_modules/@shopware-ag/meteor-component-library/src/components/layout/mt-card/mt-card.vue

# 3. does this token exist, and which package defines it?
grep -rn -- '--scale-size-24:\|--color-border-secondary-default:' \
  vendor/shopware/administration/Resources/app/administration/node_modules/@shopware-ag/

# 4. does this snippet key resolve, in every locale?
grep -rn '"myKey"' src/Resources/app/administration/src/snippet/*.json

# 5. is a class I referenced actually styled anywhere?
grep -rn '\.my-class' src/Resources/app/administration/src --include='*.scss'

# 6. am I binding a Meteor field the legacy way? (empty field, never saves)
grep -rn 'v-model:value' src/Resources/app/administration/src --include='*.twig' | grep '<mt-'

# 7. is this variant actually styled, or just a plausible word?
grep -rho 'mt-button--[a-z-]*' \
  vendor/shopware/administration/Resources/app/administration/node_modules/@shopware-ag/meteor-component-library/dist/*.css | sort -u

Six of those seven are grep. That is the point: the expensive failures in this framework are cheap to prevent and costly to diagnose.

Reference files

Read the one the task needs; they are written to be skimmed by heading.

File Read it when
references/component-contracts.md Any time you write or edit admin markup — slot lists, props, variants, tokens, the reuse table, and the core files to copy from
references/silent-failures.md A screen looks wrong but nothing errors; or before review, as a checklist
references/measuring.md You need numbers from a running Administration — overflow, box model, which CSS rule won, token values, snippet resolution
references/form-fields.md Any input, select, button or modal — the v-model contract, the nineteen shims, variants that are only TypeScript, and which mt-* the admin actually registers
references/version-deltas.md Upgrading a plugin, or diagnosing "it worked before the update" — what moved between 6.6 and 6.7 and how each move fails
references/contract-tests.md Closing the loop: guard specs, the baseline-allowlist technique, and the Twig-comment trap that breaks template specs

What this skill does not do

It is not a plugin architecture guide — DAL, DI, subscribers, migrations and Store API belong to a Shopware plugin-development skill, and this one only touches migrations where the UI depends on one (media folders and thumbnails). It also does not decide product design. It makes sure that what you decided is what the framework actually renders.