Seven follow-ups from building a derived theme end t... | NextCommerceCo/spark

Nobody has claimed this yet.

Building a derived theme end to end surfaced seven deterministic gaps in Spark itself, each with the proof that found it. Two are trivial (gitignore, a one-line settings-as-filter-argument fix in side_cart), one prevents a recurring bug class (a template-contract lint), and the rest are small. Recommended order is at the bottom.

#	Gap	Proof	Proposed change	Size
1	`.gitignore` lacks `__pycache__/` and `*.pyc`; `make verify-theme` leaves `scripts/__pycache__/` and `tests/__pycache__/` untracked, polluting every contributor's `git status` and diff baseline	run `make verify-theme` on a clean clone, then `git status --short -uall`	add `__pycache__/` and `*.pyc` to `.gitignore`	2 lines
2	`DESIGN.md` promises "Side cart and mobile nav trap focus when open" and Escape closes the mobile nav; `assets/js/theme.js` only toggles `hidden` + body overflow for `#mobile-nav` — no Escape handler, focus entry, trap, or restore	read `theme.js` lines 14–48 at 64b905a against `DESIGN.md`	implement Escape + focus entry/trap/restore for `#mobile-nav` in `theme.js` (generic, ASCII-only) with a `tests/js/` unit test	~40 lines + test
3	No template-contract lint: prose rules ("`firstof … as` yields a string — never use it to pick an object for `purchase_info_for_product`"; "`settings.*` must not be a filter argument"; no hardcoded `/products/` routes) do not survive across contributors; a derived theme re-introduced the `firstof … as` object bug once after it had been fixed	`tests/a template-contracts test` in the derived theme (three regex tests, verified failing on the defective file and passing after repair)	add `tests/test_template_contracts.py` scanning `partials/ templates/ layouts/` for (a) object-selecting `{% firstof … as %}` (any `as` target that is later passed to `purchase_info_for_product`), (b) `	filter:settings.`(settings as filter argument — the platform 500s on every route), (c)`/products/ `literals, and (d) presence of the runtime hooks the shipped JS resolves by id/attribute (`id="cart-badge"`,` data-toggle="mobile-nav"`,` id="mobile-nav"`,` <spark-cart-drawer`) — a negative control showed deleting` id="cart-badge"` passes every current gate and fails silently in the browser
4	`partials/side_cart.html` line 37 carries `{{ settings.gift_product.children.first.pk\|default:settings.gift_product.pk }}` — `settings` as a filter ARGUMENT, which raises a 500 on every route as soon as `gift_product` is set	platform bisection (see the platform issue draft on settings-as-filter-argument)	rewrite as `{% with gift=settings.gift_product %}{% firstof gift.children.first.pk gift.pk %}{% endwith %}` (PK scalar — `firstof … as` is fine for PKs)	1 line
5	No local DTL parse gate: a scratch Django 4.2 environment with stubbed platform tags parses all 71 templates in <1 s and would catch any syntax slip before upload	scratch gate used across three review rounds; the platform rejects syntax errors at upload, but only one file per push	add `scripts/check-dtl.py` (optional dev dependency `django==4.2.*`, stub library for platform tags) wired into `make verify-theme` when Django is importable	~120 lines
6	Localized settings must keep empty schema defaults so `{% t %}` fallbacks apply — enforced by `test_localization_contracts.py` but not stated in `docs/design-block-authoring.md`; a contributor adding a design-copy default hits two failed `make verify-theme` runs before finding out	builder receipt	one paragraph in `docs/design-block-authoring.md`: "localized settings keep empty defaults; add a separate non-localized key for design copy"	prose
7	Figma mobile frame width is an open decision in `docs/figma-section-library-plan.md` (375 vs 390)	the `next-theme-figma` skill hard-codes 390 in one place and allows both in another	close the decision: "match the Figma-defined width (375 or 390); capture QA at both"	prose

Recommended order: 1, 4 (trivial, zero risk) → 3 (prevents the recurring class) → 2 → 5 → 6, 7.

Not a Spark item (checked and removed): the gtm.js?id= request with an empty container id seen on every page comes from a platform-injected script — the theme tree contains no GTM reference.

Start by running make verify-theme and reading .gitignore, partials/side_cart.html, assets/js/theme.js, DESIGN.md, and the listed tests and documentation files. Work through the recommended order, using the existing proofs and platform bisection as guides; done means the verification gates pass, the documented template and accessibility contracts are covered, and the two documentation decisions are recorded.

Written by the indexing model from the issue text.

Seven follow-ups from building a derived theme end to end (gitignore, focus trap, template-contract lint, side-cart settings bug, DTL gate, docs)

Description

Contributor guide

First steps

Research direction

Assessment