A modal announcement exposed a provider bug and machine-thin docs

⁠Build log series⁠: I hand a real screen to an AI that has never seen Gunjo (@gunjo/ui) and let it build. Each article doubles as a guide to building it with Gunjo. After round one, the settings screen, this round covered a ⁠modal announcement banner⁠.

The conditions matched the previous round. I gave one agent with no knowledge of Gunjo ⁠only the public npm package @gunjo/ui (alpha.2) and the gunjo.jp docs⁠. It could not see the source repository. It had to work from a blank Next.js app (React 19 and Tailwind v4) and get through npm run build on its own.

The assignment

This is the announcement pattern almost every product needs.

• A ⁠dismissible banner⁠ at the top, with "v2 is live," a call to action, and a close button
• An ⁠announcement modal⁠ opened from the banner, with a title, body, primary and secondary buttons, and automatic opening on the first visit
• A ⁠confirmation toast⁠ after dismissal or acknowledgment: "You're all caught up"

This round crossed different categories from the first: ⁠Feedback (Banner and Toast) and Overlay (Modal)⁠. Each new round sends a cold agent through another part of the component catalog.

Result: 4/5. It worked

npm run build passed, /announce rendered as a static page, and I confirmed ⁠zero console errors⁠ on a real device.

Once again, the most useful feature was ⁠having every typed component available from one place, @gunjo/ui⁠. After reading src/index.ts, the agent found Banner, Modal, Toast, ToastProvider, and useToast. The import resolved with no path adjustments: import { Banner, Modal, ToastProvider, useToast } from "@gunjo/ui". It also read the prop contracts directly from the bundled .tsx source: action and onDismiss on Banner, isOpen and footer on Modal, and showToast(msg, type) returned by useToast(). It never needed a className override.

Two rough edges, one of them painful

1. Banner crashed SSR on its own: a library bug

The first build failed.

Error: `Tooltip` must be used within `TooltipProvider`

The cause was an inconsistency. The close button inside Banner used Tooltip, but ⁠Banner did not provide the TooltipProvider that tooltip required⁠. Toast, in the same Feedback category, wrapped its tooltip in a provider. A straightforward <Banner onDismiss> therefore crashed during server-side rendering (SSR). The agent worked around it by wrapping the page in <TooltipProvider>.

// Final version written by the agent (excerpt)
export default function AnnouncePage() {
  // Banner's dismiss action uses an internal Tooltip without its own provider,
  // so a standalone Banner needs TooltipProvider above it. Toast does not.
  return (
    <TooltipProvider>
      <ToastProvider>
        <Announcement />
      </ToastProvider>
    </TooltipProvider>
  )
}

This was not user error. It was ⁠a trap in the library⁠. I checked the source and logged issue #49. The fix was to make Banner provide its own TooltipProvider, just as Toast did, and align design, implementation, and documentation. It landed in PR#51, with design:verify passing. It was the same correction path as issue #47.

2. My docs were thin from the agent's perspective

This finding stung more. The agent reported that ⁠the docs' code examples were client-side widgets that did not appear in WebFetch or Markdown extraction⁠. Some prop descriptions existed only in Japanese. ⁠The bundled TypeScript types, not the docs, became its most reliable API reference.⁠

That cuts straight into the claim that Gunjo is usable by AI. ⁠The docs site itself was difficult for a machine to read.⁠ The typed entry point and bundled declarations carried the run to 4/5, but the weakness reached the foundation of the idea. The agent also tried /docs/feedback/banner and got a 404 because the real route is the flat /docs/components/banner. The install guide never mentioned ToastProvider. These are small details until an agent with no prior knowledge gets stuck on them.

What I took away

Have the AI use it | Find the rough edges | Fix every source consistently (SSOT) | Run it again

Round one found fixed widths. Round two found the Banner provider bug and asked whether the docs were machine-readable at all. New angles reveal rough edges that the happy path never shows. "AI can use it" is not a declaration. ⁠I can prove it only by repeatedly giving the library to an agent with no prior knowledge and removing what blocks it.⁠ No embellishment and no hiding the misses.

Next up: build log #3

• ⁠A carousel using Carousel and Card⁠, a frequent centerpiece on landing pages and in media lists.

The run

• ⁠gunjo.jp⁠: docs, showcase, and patterns
• ⁠npm: @gunjo/ui⁠ / ⁠GitHub⁠
• Previous round: I gave an AI a settings screen to build, build log #1
• Overview: Gunjo (@gunjo/ui): one design system aligned around a single source of truth
• ⁠GunjoUI by UIXHERO⁠

Gunjo was still in early alpha at the time; issues are welcome.