audi-app/design-system/.design-sync/NOTES.md

design-sync notes — @audi-dash/ui

Repo shape

• Package shape (no Storybook). Build: npm run build (tsup) in the repo root produces dist/index.js (ESM), dist/index.cjs (CJS), dist/index.d.ts, dist/styles.css. The converter's --entry points at dist/index.js.
• Converter deps are staged/installed under .ds-sync/ (isolated npm project, gitignored) — never mixed into the repo's own package.json.
• On Windows, npm install needs npm approve-scripts esbuild once per fresh .ds-sync//node_modules (npm 11's allow-scripts gate blocks esbuild's postinstall that downloads its platform binary).

Known render warns (triaged, safe to ignore on re-sync)

• [RENDER_THIN] on IconButton: "mounts have no text and paint nothing" — false positive. IconButton is intentionally icon-only (no text content, aria-label only). Screenshot confirms both cells (Default, Disabled) render the icons correctly; the heuristic just measures text content, which is legitimately empty here.

cfg.overrides

• Popup: cardMode: "single" — it's a fixed-position overlay component that portals to document.body; grid mode collapsed/escaped its card.
• Accordion, Feld, TabBar, StatGrid: cardMode: "column" — one or more of their authored stories render wider than a grid cell (multi-field forms / full-width nav bars); column mode gives them the full card width instead of being cropped.

Preview authoring conventions

• Every preview wraps its composition in <div className="ads-root" data-theme="nacht"> (a local Root helper duplicated per file) — the library only applies text color/background via .ads-root, and without it previews render with browser-default black-on-white instead of the app's actual dark theme. This is required for every future preview — the components' color tokens are on :root (theme-independent) but color/background inheritance only kicks in under .ads-root.
• Popup's children portal to document.body, escaping any local .ads-root wrapper. This doesn't break styling because Popup's own CSS (.ads-popup, .ads-popup-item) sets background/color directly from var(--tile-2)/var(--fg) rather than relying on inherited color — so it renders correctly even though the wrapper technically doesn't reach it.
• SwipeRow's SwipedOpen story shows content clipped at the left edge behind the revealed delete button — this is correct, faithful behavior (the row slides left to reveal the delete action), not a rendering defect.

Re-sync risks

• All 20 previews are hand-authored (no floor cards) — a future re-sync only needs to touch previews for components whose source or .tsx actually changed; everything else carries forward via the grade cache + _ds_sync.json anchor.
• The Root wrapper pattern (data-theme="nacht") is duplicated per preview file rather than imported from a shared module — if a preview is added later without it, it will silently render unthemed (black text, no background). Check for data-theme="nacht" in any new preview before grading it.
• Playwright/Chromium was freshly installed for this sync (.ds-sync/node_modules/playwright, chromium cached at ~/AppData/Local/ms-playwright) — not committed, machine-local. A re-sync on a different machine needs to reinstall it (package-validate.mjs will prompt if missing).
• No docsDir/docs were found in this repo (it's a fresh internal design system, no README-per-component docs yet) — all .prompt.md files are synthesized from .d.ts + the authored preview .tsx, not from hand-written docs. If per-component docs are added later, set cfg.docsDir to pick them up.