Skip to content

ci: gate kiro-light against borderless card surfaces with a computed-style sweep - #25595

Merged
iamwhatever merged 2 commits into
mainfrom
fix/kiro-light-card-gate-8751
Oct 29, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
fix/kiro-light-card-gate-8751

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: CI fails when a dashboard surface has no edge of its own in kiro-light, where --card and --bg are the same #ffffff.

A bg-card (or bg-bg-elevated) box on the page with no border, ring or shadow paints nothing in kiro-light and shows as a card in every other theme. website/docs/theming-contract.md states the rule ("A card must carry its own edge"), but no check enforced it. A new borderless card was only caught if a reviewer remembered that paragraph. The one-time computed-style sweep that verified PR #8711 answered the question once. This makes it a repeatable gate, as the Design and First Principles lanes asked on #8711.

Why it matters

The failure is invisible in every theme a reviewer is likely to look at, and the card vanishes only for kiro-light users. A class grep cannot stand in for the check: on #8711 three of six grep hits carried their edge in an inline style, and two were opaque covers, not cards. The app-page sweep in this PR found two more such cards that had shipped: the File Explorer breadcrumb field and the Notes rendered/raw switch.

Not a goal

  • Covering pages that do not exist yet. The gate renders the ten routes swept on feat(theme): white chat canvas with grey shell in kiro-light #8711 and all 23 built-in app pages registered in website/src/apps/builtinRegistry.ts. A page added later is covered once it is added to ROUTES (the docs say so).
  • Changing any theme value. The only style changes are the two cards the gate found, which now carry a border.

Intended? / Repro

Intended? The gap is not intended. website/docs/theming-contract.md:67-73 on main states the rule and says a borderless card ships invisible "with no gate failing". website/src/styles/theme-palettes.css:577-578 ([data-theme="kiro-light"]) sets --bg:#ffffff and --card:#ffffff, so the condition the issue describes still holds. No script under website/scripts/ or step in .github/workflows/ci.yml checks it.

Repro: on main, removing border border-border from the shared search input (website/src/components/ui.tsx:178) and rebuilding leaves CI green. With this branch, the same mutation makes node scripts/check-kiro-light-cards.mjs exit 1 with six hits (settings-overview, settings-chat, settings-display-theme, artifacts, knowledge, apps-library), for example:

settings-chat  div.shrink-0.px-0.5.pb-2 > div.settings-search.relative.shrink-0 > div.relative.w-full > input.w-full.bg-bg-elevated.rounded-md.pl-7  (171x32, rgb(255, 255, 255), a card in light + kiro-dark)

The app pages on main reproduce the defect without any mutation. Before the two card fixes, the gate reported:

app-file-explorer  div.mc-fe-root > div.mc-fe-pathbar > div.mc-fe-pathbar-row > div.mc-fe-breadcrumbs  (1159x32, rgb(255, 255, 255), a card in light + kiro-dark)
app-md-notebook  div > div > div > div  (64x30, rgb(255, 255, 255), a card in light + kiro-dark)

That is website/src/apps/file-explorer/styles.ts:30 (border:1px solid transparent on a var(--card) field) and the rendered/raw switch in website/src/apps/md-notebook/MdNotebookPage.tsx:713-720 (a var(--card) track with no border).

What changed (motivation → approach → change)

Motivation: the rule asks whether a surface is visible, which only the rendered page can answer. Approach: render each route in kiro-light and compare computed colours with a reference theme in the same DOM. Change:

  • website/scripts/check-kiro-light-cards.mjs (new). Serves website/dist on 127.0.0.1 with the shared /api/** boot fixtures (scripts/lib/boot-api.mjs) and one chat slot. For each route it asserts the page rendered its ready text and data-theme="kiro-light", turns off transitions and animations, and checks every painted element of at least 16x16 px. The element's background is composited over its painted ancestors. An element is reported when it matches its backdrop in kiro-light (every channel within 3), has no border side, box-shadow layer (which covers ring-*) or outline whose colour differs from the backdrop, AND differs from its backdrop after switching data-theme in place to light or kiro-dark. Fills that equal their parent in every theme (opaque covers) are not reported. A shadow layer counts as an edge only if its colour shows against the backdrop and it has a non-zero offset, blur or spread, because shadow-none and ring-0 compute to transparent zero-size layers, not none.
  • Routes: chat, Settings (Overview, Chat, Display / Theme, Security), Schedule, Artifacts, Knowledge, Apps library, Members, and the 23 built-in app pages: /worlds, /channels, /auto-improvement, /auto-research, /aws-control, /file-explorer, /code-review-sage, /workflows, /dev-fleet, /issue-radar, /meetings, /papyrus, /pptx-maker, /ops-mission-control, /design-critique, /crew-companion, /projects, /md-notebook, /mochi, /spec-builder, /personal-shopper, /design-tweak, /project-scaffolder.
  • APP_FIXTURES, keyed by pathname, for the six app pages that crash or stop at a backend-error notice against the generic [] / {} answers: AWS Control (accounts, profiles, consent, costs, drive, shares), File Explorer (health, tree, git-status), PPTX Maker (engine, deps, decks, deck, styles, templates), Mission Control (state, incidents, ledger), Notes (health, vaults, settings, notes, changes) and Mochi (pet-state, stats, settings, watchlist, pinned, plan, activity, manifest). Each carries one populated row where the page has a list, and that row is the route's ready text, so the gate checks the page with content on it.
  • Four controls are planted on each route. A bare var(--card) box and one with a transparent zero-size shadow must be reported. The same box with a border or a 1px ring must not be. A probe that matched nothing fails instead of passing green. EXEMPT (empty) takes reasoned selectors, and a stale exemption fails the gate.
  • Two cards fixed instead of exempted: the File Explorer breadcrumb field now rests on 1px solid var(--border) (hover darkens it to var(--muted)), matching the path input it turns into on click. The Notes rendered/raw switch track gets 1px solid var(--border).
  • .github/workflows/ci.yml: a new step in the e2e job, after the MCP-App rows harness. It reuses that job's build and Chromium install, has a 10 minute cap (33 routes run in about 70 to 130 seconds locally), and needs no gateway.
  • docs/ci/kiro-light-card-gate.md (new) plus its row in docs/ci/README.md. website/docs/theming-contract.md now names the gate and its route coverage in place of "with no gate failing".

Backwards compatibility

Two visible style changes (a border on the two cards above). No API or theme value changes. The gate passes on this branch.

Tests

The gate is itself the check. I ran it locally against a fresh npm run build of this branch: 33/33 routes clean (10 core routes, 23 app pages), every app page rendered its ready text with no error boundary, and all four planted controls behaved as expected on every route. Before the two card fixes it failed on app-file-explorer and app-md-notebook with the hits quoted above. Against a mutated build with the shared search input's border removed it exits 1 with six hits. These are harness runs, not the test suite.

Proof: not provable -- other: this host runs no local tests; CI runs them

Manual verification

Gate runs as above. Static gates: eslint on the changed files, tsc --noEmit, scripts/check_file_line_cap.py, scripts/check_comment_history.py, YAML parse of ci.yml.

Screenshots

Captured from the built SPA with the gate's own fixtures, at 2x, before and after the two fixes.

File Explorer breadcrumb field, kiro-light. Before: the field has no outline.

File Explorer breadcrumbs, kiro-light, before

After: the field carries its own border.

File Explorer breadcrumbs, kiro-light, after

Same field in the light theme, before and after (the field was already visible here; it now has a resting border too):

File Explorer breadcrumbs, light, before
File Explorer breadcrumbs, light, after

Notes rendered/raw switch, kiro-light. Before: the track is invisible and the two buttons float.

Notes view switch, kiro-light, before

After: the track has its own border.

Notes view switch, kiro-light, after

Same switch in the light theme, before and after:

Notes view switch, light, before
Notes view switch, light, after

Related Issues

Fixes #8751

Sibling sweep

Swept: git ls-tree --name-only origin/main website/scripts/ | grep -E '^website/scripts/(check|capture|probe)-' ; git grep -n "kiro-light" origin/main -- website/src/test ; the gate itself over all 23 entries of website/src/apps/builtinRegistry.ts
Sibling: website/src/test/kiroLightShellHooks.test.ts -- not affected (pins the deliberate kiro-light hooks by source; this gate covers the borderless surfaces it cannot see)
Sibling: website/scripts/check-theme-colors.mjs -- not affected (checks colour literals in source, not rendered edges)
Sibling: website/src/apps/file-explorer/styles.ts -- changed here (breadcrumb field border)
Sibling: website/src/apps/md-notebook/MdNotebookPage.tsx -- changed here (rendered/raw switch border)

Pattern harvest

Reusable: the in-place data-theme switch with transitions off gives a two-theme comparison from one DOM, with no element matching across loads. The planted must-report / must-not-report controls are what keep a computed-style gate from passing vacuously. Per-route ready text taken from a fixture row keeps an app page from passing at its empty or error state.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@CrysisDeu
CrysisDeu requested review from a team and KiroCrewCaptain as code owners October 29, 2026 02:51
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 29, 2026
@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of cf3c5fd3045d30c591d9a3937073caa22c1609cd — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks: both visible changes are only a border added to an existing control, and the before and after screenshots in both themes show them. The blind reader read both correctly.

Notes

  • .mc-fe-breadcrumbs:hover { border-color:var(--muted) } is a changed state that no screenshot shows. A hover still might help confirm the darker border shows up clearly against the new resting border.

[UX-REVIEWED] cf3c5fd

Description read

[DESCRIPTION-READ] 1460e9e84a73adeab3eda2680eecb2a64ae6c168aaec1733b80177854ce51554

That sha256 names everything this verdict read: the PR description, plus the 11 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of cf3c5fd3045d30c591d9a3937073caa22c1609cd — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the gate checks rendered output for a rule only rendered output can answer, the two card fixes have screenshots, and the patch takes nothing away.

Notes

  • ROUTES lists the 23 app pages by hand, so a built-in app added to website/src/apps/builtinRegistry.ts later goes unchecked until someone remembers to add it, the same reliance on memory this gate replaces. Building the app routes from the registry, or failing when the registry has an app ROUTES lacks, would close that.

[DESIGN-REVIEWED] cf3c5fd

Description read

[DESCRIPTION-READ] deea28dd079424fc4c0b204c914663fe7185925394e75280684f595d72921382

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of cf3c5fd3045d30c591d9a3937073caa22c1609cd — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. The gate enforces a documented rule (theming-contract.md, "A card must carry its own edge") and has already caught two real cards on main. The notes cover three pieces that nothing uses yet.

Notes

  • Item 6 — zero consumers: CI runs it with --json "$RUNNER_TEMP/kiro-light-cards.json", but no upload-artifact step in the e2e job picks up that path, so the file is thrown away when the job ends. The console.error failure list already carries every hit. Subtraction: drop --json … from the ci.yml step.
  • Item 7 — zero consumers: const EXEMPT = [] and the stale-exemption loop ship with no entries. Subtraction: delete EXEMPT, exemptHits and exemptBy until a first exemption exists.
  • Item 8 — duplicate of the check-kiro-light-cards.mjs header docblock: docs/ci/kiro-light-card-gate.md repeats the rule, the probe steps and the canaries the script already documents, and the theming-contract.md edit names the script. Subtraction: delete the new doc and its docs/ci/README.md row, and point theming-contract.md at the script.

What this change ships

Inventory (8 items) — 5 justified

Intent: catch, in CI, any dashboard surface that disappears in kiro-light because it has no edge of its own. This is an ADDITION (a gate) plus two fixes the gate found.

  1. CI now fails when a surface is a card in light or kiro-dark but has no edge in kiro-light, across 33 routes — justified
  2. The File Explorer breadcrumb field now shows a border at rest — justified
  3. The breadcrumb's hover border changes from --border to --muted — justified
  4. The Notes rendered/raw switch track gains a border — justified
  5. Planted control boxes on every route prove the probe is working — justified
  6. CI writes a JSON hit report that nothing uploads — zero consumers
  7. An empty EXEMPT list with a stale-entry check — zero consumers
  8. A new docs/ci page and README row — duplicate of the script header

[FIRST-PRINCIPLES-REVIEWED] cf3c5fd

Description read

[DESCRIPTION-READ] d3505d59e17797f5abc4a3b1b9071c4a1b315de8e9cf3f2c9d04f0fcf7d5fd86

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed cf3c5fd3045d30c591d9a3937073caa22c1609cd — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] cf3c5fd

Verdict parsed from the review's SHA-scoped output markers for commit cf3c5fd3045d30c591d9a3937073caa22c1609cd.

False positive or not applicable? A repository writer can comment:
/ai-review override fable cf3c5fd3045d30c591d9a3937073caa22c1609cd false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of cf3c5fd3045d30c591d9a3937073caa22c1609cd and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] cf3c5fd

False positive or not applicable? A repository writer can comment:
/ai-review override gpt cf3c5fd3045d30c591d9a3937073caa22c1609cd false-positive: <reason, 20 to 500 characters>

@CrysisDeu
CrysisDeu force-pushed the fix/kiro-light-card-gate-8751 branch from 3b8d801 to 4393ee4 Compare October 29, 2026 04:11
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 29, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

REQUEST_CHANGES at 4393ee47a661bd03c489c5203039ba254b66ac0c (issue needed, no code defect found).

The gate looks sound. It renders ten routes in kiro-light, compares each painted surface against light and kiro-dark in the same DOM, and plants must-report and must-not-report canaries on every route so a blind probe fails (check-kiro-light-cards.mjs#L95-L100). The CI step reuses the e2e job's build, adds no permissions or secrets, and passed on this head.

Blocker: untracked deferral. "Not a goal" leaves built-in app pages "for a later route addition", and the theming contract now says pages outside the list are only caught in review (theming-contract.md#L72-L74). #8751 named those app pages, and Fixes #8751 will close it on merge, so nothing would track the gap. Please open one issue for app-page coverage (per-app fixtures) and link it in the description, or switch to Part of #8751.

AI findings judged non-blocking

  • First Principles: unused --json report, empty EXEMPT machinery, doc repeats the script header. These are subtraction suggestions with no user-visible harm.
  • Design: Chromium style serialisation drift could fail the gate. Canaries are checked first on every route, so drift fails loudly as a canary miss (#L327-L332).

— crew-pr-reviewer (r134)

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 29, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

Thanks. Took the second option: the description now says Part of #8751 instead of Fixes #8751, so merging leaves #8751 open to track built-in app-page coverage (per-app fixtures). closingIssuesReferences is now empty. The "Not a goal" line says the same. No code change, so no new push.

On the non-blocking notes: agreed they are subtraction suggestions; leaving the --json report and EXEMPT hook as they are unless you want them removed.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 29, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

@iamwhatever thanks for the review. App-page coverage is now in this PR, on head 5943a83, so nothing is deferred.

  • check-kiro-light-cards.mjs now also renders all 23 built-in app pages from builtinRegistry.ts: /worlds, /channels, /auto-improvement, /auto-research, /aws-control, /file-explorer, /code-review-sage, /workflows, /dev-fleet, /issue-radar, /meetings, /papyrus, /pptx-maker, /ops-mission-control, /design-critique, /crew-companion, /projects, /md-notebook, /mochi, /spec-builder, /personal-shopper, /design-tweak, /project-scaffolder. Each route has ready text that only its real content shows, and the existing canaries and error-boundary checks run on every one.
  • APP_FIXTURES gives per-app answers to the six pages that crashed or showed a backend-error notice against the generic stubs: AWS Control (accounts, profiles, consent, costs, drive, shares), File Explorer (health, tree, git-status), PPTX Maker (engine, deps, decks, deck, styles, templates), Mission Control (state, incidents, ledger), Notes (health, vaults, settings, notes, changes) and Mochi (pet-state, stats, settings, watchlist, pinned, plan, activity, manifest). Each has one populated row, and that row is the route's ready text.
  • The sweep found two real bare cards, and both now have their own border instead of an exemption: the File Explorer breadcrumb field (file-explorer/styles.ts) and the Notes rendered/raw switch (MdNotebookPage.tsx). The description has before/after screenshots of both.
  • The theming contract and docs/ci/kiro-light-card-gate.md now describe the full route list. The line saying pages outside the list are only caught in review is gone. The CI step cap is now 10 minutes for 33 routes.

The description is back to Fixes #8751. Please re-review.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 29, 2026
Zezhen Xu added 2 commits October 29, 2026 09:44
…style sweep

Render ten dashboard routes of the built SPA in kiro-light over loopback
with fixture API answers and fail when a surface is a card in the light
or kiro-dark theme but has no border, ring, shadow or outline in
kiro-light, where --card equals --bg. Planted bare and bordered controls
on each route keep the probe from passing vacuously.

Fixes #8751
Add the 23 built-in app pages from builtinRegistry.ts to the gate's route
list, each with ready text that only its real content shows. The pages
that crash or stop at a backend-error notice against the generic stub
answers (AWS Control, File Explorer, PPTX Maker, Mission Control, Notes,
Mochi) get per-app fixtures with one populated row each.

The sweep found two bare cards on those pages, and both now carry a
border: the File Explorer breadcrumb field and the Notes rendered/raw
switch.

Fixes #8751
@CrysisDeu
CrysisDeu force-pushed the fix/kiro-light-card-gate-8751 branch from 5943a83 to cf3c5fd Compare October 29, 2026 09:45
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 29, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving cf3c5fd.

Our r134 blocker (untracked app-page coverage) is resolved: the gate now renders all 23 built-in app pages plus the 10 core routes (ROUTES), with planted canaries on every route so a probe that matches nothing fails (L429-L449). The CI step adds no permissions or secrets, serves only on 127.0.0.1, and ran green in the E2E job on this head. The two card fixes are one border each, with screenshots. All lanes pass and every check is green.

AI findings judged non-blocking

  • Design: ROUTES is hand-listed, so a future app can be missed. Every page that exists today is covered, and the theming contract tells authors to add new pages. A registry cross-check would be a nice later addition.
  • UX: no screenshot of the breadcrumb hover state. The hover rule only darkens an existing border. This is evidence polish.
  • First Principles 6-8: the unused --json report, the empty EXEMPT list and the docs page are extra surface with no user harm. The author chose to keep them.

— crew-pr-reviewer (r135)

@iamwhatever
iamwhatever merged commit a632b3b into main Oct 29, 2026
94 checks passed
@iamwhatever
iamwhatever deleted the fix/kiro-light-card-gate-8751 branch October 29, 2026 17:07
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 29, 2026
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.

ci: gate kiro-light against borderless bg-card surfaces with a rendered computed-style sweep

2 participants