A blog post exposed the shared cause behind heading defects
/blog/postCaptured at a 375px viewport. Long pages scroll inside the frame.
The screenshots stay in Japanese. Every round is a real screen for a real Japanese industry, so an English re-render would no longer be the screen the agent actually produced.
Write-up
A blog post exposed the shared cause behind heading defects
Build log series: I hand a real screen to an AI that has never seen Gunjo (
@gunjo/ui) and let it build. This round covered a long-form blog post.
I kept the setup cold by sharing the shipped package and docs but withholding the source. The /blog/post assignment called for breadcrumbs, a title, author details, tags, a table of contents, an article with h2 and h3 headings, lists, quotations, several CodeBlock examples, callouts, and related posts.
Round #20 showed that accessibility still needed to be addressed one kind of component at a time. An article page puts the most pressure on heading hierarchy and code-block accessibility, which made it the right next screen.
Result: 4.5/5, with no accessibility bug inside a component
tsc and build passed, the console stayed clear, the server and browser output matched with no hydration errors, and nothing overflowed at 375px. The page had exactly one h1, skipped no heading levels, and connected every table-of-contents link to a real anchor.
The cold agent's key finding was:
The individual components are stable. This round found no new accessibility bug inside a component.
CopyButtonis accessible too.
The strongest result: CodeBlock is a complete component
"use client"plus deterministic regex-based highlighting, with no Shiki work at runtime, kept the server and browser output identical.- The copy button has an
aria-labeland announces "Copied" through a role="status"live region. <pre overflow-x-auto>keeps horizontal scrolling inside the component at 375px instead of overflowing the whole page. The line numbers stay aligned.
What the round exposed: the shared cause of recurring accessibility gaps
No new accessibility bug appeared. Instead, the cold agent identified why the same class of problem kept returning:
1. DocNote could not represent a note, warning, or tip at the time. It supported only default and reference, rendered its title as a <div>, and provided neither a role nor an icon. The docs described it as a callout component, but it could not render the common callout cases. The agent had to hand-roll one. I logged issue #109.
2. At the time, there was no Prose, Heading, or typography component. Consumers had to hand-roll h1 through h6, body spacing, quotations, and a table of contents on every page. No shared component guaranteed one h1 or prevented skipped heading levels. I logged issue #110.
The heading defects I had fixed component by component, including
EmptyStateandStatusScreenin issue #104, were symptoms of the missing typography layer. Individual controls had stabilized, but the gap had moved up to page-level heading hierarchy. To keep accessibility defects from recurring, that shared layer needed to be the next fix.
What I took away: prevent the class of defect, not just each instance
Through #20: fix accessibility one component at a time (issues #57, #71, #83, #87, #93, and #104)
#21: individual controls are stable, but the shared cause is a missing typography and Heading layer
Next: add Heading and Prose so the source can enforce page-level heading hierarchy
The accessibility work had moved beyond fixing isolated recurrences to removing their shared cause. With <Heading level> and <Prose>, the design system can enforce the heading hierarchy of long-form pages and prevent page-level omissions like issue #104 by construction. That is a design change, not a local patch, so I moved it to the beta gate.
(All findings in #21 concerned the design or docs, so there was no individual source fix in this session. The Heading and Prose work plus the DocNote extension went to the beta gate.)
Next up: build log #22
- A landing page, pricing comparison, or docs home, continuing with the typography layer and higher-level components.
The run
- gunjo.jp / npm
@gunjo/ui/ GitHub - Earlier rounds: #1 through #20
- Overview: Gunjo (
@gunjo/ui) / Why it exists: Design systems in the age of AI - GunjoUI by UIXHERO
Gunjo was still in early alpha at the time; issues are welcome.
This series is co-created with AI (Claude and Codex). A human designs the experiments, makes the calls, and fact-checks before publishing; the AI does the hands-on work and drafting.
Components from @gunjo/ui
The components this screen's source imports directly.
The code the agent actually wrote
Click a file to expand its source.