Classify tool input sizing intents (#325)

Author: baixiangcpp

docs/quality/input-intent-taxonomy.md

@@ -0,0 +1,15 @@
+# Input intent taxonomy
+
+Tool input sizing uses five stable intents:
+
+| Intent | Use |
+| --- | --- |
+| `scalar` | Numbers, colors, flags, enum-like controls, and other compact values. |
+| `shortText` | URLs, names, expressions, and short free-form text. |
+| `payload` | User-authored JSON, CSV, tokens, logs, code, and multiline data. |
+| `workbench` | Dense editor or split-pane work areas. |
+| `generatedOutput` | Read-only generated text or code with copy/export actions. |
+
+`Input`, `Textarea`, Monaco wrappers, and `TextOutputPanel` emit `data-input-intent` at runtime. The create-tool scaffold declares a payload input, a workbench container, and generated output explicitly.
+
+`tests/guards/input-intent-taxonomy.test.ts` parses every TSX file under `src` to inventory shared controls plus raw `input`, `textarea`, and `select` elements. Representative routes must declare an explicit intent. Remaining hardcoded height tokens are frozen by a stable file/tag/token hash, so a new unclassified size fails CI without depending on source line numbers.

scripts/e2e/run-playwright-smoke.js

@@ -47,6 +47,19 @@ const AXE_REVIEW_ROUTES = [
     "/en/trust-center",
     "/en/install-app",
 ];
+const INPUT_INTENT_AUDIT_ROUTES = [
+    { route: "/en/qr-code-generator", requiredIntents: ["shortText", "scalar"] },
+    { route: "/en/base64-encode-decode", requiredIntents: ["payload", "generatedOutput"] },
+    { route: "/en/regex-tester", requiredIntents: ["scalar", "shortText", "payload"] },
+    { route: "/en/json-formatter", requiredIntents: ["workbench", "payload"] },
+    { route: "/en/csv-json-converter", requiredIntents: ["workbench", "payload", "generatedOutput"] },
+    { route: "/en/jwt-decoder", requiredIntents: ["workbench", "payload", "generatedOutput"] },
+    { route: "/en/pipeline-builder", requiredIntents: ["workbench", "shortText", "payload", "generatedOutput"] },
+];
+const INPUT_INTENT_AUDIT_VIEWPORTS = [
+    { width: 390, height: 844, mobile: true },
+    { width: 1280, height: 900, mobile: false },
+];
 const ALL_TOOLS_FILTER_INTERACTION_BUDGET_MS = 2000;
 const ALL_TOOLS_MOBILE_SCROLL_BUDGET_MS = 3500;
 const ALL_TOOLS_MOBILE_MAX_FRAME_DELTA_MS = 500;
@@ -194,6 +207,7 @@ function parseArgs(argv) {
         includePwa: false,
         firstLoadOnly: false,
         writeFirstLoadArtifacts: false,
+        inputIntentsOnly: false,
     };
 
     for (const arg of argv) {
@@ -217,6 +231,11 @@ function parseArgs(argv) {
             continue;
         }
 
+        if (arg === "--input-intents-only") {
+            args.inputIntentsOnly = true;
+            continue;
+        }
+
         if (arg.startsWith("--port=")) {
             const parsed = Number(arg.slice("--port=".length));
             if (Number.isFinite(parsed) && parsed > 0) {
@@ -1139,6 +1158,93 @@ async function assertMobileReviewMatrix(browser, baseUrl) {
     }
 }
 
+async function assertInputIntentSizingMatrix(browser, baseUrl) {
+    for (const viewport of INPUT_INTENT_AUDIT_VIEWPORTS) {
+        const context = await browser.newContext({
+            serviceWorkers: "block",
+            viewport: { width: viewport.width, height: viewport.height },
+            isMobile: viewport.mobile,
+        });
+
+        try {
+            for (const audit of INPUT_INTENT_AUDIT_ROUTES) {
+                const page = await context.newPage();
+                const routeLabel = `${audit.route} input intent ${viewport.width}x${viewport.height}`;
+                const runtime = createRuntimeObserver(page, routeLabel, baseUrl);
+
+                try {
+                    await page.goto(`${baseUrl}${audit.route}`, { waitUntil: "domcontentloaded" });
+                    await page.waitForSelector("main", { timeout: 15_000 });
+                    await page.locator("[data-input-intent]").first().waitFor({ state: "attached", timeout: 15_000 });
+
+                    const measurements = await page.evaluate(({ mobile }) => {
+                        const isVisible = (element) => {
+                            const style = window.getComputedStyle(element);
+                            const rect = element.getBoundingClientRect();
+                            return style.display !== "none" && style.visibility !== "hidden" && Number(style.opacity) !== 0 && rect.width > 0 && rect.height > 0;
+                        };
+                        const nodes = Array.from(document.querySelectorAll("[data-input-intent]")).filter(isVisible);
+                        const counts = {};
+                        const issues = [];
+
+                        for (const element of nodes) {
+                            const intent = element.getAttribute("data-input-intent");
+                            if (!intent) continue;
+                            counts[intent] = (counts[intent] || 0) + 1;
+
+                            const rect = element.getBoundingClientRect();
+                            const tag = element.tagName.toLowerCase();
+                            const field = ["input", "textarea", "select"].includes(tag);
+                            if (intent === "scalar" && field) {
+                                const target = element.closest("label") || element;
+                                const targetRect = target.getBoundingClientRect();
+                                const minimum = mobile ? 44 : 36;
+                                if (targetRect.height + 0.5 < minimum || targetRect.width + 0.5 < minimum) {
+                                    issues.push(`${intent} ${tag}: ${Math.round(targetRect.width)}x${Math.round(targetRect.height)}`);
+                                }
+                            }
+                            if (intent === "shortText" && tag === "input" && rect.height + 0.5 < (mobile ? 44 : 44)) {
+                                issues.push(`${intent} input height: ${Math.round(rect.height)}px`);
+                            }
+                            if (intent === "shortText" && tag === "textarea") {
+                                const style = window.getComputedStyle(element);
+                                const resize = style.resize;
+                                if (rect.height + 0.5 < 144) issues.push(`${intent} textarea height: ${Math.round(rect.height)}px (min-height ${style.minHeight}; ${element.className})`);
+                                if (!resize.includes("vertical") && resize !== "both") issues.push(`${intent} textarea resize: ${resize}`);
+                            }
+                            if (["payload", "generatedOutput"].includes(intent) && ["textarea", "pre"].includes(tag) && rect.height + 0.5 < 256) {
+                                issues.push(`${intent} ${tag} height: ${Math.round(rect.height)}px`);
+                            }
+                        }
+
+                        return { counts, issues };
+                    }, { mobile: viewport.mobile });
+
+                    for (const intent of audit.requiredIntents) {
+                        if (!measurements.counts[intent]) {
+                            throw new Error(`${routeLabel} did not render required ${intent} input intent.`);
+                        }
+                    }
+                    if (measurements.issues.length > 0) {
+                        throw new Error(`${routeLabel} input sizing failed:\n- ${measurements.issues.join("\n- ")}`);
+                    }
+
+                    await assertNoHorizontalOverflow(page, routeLabel);
+                    const screenshot = await page.screenshot({ animations: "disabled", fullPage: false });
+                    if (screenshot.byteLength < 5_000) {
+                        throw new Error(`${routeLabel} sizing screenshot was unexpectedly blank (${screenshot.byteLength} bytes).`);
+                    }
+                    runtime.assertClean();
+                } finally {
+                    await page.close();
+                }
+            }
+        } finally {
+            await context.close();
+        }
+    }
+}
+
 async function assertAxeSeriousCriticalMatrix(browser, baseUrl) {
     const context = await browser.newContext({ serviceWorkers: "block" });
 
@@ -2046,6 +2152,9 @@ async function runSmoke(baseUrl, { writeFirstLoadArtifacts = false } = {}) {
         await assertMobileReviewMatrix(browser, baseUrl);
         console.log("[playwright-smoke] PASS mobile review matrix: no overflow or touch-target regressions");
 
+        await assertInputIntentSizingMatrix(browser, baseUrl);
+        console.log("[playwright-smoke] PASS input intent sizing matrix: mobile/desktop heights, touch targets, overflow, and screenshots");
+
         await assertAxeSeriousCriticalMatrix(browser, baseUrl);
         console.log("[playwright-smoke] PASS accessibility: no serious or critical axe violations on representative pages");
     } finally {
@@ -2073,11 +2182,22 @@ async function runPwaSmoke(baseUrl) {
     }
 }
 
+async function runInputIntentSmoke(baseUrl) {
+    const browser = await chromium.launch({ headless: true });
+    try {
+        await assertInputIntentSizingMatrix(browser, baseUrl);
+        console.log("[playwright-smoke] PASS input intent sizing matrix: mobile/desktop heights, touch targets, overflow, and screenshots");
+    } finally {
+        await browser.close();
+    }
+}
+
 async function main() {
     const {
         baseUrl,
         firstLoadOnly,
         includePwa,
+        inputIntentsOnly,
         port,
         skipServer,
         writeFirstLoadArtifacts,
@@ -2091,15 +2211,19 @@ async function main() {
             console.log(`[playwright-smoke] Static server ready at ${baseUrl}`);
         }
 
-        if (firstLoadOnly) {
+        if (inputIntentsOnly) {
+            await runInputIntentSmoke(baseUrl);
+        } else if (firstLoadOnly) {
             await runFirstLoadAudit(baseUrl, { writeArtifacts: writeFirstLoadArtifacts });
         } else {
             await runSmoke(baseUrl, { writeFirstLoadArtifacts });
         }
-        if (includePwa && !firstLoadOnly) {
+        if (includePwa && !firstLoadOnly && !inputIntentsOnly) {
             await runPwaSmoke(baseUrl);
         }
-        console.log("[playwright-smoke] PASS: critical routes render and navigate correctly");
+        if (!firstLoadOnly && !inputIntentsOnly) {
+            console.log("[playwright-smoke] PASS: critical routes render and navigate correctly");
+        }
     } catch (error) {
         console.error("[playwright-smoke] FAILED");
         if (serverHandle) {

scripts/scaffolding/create-tool.js

@@ -333,20 +333,21 @@ export function ${componentName}Page() {
                 </Button>
             </div>
 
-            <div className="grid gap-4 lg:grid-cols-2">
+            <div data-input-intent="workbench" className="grid gap-4 lg:grid-cols-2">
                 <div className="space-y-2">
                     <label className="text-sm font-medium text-muted-foreground">{inputLabel}</label>
                     <Textarea
+                        intent="payload"
                         value={input}
                         onChange={(event) => setInput(event.target.value)}
                         placeholder={inputLabel}
-                        className="min-h-[360px] font-mono"
+                        className="font-mono"
                     />
                 </div>
 
                 <div className="space-y-2">
                     <label className="text-sm font-medium text-muted-foreground">{outputLabel}</label>
-                    <Textarea value={output} readOnly className="min-h-[360px] font-mono" />
+                    <Textarea intent="generatedOutput" value={output} readOnly className="font-mono" />
                 </div>
             </div>
         </ToolPageContainer>

src/app/globals.css

@@ -154,6 +154,19 @@
     min-height: 44px !important;
     min-width: 44px !important;
   }
+
+  textarea[data-input-intent="shortText"] {
+    min-height: 9rem !important;
+  }
+
+  textarea[data-input-intent="payload"],
+  textarea[data-input-intent="generatedOutput"] {
+    min-height: 16rem !important;
+  }
+
+  textarea[data-input-intent="workbench"] {
+    min-height: 22rem !important;
+  }
 }
 }
 

src/components/ui/input-intent.ts

@@ -0,0 +1,48 @@
+export const INPUT_INTENTS = [
+    "scalar",
+    "shortText",
+    "payload",
+    "workbench",
+    "generatedOutput",
+] as const
+
+export type InputIntent = (typeof INPUT_INTENTS)[number]
+
+type InputIntentControl = "input" | "textarea" | "editor" | "output"
+
+export const INPUT_INTENT_CLASS_NAMES: Record<InputIntent, Record<InputIntentControl, string>> = {
+    scalar: {
+        input: "h-11 lg:h-9",
+        textarea: "min-h-11 resize-y",
+        editor: "min-h-44",
+        output: "min-h-44",
+    },
+    shortText: {
+        input: "min-h-11",
+        textarea: "min-h-36 resize-y",
+        editor: "min-h-56",
+        output: "min-h-56",
+    },
+    payload: {
+        input: "min-h-11",
+        textarea: "min-h-64 resize-y",
+        editor: "min-h-80",
+        output: "min-h-80",
+    },
+    workbench: {
+        input: "min-h-11",
+        textarea: "min-h-[22rem] resize-y lg:resize-none",
+        editor: "min-h-[22rem]",
+        output: "min-h-[22rem]",
+    },
+    generatedOutput: {
+        input: "min-h-11",
+        textarea: "min-h-64 resize-y",
+        editor: "min-h-80",
+        output: "min-h-64",
+    },
+}
+
+export function inputIntentClassName(intent: InputIntent, control: InputIntentControl) {
+    return INPUT_INTENT_CLASS_NAMES[intent][control]
+}

src/components/ui/input.tsx

@@ -1,16 +1,25 @@
 import * as React from "react"
 
 import { cn } from "@/core/utils/utils"
+import { inputIntentClassName, type InputIntent } from "@/components/ui/input-intent"
+
+export type InputProps = React.ComponentProps<"input"> & {
+  intent?: InputIntent
+}
+
+function Input({ className, intent, type, ...props }: InputProps) {
+  const resolvedIntent = intent ?? "shortText"
 
-function Input({ className, type, ...props }: React.ComponentProps<"input">) {
   return (
     <input
       type={type}
       data-slot="input"
+      data-input-intent={resolvedIntent}
       className={cn(
-        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-input h-11 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm lg:h-9",
+        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-input w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
         "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
         "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+        intent ? inputIntentClassName(intent, "input") : "h-11 lg:h-9",
         className
       )}
       {...props}

src/components/ui/textarea.tsx

@@ -1,13 +1,22 @@
 import * as React from "react"
 
 import { cn } from "@/core/utils/utils"
+import { inputIntentClassName, type InputIntent } from "@/components/ui/input-intent"
+
+export type TextareaProps = React.ComponentProps<"textarea"> & {
+  intent?: InputIntent
+}
+
+function Textarea({ className, intent, ...props }: TextareaProps) {
+  const resolvedIntent = intent ?? "payload"
 
-function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
   return (
     <textarea
       data-slot="textarea"
+      data-input-intent={resolvedIntent}
       className={cn(
-        "border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        intent ? inputIntentClassName(intent, "textarea") : "field-sizing-content min-h-16",
         className
       )}
       {...props}