design-sync notes — myMat Brand Kit

Project: myMat Brand Kit — https://claude.ai/design/p/8e7513e1-b429-4b24-a72d-59f318ac7d54 First synced 2026-08-28. Shape: package, tokens-only (no components).

What this repo is

An Eleventy static site, not a React component library: no dist/, no Storybook, no .jsx/.tsx anywhere. The converter's documented tokens-only path handles this — it prints [ZERO_MATCH] no component exports — treating as tokens-only DS and emits styles.css + tokens/ + fonts/ with an empty-bodied _ds_bundle.js. That line is expected, not a failure.

The uploaded kit is therefore CSS only. window.MyMatBrand is empty by design; .design-sync/conventions.md tells the design agent so explicitly, because the generated README body otherwise claims it is a React library.

The brand-pkg generation step

cfg.cssEntry is bounded by design-sync to the package directory (its content uploads verbatim), so it cannot point at assets/css/site.css. Instead .design-sync/build-brand-pkg.mjs regenerates .design-sync/brand-pkg/ from the site's own CSS. It is cfg.buildCmd — run it before every re-sync.

Inputs and how they are split (logic in brand-kit.mjs, tested in test/brand-kit-css.test.mjs):

• assets/css/site.css — canonical core + editorial rules, taken whole.
• the inline <style> block in index.html — the same core rules again plus the marketing-only ones; only its non-duplicates are added.

As of 2026-08-28 all 44 shared rules were byte-identical, so nothing is lost to de-duplication. site.css's own header comment warns that the four original pages still carry inline copies — if those pages are ever pointed at site.css, or the copies drift, re-check that assumption.

Two behaviours are load-bearing and fail silently, which is why they are unit-tested rather than eyeballed:

1. @font-face url rewriting. The site declares fonts absolutely (url('/assets/fonts/…')). design-sync resolves url()s against the stylesheet dir and an absolute path wins, so unrewritten rules never copy the .woff2 and every design silently renders in a fallback font. The generator rewrites them to ../../assets/fonts/… and they are wired via cfg.extraFonts (bounded to the workspace root, unlike cssEntry).
2. De-duplication keys on selector + normalised body, not selector alone — both sources declare @media (max-width: 820px) with different bodies.

Fresh-clone setup

.design-sync/brand-pkg/ is gitignored (generated). Recreate it and the symlink that cfg.tokensPkg resolves through:

node .design-sync/build-brand-pkg.mjs
ln -sfn ../../.design-sync/brand-pkg .ds-sync/node_modules/mymat-brand

Re-sync

# re-copy the staged scripts first (a stale .ds-sync/ runs an old converter)
node .design-sync/build-brand-pkg.mjs
node .ds-sync/resync.mjs --config .design-sync/config.json \
  --node-modules .ds-sync/node_modules \
  --entry .design-sync/brand-pkg/index.mjs \
  --out ./ds-bundle --no-render-check \
  --remote .design-sync/.cache/remote-sync.json
node .design-sync/validate-conventions.mjs

Then re-read conventions.md against the fresh build — keeping it true is a standing job; do not rewrite it, report drift.

Decisions on the record

• --no-render-check is deliberate, signed off by the repo owner on 2026-08-28. design-sync's render check screenshots component preview cards and this kit has zero of them, so it would verify nothing while costing a ~150MB Chromium install. Rendering was verified directly instead: the real index.html body markup served against ds-bundle/styles.css in Chromium — the kit was the only stylesheet, both brand families reported document.fonts.status === "loaded", tokens resolved, and all 160 source selectors were accounted for in the output.
• [DTS_REACT] @types/react not found is printed on every build and is harmless here — there are no components whose props need resolving.

Re-sync risks

• The generated README body is misleading by construction. It is written for React DSes and says "the published mymat-brand React library … All 0 components are the real upstream code". Only conventions.md, prepended above it, corrects this. If that header is ever dropped or truncated, the design agent will look for components that do not exist.
• index.html is the marketing design's only source. The hero, features, wizard, pricing, FAQ and CTA rules exist nowhere else. If that page is refactored onto _layouts/base.njk and its <style> block removed, the generator will silently emit a much smaller kit — the tests assert .hero-card, .features-grid, .wizard-step, .pricing-card, .faq-item and .cta-strip survive, so they will fail loudly. Fix the generator's inputs, don't delete the assertions.
• Fonts are referenced out of the repo, not copied into brand-pkg/. Moving or renaming anything under assets/fonts/ breaks the kit's @font-face srcs. package-validate.mjs catches this as [FONT_DANGLING].
• No verification carries forward beyond the uploaded _ds_sync.json anchor, and with zero components it anchors zero render hashes — every re-sync re-does the (cheap) styling work from scratch.