Skip to content

Let the design lint check one section of a running app for crowded rows, cramped help text, loud notes and small tap targets - #4138

Merged
capy-ai[bot] merged 7 commits into
mainfrom
gst1741-app-lint
Nov 7, 2026
Merged

capy-ai[bot] merged 7 commits into
mainfrom
gst1741-app-lint

Conversation

@garrytan

@garrytan garrytan commented Nov 7, 2026 •

Copy link
Copy Markdown
Owner

gstack's design lint can now measure one section of a running app screen (gstack-design-lint --scope app) and flag the spacing mistakes agents make when they build new UI: crowded two-line rows, help text jammed under a list, status notes as loud as the names beside them, and tap targets under 32px on phones. It serves the README's promise of "a designer who catches AI slop" during Build and Review, not only on finished pages.

What changed

gstack-design-lint --scope app is a new, opt-in profile that measures one section of a running app screen and says whether its rows, help copy, notes and row controls are spaced right:

gstack-design-lint --scope app --url http://localhost:5173/personas/p-launch --within '[data-testid="access-section"]'
LINT: ask row-crowding … a 2-line row leaves 9px between its last text line and the next row's text (under 16px)
LINT: ask copy-flush-under-list … the text under the list starts 8px below it (under 12px)
LINT_APP: verdict=open code=OPEN states=1/1 viewports=1440x900,375x812 within=[data-testid="access-section"] matched=1 open=… waived=0
  • Five app rules at ask: row-crowding, copy-flush-under-list, note-in-row-weight, small-hit-area (375px), section-overflow. They run only under --scope app; page and component output and exit codes are byte-identical to main (hashed golden of 14 runs).
  • Its own scheduler (lib/design-lint/render-app.ts, probes in render-probe-app.ts on window.__gstackLintApp): one render per state, measured at each --viewport (default 1440x900 and 375x812), through open, slotted and nested shadow roots, confined to --within.
  • One machine verdict: clean exit 0 only when every state × viewport was measured; open exit 1 for any unwaived app finding, whatever its tier; incomplete exit 4 with a code (NO_BROWSER, UNREACHABLE, TIMEOUT, NOT_READY, STATE_MISMATCH, WITHIN_NO_MATCH, CLOSED_SHADOW, PROBE_ERROR, ASSET_MISSING), each with a fix line and a docs anchor. Exit 3 is usage only.
  • States and waivers as files: --state-file (versioned, per-state expect selector) and --waivers (rule + locator + reason), both validated before any render. URL credentials are redacted from text, JSON, stderr and traces.
  • Behavior change, every scope: --url with no browser now prints RENDER_UNAVAILABLE and exits 4 instead of exiting 0 having measured nothing. --render over files keeps today's skip.
  • Fixes from review: secret-looking #fragment parameters (like #access_token=) are now redacted like query ones; two --url states whose redacted names match stay two states (name~2, picked from the names already in use) and only the same URL given twice is refused; a trace file that cannot be written keeps the state PROBE_ERROR instead of crashing with exit 1; a section selector the browser refuses no longer stalls the readiness wait. The design-lint usage block and the project map now mention --scope app.

Why

qm#3186 shipped three spacing defects (crowded two-line rows, help copy flush under a list, a status note at full weight in a row). gstack-design-lint --render on that page printed 697 findings and none of the three. A follow-up change adds an opt-in /design-review --build loop that calls this profile.

Six qm builds from the earlier probe show how it reads on real builds, compared per section with the preregistered scorer (independent code and thresholds).

Build Scorer --scope app
no gstack B1 (what qm#3186 shipped) crowded rows (access), copy flush (both), loud note (channels) same, plus the same unmuted note in access
no gstack B2 crowded rows (access), copy flush (both) same
gstack as is A1, A2 copy flush (both) same
loop prototype C1, C2 clean clean, exit 0

The false-positive corpus (12 repo pages, test/fixtures/ui-spacing/corpus.json) gives zero app findings; negative controls (nav list, table, card grid, a correct list) carry deliberate trigger bait.

Blast radius

Opt-in flag; no skill prose, no reviewer prompts, no /ship or /review change. The only change outside --scope app is the --url-with-no-browser exit (now 4), listed in the changelog fragment. test/design-lint-app-profile.test.ts needs a browser and fails loudly in CI without one; it runs about 50 s on a 4-core machine.

Approvals

Approved: yes. The plan was approved before the build started; the record ids are under Internal references at the end.

Summary

The lint gets an app profile that only measures inside one section, with five spacing rules and a single verdict a build loop can act on. Review found a token leak through URL fragments and three smaller failure-path bugs, and all four are fixed with tests.

Test Coverage

Every changed runtime file has a changed test that names it.
The full free suite (1631 test files) passed in CI run 42407191649 on the pushed code.
Focused local runs on the reviewed code were all green: the app contract tests, the browser app-profile tests, the module-size and scope-guard tests, typecheck, and the test type check.

Pre-Landing Review

Each issue review found is listed below as fixed or skipped, or under Review notes. None is open.

  • [blocking, fixed] lib/design-lint/app-input.ts: tokens in a URL fragment (#access_token=) printed in full in text, JSON, stderr and trace files. Found by the security checklist and confirmed by running the CLI.
  • [fixed] lib/design-lint/app-cli.ts: two --url states that differ only in a redacted value were refused as duplicates.
  • [fixed] lib/design-lint/render-app.ts: a trace file that could not be written crashed the run with exit 1, which means "open".
  • [fixed] lib/design-lint/render-app.ts, render-probe-app.ts: a --within selector the browser refuses stalled readiness and reported NOT_READY with "selector undefined".
  • [blocking, fixed] lib/design-lint/app-cli.ts: the new name~2 suffix could collide with a URL path that already ends in ~2, so two states shared a name and the state count came out low. Found by the outside reviewer (another model family), the specialist and the adversarial reviewer; fixed and checked again with no findings.
  • [skipped] lib/design-lint/render-app.ts: the reachability check before rendering can mark a login-protected dev route unreachable and can spend a single-use URL token. The check is part of the spec; narrowing it to connection failures is a follow-up.

Review notes

Below the blocking bar; recorded here and not fixed in this PR.

  • lib/design-lint/app-input.ts:44: a URL that passes the http(s) check but that new URL rejects (for example port 99999) keeps its query and fragment secrets in the printed state name. Such a URL cannot load; refusing it up front is the follow-up.
  • lib/design-lint/app-input.ts:34-49: redacting a fragment re-encodes a hash-router route in printed output. Navigation still uses the real URL.
  • lib/design-lint/render-probe-app.ts:394: an explicit --wait-for the browser refuses reports NOT_READY (exit 4) with a fix line about slow pages.
  • lib/design-lint/render-app.ts:176: the soft-wait NOT_READY detail names the section for any wait timeout.

Exploratory QA

Six CLI checks on the code as pushed before review: bad selector, app-only flag without --scope app, bad viewport and file paths under --scope app each exit 3 with a reason and a fix line; an unreachable --url exits 4 with the password and ?token= redacted. The same run printed a #access_token= value in full (the first blocking issue above); after the fix it prints #access_token=REDACTED. Limits: these checks were logged by hand, not through the QA evidence recorder, and in-browser measurement is covered by the app-profile tests rather than a separate check.

Design Review

Static only (no preview declared). The changed frontend files are test pages that are wrong on purpose, so the design checklist found nothing to report. The external design detector is not installed.

Eval Results

No prompt-related files changed, so evals were skipped.

TODOS

No TODO items completed in this PR.

Documentation

Status: current. Docs already match the branch, so nothing was edited.

Scope: 34 committed files from e58be61 to 32af9a0 (the design-lint --scope app profile, --url exit 4 with no browser, five app rules). The candidate has no staged, unstaged or new files.

Documentation health:

  • docs/design-lint.md: Current (the app usage line, RENDER_UNAVAILABLE exit 4, APP_ONLY, the five rules, the LINT_APP verdict and its codes, and the traces and waivers all match the code)
  • docs/PROJECT_STRUCTURE.md: Current (the bin/ row names --scope app)
  • changelog.d/gst1741-app-lint.md: Current (agrees with the doc and the code)
  • NOTICE.md: Current (the render*.ts glob covers the new files)
  • design-html and design-review craft templates: Current (file-based --render is unchanged)

Documentation Debt

  • --scope app: it has reference docs and a usage example in docs/design-lint.md, but no skill workflow (/design-review, /design-html) says when to run it, so the how-to step is missing.
  • Diagram drift: none.

Test plan

  • bun test test/design-lint-app-contract.test.ts: green
  • bun test test/design-lint-app-profile.test.ts: green (browser)
  • bun test test/module-size-ratchet.test.ts test/design-lint-scope-guard.test.ts: green
  • bun run typecheck: clean; bun run typecheck:test: none new
  • Full free suite (bun run test): 1631 files passed in CI run 42407191649 on 32af9a0; the macOS regression job passed in the same run

Internal references

  • Issue: GST-1741, PR 1 of 2. Gate-2 tasks T3, T5, T7, T14, T17, T18, T21, T22, T26, the receipt half of T29, T31, T36, T37 and T38 belong to PR 2.

Approved: yes (record r-8464717ba4b1). The full approval record stays private: this repository is public or its visibility is unknown.
Plan: approved: run-20261107060947
Plan check: approved run-20261107060947 row=a-80e4c1654af2

  • Plan completion audit: not run (no plan is bound to this branch and no docs/designs/ file matches); the plan is autoplan run run-20261107060947.
  • Fix-check grant (review_loop_exception): one scoped fix-check after round 2, granted by Captain GStack Minder (GSTA-36) as approval a-7c954c6c661f (recorded with its stop head as a-0a2728b5c0fc); the fix-check returned NO FINDINGS.
  • Review findings by ledger id: p1/specialist-batched#1, p1/specialist-batched#2, p1/red-team#1, p1/red-team#2 (fixed), p1/red-team#3 (skipped), p2/outside-voice#1 with p2/specialist-batched#1 and p2/adversarial-native#1 (fixed), p2/red-team#1 and p2/adversarial-native#2-Fix project-local /browse installs and harden setup #4 (notes). Outside reviewer: openai/gpt-6.1-sol.
    REVIEW_LOOP: passes=2 blocking_found=4 deferred=0 noted=2 fixed=7 scope=frozen ledgers_read=8 fix_checks=2 dispatches=10
    Gate edits: none detected (25 listed, 2 read; patterns: RH-1,RH-3,RH-4,RH-12,RH-13,RH-14,RH-15,RH-16; unlisted idioms: none)
{
  "schema_version": 1,
  "pr": 4138,
  "head": "32af9a0234ae5134f40c3cfd06cbe07387f03ad6",
  "version": "1.98.0.0",
  "base": "main",
  "gate": {
    "free": {
      "pass": 1631,
      "fail": 0,
      "skip": 0
    }
  },
  "ci_carried": [
    {
      "lane": "free",
      "run": 42407191649,
      "attempt": 1,
      "tree": "48e4d94beb94b8cd7ba48bf3138685da545eb68c"
    }
  ],
  "session_kind": "unattended",
  "head_tree": "48e4d94beb94b8cd7ba48bf3138685da545eb68c",
  "product_patch_id": "08cc969b04b192f5da4275e0f417a8800c99edba",
  "gstack_version": "1.98.0.0",
  "review_depth": {
    "depth": "full",
    "class": "code",
    "runtime_lines": 988,
    "rules": "c6a079fdf812f479",
    "base": "1a29fbc3444f858c72ec001abdb4f0f3bebfa76c",
    "registry": "1a29fbc3444f858c72ec001abdb4f0f3bebfa76c",
    "gate_scan": {
      "tagged": 0,
      "head": "32af9a0234ae5134f40c3cfd06cbe07387f03ad6"
    },
    "reasons": [
      "risk:security",
      "runtime=988"
    ],
    "risk": [
      "security"
    ],
    "mode": "panel"
  },
  "pregate": "requires-remote cleared @48e4d94beb94 (8 checks, current for 32af9a0234ae)",
  "requires_remote": [
    "free-tests.yml/macos-named-regressions: https://github.com/garrytan/gstack/actions/runs/42407191649/attempts/1",
    "pregate.json/remote_gate: remote-gate tree=48e4d94beb94 tests=36151 skipped=71 runs=42407191649/1 profiles=ci-reuse/free-tests heads=32af9a0234ae verified=2026-11-07T19:45:41.704Z"
  ],
  "issues": {
    "fixes": [],
    "refs": [],
    "flakes": []
  },
  "docs": {
    "status": "current",
    "scope": "docs/ and README.md over e58be61..32af9a0 (design-lint --scope app)"
  },
  "review_loop": {
    "passes": 2,
    "blocking_found": 4,
    "deferred": 0,
    "noted": 2,
    "fixed": 7,
    "scope": "frozen",
    "fix_checks": 2,
    "rounds": 4,
    "ledgers_read": 8,
    "dispatches": {
      "specialist": 8,
      "red-team": 2
    }
  },
  "design": {
    "mode": "static",
    "reason": "no preview declared"
  }
}

Open in Capy

garrytan and others added 3 commits November 7, 2026 18:32
…ng, flush help copy, loud notes and small targets (GST-1741 PR 1)

Adds an opt-in, render-only app profile to gstack-design-lint: its own
scheduler (lib/design-lint/render-app.ts) and probes
(lib/design-lint/render-probe-app.ts on window.__gstackLintApp), five
app-only rules at ask (row-crowding, copy-flush-under-list,
note-in-row-weight, small-hit-area, section-overflow), --within matched
through open shadow roots, readiness and state assertions, a LINT_APP
verdict with exit 0 clean / 1 open / 4 incomplete / 3 usage, --waivers,
URL redaction everywhere and private trace files for probe errors.

Behavior change: --url with no browser now exits 4 with
RENDER_UNAVAILABLE under every scope. Page and component output is
otherwise byte-identical to e58be61 (test/design-lint-scope-guard.test.ts).

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…cases (GST-1741 PR 1)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…noise never fires a threshold (GST-1741 PR 1)

Measured against six real qm builds from the probe: the shipped access list
(flex rows, no border) slipped past row-crowding, and 8px padding read as 7.99px
and fired. Rows that set an avatar, text and control side by side now count as
a list of rows; thresholds ignore the last 0.05px.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@trunk-io

trunk-io Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

😎 This pull request was merged.

garrytan and others added 4 commits November 7, 2026 19:01
Redact secret-looking #fragment parameters like query ones; keep two --url states whose redacted names match as two states (name~2) and refuse only the same URL twice; a trace that cannot be written keeps the state PROBE_ERROR instead of crashing to exit 1; a section selector the browser refuses no longer holds the soft readiness wait, and a NOT_READY without --wait-for names the section.

Review-Finding: p1/specialist-batched#1 reader=security
Review-Finding: p1/specialist-batched#2 reader=testing
Review-Finding: p1/red-team#1 reader=red-team
Review-Finding: p1/red-team#2 reader=red-team
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
…41 PR 1)

Names for --url states are given out from the set of names already used, so /p, /p#x and /p~2 measure as three states. Review-loop exception a-7c954c6c661f.

Review-Finding: p2/outside-voice#1 reader=outside-voice
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
@capy-ai capy-ai Bot changed the title design-lint: --scope app measures one app section for row spacing, flush help copy, loud notes and small targets (GST-1741 PR 1) Let the design lint check one section of a running app for crowded rows, cramped help text, loud notes and small tap targets Nov 7, 2026
@capy-ai
capy-ai Bot merged commit 5f9b7ef into main Nov 7, 2026
64 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant