From 6a469237107d7e1a31c01e4c0b5dc0a10e59c422 Mon Sep 17 00:00:00 2001 From: Zach Dunn Date: Fri, 14 Aug 2026 09:12:36 -0400 Subject: [PATCH 1/2] chore(design-system): re-sync @uploads/ui to Claude Design MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-sync of the 14-component library to the "Uploads" Claude Design project. All 14 verified-by-upload against the project's `_ds_sync.json` anchor — no component sources changed, so nothing needed re-grading. Three sync inputs corrected along the way: - `Progress` and `Select` now take `cardMode: "column"`. A newer converter measures grid cells differently and flagged both `[GRID_OVERFLOW]`; NOTES.md had recorded them as fitting the default width. Their preview sheets were re-checked after the fix and still grade good. - `conventions.md` now lists `Button`'s `solid` variant and `icon` prop. Both ship real CSS and JSDoc, but the header predated them — the design agent would never have learned `solid` exists. - NOTES.md: the worktree build recipe said `npx tsup`, which emits no declarations (`dts: false` in tsup.config.ts). Corrected to `npm run build`, plus a note that header drift is usually additive rather than renames. Validate exits clean with no warnings; render check 14/14. --- .design-sync/NOTES.md | 25 +++++++++++++++++++++---- .design-sync/config.json | 4 +++- .design-sync/conventions.md | 4 +++- 3 files changed, 27 insertions(+), 6 deletions(-) diff --git a/.design-sync/NOTES.md b/.design-sync/NOTES.md index 2356408e..149848f6 100644 --- a/.design-sync/NOTES.md +++ b/.design-sync/NOTES.md @@ -42,8 +42,13 @@ restage by hand (or copy from main) in those worktrees. with **tsup** → `packages/ui/dist/{index.js,index.d.ts,uploads-ui.css}`. - `cfg.buildCmd` = `pnpm --filter @uploads/ui build`. That needs the package's devDeps installed. In an isolated worktree with no workspace install, build it - standalone: `cd packages/ui && npm install --no-save --no-package-lock && npx tsup` + standalone: `cd packages/ui && npm install --no-save --no-package-lock && npm run build` (npm avoids pnpm workspace resolution; approve the esbuild postinstall). + **Use `npm run build`, not `npx tsup`.** `tsup.config.ts` sets `dts: false`, so + tsup alone emits only `index.js` + `uploads-ui.css`; the 12 `.d.ts` files come + from the second half of the build script (`tsc -p tsconfig.build.json + --emitDeclarationOnly --outDir dist`). Skip it and every `Props` contract + the design agent codes against degrades silently. - Converter invocation (from repo root): `node .ds-sync/package-build.mjs --config .design-sync/config.json --node-modules packages/ui/node_modules --entry ./packages/ui/dist/index.js --out ./ds-bundle` `PKG_DIR` is walked up from `--entry`, so the entry must be the real @@ -88,9 +93,15 @@ restage by hand (or copy from main) in those worktrees. - Playwright + chromium live under `.ds-sync/node_modules` (see restage above — install with the other converter deps in one `npm i`). On a fresh clone the `.ds-sync/` tree is gitignored and regenerated, so reinstall before validating. -- 5 components use `cfg.overrides..cardMode = "column"` (Button, Divider, - Field, GalleryTile, Panel) to resolve `[GRID_OVERFLOW]` — their previews are wider - than a grid cell. Not a warn once the override is applied. +- 7 components use `cfg.overrides..cardMode = "column"` (Button, Divider, + Field, GalleryTile, Panel, Progress, Select) to resolve `[GRID_OVERFLOW]` — their + previews are wider than a grid cell. Not a warn once the override is applied. +- **Progress and Select were added to that list on the 2026-08-14 re-sync.** The + 2026-08-14 sync recorded them as fitting the default card width; a later converter + measures grid cells differently and flagged both `[GRID_OVERFLOW]` (`wide`). If a + future converter flags more components the same way, the remedy is the same one + the warn names — merge `cardMode: "column"`, then + `preview-rebuild.mjs --components `; grades carry through it. - No `[RENDER_THIN]` / `variants-identical` warns to record — all cells graded good. - **Progress** and **Select** were added to `@uploads/ui` and authored on the 2026-08-14 sync (`previews/Progress.tsx`, `previews/Select.tsx`) — 3 cells each, @@ -110,6 +121,12 @@ restage by hand (or copy from main) in those worktrees. - `.design-sync/conventions.md` enumerates real tokens/props/components validated against the build. If `packages/ui` renames a token or component, re-validate the header (the base skill's conventions step does this) and fix drift. + **Drift is usually additive, not renames** — the 2026-08-14 re-sync found + `Button.variant` had gained `"solid"` (a real variant with its own + `ul-btn--solid` CSS) while the header still listed only four. Nothing the header + named was wrong, so a name-existence check alone passes; also diff each + enumerated union against the fresh `.d.ts` for *added* members, or the + design agent never learns the new option exists. - The scoped `npm install` in `packages/ui` writes no lockfile (`--no-package-lock`), so the exact tsup/esbuild versions aren't pinned there — the committed `package.json` ranges are the source of truth. A real `pnpm install` at repo root diff --git a/.design-sync/config.json b/.design-sync/config.json index c1be0071..998b4437 100644 --- a/.design-sync/config.json +++ b/.design-sync/config.json @@ -11,6 +11,8 @@ "Divider": { "cardMode": "column" }, "Field": { "cardMode": "column" }, "GalleryTile": { "cardMode": "column" }, - "Panel": { "cardMode": "column" } + "Panel": { "cardMode": "column" }, + "Progress": { "cardMode": "column" }, + "Select": { "cardMode": "column" } } } diff --git a/.design-sync/conventions.md b/.design-sync/conventions.md index 0e23cd40..460c0a86 100644 --- a/.design-sync/conventions.md +++ b/.design-sync/conventions.md @@ -32,7 +32,9 @@ Build every screen inside one. There is **no utility-class vocabulary to author**. Style two ways only: 1. **Component props** carry the design language: - - `Button` — `variant` (`default | primary | ghost | danger`), `size` (`sm | md | lg`), `block` + - `Button` — `variant` (`default | primary | solid | ghost | danger`; `solid` + fills with the accent — at most one per surface), `size` (`sm | md | lg`), + `block`, `icon` - `Callout` — `tone` (`info | ready | error | muted`), `title` - `Badge` — `tone` (`neutral | accent | ok | danger`), `dot` - `Field` — `label`, `hint`, `invalid` From bb5ff591f42d69d33760a31db236fa6b24692cb8 Mon Sep 17 00:00:00 2001 From: Zach Dunn Date: Fri, 14 Aug 2026 09:32:28 -0400 Subject: [PATCH 2/2] fix(design-system): re-sync on top of #664 after a stale-base upload MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The earlier sync in this branch was built from a worktree branched at #663, one commit before #664 landed. It rebuilt and re-uploaded the pre-#664 stylesheet about an hour after that fix merged, restoring the exact `--ul-progress-fill` declaration #664 removed. The Claude Design agent kept reporting the finding against the uploaded CSS and was correct to. Rebased onto `origin/main` (9f0de534), rebuilt, and re-uploaded. The shipped bundle now has zero `--ul-*` custom-property declarations; the token count drops 32 -> 31. Progress still renders three distinct bands through `currentColor` (sheets re-checked, grades held), render check 14/14, validate clean with no warnings. Adds a Re-sync risk note: a sync uploads whatever the tree builds, so a stale base silently reverts merged design-system fixes and the anchor diff cannot catch it — the bundle genuinely changed and reads as a legitimate update. Fetch and check `origin/main` before building, then grep the built bundle for whatever the most recent DS fix removed. --- .design-sync/NOTES.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/.design-sync/NOTES.md b/.design-sync/NOTES.md index 149848f6..6c40566a 100644 --- a/.design-sync/NOTES.md +++ b/.design-sync/NOTES.md @@ -105,13 +105,24 @@ restage by hand (or copy from main) in those worktrees. - No `[RENDER_THIN]` / `variants-identical` warns to record — all cells graded good. - **Progress** and **Select** were added to `@uploads/ui` and authored on the 2026-08-14 sync (`previews/Progress.tsx`, `previews/Select.tsx`) — 3 cells each, - all graded good, no grid override needed (default card width fits). Select is a + all graded good (both later needed `cardMode: "column"`, see above). Select is a new export from `Field.tsx` (`ul-select` / compact `ul-select--sm`); Progress is its own file (`ul-progress__*`, `data-level` fill bands). Both added to `conventions.md`. That brought the DS from 12 → 14 components. ## Re-sync risks +- **Sync from an up-to-date `main`, and check before uploading.** A sync uploads + whatever the working tree builds, so a stale base silently *reverts* merged + design-system fixes in the Claude Design project — the anchor diff can't catch + it, because the bundle genuinely changed and looks like a legitimate update. + This bit us on 2026-08-14: a worktree branched at #663 re-synced ~1h after #664 + merged and re-uploaded the pre-#664 stylesheet, restoring the exact + `--ul-progress-fill` declaration #664 removed. The design agent kept reporting + the finding and was correct. **Run `git fetch && git log --oneline -3 + origin/main` before the build**, and after building grep the bundle for + whatever the most recent DS fix removed + (`grep -c 'ul-progress-fill' ds-bundle/_ds_bundle.css` → expect 0). - **Harness is not in git** — if `.ds-sync/` is missing, restage before build/ validate (see "Converter harness" above). Worktrees only inherit it when main already has a staged copy.