chore(web): design-system reconciliation, both directions (HT-94) - #105
Conversation
📝 WalkthroughWalkthroughThe PR tightens UI fidelity guidance, expands Biome overrides, and standardizes design-system declarations and JSX formatting across core and inbox components. Runtime behavior is preserved except that command shortcuts now accept ChangesDesign-system alignment
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
PR #103 stopped Biome from reformatting web/src/components/ds/ on arrival, but it could not un-mangle the 16 components already there. This does that: each file re-fetched from the Claude Design "Helpthread" project via DesignSync and written byte-for-byte — double quotes, semicolons, original import order and line wrapping restored. Equivalence was proven before overwriting, not assumed. Both the pre-change and post-change trees were formatted through one canonical Biome config and diffed; the diff is empty across all 32 files. So no style value, prop, or branch of logic changed — the whole historical drift really was formatting, and nothing had been hand-edited in the app or moved in the design project. Byte fidelity spot-checked against fresh get_file responses; all 32 files end with a newline and none carry CRLF. Gates (each on its own exit code): biome check . = 0, npm run typecheck = 0, npm run build = 0. Stacked on feat/ht-93-ds-new-primitives — the biome.json override there is a precondition for the biome gate to pass on verbatim files.
The section said improvements go upstream in the design project first. That has not been the working policy: HT-54's screens were built app-first and approved in the app, and TJ's call (2026-07-20) is that approval in the app is approval — the work flows back up. Documents both directions, why ds/ is excluded from Biome (a formatter pass breaks byte comparison as a drift detector), and that a semantic difference found during a re-pull is a finding to escalate rather than something to quietly resolve.
The four new primitives (plus their shared helpers) were promoted into the design project's components/core/ in this ticket. This re-pulls them back down verbatim, so ds/ no longer holds five files that were a conversion rather than a copy — every file under ds/ is now a byte-for-byte copy of its design-project counterpart, which is what CLAUDE.md claims. Round-trip proven byte-exact: the ten re-pulled files were `cmp`'d against the exact bytes uploaded, all identical. Two defects were caught by the normalized-diff pass and fixed upstream first, then re-pulled: - CommandMenu flattened the curly quotes in `Nothing matches “…”` to straight quotes. That is rendered output, so it is a fidelity break, not formatting. - CredentialRow.d.ts narrowed `lastUsed?: Date | null` to `Date`, losing the null the component actually branches on. Three .d.ts signatures deliberately differ from PR #103's: IconKey, IconReply and IconClock take a required `sz`, because unlike IconSearch and IconPlus they carry no default and render wrong without it. The biome.json override gains noAutofocus, useExhaustiveDependencies and noArrayIndexKey. PR #103 suppressed these with inline biome-ignore comments; those are app-lint artifacts and do not belong in verbatim design source, so the suppression moves to the override that already exists for exactly this purpose. The design rationale comments stay in the components. No rule is relaxed outside web/src/components/ds/**. Gates (each on its own exit code): biome check . = 0, npm run typecheck = 0, npm run build = 0.
…-94) TJ approved components/app/ as the home for app-level surface upstream, so the rule it implies gets written down rather than living in one PR thread. core/ is primitives, inbox/ is inbox-specific composition, app/ is whole screens plus the chrome framing them; the test for app/ is that the thing owns a route or wraps all of them. Also records the one place the two sides are deliberately NOT byte-identical: the app/ screens are .tsx here and are converted to presentational .jsx on the way up, unlike ds/ which is a copy. The same taxonomy note is now in the design project's own readme.md.
492cd90 to
8abcaaf
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@web/src/components/ds/core/Avatar.d.ts`:
- Line 13: Update the component declarations to use React.JSX.Element instead of
global JSX.Element in Avatar.d.ts (13-13), EmptyState.d.ts (7-7), MenuItem.d.ts
(9-9), and Skeleton.d.ts (7-7). In DropdownMenu.d.ts (9-9), use
React.JSX.Element | null to reflect its closed-state return value.
In `@web/src/components/ds/core/primitives-support.d.ts`:
- Around line 7-10: Update the declarations for IconKey, IconReply, and
IconClock to make their sz parameters optional, matching the shared svg helper’s
runtime defaults; leave IconSearch unchanged.
In `@web/src/components/ds/inbox/ConversationRow.d.ts`:
- Line 23: Replace the global JSX.Element return type with React.JSX.Element in
ConversationRow.d.ts (23-23), FolderItem.d.ts (12-12), MessageBand.d.ts (19-19),
and ToolbarBand.d.ts (7-7), preserving each declaration’s existing props and
function signatures.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 481c11c5-a8a0-4af9-9b7d-ea5029d93ab4
📒 Files selected for processing (44)
CLAUDE.mdbiome.jsonweb/src/components/ds/core/Avatar.d.tsweb/src/components/ds/core/Avatar.jsxweb/src/components/ds/core/Button.d.tsweb/src/components/ds/core/Button.jsxweb/src/components/ds/core/CommandMenu.d.tsweb/src/components/ds/core/CommandMenu.jsxweb/src/components/ds/core/CredentialRow.d.tsweb/src/components/ds/core/CredentialRow.jsxweb/src/components/ds/core/DropdownMenu.d.tsweb/src/components/ds/core/DropdownMenu.jsxweb/src/components/ds/core/EmptyState.d.tsweb/src/components/ds/core/EmptyState.jsxweb/src/components/ds/core/IconButton.d.tsweb/src/components/ds/core/IconButton.jsxweb/src/components/ds/core/Kbd.d.tsweb/src/components/ds/core/Kbd.jsxweb/src/components/ds/core/MenuItem.d.tsweb/src/components/ds/core/MenuItem.jsxweb/src/components/ds/core/Skeleton.d.tsweb/src/components/ds/core/Skeleton.jsxweb/src/components/ds/core/SnoozePicker.d.tsweb/src/components/ds/core/SnoozePicker.jsxweb/src/components/ds/core/SplitButton.d.tsweb/src/components/ds/core/SplitButton.jsxweb/src/components/ds/core/StatusPill.d.tsweb/src/components/ds/core/StatusPill.jsxweb/src/components/ds/core/TagChip.d.tsweb/src/components/ds/core/TagChip.jsxweb/src/components/ds/core/TextInput.d.tsweb/src/components/ds/core/TextInput.jsxweb/src/components/ds/core/Toast.d.tsweb/src/components/ds/core/Toast.jsxweb/src/components/ds/core/primitives-support.d.tsweb/src/components/ds/core/primitives-support.jsxweb/src/components/ds/inbox/ConversationRow.d.tsweb/src/components/ds/inbox/ConversationRow.jsxweb/src/components/ds/inbox/FolderItem.d.tsweb/src/components/ds/inbox/FolderItem.jsxweb/src/components/ds/inbox/MessageBand.d.tsweb/src/components/ds/inbox/MessageBand.jsxweb/src/components/ds/inbox/ToolbarBand.d.tsweb/src/components/ds/inbox/ToolbarBand.jsx
| style?: React.CSSProperties; | ||
| } | ||
| export declare function Avatar(props: AvatarProps): JSX.Element | ||
| export declare function Avatar(props: AvatarProps): JSX.Element; |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
if rg -n '\bJSX\.Element\b' web/src/components/ds/core --glob '*.d.ts'; then
echo "Replace global JSX.Element declarations with React.JSX.Element."
exit 1
fiRepository: Helpthread/helpthread
Length of output: 3135
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
printf '\n## target declarations\n'
sed -n '1,80p' web/src/components/ds/core/Avatar.d.ts
printf '\n---\n'
sed -n '1,80p' web/src/components/ds/core/DropdownMenu.d.ts
printf '\n---\n'
sed -n '1,80p' web/src/components/ds/core/EmptyState.d.ts
printf '\n---\n'
sed -n '1,80p' web/src/components/ds/core/MenuItem.d.ts
printf '\n---\n'
sed -n '1,80p' web/src/components/ds/core/Skeleton.d.ts
printf '\n## similar uses of React.JSX or import type React\n'
rg -n 'React\.JSX|import type \* as React|import type React' web/src/components/ds/core web/src/components -g '*.d.ts' -g '*.tsx' -g '*.ts' || true
printf '\n## files that already use React.JSX.Element in declarations\n'
rg -n '\bReact\.JSX\.Element\b' web/src/components/ds/core -g '*.d.ts' || trueRepository: Helpthread/helpthread
Length of output: 1652
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
printf '\n## DropdownMenu source and declaration context\n'
sed -n '1,220p' web/src/components/ds/core/DropdownMenu.tsx
printf '\n---\n'
sed -n '1,120p' web/src/components/ds/core/DropdownMenu.d.ts
printf '\n## package / tsconfig hints\n'
sed -n '1,220p' package.json
printf '\n---\n'
find web -maxdepth 2 \( -name 'tsconfig*.json' -o -name 'vite.config.*' -o -name 'biome.json' \) -print | sort | while read -r f; do
echo "### $f"
sed -n '1,220p' "$f"
echo '---'
done
printf '\n## react type/version references\n'
rg -n '"react"|`@types/react`|jsxImportSource|jsx:' package.json web -g 'package.json' -g 'tsconfig*.json' -g 'vite.config.*' -g '*.json' || trueRepository: Helpthread/helpthread
Length of output: 294
🌐 Web query:
React 19 upgrade guide JSX.Element React.JSX global JSX namespace declaration files
💡 Result:
In React 19, the global JSX namespace has been removed to prevent type pollution and conflicts with other UI libraries [1][2][3]. Developers must now use the scoped React.JSX namespace instead [1][4][3]. Key Changes and Migration Steps: 1. Update Code References: Replace all instances of JSX.Element (or other JSX types) with React.JSX.Element by importing the namespace from the react package [4][5]: import { JSX } from 'react'; // Use JSX.Element as before, now correctly scoped 2. Automated Migration: You can use the types-react-codemod tool to automatically update your codebase. The scoped-jsx preset is specifically designed to migrate deprecated global JSX references to React.JSX [1][6][2]: npx types-react-codemod scoped-jsx. 3. Module Augmentation: If your project relies on module augmentation to extend the JSX namespace (e.g., for custom elements), you must update your declaration files to augment the react module instead of the global scope [1][2][7]. Old way (Global): declare global { namespace JSX { interface IntrinsicElements { "my-element": { myProp: string }; } } } New way (Scoped): declare module "react" { namespace JSX { interface IntrinsicElements { "my-element": { myProp: string }; } } } The exact module specifier (e.g., "react", "react/jsx-runtime", or "react/jsx-dev-runtime") in your declare module block depends on the "jsx" compiler option set in your tsconfig.json [1][7]. Most standard configurations use "react" [1]. If you encounter "Cannot find namespace 'JSX'" errors in third-party dependencies after upgrading, those packages likely still reference the deprecated global namespace and may require updates or patch-package resolutions [8][9].
Citations:
- 1: https://react.dev/blog/2024/04/25/react-19-upgrade-guide
- 2: [react] Types for React 19 DefinitelyTyped/DefinitelyTyped#69022
- 3: https://github.com/react/react/blob/refs/heads/main/CHANGELOG.md
- 4: @types/react - Cannot find namespace 'JSX' DefinitelyTyped/DefinitelyTyped#74625
- 5: [lexical-react] Bug Fix: Import
JSXtype from React to prevent "Cannot find namespace 'JSX'"-error when type-checking with React 19 facebook/lexical#7080 - 6: Replace usage of deprecated
JSXglobal namespace withReact.JSXreduxjs/redux-toolkit#4381 - 7: [@types/react] does not exist on type 'JSX.IntrinsicElements'.ts after upgrade to react 19 and @types/react 19.0.1 DefinitelyTyped/DefinitelyTyped#71395
- 8: Cannot find namespace 'JSX' error when using React 19 types styled-components/styled-components#4359
- 9: With React 19 typings: Cannot find namespace 'JSX'. clauderic/dnd-kit#1559
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
echo "## package.json"
sed -n '1,220p' package.json
echo
echo "## tsconfig files"
find . -maxdepth 3 \( -name 'tsconfig*.json' -o -name 'package.json' \) | sort | while read -r f; do
echo "### $f"
sed -n '1,220p' "$f"
echo "---"
done
echo
echo "## dropdown menu source location"
fd -a 'DropdownMenu.*' web/src/components/ds/core
echo
echo "## any React 19 type references in repo"
rg -n '"react":|"`@types/react`":|jsxImportSource|React\.JSX|Cannot find namespace \'JSX\'' . -g 'package.json' -g 'tsconfig*.json' -g '*.d.ts' -g '*.ts' -g '*.tsx' || trueRepository: Helpthread/helpthread
Length of output: 50378
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
echo "## web/package.json"
sed -n '1,220p' web/package.json
echo
echo "## web tsconfig files"
find web -maxdepth 2 \( -name 'tsconfig*.json' -o -name 'package.json' \) | sort | while read -r f; do
echo "### $f"
sed -n '1,220p' "$f"
echo "---"
done
echo
echo "## React / JSX references in web workspace"
rg -n '"react":|"`@types/react`":|jsxImportSource|React\.JSX|namespace JSX|Cannot find namespace \'JSX\'' web -g 'package.json' -g 'tsconfig*.json' -g '*.d.ts' -g '*.ts' -g '*.tsx' || trueRepository: Helpthread/helpthread
Length of output: 2450
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
echo "## DropdownMenu files"
fd -a 'DropdownMenu' web/src/components/ds/core
echo
echo "## core declaration files with JSX.Element"
rg -n '\bJSX\.Element\b' web/src/components/ds/core -g '*.d.ts'
echo
echo "## possible source files for DropdownMenu"
fd -a 'DropdownMenu.*' web/src/components/ds/core web/src/components || true
echo
echo "## search for 'return null' near DropdownMenu"
rg -n -C 3 'return null|DropdownMenu' web/src/components/ds/core web/src/components -g '*.ts' -g '*.tsx' -g '*.d.ts' || trueRepository: Helpthread/helpthread
Length of output: 16459
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
sed -n '1,220p' web/src/components/ds/core/DropdownMenu.jsxRepository: Helpthread/helpthread
Length of output: 854
Use React.JSX.Element in these declarations
These declarations still use the global JSX.Element return type; switch them to React.JSX.Element for the React 19 typings. DropdownMenu also needs | null because it returns null when closed.
web/src/components/ds/core/Avatar.d.tsweb/src/components/ds/core/DropdownMenu.d.tsweb/src/components/ds/core/EmptyState.d.tsweb/src/components/ds/core/MenuItem.d.tsweb/src/components/ds/core/Skeleton.d.ts
📍 Affects 5 files
web/src/components/ds/core/Avatar.d.ts#L13-L13(this comment)web/src/components/ds/core/DropdownMenu.d.ts#L9-L9web/src/components/ds/core/EmptyState.d.ts#L7-L7web/src/components/ds/core/MenuItem.d.ts#L9-L9web/src/components/ds/core/Skeleton.d.ts#L7-L7
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@web/src/components/ds/core/Avatar.d.ts` at line 13, Update the component
declarations to use React.JSX.Element instead of global JSX.Element in
Avatar.d.ts (13-13), EmptyState.d.ts (7-7), MenuItem.d.ts (9-9), and
Skeleton.d.ts (7-7). In DropdownMenu.d.ts (9-9), use React.JSX.Element | null to
reflect its closed-state return value.
| export declare function IconKey(sz: number): JSX.Element; | ||
| export declare function IconSearch(sz?: number): JSX.Element; | ||
| export declare function IconReply(sz: number): JSX.Element; | ||
| export declare function IconClock(sz: number): JSX.Element; |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'Repo root: '; pwd
# Locate the relevant files and any obvious consumers.
git ls-files 'web/src/components/ds/core/primitives-support.*' 'web/src/components/ds/**/*' | sed -n '1,120p'
printf '\n--- outline primitives-support.d.ts ---\n'
ast-grep outline web/src/components/ds/core/primitives-support.d.ts --view expanded || true
printf '\n--- outline primitives-support.jsx ---\n'
ast-grep outline web/src/components/ds/core/primitives-support.jsx --view expanded || true
printf '\n--- search for IconKey/IconReply/IconClock usages without args ---\n'
python3 - <<'PY'
from pathlib import Path
import re
files = [Path(p) for p in Path('web/src').rglob('*.[tj]s*')]
targets = ['IconKey', 'IconReply', 'IconClock']
pattern = re.compile(r'\b(' + '|'.join(targets) + r')\b')
for path in files:
try:
text = path.read_text()
except Exception:
continue
for m in pattern.finditer(text):
# crude check: line containing name
line_no = text.count('\n', 0, m.start()) + 1
line = text.splitlines()[line_no-1]
if re.search(r'\b' + re.escape(m.group(1)) + r'\s*\(\s*\)', line):
print(f"{path}:{line_no}:{line.strip()}")
PY
printf '\n--- show relevant file snippets ---\n'
sed -n '1,120p' web/src/components/ds/core/primitives-support.d.ts
printf '\n'
sed -n '1,160p' web/src/components/ds/core/primitives-support.jsxRepository: Helpthread/helpthread
Length of output: 8441
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '1,120p' web/src/components/ds/core/primitives-support.d.ts
printf '\n---\n'
sed -n '1,180p' web/src/components/ds/core/primitives-support.jsxRepository: Helpthread/helpthread
Length of output: 5272
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Check whether this declaration file is part of a public barrel/export surface.
rg -n --hidden --glob '!**/node_modules/**' \
'primitives-support' \
web/src package.json . | sed -n '1,200p'
printf '\n--- nearby exports/index files under ds ---\n'
git ls-files 'web/src/components/ds/**/index.*' 'web/src/components/ds/**/*.*' | sed -n '1,120p'
printf '\n--- consumers of IconKey/IconReply/IconClock in TypeScript/JSX ---\n'
rg -n --hidden --glob '!**/node_modules/**' \
'\b(IconKey|IconReply|IconClock)\b' web/src | sed -n '1,200p'Repository: Helpthread/helpthread
Length of output: 4801
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- imports/usages of the icon exports ---'
rg -n --hidden --glob '!**/node_modules/**' '\b(import|export).*\b(IconKey|IconReply|IconClock)\b|\b(IconKey|IconReply|IconClock)\b' web/src | sed -n '1,220p'
printf '\n--- package metadata / build entry points mentioning ds core ---\n'
rg -n --hidden --glob '!**/node_modules/**' 'components/ds/core|primitives-support|exports' package.json web/src | sed -n '1,220p'Repository: Helpthread/helpthread
Length of output: 2811
Keep sz optional here
IconKey, IconReply, and IconClock all default through the shared svg helper, so the declarations should stay sz?: number to match the runtime contract.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@web/src/components/ds/core/primitives-support.d.ts` around lines 7 - 10,
Update the declarations for IconKey, IconReply, and IconClock to make their sz
parameters optional, matching the shared svg helper’s runtime defaults; leave
IconSearch unchanged.
Source: Coding guidelines
| onClick?: () => void; | ||
| } | ||
| export declare function ConversationRow(props: ConversationRowProps): JSX.Element | ||
| export declare function ConversationRow(props: ConversationRowProps): JSX.Element; |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
rg -n '"`@types/react`"|react' package.json package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null || true
rg -n '\bJSX\.Element\b' web/src/components/ds/inbox/*.d.tsRepository: Helpthread/helpthread
Length of output: 2042
🌐 Web query:
React 19 @types/react JSX.Element React.JSX.Element global JSX namespace compatibility
💡 Result:
In React 19 and @types/react v19, the global JSX namespace has been removed to improve interoperability and prevent type collisions with other libraries [1][2][3]. Compatibility and Changes: - Global Namespace Removal: You can no longer rely on a global JSX namespace. Instead, types are now scoped to the react package [1][4][2]. - Accessing Types: Where you previously used JSX.Element, you should now use React.JSX.Element (by importing React from 'react') or JSX.Element (by importing JSX directly from 'react') [4][5][6]. - Module Augmentation: If you previously used declare global { namespace JSX { ... } } to extend intrinsic elements (e.g., for custom web components), this will no longer work globally [7][8]. You must now use declare module scoped to the React types [1][8]: // Example of how to augment JSX in React 19 declare module "react" { namespace JSX { interface IntrinsicElements { "my-custom-element": { propName: string }; } } } The specific module name you use ("react", "react/jsx-runtime", or "react/jsx-dev-runtime") depends on your TypeScript compilerOptions.jsx configuration [1][7][8]. Migration: The types-react-codemod tool provides a scoped-jsx preset designed to help automate the transition of your codebase to these new import requirements [1][7][6]. Manual refactoring involves updating references from the global JSX namespace to imports from the react package [4][6].
Citations:
- 1: https://react.dev/blog/2024/04/25/react-19-upgrade-guide
- 2: https://github.com/react/react/releases/tag/v19.0.0
- 3: https://github.com/facebook/react/blob/ee0855f427832e899767f7659c5289364218ab9e/CHANGELOG.md
- 4: @types/react - Cannot find namespace 'JSX' DefinitelyTyped/DefinitelyTyped#74625
- 5: https://stackoverflow.com/questions/76224848/what-is-the-correct-return-type-replacement-for-jsx-element-after-the-global-jsx
- 6: https://github.com/eps1lon/types-react-codemod
- 7: [react] Types for React 19 DefinitelyTyped/DefinitelyTyped#69022
- 8: [@types/react] does not exist on type 'JSX.IntrinsicElements'.ts after upgrade to react 19 and @types/react 19.0.1 DefinitelyTyped/DefinitelyTyped#71395
Use React.JSX.Element here
These declarations still use the global JSX.Element return type. With React 19 typings, switch ConversationRow.d.ts, FolderItem.d.ts, MessageBand.d.ts, and ToolbarBand.d.ts to React.JSX.Element.
📍 Affects 4 files
web/src/components/ds/inbox/ConversationRow.d.ts#L23-L23(this comment)web/src/components/ds/inbox/FolderItem.d.ts#L12-L12web/src/components/ds/inbox/MessageBand.d.ts#L19-L19web/src/components/ds/inbox/ToolbarBand.d.ts#L7-L7
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@web/src/components/ds/inbox/ConversationRow.d.ts` at line 23, Replace the
global JSX.Element return type with React.JSX.Element in ConversationRow.d.ts
(23-23), FolderItem.d.ts (12-12), MessageBand.d.ts (19-19), and ToolbarBand.d.ts
(7-7), preserving each declaration’s existing props and function signatures.
Adjudicating CodeRabbit's three findingsAll three are the same issue — the global This repo is on Not fixing it here, deliberately, for two reasons.
Tracked as HT-97, which also covers the matching This is a good catch that only surfaced because the base was retargeted to |
… (HT-97) (#111) Every .d.ts under web/src/components/ds/ declared its return type as the GLOBAL `JSX.Element`. React 19 removed that namespace, and this repo runs react / @types/react ^19.2.4, so those 34 declarations resolved to nothing. CI never caught it because web/tsconfig.json sets skipLibCheck: true, which skips declaration-file checking entirely — the build and typecheck were green over broken types the whole time. Found by CodeRabbit on PR #105. Fixed UPSTREAM FIRST in the Claude Design project, then re-pulled verbatim, per the bidirectional policy in CLAUDE.md — editing these copies directly would have broken the verbatim invariant on 21 files. All 26 upstream .d.ts were fixed (including the five components/app/ screens that live only in the design project); the 21 that mirror into ds/ came back down here. `React.JSX.Element` rather than an added import: these files already use `React.ReactNode` and `React.CSSProperties` off the UMD global without importing React, and those resolve fine — only the bare `JSX` namespace did not. This keeps the house style unchanged. Verified: - tsc --noEmit --types react over ds/**/*.d.ts WITHOUT --skipLibCheck: exit 0, 0 errors (was exit 2, 29 x TS2503 "Cannot find namespace 'JSX'") - the diff contains no line that isn't a JSX.Element qualification - all 21 files byte-identical to the design project after the re-pull - upload read back and compared before re-pulling, since a write_files reporting success is not proof it applied (learned the hard way in HT-94) Gates (each on its own exit code): biome check . = 0, npm run typecheck = 0, npm run build = 0.
1 participant
Closes HT-94. Follow-up to HT-93 / #103.
Why
web/src/components/ds/is supposed to hold verbatim copies of the Claude Design "Helpthread" project. Two things had broken that:A — the 16 existing components, re-pulled verbatim
All 32 files (
.jsx+.d.ts) re-fetched via DesignSync and written byte-for-byte.Equivalence was proven before overwriting, not assumed. The pre-change and post-change trees were both formatted through one canonical Biome config and diffed: empty diff, all 32 files. No style value, prop, or branch of logic changed. Nothing had been hand-edited in the app and the design had not moved — the whole historical drift really was formatting. No escalation needed.
B + C — pushed upstream (design project, already written)
components/core/gains SplitButton, CommandMenu, SnoozePicker, CredentialRow + PasskeyList, andprimitives-support, promoted out oftemplates/new-primitives/into the library, in that project's house style.components/app/is new: TopBar, SettingsScreen, SetupScreen, TeamListScreen, NewAgentScreen — converted from.tsxwith API wiring to presentational.jsxwith fixture data.readme.md's index and its closing "intentional additions" note now describe the bidirectional policy.Style fidelity on the conversion was checked mechanically, not by eye: CSS-token, px and hex-colour multisets are identical between each app source and its upstream counterpart, counts included, and zero user-visible copy strings went missing.
The loop, closed
The five primitives #103 added to
ds/were acreateElement→JSX conversion, not a copy — sods/held 27 verbatim files and 5 that weren't, contradicting the very invariant this PR documents. Now that they exist upstream in house style, they are re-pulled: every file underds/is byte-for-byte its design-project counterpart. Round-trip proven withcmpagainst the exact uploaded bytes — all 10 identical.Two defects the diff caught
Both fixed upstream first, then re-pulled — the design project stays the source of truth:
Nothing matches “…”to straight quotes. That is rendered output, so a fidelity break rather than formatting.CredentialRow.d.tsnarrowedlastUsed?: Date | nulltoDate, dropping the null the component actually branches on.Lint suppressions moved, not removed
#103 held five findings back with inline
biome-ignorecomments. Those are app-lint artifacts and have no place in verbatim design source, so the suppression moves into theds/**override that already exists for this purpose (noAutofocus,useExhaustiveDependencies,noArrayIndexKey). The design rationale comments stay in the components. No rule is relaxed outsideweb/src/components/ds/**.Docs
CLAUDE.md's UI fidelity section said improvements go upstream first. That was never the working policy — HT-54 was built app-first and approved in the app. It now documents both directions, whyds/is excluded from Biome, and that a semantic difference found during a re-pull is a finding to escalate rather than resolve in passing.Verification
./node_modules/.bin/biome check .npm run typecheck(web)npm run build(web)Reviewer attention
npx biomein this repo resolves to an unrelated stub package at version 0.3.3, not Biome 2.5.4. It exits 0 while processing zero files. The real binary is./node_modules/.bin/biomeat the repo root, and rootnpm installis required —web/alone is not enough. Any past or future "biome passed" claim made vianpx biomeis worthless. Biome also silently skips dot-directories and, withvcs.useIgnoreFile, untracked files.The claim most worth checking is pixel fidelity on the Task C conversion — that no style value drifted while stripping the server actions. The token/px/colour multiset checks cover presence and count, but not position.
🤖 Generated with Claude Code
Summary by CodeRabbit
Refactor
Documentation
Chores