πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
design-sync notes (Rybbit)
Repo-specific facts a future sync needs. Config lives in config.json; this file holds the why.
Shape and layout
- Rybbit is a Next.js app, not a package: the design system is
client/src/components/ui/*.tsx(shadcn new-york style, Tailwind v4, Radix). No Storybook anywhere; shape =package. .design-sync/pkg/is a committed facade package (@rybbit/ui) built bynode .design-sync/pkg/build.mjs(=cfg.buildCmd, run before every converter run):src/index.tsbarrel: oneexport *per ui file.basic-tabsclashes withtabson Tabs/TabsList/TabsTrigger/TabsContent, so it's re-exported asBasicTabs*.src/shims/utils.tsreplaces@/lib/utils(the real one imports luxon, Avatar, the app store). Exportscn+formatter(input-with-suggestions usesformatter). Add here if a ui file starts importing something else from@/lib/utils(esbuild fails loudly: "No matching export").src/RybbitTheme.tsx: thecfg.provider. Addsdarkto<html>(portals!) and the wrapper, Inter font,bg-background text-foreground, wrapsTooltipProvider(Radix Tooltip throws without it).src/styles.css:@imports the app'sglobals.css, scansclient/src+.design-sync/previews, vendors Inter (fonts/*.woff2, copied fromclient/.next/static/medianext/font output; latin + latin-ext, SIL OFL), and carries a@source inline()safelist so utilities the app never uses (grid-cols-3,bg-card,md:variants,/20tints, fractions) still exist for the design agent. Output ~650 KB. Trim the safelist if the README size warning ever fires body-side.- tsc emits declarations with
rootDir: ../..βdist/types/{client,.design-sync}/...;dist/types/index.d.tsis the types root (so ts-morph parses the whole tree);@/specifiers in the emitted d.ts are rewritten to relative paths by build.mjs. pkg/node_modulesis a symlink toclient/node_modulescreated by build.mjs (gitignored).- Toolchain: esbuild from
.ds-sync/node_modules(the staged converter deps); typescript, postcss, @tailwindcss/postcss fromclient/node_modules. So.ds-syncmust be staged + installed BEFORE running build.mjs on a fresh clone.
- Converter invocation:
--entry .design-sync/pkg/dist/index.js --node-modules client/node_modules. PKG_DIR resolves to.design-sync/pkg(walk-up to the named package.json). - Cards are one per family (39): every PascalCase sub-part (DialogContent, TableRow, β¦) is
nullincfg.componentSrcMap(134 entries) but still ships onwindow.Rybbit. Each family's.design-sync/docs/<Name>.mdlists its parts; a doc body REPLACES the synthesized examples in.prompt.md, so every doc must carry an example. - Grouping comes from the docs'
category:frontmatter (ui/is a generic dir name, so src-derived groups would all be "general"). Categories: Actions, Forms, Overlays, Navigation, Data display, Feedback, Replay. cfg.guidelinesGlobpulls repo-rootDESIGN.md+PRODUCT.mdintoguidelines/.- Sub-part exclusion means
Toasterneeds an explicit src pin (sonner.tsx).
Verification harness
- Chromium is cached at
~/Library/Caches/ms-playwright/chromium-1234(+1228).[email protected]pins 1234, so.ds-syncinstalls[email protected]and no browser download is needed. If the cache moves, setDS_CHROMIUM_PATHto the executable instead of reinstalling. preview-rebuild.mjsdoes NOT recompile the facade CSS; a preview using a utility outside the app's usage + safelist only renders afterbuild.mjs+ a full converter run.
Preview-authoring learnings (folded from the first-sync batches)
- Authoring brief for future previews:
.design-sync/AUTHORING.md(what subagents were told; keep it current). - Overriding a component colour that the component sets with a
dark:prefix needs adark:prefix too (dark:border-red-400,dark:bg-neutral-700), or the component's own rule wins on specificity. - Arbitrary values (
w-[420px],aria-[invalid=true]:β¦) only exist in the CSS if the app or an authored preview uses them at FULL rebuild time; the safelist covers scale values only. Preferw-64/72/80/96,max-w-*,grid-cols-*.preview-rebuildnever recompiles CSS. [CONFIG_STALE]: addingcfg.overrides.<Name>after a full build blockspreview-rebuild --components <Name>until the nextpackage-build.mjs. Set card modes BEFORE fanning out, or expect the wave to report blocked components (first sync: Select, MultiSelect, InputWithSuggestions, DropdownMenu, Toaster).- Capture clock is pinned to 2024-05-15: Calendar previews use
defaultMonthMay 2024. - Radix Popover autofocuses its first focusable child β blue browser ring in captures; previews pass
onOpenAutoFocus={e => e.preventDefault()}. - MultiSelect has no
openprop (mount effect clicks the combobox); InputWithSuggestions opens on focus (mount effect focuses + dispatchesfocusin); NavigationMenu opens statically viavalueon root + item. - Toaster: react-hot-toast auto-dismisses success at 2s, others at 4s; the preview fires toasts from a mount effect, so a capture slower than ~2s loses the Success cell.
CommandListcaps at 300px (max-h-[300px]): keep palette previews β€7 rows.- Slider / TimelineSlider
disabledlooks identical to enabled (thedisabled:utility sits on a span). - Solo
?story=capture bodies are white in emit.mjs; RybbitTheme now paints<body>withbg-background text-foreground(as the app's root layout does), so portalled overlays composite over dark. CardLoaderandToasterread next-themesuseTheme(): RybbitTheme mounts a forced-theme ThemeProvider.
Known render warns
[TOKENS_MISSING] --card, --card-foreground, --radix-navigation-menu-viewport-height/width: globals.css declares--color-card: hsl(var(--card))in@themebut never defines--card(the app never usesbg-card); the radix vars are set at runtime by NavigationMenu. Harmless; conventions.md steers the agent tobg-neutral-900for cards.- First-sync floor cards flagged
[RENDER_BLANK]for ActivitySlider/Checkbox/Input/Progress/Slider/ Textarea/TimelineSlider β gone once previews were authored; a re-sync that drops a preview will bring one back.
Re-sync risks
- Vendored Inter subsets in
pkg/fonts/are a snapshot of next/font output; if the app changes fonts, re-copy fromclient/.next/static/media(the.p.woff2= latin) and updatesrc/styles.cssranges. .ds-sync/must be staged +npm i esbuild ts-morph @types/react [email protected](chromium-1234 cache) BEFOREbuild.mjs, which borrows esbuild from there. A newer chromium cache needs the matching playwright orDS_CHROMIUM_PATH.- The safelist in
pkg/src/styles.cssis hand-curated: new token families added to globals.css (a new colour role, a new radius) must be appended there or the design agent can't reach them. componentSrcMapnulls enumerate 134 sub-part exports by name. A NEW ui file with new PascalCase parts will surface each part as its own card until its parts are added asnull(and adocs/<Name>.mdwith acategory:is written) β thecomponents:count jumping past 39 is the tell.- Toaster's Success cell depends on capture finishing within ~2s of load (react-hot-toast auto-dismiss).
- Previews assume the capture clock is pinned to 2024-05-15 (Calendar) and a 720px-wide single-card viewport for ResponsiveDialog's dialog branch.
- Capture stamps for AlertDialog/Sheet/Drawer/ResponsiveDialog/Popover/Tooltip were first minted from a scratch copy of ds-bundle (batch C worked around [CONFIG_STALE]); they carried forward cleanly on the final driver run, so no action β noted only in case a future run reports them as cleared.
pkg/build.mjsrunstscover client sources understrict; type errors are printed but do not block emit. Ifdist/types/.design-sync/pkg/src/index.d.tsdisappears, the build exits 1.