Skip to content

Commit a9ffc90

Browse files
chore(lint): report className restyling of components/ui exports
App code keeps restyling components/ui exports with ad-hoc className overrides instead of using variants and sizes, which is where most of the visual inconsistency comes from. There are 1247 such overrides today across 146 files, and the count has tripled in 60 days. Enable shadcn/no-restyle (allow: layout) as a warning for apps/web, scoped outside components/ui itself, so every finding names the component and its existing variants. A CI gate caps the warning count at the current 1247 so it cannot grow; lower the ceiling as files migrate to variants. Bump vite-plus to 0.3.3 for the oxlint version the plugin needs. Co-Authored-By: Claude Fable 5 <[email protected]>
1 parent e65bc1c commit a9ffc90

8 files changed

Lines changed: 868 additions & 476 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,9 @@ jobs:
5252
- name: Check
5353
run: vp check
5454

55+
- name: Check className overrides on components/ui do not grow
56+
run: vp run lint:restyle-ceiling
57+
5558
- name: Typecheck
5659
run: vpr typecheck
5760

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,7 @@ Full glossary with file links: `docs/internals/glossary.md`
158158
## Taste
159159

160160
- Complexity belongs at the adapter boundary. Orchestration stays pure, UI stays dumb.
161+
- `apps/web/src/components/ui` exports own their look. Pick a `variant` or `size`; do not restyle one with `className`. If none fits, add a variant to the component, not classes at the call site. Layout classes (width, flex, margin, position) belong on the parent. `shadcn/no-restyle` reports violations and CI caps their count.
161162
- Inferred types over annotations. `any` is the enemy.
162163
- Comments describe how a thing is used, and move when the code moves. To be used mostly to describe functions, not to annotate every line of behavior.
163164
- Our users drive agents all day and notice a dropped frame, a lying spinner, and a stale label. No continuously repainting animations; they peg the GPU on high-refresh displays.

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
"knip:check": "knip --include files,dependencies --no-config-hints && knip --workspace apps/server --workspace apps/desktop --workspace apps/web --workspace packages/client-runtime --workspace packages/contracts --workspace packages/effect-acp --workspace packages/effect-codex-app-server --workspace packages/shared --workspace packages/ssh --workspace packages/tailscale --exports --preprocessor ./scripts/knip-schemas.ts --no-config-hints",
3232
"knip:production": "knip --production --preprocessor ./scripts/knip-schemas.ts",
3333
"lint:mobile": "node scripts/mobile-native-static-check.ts",
34+
"lint:restyle-ceiling": "node scripts/lint-restyle-ceiling.ts",
3435
"test": "vp run -r test",
3536
"test:resource-monitor": "cargo test --locked --manifest-path native/resource-monitor/Cargo.toml",
3637
"test:desktop-smoke": "vp run --filter @t3tools/desktop smoke-test",
@@ -51,6 +52,7 @@
5152
},
5253
"devDependencies": {
5354
"@effect/tsgo": "catalog:",
55+
"@shadcn/lint": "0.1.5",
5456
"@types/node": "catalog:",
5557
"knip": "6.34.0",
5658
"typescript": "catalog:",

‎pnpm-lock.yaml‎

Lines changed: 753 additions & 473 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pnpm-workspace.yaml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,8 @@ catalog:
4949
lightningcss: 1.33.0
5050
tailwindcss: 4.3.3
5151
typescript: 7.0.2
52-
vite: npm:@voidzero-dev/[email protected].0
53-
vite-plus: 0.3.0
52+
vite: npm:@voidzero-dev/[email protected].3
53+
vite-plus: 0.3.3
5454
yaml: ^2.9.0
5555

5656
minimumReleaseAgeExclude:
@@ -94,6 +94,8 @@ minimumReleaseAgeExclude:
9494
- "@distilled.cloud/[email protected]"
9595
- "@distilled.cloud/[email protected]"
9696
- "@distilled.cloud/[email protected]"
97+
- "@shadcn/[email protected]"
98+
9799

98100
overrides:
99101
# Earlier React Navigation declarations create a circular type alias in TypeScript 7.
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import { assert, describe, it } from "@effect/vitest";
2+
3+
import { countRestyleFindings, evaluateCeiling } from "./lint-restyle-ceiling.ts";
4+
5+
describe("lint-restyle-ceiling", () => {
6+
it("counts only no-restyle diagnostics", () => {
7+
const count = countRestyleFindings({
8+
diagnostics: [
9+
{ code: "shadcn(no-restyle)" },
10+
{ code: "react(refs)" },
11+
{ code: "shadcn(no-restyle)" },
12+
],
13+
});
14+
assert.strictEqual(count, 2);
15+
});
16+
17+
it("fails above the ceiling and passes at or below it", () => {
18+
assert.isFalse(evaluateCeiling(11, 10).ok);
19+
assert.isTrue(evaluateCeiling(10, 10).ok);
20+
const below = evaluateCeiling(7, 10);
21+
assert.isTrue(below.ok);
22+
assert.include(below.message, "Lower RESTYLE_CEILING");
23+
});
24+
});

‎scripts/lint-restyle-ceiling.ts‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
#!/usr/bin/env node
2+
// @effect-diagnostics nodeBuiltinImport:off - one-shot CI gate over a child process.
3+
import * as NodeChildProcess from "node:child_process";
4+
import * as NodePath from "node:path";
5+
import * as NodeURL from "node:url";
6+
7+
// `shadcn/no-restyle` stays a warning while the existing className overrides on
8+
// components/ui exports are migrated to variants (see vite.config.ts). This gate keeps the
9+
// count from growing: CI fails when findings exceed the ceiling. Lower the ceiling when you
10+
// migrate a file, and delete this script when the rule becomes an error.
11+
export const RESTYLE_CEILING = 1247;
12+
13+
const RULE = "shadcn(no-restyle)";
14+
15+
const repoRoot = NodePath.resolve(NodePath.dirname(NodeURL.fileURLToPath(import.meta.url)), "..");
16+
17+
interface LintReport {
18+
readonly diagnostics: ReadonlyArray<{ readonly code: string }>;
19+
}
20+
21+
export function countRestyleFindings(report: LintReport): number {
22+
return report.diagnostics.filter((diagnostic) => diagnostic.code === RULE).length;
23+
}
24+
25+
export function evaluateCeiling(
26+
count: number,
27+
ceiling: number,
28+
): { readonly ok: boolean; readonly message: string } {
29+
if (count > ceiling) {
30+
return {
31+
ok: false,
32+
message:
33+
`${RULE}: ${count} findings exceed the ceiling of ${ceiling}. ` +
34+
"Use a variant or size on the components/ui export instead of a className override " +
35+
"(run `vp lint apps/web/src` for the list).",
36+
};
37+
}
38+
const slack = ceiling - count;
39+
return {
40+
ok: true,
41+
message:
42+
slack === 0
43+
? `${RULE}: ${count} findings, at the ceiling.`
44+
: `${RULE}: ${count} findings, ${slack} below the ceiling of ${ceiling}. Lower RESTYLE_CEILING in scripts/lint-restyle-ceiling.ts to ${count}.`,
45+
};
46+
}
47+
48+
function main() {
49+
const result = NodeChildProcess.spawnSync("vp", ["lint", "--format", "json", "apps/web/src"], {
50+
cwd: repoRoot,
51+
encoding: "utf8",
52+
maxBuffer: 256 * 1024 * 1024,
53+
});
54+
if (result.error) throw result.error;
55+
const report = JSON.parse(result.stdout) as LintReport;
56+
const verdict = evaluateCeiling(countRestyleFindings(report), RESTYLE_CEILING);
57+
process.stdout.write(`${verdict.message}\n`);
58+
process.exitCode = verdict.ok ? 0 : 1;
59+
}
60+
61+
if (
62+
process.argv[1] !== undefined &&
63+
NodePath.resolve(process.argv[1]) === NodeURL.fileURLToPath(import.meta.url)
64+
) {
65+
main();
66+
}

‎vite.config.ts‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,10 @@ export default defineConfig({
109109
"apps/mobile/uniwind-types.d.ts",
110110
],
111111
plugins: ["eslint", "oxc", "react", "unicorn", "typescript"],
112-
jsPlugins: ["./oxlint-plugin-t3code/index.ts"],
112+
jsPlugins: ["./oxlint-plugin-t3code/index.ts", "@shadcn/lint"],
113+
settings: {
114+
shadcn: { ui: "~/components/ui" },
115+
},
113116
categories: {
114117
correctness: "warn",
115118
suspicious: "warn",
@@ -167,6 +170,17 @@ export default defineConfig({
167170
files: ["apps/mobile/src/**"],
168171
rules: { "t3code/no-mobile-uniwind-theme-escape-hatches": "error" },
169172
},
173+
{
174+
// components/ui exports own their look. App code picks a variant or size instead
175+
// of restyling with className; layout classes (width, flex, margin, position) stay
176+
// allowed because placement belongs to the parent. Warn-only until the existing
177+
// overrides are migrated to variants; the ceiling below stops the count growing.
178+
files: ["apps/web/src/**"],
179+
excludeFiles: ["apps/web/src/components/ui/**"],
180+
rules: {
181+
"shadcn/no-restyle": ["warn", { allow: ["layout"] }],
182+
},
183+
},
170184
{
171185
// Shared client code must not call APIs missing from Hermes. Our ESNext
172186
// TypeScript target accepts them even when they would crash mobile at launch.

0 commit comments

Comments
 (0)