dirtydishes/islandflow
1
0
Fork 0
Code Issues 2 Pull requests 4 Projects Releases Packages Wiki Activity Actions 1

harden terminal view, add $impeccable design docs, update AGENTS.md

Browse source
This commit is contained in:
dirtydishes 2026-05-14 18:26:46 -04:00
parent 1089174264
commit 9644e9ceef
10 changed files with 1716 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

486
docs/terminal-audit-2026-05-14-0432.html Normal file
View file

@ -0,0 +1,486 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Terminal Audit - 2026-05-14 04:32</title>
<style>
:root {
color-scheme: dark;
--bg: #0b1016;
--panel: #111820;
--panel-2: #0d141b;
--border: rgba(255, 255, 255, 0.1);
--text: #e6edf4;
--text-dim: #90a0b2;
--text-faint: #6e7b8c;
--accent: #f5a623;
--accent-soft: rgba(245, 166, 35, 0.14);
--green: #25c17a;
--green-soft: rgba(37, 193, 122, 0.16);
--red: #ff6b5f;
--red-soft: rgba(255, 107, 95, 0.16);
--blue: #4da3ff;
--blue-soft: rgba(77, 163, 255, 0.16);
}
* {
box-sizing: border-box;
}
body {
margin: 0;
font-family: Inter, "IBM Plex Sans", Arial, sans-serif;
background: linear-gradient(180deg, #081017 0%, #05070a 100%);
color: var(--text);
}
main {
width: min(1100px, calc(100vw - 32px));
margin: 0 auto;
padding: 32px 0 48px;
}
h1,
h2,
h3,
h4,
p,
ul,
ol,
table {
margin-top: 0;
}
h1,
h2,
h3 {
letter-spacing: 0.04em;
}
h1 {
font-size: 2rem;
margin-bottom: 10px;
}
h2 {
font-size: 1.15rem;
margin-bottom: 14px;
}
h3 {
font-size: 0.95rem;
margin-bottom: 10px;
text-transform: uppercase;
color: var(--text-dim);
}
p,
li,
td,
th {
line-height: 1.55;
color: var(--text);
}
.lede {
color: var(--text-dim);
max-width: 76ch;
}
.summary {
padding: 24px;
border: 1px solid var(--border);
border-radius: 16px;
background: linear-gradient(180deg, rgba(255, 255, 255, 0.035), rgba(255, 255, 255, 0.02));
margin-bottom: 24px;
}
.score-row {
display: flex;
flex-wrap: wrap;
gap: 12px;
align-items: center;
margin: 14px 0 18px;
}
.score-badge,
.pill {
display: inline-flex;
align-items: center;
gap: 8px;
min-height: 32px;
padding: 6px 10px;
border-radius: 999px;
border: 1px solid var(--border);
background: rgba(255, 255, 255, 0.03);
font-size: 0.82rem;
}
.score-badge {
border-color: rgba(245, 166, 35, 0.35);
background: var(--accent-soft);
color: #ffe2aa;
font-weight: 700;
}
.pill-good {
border-color: rgba(37, 193, 122, 0.35);
background: var(--green-soft);
}
.pill-warn {
border-color: rgba(245, 166, 35, 0.35);
background: var(--accent-soft);
}
.pill-risk {
border-color: rgba(255, 107, 95, 0.35);
background: var(--red-soft);
}
.panel {
padding: 22px 24px;
border: 1px solid var(--border);
border-radius: 16px;
background: var(--panel);
margin-bottom: 20px;
}
.subpanel {
padding: 18px;
border: 1px solid var(--border);
border-radius: 14px;
background: var(--panel-2);
margin-top: 16px;
}
table {
width: 100%;
border-collapse: collapse;
font-size: 0.94rem;
}
th,
td {
padding: 12px 10px;
border-bottom: 1px solid var(--border);
text-align: left;
vertical-align: top;
}
th {
color: var(--text-dim);
font-size: 0.8rem;
text-transform: uppercase;
letter-spacing: 0.08em;
}
code {
font-family: "IBM Plex Mono", Menlo, monospace;
font-size: 0.88em;
color: #ffe2aa;
}
.finding {
border-top: 1px solid var(--border);
padding-top: 18px;
margin-top: 18px;
}
.finding:first-of-type {
border-top: 0;
padding-top: 0;
margin-top: 0;
}
.meta {
color: var(--text-dim);
font-size: 0.92rem;
}
.meta strong {
color: var(--text);
}
.note {
color: var(--text-dim);
}
.verdict-pass {
color: #bfe7cf;
}
.footer-note {
color: var(--text-dim);
font-size: 0.95rem;
}
@media (max-width: 720px) {
main {
width: min(100vw - 20px, 1100px);
padding: 20px 0 32px;
}
.summary,
.panel {
padding: 18px;
}
th,
td {
padding: 10px 8px;
font-size: 0.9rem;
}
}
</style>
</head>
<body>
<main>
<section class="summary">
<h1>Terminal View Audit</h1>
<p class="lede">
Audit report for the Islandflow terminal view, formatted for handoff and review. This preserves the
full findings set: scorecard, anti-pattern verdict, executive summary, detailed issues, systemic
patterns, positive findings, and recommended follow-up commands.
</p>
<div class="score-row">
<span class="score-badge">Overall Score: 11/20</span>
<span class="pill pill-warn">Rating Band: Acceptable</span>
<span class="pill pill-risk">Severity Mix: P0 0, P1 5, P2 3, P3 1</span>
<span class="pill">Generated: 2026-05-14 04:32</span>
</div>
<p>
The terminal does <strong>not</strong> read as generic AI-generated UI overall. It has a coherent
instrument-panel identity, consistent density, and restrained accent use. The biggest problems are
implementation quality issues: invalid nested interactive controls, inaccessible drawer behavior,
weak focus treatment, mobile layouts that depend on horizontal scrolling, token drift, and repeated
banned side-stripe accents.
</p>
</section>
<section class="panel">
<h2>Audit Health Score</h2>
<table>
<thead>
<tr>
<th>#</th>
<th>Dimension</th>
<th>Score</th>
<th>Key Finding</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>Accessibility</td>
<td>2/4</td>
<td>Invalid nested interactive controls in options rows.</td>
</tr>
<tr>
<td>2</td>
<td>Performance</td>
<td>3/4</td>
<td>Virtualization is good, but blur-heavy chrome and overlays add avoidable cost.</td>
</tr>
<tr>
<td>3</td>
<td>Responsive Design</td>
<td>2/4</td>
<td>Core tables rely on large fixed minimum widths and horizontal scrolling.</td>
</tr>
<tr>
<td>4</td>
<td>Theming</td>
<td>2/4</td>
<td>Token base exists, but many hard-coded colors and undefined vars bypass it.</td>
</tr>
<tr>
<td>5</td>
<td>Anti-Patterns</td>
<td>2/4</td>
<td>Repeated side-stripe accents violate the stated design bans.</td>
</tr>
<tr>
<td><strong>Total</strong></td>
<td></td>
<td><strong>11/20</strong></td>
<td><strong>Acceptable</strong></td>
</tr>
</tbody>
</table>
</section>
<section class="panel">
<h2>Anti-Patterns Verdict</h2>
<p class="verdict-pass">
Pass, with caveats.
</p>
<p>
The terminal does not look AI-generated overall. It has a coherent instrument-panel identity,
consistent density, and restrained accent use. The main tells are implementation-level:
banned side-stripe accents on live rows, decorative blur-heavy chrome, and some product-UI
typography choices that drift toward display styling.
</p>
</section>
<section class="panel">
<h2>Executive Summary</h2>
<ul>
<li><strong>Audit Health Score:</strong> 11/20 (Acceptable)</li>
<li><strong>Total issues found:</strong> 9</li>
<li><strong>Severity mix:</strong> P0: 0, P1: 5, P2: 3, P3: 1</li>
<li>
<strong>Top issues:</strong> nested buttons inside clickable options rows, drawers that are not true
accessible dialogs, suppressed focus indicators, mobile dependence on oversized horizontal tables,
and repeated banned side-stripe row styling.
</li>
</ul>
</section>
<section class="panel">
<h2>Detailed Findings By Severity</h2>
<article class="finding">
<h3>[P1] Nested Interactive Controls Inside Clickable Row</h3>
<p class="meta"><strong>Location:</strong> <code>apps/web/app/terminal.tsx:7118-7135</code>, <code>apps/web/app/terminal.tsx:7155-7179</code></p>
<p class="meta"><strong>Category:</strong> Accessibility</p>
<p><strong>Impact:</strong> Decorated option rows render as outer <code>&lt;button&gt;</code> elements containing inner contract-focus <code>&lt;button&gt;</code> elements. This is invalid HTML and can create inconsistent tab order, click handling, and screen-reader output.</p>
<p><strong>WCAG/Standard:</strong> WCAG 4.1.2 Name, Role, Value; HTML interactive content nesting rules</p>
<p><strong>Recommendation:</strong> Split row selection and contract focus into non-nested controls. Use a non-button row container with one explicit action button, or keep the row as the only button and turn inner controls into non-interactive text.</p>
<p><strong>Suggested command:</strong> <code>$impeccable harden terminal view</code></p>
</article>
<article class="finding">
<h3>[P1] Drawer Panels Are Visually Drawers, Not Accessible Dialogs</h3>
<p class="meta"><strong>Location:</strong> <code>apps/web/app/terminal.tsx:4524-4629</code>, <code>4639-4737</code>, <code>4747-4841</code>, <code>4850-4952</code>, close handling at <code>5070-5102</code></p>
<p class="meta"><strong>Category:</strong> Accessibility</p>
<p><strong>Impact:</strong> The drawers close on outside click and <code>Escape</code>, but they lack <code>role="dialog"</code>, <code>aria-modal</code>, focus entry, focus return, and trap behavior. Keyboard users can tab behind the drawer and lose context.</p>
<p><strong>WCAG/Standard:</strong> WCAG 2.1.1 Keyboard, 2.4.3 Focus Order, 4.1.2 Name, Role, Value</p>
<p><strong>Recommendation:</strong> Promote drawers to true modal dialogs with labelled titles, initial focus, focus containment, inert background, and focus restoration on close.</p>
<p><strong>Suggested command:</strong> <code>$impeccable harden terminal view</code></p>
</article>
<article class="finding">
<h3>[P1] Focus Indicators Are Suppressed In Multiple Core Controls</h3>
<p class="meta"><strong>Location:</strong> <code>apps/web/app/globals.css:325-327</code>, <code>413-415</code>, <code>1054-1058</code>, <code>1213-1218</code></p>
<p class="meta"><strong>Category:</strong> Accessibility</p>
<p><strong>Impact:</strong> Several controls explicitly remove the browser outline. Some surfaces get only a subtle background shift, which is weaker than a reliable visible focus ring, especially in dense data views.</p>
<p><strong>WCAG/Standard:</strong> WCAG 2.4.7 Focus Visible</p>
<p><strong>Recommendation:</strong> Restore strong <code>:focus-visible</code> treatment on inputs, row buttons, and inline instrument actions using a consistent high-contrast ring or border treatment.</p>
<p><strong>Suggested command:</strong> <code>$impeccable harden terminal view</code></p>
</article>
<article class="finding">
<h3>[P1] ARIA Table Semantics Are Incomplete</h3>
<p class="meta"><strong>Location:</strong> <code>apps/web/app/terminal.tsx:7061-7075</code>, <code>7251-7259</code>, <code>7348-7359</code>, <code>7496-7505</code>, <code>7609-7616</code>, <code>7732-7739</code></p>
<p class="meta"><strong>Category:</strong> Accessibility</p>
<p><strong>Impact:</strong> The app uses <code>role="table"</code> and <code>role="row"</code> but not full table semantics such as <code>rowgroup</code>, <code>columnheader</code>, and cell roles. Screen readers will get a weaker structural model than a real table or fully formed ARIA grid.</p>
<p><strong>WCAG/Standard:</strong> WCAG 1.3.1 Info and Relationships</p>
<p><strong>Recommendation:</strong> Prefer semantic <code>&lt;table&gt;</code> markup where possible, or complete the ARIA table structure consistently.</p>
<p><strong>Suggested command:</strong> <code>$impeccable harden terminal view</code></p>
</article>
<article class="finding">
<h3>[P1] Narrow-Screen Experience Depends On Oversized Horizontal Tables</h3>
<p class="meta"><strong>Location:</strong> <code>apps/web/app/globals.css:967-1009</code>, <code>1116-1144</code>, <code>1645-1714</code></p>
<p class="meta"><strong>Category:</strong> Responsive Design</p>
<p><strong>Impact:</strong> Major views keep <code>min-width</code> values like <code>1280px</code>, <code>1260px</code>, <code>900px</code>, and <code>820px</code>. The mobile fallback is horizontal scroll rather than structural adaptation, which increases cognitive load and makes comparison harder on phones and small tablets.</p>
<p><strong>WCAG/Standard:</strong> Responsive design best practice</p>
<p><strong>Recommendation:</strong> Define compact column sets, progressive disclosure, or cardless stacked row summaries under mobile breakpoints instead of preserving full desktop schema.</p>
<p><strong>Suggested command:</strong> <code>$impeccable adapt terminal view</code></p>
</article>
<article class="finding">
<h3>[P2] Touch Targets Are Below Recommended Minimum In Key Controls</h3>
<p class="meta"><strong>Location:</strong> <code>apps/web/app/globals.css:255</code>, <code>330-347</code>, <code>365-379</code>, <code>461-468</code></p>
<p class="meta"><strong>Category:</strong> Responsive Design</p>
<p><strong>Impact:</strong> Controls and chips commonly bottom out around <code>32px</code> height. That is workable on desktop, but it is tight for touch use and increases mis-taps on mobile.</p>
<p><strong>WCAG/Standard:</strong> WCAG 2.5.5 Target Size (AAA), platform mobile guidance</p>
<p><strong>Recommendation:</strong> Raise interactive height to at least <code>40px</code>, ideally <code>44px</code>, for topbar controls, focus chips, and filter triggers under touch breakpoints.</p>
<p><strong>Suggested command:</strong> <code>$impeccable adapt terminal view</code></p>
</article>
<article class="finding">
<h3>[P2] Token Discipline Is Partial, Not Consistent</h3>
<p class="meta"><strong>Location:</strong> <code>apps/web/app/globals.css:41</code>, <code>306</code>, <code>321</code>, <code>362</code>, <code>375</code>, <code>479</code>, <code>502</code>, <code>565</code>, <code>616</code>, <code>763</code>, <code>1452-1470</code></p>
<p class="meta"><strong>Category:</strong> Theming</p>
<p><strong>Impact:</strong> The file starts with a clear token layer, but many later rules bypass it with hard-coded hex values. That makes palette evolution and future theme work harder.</p>
<p><strong>WCAG/Standard:</strong> Theming and system quality</p>
<p><strong>Recommendation:</strong> Replace one-off literals with named variables, especially amber text variants, chart surface background, and severity-strip foreground colors.</p>
<p><strong>Suggested command:</strong> <code>$impeccable polish terminal view</code></p>
</article>
<article class="finding">
<h3>[P2] Undefined CSS Variables Create Silent Theming Bugs</h3>
<p class="meta"><strong>Location:</strong> <code>apps/web/app/globals.css:398</code>, <code>1186</code></p>
<p class="meta"><strong>Category:</strong> Theming</p>
<p><strong>Impact:</strong> <code>var(--text-muted)</code> and <code>var(--muted)</code> are referenced but not defined in <code>:root</code>. Those declarations will fail and fall back to inherited color, which makes the result fragile and inconsistent.</p>
<p><strong>WCAG/Standard:</strong> CSS correctness</p>
<p><strong>Recommendation:</strong> Replace them with existing tokens such as <code>--text-dim</code> or define the missing variables explicitly.</p>
<p><strong>Suggested command:</strong> <code>$impeccable harden terminal view</code></p>
</article>
<article class="finding">
<h3>[P2] Blur-Heavy Chrome Is Overused For Product UI</h3>
<p class="meta"><strong>Location:</strong> <code>apps/web/app/globals.css:174-176</code>, <code>518-525</code>, <code>1504-1506</code></p>
<p class="meta"><strong>Category:</strong> Performance / Anti-Pattern</p>
<p><strong>Impact:</strong> <code>backdrop-filter: blur(12px)</code> and <code>blur(18px)</code> on persistent UI surfaces add cost and push the product UI slightly toward decorative glass treatment, which the design rules explicitly warn against as a default.</p>
<p><strong>WCAG/Standard:</strong> Performance and product-design guidance</p>
<p><strong>Recommendation:</strong> Keep blur only where separation is essential, or replace it with tonal contrast and border treatment.</p>
<p><strong>Suggested command:</strong> <code>$impeccable quieter terminal view</code></p>
</article>
<article class="finding">
<h3>[P3] Side-Stripe Row Accents Are Repeated Across Tables</h3>
<p class="meta"><strong>Location:</strong> <code>apps/web/app/globals.css:1092-1114</code>, <code>1221-1224</code></p>
<p class="meta"><strong>Category:</strong> Anti-Pattern</p>
<p><strong>Impact:</strong> The interface repeatedly uses <code>border-left: 3px</code> to communicate severity, direction, and classifier state. That is one of the skill's explicit banned patterns and makes rows feel more template-like than intentional.</p>
<p><strong>WCAG/Standard:</strong> Design-system rule</p>
<p><strong>Recommendation:</strong> Move semantic emphasis into full-row tinting, chips, iconography, or stronger text hierarchy instead of colored side rails.</p>
<p><strong>Suggested command:</strong> <code>$impeccable polish terminal view</code></p>
</article>
</section>
<section class="panel">
<h2>Patterns And Systemic Issues</h2>
<ul>
<li>Accessibility semantics are strongest at the surface level, labels and buttons exist, but weaker in composite patterns, drawers, virtualized tables, and focus handling.</li>
<li>The responsive strategy is mostly preserve desktop density and allow scrolling, not restructure the workflow for narrow screens.</li>
<li>The CSS starts from a tokenized system, then drifts into literal color values in later component rules.</li>
<li>The visual system is disciplined overall, but a few repeated product bans, side stripes and default blur, show up across multiple components.</li>
</ul>
</section>
<section class="panel">
<h2>Positive Findings</h2>
<ul>
<li>The terminal has a clear, distinctive product identity without falling into meme-trader styling.</li>
<li>Virtualized list rendering is the right performance baseline for these dense live data views.</li>
<li>The top-level shell and pane structure are predictable and support fast scanning.</li>
<li>Core inputs are labelled, and many actionable rows are implemented as real buttons instead of click-only divs.</li>
<li>Color usage is generally restrained and semantically meaningful, even where implementation cleanup is still needed.</li>
</ul>
</section>
<section class="panel">
<h2>Recommended Actions</h2>
<ol>
<li><strong>[P1] <code>$impeccable harden terminal view</code>:</strong> Fix nested buttons, accessible dialog behavior, focus visibility, and incomplete ARIA table semantics.</li>
<li><strong>[P1] <code>$impeccable adapt terminal view</code>:</strong> Redesign narrow-screen table behavior and increase touch target sizes in the shell and filter controls.</li>
<li><strong>[P2] <code>$impeccable quieter terminal view</code>:</strong> Reduce default blur and glass treatment in topbar, popover, and drawer chrome.</li>
<li><strong>[P2] <code>$impeccable polish terminal view</code>:</strong> Normalize tokens, remove hard-coded color drift, and replace banned side-stripe accents.</li>
<li><strong>[P2] <code>$impeccable polish terminal view</code>:</strong> Final cleanup pass once the structural fixes are in.</li>
</ol>
<div class="subpanel">
<p class="footer-note">
You can ask me to run these one at a time, all at once, or in any order you prefer.
</p>
<p class="footer-note">
Re-run <code>$impeccable audit</code> after fixes to see the score improve.
</p>
</div>
</section>
</main>
</body>
</html>