Skip to content

πŸ™Œ OpenHands: AI-Driven Development

chore(lint): reject unknown Tailwind classes with verified theme loading (#17644)

🐾 smolpaws8bb2293410c3
diff --git a/.pr/lint-verification.md b/.pr/lint-verification.md
new file mode 100644
index 0000000000..3689ea5d3a
--- /dev/null
+++ b/.pr/lint-verification.md
@@ -0,0 +1,87 @@
+# Unknown-class lint adoption
+
+Base: `a3cfe98267c52937dc4e91a55644a6131c6c01bc`. Pinned linter: `@shadcn/[email protected]`.
+
+The rule is enabled at error level now that its initial findings are resolved. Four inert class usages are also removed; generated styling and the DOM structure are preserved.
+
+## Inventory
+
+`npx eslint src --rule 'shadcn/no-unknown-classes:warn' --format json` initially reported **6** unknown-class warnings, alongside **347** existing arbitrary-value warnings. No theme-loading or worker-fallback warnings were emitted.
+
+Two exact exceptions are supported by code:
+
+- `environment-switch-overlay`: `src/index.css:134` uses it to animate child elements; that stylesheet is outside the Tailwind theme import graph.
+- `conversation-overview-diffs-git-action`: a selector target in `src/components/features/conversation/conversation-overview-diffs-row.tsx:40` for clearing row hover while the action is hovered.
+
+All **4 genuine findings are fixed** by removing inert classes:
+
+| File | Finding and correction |
+| --- | --- |
+| `src/components/features/chat/drag-over.tsx` | Remove `drag-over-content`, which has no stylesheet or selector consumer; retain the wrapper element. |
+| `src/components/features/home/repo-selection-form.tsx` | Remove `max-w-auto`, which emits no CSS. |
+| `src/components/features/home/workspace-selection-form.tsx` | Remove the same unsupported width class. |
+| `src/utils/form-control-classes.ts` | Remove unsupported `ease`; retain the existing transform transition, duration, reduced-motion handling, and default timing. |
+
+The dropdowns pass the optional class to `cn("relative", className)`; removing it does not reveal a previously overridden maximum width. Do not substitute `min-w-auto`: minimum width is a different property. Likewise, connecting the drag overlay to the similarly named `.drag-over-ui-content` rule would newly force white text and fixed typography. That is a separate visual decision, not necessary to remove an unused marker.
+
+`node .pr/verify-inert-classes.mjs` verifies identical compiled CSS before/after removal with the actual Tailwind theme/plugins and checks that class merging preserves all valid utilities. A repository search found no CSS/JS/test consumers of the removed marker or utilities. The transition helper is shared by caret controls in both standalone and embedded Canvas, independent of backend/agent type; it retains its existing behavior in all consumers.
+
+## Reproduction
+
+Run `node .pr/verify-unknown-classes.mjs` from the repository root. It uses the actual ESLint config and virtual TSX under `src/ui`, verifying that the rule remains active inside component implementations.
+
+Observed output:
+
+```text
+"hovr:flex" ... Did you mean "hover:flex"?
+"flex-cols" ... Did you mean "flex-col"?
+"environment-switch-overla" ... no CSS is generated for it.
+PASS: real theme/plugins accepted; typos are errors; exceptions stay exact.
+```
+
+Accepted: Canvas surface/border/focus tokens, `prose`, `scrollbar-hide`, a HeroUI color with a data variant, and the two documented markers. This also detects the documented fallback mode that incorrectly accepts `hovr:flex`.
+
+## Original adoption checks
+
+Executed with Node 22.23.2, npm 10.9.8 on macOS (CI's supported Node environment should also run its normal checks):
+
+- `npm run lint`: passed, **0 errors / 351 warnings** (347 existing + 4 new genuine findings).
+- `npm run build`: passed.
+- `npm run build:lib`: passed.
+- `npm test -- --maxWorkers=2`: **733 files passed / 1 failed; 7,718 tests passed / 1 failed / 7 todo**. The existing `DeleteProfileModal > calls deleteProfile and shows success toast on successful delete` assertion expected a success-toast call but observed zero. No runtime source changed in this branch. Rerunning that file alone passed all 12 tests; the full-suite failure remains disclosed.
+- Initial sandboxed test attempt was stopped because launcher tests could not bind local ports. Results above are from the rerun with port access.
+
+The pinned rule delegates some missing color-token diagnostics to `no-raw-colors`; it is not a complete missing-token guard, nor does it detect the semantic `text-base` collision. Other rules retain their original settings.
+
+This directory is PR-only evidence. Fork PRs require manual `.pr/` cleanup before merge.
+
+## Warning cleanup checks
+
+- `node .pr/verify-inert-classes.mjs`: passed; merged valid classes and compiled CSS are identical for all removals.
+- `node .pr/verify-unknown-classes.mjs`: passed; valid theme/plugin utilities and exact selector exceptions accepted while typos remain reported.
+- `npm run lint`: passed, **0 unknown-class warnings / 347 existing arbitrary-value warnings / 0 errors**; formatting and TypeScript checks passed.
+- `npx vitest run __tests__/components/features/home/repo-selection-form.test.tsx __tests__/components/features/home/workspace-selection-form.test.tsx __tests__/components/features/home/git-repo-dropdown.test.tsx __tests__/components/features/home/workspace-dropdown.test.tsx __tests__/utils/form-control-classes.test.ts --maxWorkers=2`: **5 files / 69 tests passed**.
+- `npm run build` and `npm run build:lib`: passed.
+- No visual change is claimed: the removed classes have no styling or selector consumers, and the compiled CSS comparison above is identical. The PR also includes real-app workspace screenshots to satisfy frontend evidence CI; they are a smoke comparison, not pixel-diff coverage of every component.
+- The original PR head passed Ubuntu and Windows test/build CI. The checks above disclose the earlier local full-suite flake; no new tests or weakened assertions were introduced for inert class removal.
+
+### Real-app screenshot setup
+
+`PATH=/opt/homebrew/opt/node@22/bin:$PATH VITE_DO_NOT_TRACK=1 npm run dev:mock -- --host 127.0.0.1 --port 3196 --strictPort`
+
+Open Workspace in the real Canvas UI using MSW data. `workspace-before.png` uses the four affected source files from `0bfdebb`; `workspace-after.png` uses `a35e74e`. The same running app applied the revisions through Vite HMR. No live LLM or credentials were used. The workspace field and its shared caret retain their appearance; compiler/merge parity covers all four removals.
+
+## Error-level enforcement after updating from main
+
+Merged upstream main at `35dc8aafaad2d883cf0c6629dea857eb2235895e` following [review 5297880470](https://github.com/OpenHands/OpenHands/pull/17644#pullrequestreview-5297880470). With the initial findings resolved, `shadcn/no-unknown-classes` is now `error`; both exact exceptions and every other rule setting are unchanged. This supersedes the issue's original warning-level rollout. CI continues to use ordinary `npm run lint`, without a warning-count gate.
+
+Verified on the merged tree with a fresh `npm ci` (Node 22.23.2):
+
+- `npm run lint`: passed, **zero unknown-class findings / zero errors / 376 existing `shadcn/no-arbitrary-values` warnings**. TypeScript and formatting checks also passed.
+- `node .pr/verify-unknown-classes.mjs`: passed; each deliberately invalid utility/variant is severity 2, representative project/plugin utilities are accepted, and exceptions remain exact.
+- Real CLI negative check: created a temporary `src/ui/lint-rule-probe-*.tsx` containing `export const Probe = () => <div className="hovr:flex" />;`, ran `node node_modules/eslint/bin/eslint.js <file> --format json`, then removed the file in `finally`. **Exit 1**, exactly one error, from `shadcn/no-unknown-classes`; no parser/fatal error. The earlier stdin attempt was unsuitable for the project-aware parser, so the final check used an actual source file.
+- `node .pr/verify-inert-classes.mjs`: passed; the merged theme still generates identical CSS for the removals.
+- The five form/dropdown/helper test files listed above: **70 tests passed** on current main.
+- `npm run build` and `npm run build:lib`: passed.
+
+Full-suite CI will rerun on the pushed merge. The historical checks above refer to earlier heads; no new full-suite local result is claimed here.
diff --git a/.pr/verify-inert-classes.mjs b/.pr/verify-inert-classes.mjs
new file mode 100644
index 0000000000..5bbda09eaa
--- /dev/null
+++ b/.pr/verify-inert-classes.mjs
@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { compile } from "@tailwindcss/node";
+import { twMerge } from "tailwind-merge";
+
+// PR-only evidence: run from the repository root with installed dependencies.
+// These are the affected elements' class combinations, including the shared
+// caret transition helper. Removal must not resurrect a merged-away utility.
+const pairs = [
+ ["drag-over-content", ""],
+ ["relative max-w-auto", "relative"],
+ [
+ "transition-[transform] ease duration-75 motion-reduce:transition-none",
+ "transition-[transform] duration-75 motion-reduce:transition-none",
+ ],
+];
+const stylesheet = readFileSync("src/tailwind.css", "utf8");
+async function css(classes) {
+ const compiler = await compile(stylesheet, {
+ base: resolve("src"),
+ onDependency() {},
+ });
+ return compiler.build(twMerge(classes).split(/\s+/).filter(Boolean));
+}
+for (const [before, after] of pairs) {
+ assert.equal(await css(before), await css(after));
+ assert.equal(
+ twMerge(before)
+ .split(/\s+/)
+ .filter((c) => !["drag-over-content", "max-w-auto", "ease"].includes(c))
+ .join(" "),
+ twMerge(after),
+ );
+}
+console.log(
+ "PASS: merged valid classes and compiled CSS are identical for all removals.",
+);
diff --git a/.pr/verify-unknown-classes.mjs b/.pr/verify-unknown-classes.mjs
new file mode 100644
index 0000000000..3fca1842ed
--- /dev/null
+++ b/.pr/verify-unknown-classes.mjs
@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import { ESLint } from "eslint";
+
+// Run from the repository root: node .pr/verify-unknown-classes.mjs
+// Use the real flat config and theme, but let lintText accept a virtual TSX file.
+const eslint = new ESLint({
+ overrideConfig: [
+ {
+ languageOptions: { parserOptions: { project: null } },
+ rules: { "@typescript-eslint/prefer-optional-chain": "off" },
+ },
+ ],
+});
+const classes = [
+ "hovr:flex",
+ "flex-cols", // Deliberate mistakes; also detect grammar fallback.
+ "bg-surface-raised",
+ "border-border-input",
+ "ring-focus", // Canvas theme.
+ "prose",
+ "scrollbar-hide",
+ "data-[hover=true]:bg-default-100", // Plugins.
+ "environment-switch-overlay",
+ "conversation-overview-diffs-git-action", // Exceptions.
+ "environment-switch-overla", // A nearby typo must still be reported.
+];
+const [result] = await eslint.lintText(
+ `export const probe = <div className="${classes.join(" ")}" />;`,
+ { filePath: "src/ui/lint-probe.tsx" },
+);
+assert.equal(result.fatalErrorCount, 0);
+const findings = result.messages.filter(
+ (m) => m.ruleId === "shadcn/no-unknown-classes",
+);
+assert.deepEqual(findings.map((m) => m.message.match(/^"([^"]+)"/)[1]).sort(), [
+ "environment-switch-overla",
+ "flex-cols",
+ "hovr:flex",
+]);
+for (const finding of findings) {
+ assert.equal(finding.severity, 2);
+ console.log(finding.message);
+}
+
+console.log(
+ "PASS: real theme/plugins accepted; typos are errors; exceptions stay exact.",
+);
diff --git a/.pr/workspace-after.png b/.pr/workspace-after.png
new file mode 100644
index 0000000000..149a0d868b
Binary files /dev/null and b/.pr/workspace-after.png differ
diff --git a/.pr/workspace-before.png b/.pr/workspace-before.png
new file mode 100644
index 0000000000..9236b6fa4a
Binary files /dev/null and b/.pr/workspace-before.png differ
diff --git a/eslint.config.js b/eslint.config.js
index ef1c4080fd..4f0f137f72 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -395,7 +395,8 @@ export default [
// Rules: https://github.com/shadcn-ui/lint#rules
// `no-arbitrary-values` stays at "warn": the remaining hits are one-offs
// (raw hex, vh/vw, calc(), grid templates) with no theme-scale equivalent.
- // The other rules need per-component contracts before they are useful here.
+ // Class existence does not need component contracts. With no remaining
+ // unknown utilities, new findings fail lint; styling policy remains opt-in.
{
files: ["src/**/*.{ts,tsx}"],
plugins: { shadcn: shadcnPlugin },
@@ -405,7 +406,17 @@ export default [
"shadcn/no-raw-colors": "off",
"shadcn/no-inline-styles": "off",
"shadcn/require-static-classes": "off",
- "shadcn/no-unknown-classes": "off",
+ "shadcn/no-unknown-classes": [
+ "error",
+ {
+ allow: [
+ // src/index.css owns the overlay animation outside the theme graph.
+ "environment-switch-overlay",
+ // Selector target for has-[.conversation-overview-diffs-git-action:hover].
+ "conversation-overview-diffs-git-action",
+ ],
+ },
+ ],
},
},
];
diff --git a/src/components/features/chat/drag-over.tsx b/src/components/features/chat/drag-over.tsx
index 60695ad2cf..90dc5030c5 100644
--- a/src/components/features/chat/drag-over.tsx
+++ b/src/components/features/chat/drag-over.tsx
@@ -21,7 +21,7 @@ export function DragOver() {
className="absolute top-[-16px] left-[-20px]"
/>
</div>
- <div className="drag-over-content">
+ <div>
<p>{t(I18nKey.COMMON$DROP_YOUR_FILES_HERE)}</p>
</div>
</div>
diff --git a/src/components/features/home/repo-selection-form.tsx b/src/components/features/home/repo-selection-form.tsx
index ea95086e79..fd0f523495 100644
--- a/src/components/features/home/repo-selection-form.tsx
+++ b/src/components/features/home/repo-selection-form.tsx
@@ -151,7 +151,6 @@ export function RepositorySelectionForm({
placeholder="user/repo"
disabled={!selectedProvider || isLoadingSettings}
onChange={handleRepoSelection}
- className="max-w-auto"
/>
);
};
diff --git a/src/components/features/home/workspace-selection-form.tsx b/src/components/features/home/workspace-selection-form.tsx
index 860b60c1f3..a785067f04 100644
--- a/src/components/features/home/workspace-selection-form.tsx
+++ b/src/components/features/home/workspace-selection-form.tsx
@@ -204,7 +204,6 @@ export function WorkspaceSelectionForm({
onChange={handleWorkspaceChange}
onAddClick={() => setIsBrowserOpen(true)}
onManageClick={() => setIsManageOpen(true)}
- className="max-w-auto"
key={selectedWorkspace?.path ?? "empty-workspace-selection"}
/>
diff --git a/src/utils/form-control-classes.ts b/src/utils/form-control-classes.ts
index 6138fc74c5..f9bade75af 100644
--- a/src/utils/form-control-classes.ts
+++ b/src/utils/form-control-classes.ts
@@ -36,7 +36,7 @@ export const formControlHeroUiWrapperTransitionClassName = cn(
/** Transform-only transitions (e.g. combobox carets). */
export const formControlTransformTransitionClassName = cn(
- "transition-[transform] ease",
+ "transition-[transform]",
formControlTransitionDurationClassName,
formControlMotionReduceClassName,
);