cloudrite/.design-sync/NOTES.md

design-sync notes — Cloudrite

Repo-specific gotchas for future syncs. Read this before re-running.

What this repo is

Not a component library — a Next.js 16 marketing site (private: true, no dist/, no exports, no .d.ts tree). The DS surface is components/ui/* (54 shadcn/ui primitives, new-york style) plus 7 hand-built Cloudrite page sections.

The staging package (.ds-pkg/)

The converter needs a package with a built entry and a .d.ts tree. Three scripts under .design-sync/ build one from source; run them in this order (this is cfg.buildCmd):

1. node_modules/.bin/tsc -p .design-sync/tsconfig.dts.json — declaration emit, 69 .d.ts files. Exits 0; all three steps are chained with &&, so a real failure stops the run. ../next-env.d.ts must stay in that config's include. It pulls in Next's JSX augmentation for styled-jsx; without it the <style jsx> blocks in hero.tsx and footer.tsx raise TS2322 and the emit exits non-zero. Those are not repo errors — pnpm build and tsc --noEmit -p tsconfig.json are both clean.
2. node .design-sync/build-css.mjs — compiles Tailwind v4 → .design-sync/compiled.css.
3. node .design-sync/make-pkg.mjs — writes .ds-pkg/{package.json,index.js,index.d.ts}, copies the stylesheet + fonts in, and regenerates .design-sync/docs/*.md.

index.js re-exports every symbol from source (292 exports → window.Cloudrite), while index.d.ts re-exports only the 61 roots. That split is deliberate: shadcn exports compound parts flat (CardHeader, not Card.Header), and the converter's subcomponent grouping only recognises TS-namespace compounds — so without the split all 292 exports would each get their own preview card. The parts are instead documented per-root in the generated .design-sync/docs/<Root>.md parts tables, which become the .prompt.md the design agent reads.

Known render warns

• [DTS_STYLE_SYSTEM] filtering @types/react props — expected. Most shadcn primitives type their props as React.ComponentProps<'div'>, so the CSS-shorthand filter trips on React's own DOM prop bag. The emitted <Name>Props still carry the real API (variant unions, asChild, etc.). Not a defect.
• inlined npm packages: 1 in the build log is a pnpm artifact, not a real count — the metafile regex matches .pnpm first in pnpm's node_modules/.pnpm/<pkg>@ver/... layout. The bundle really does inline radix, lucide, cva, etc.

Gotchas that cost a debugging cycle

• cfg.tsconfig must use /* */ comments only. The converter strips // comments with a regex that also mangles a "//" JSON key, leaving unparseable JSON. The failure is silent: tsconfigPathsPlugin returns null, esbuild falls back to autodiscovering the repo's own tsconfig.json, and next/link resolves to the real Next runtime — which bundles the App Router and makes every preview die with ReferenceError: process is not defined.
• next/link is shimmed to a plain anchor (.design-sync/shims/next-link.tsx) via compilerOptions.paths. Header, Hero and Footer import it; the real one needs AppRouterContext, which doesn't exist outside a Next app.
• CSS edits need a full package-build.mjs. lib/preview-rebuild.mjs only recompiles _preview/*.js; it does not re-copy the stylesheet, so a CSS fix appears to do nothing until the full build runs.
• Never set html { background } in the DS stylesheet. The card harness paints body{background:#fff} in a later inline <style>, so a dark html under a white body box paints a black band across the bottom of every card. body alone is correct: designs get the brand surface, cards keep the harness's white chrome.
• Fonts are self-hosted. next/font/google supplies Space Grotesk + Inter at runtime in the app, so the repo has no font files. Latin + latin-ext woff2 subsets were downloaded from Google Fonts into .design-sync/fonts/ (SIL OFL) and are committed. app/globals.css declares --font-sans: var(--font-sans), …, which is a self-reference that is invalid outside Next — .design-sync/tailwind-entry.css re-declares both families with real stacks.

Preview conventions (apply to every new preview)

• Wrap every story in a Surface — <div className="bg-background text-foreground rounded-lg p-6">. Cloudrite is dark-only; ghost, link, outline and border-border are all invisible against the harness's white card body.
• Overlay / menu components need an open state. Give them a defaultOpen story and set cfg.overrides.<Name> = {"cardMode":"single","primaryStory":"Open","viewport":"WxH"} — see Select. A closed trigger shows none of the compound parts.
• Animated sections need transitions zeroed. Hero fades in on a 300 ms timer plus a 1 s transition; the capture harness only waits on fonts and images, so an unmodified render screenshots at ~10 % opacity. See the still style in previews/Hero.tsx. Features and Process use IntersectionObserver instead and settle on their own.
• Use real Cloudrite copy (Auckland IT services, 021 107 7483, the four service lines), never foo/bar.
• Recompile the CSS after authoring previews: Tailwind only emits utilities for classes it can see, and @source './previews' covers the preview files.

Excluded from the DS, on purpose

• components/chatwidget.tsx — Chatwoot script injector. Renders no markup and fetches /api/chatwoot on mount.
• components/ui/toaster.tsx — legacy Toaster, colliding with ui/sonner.tsx's. Sonner wins; the site uses neither.
• ThemeProvider — in the bundle (wrap-able) but given no card.

Re-sync risks

• .ds-pkg/ and .design-sync/compiled.css are gitignored and regenerated. A fresh clone must run all three buildCmd steps before the converter, or the entry and stylesheet won't exist.
• The scaffolding is inert to the app build, but only because of dot-prefixing. tsconfig.json includes **/*.ts(x) from the repo root with only node_modules excluded; TypeScript's glob matcher skips directories beginning with ., which is the sole reason .design-sync/previews/*.tsx (they import 'cloudrite', which does not resolve in the app) and .ds-pkg/types/** don't enter the app's program. Verified: pnpm build and a cold tsc --noEmit both exit 0. If any of this is ever moved to a non-dotted path, add it to the app tsconfig's exclude first.
• next build is not a substitute for the staging package, but it does compile the Tailwind stylesheet (~136 KB, hash-named under .next/static/chunks/*.css). That is smaller than .design-sync/compiled.css (~170 KB) because Tailwind only emits classes it can see and the app never references the utilities used by .design-sync/previews/. The app build supplies no library entry and no declarations, which is what .ds-pkg/ exists to provide.
• The fonts are a point-in-time copy. If Google Fonts revs the woff2, nothing here notices; the committed files keep working. Re-download only deliberately.
• The parts tables in .design-sync/docs/ are generated by make-pkg.mjs from the declaration emit — never hand-edit them; they are overwritten every run. The prop signature column falls back to — for declarations that aren't plain functions.
• ROOT_OVERRIDE in make-pkg.mjs is a hand-maintained exception list (currently just toast.tsx → Toast, whose first export is the provider). A new shadcn component whose first export isn't the root needs an entry there.
• Only 40 of 61 components have authored previews; the other 21 ship the floor card and can be authored on any later sync. .design-sync/previews/ and the grades carry forward.
• Playwright drives the machine's installed Google Chrome via DS_CHROMIUM_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" (no 200 MB chromium download). Export it before package-validate.mjs / package-capture.mjs, or the render check is skipped.

Findings for the Cloudrite team (not sync bugs)

• --accent is set to the brand green, byte-identical to --primary (oklch(0.75 0.18 145)), in both the :root and .dark blocks of app/globals.css. shadcn's default is a low-contrast neutral used for hover and placeholder surfaces, so every bg-accent consumer is now vivid green — most visibly Skeleton (loading blocks render as solid green bars), plus the hover states in dropdown-menu, command, menubar, navigation-menu, calendar, item, toggle, button and dialog. The previews render this faithfully rather than papering over it. If it wasn't intentional, giving --accent its own muted value is a one-line change.
• styles/globals.css is an unused light-theme duplicate of app/globals.css (v0 scaffolding). Nothing imports it.

Gotchas found after the first NOTES pass

• package-build.mjs wipes the whole --out dir, _screenshots/ included. Any review sheet captured before a full rebuild is gone; re-run package-capture.mjs for anything still awaiting a grade.
• Overlay content must not be given className="relative". Radix positions DialogContent with fixed plus translate(-50%,-50%); switching it to relative keeps the translate but drops the centring anchor, so the card clips the title. Size the card via cfg.overrides.<Name>.viewport instead.
• Radix autofocuses the first focusable in an open overlay, which screenshots as a green text selection. onOpenAutoFocus={(e) => e.preventDefault()} gives a clean still.
• DS_CHROMIUM_PATH must be exported for resync.mjs too — without it the driver's validate stage fails [RENDER_SKIPPED] and skips capture on prior_failure.