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:lineyou 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
- 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.
- 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.
- 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. - 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.
- 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. - 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. - Know which generation you are on. 6.7 ships the legacy
sw-*set and the Meteormt-*set side by side, joined by nineteen shims that are all removed in 6.8. The two generations bindv-modeldifferently, 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. - 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. Checkvue.adapter.tsandapp/component/index.ts, and check whether what you get is a Shopware wrapper rather than the library component —mt-cardis.
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-cardin the Administration is a Shopware wrapper with a requiredposition-identifier, not the component innode_modules. Checkmeteor-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-*takesv-model; the legacy set takesv-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.