doesntbreak

A Claude Agent Skill that makes Claude write web UI which holds up on small screens by default (mobile-first, no horizontal scroll, fluid layouts) working from 320px up, without you ever having to ask for "responsive."

The problem

Vibe-coded UI looks great on a 1440px desktop and falls apart on a 375px phone. The usual symptoms:

• A horizontal scrollbar that shouldn't be there.
• Elements overlapping or squishing into each other.
• Text overflowing its container or getting clipped.
• Tap targets too small to reliably hit with a thumb.

The cause is almost always desktop-first habits: fixed pixel widths, hand-written breakpoints that fight each other, and layouts that were only ever checked at one width.

What it does

The skill bakes responsive discipline into Claude's default output so you don't have to remember to ask for it.

• Mobile-first by default. Base styles target the smallest screen; complexity is layered upward with min-width queries. Never the reverse.
• Non-negotiables, applied automatically:
  • No fixed pixel widths on layout containers: cap with min(100%, Npx).
  • Let flex and grid reflow (flex-wrap, auto-fit grids) instead of hand-written breakpoints.
  • min-height, not fixed height, so containers grow with content.
  • Media capped with max-width: 100%.
  • Touch targets at least 44x44px.
  • At least 16px font on inputs, so iOS Safari doesn't zoom on focus.
  • Long unbroken strings broken with overflow-wrap, not left to overflow.
  • dvh/svh/lvh for full-height sections, so a 100vh hero isn't clipped by the mobile address bar.
  • Wide content (tables, <pre>, code blocks) scrolls in its own overflow-x: auto container, never the page.
• Tests at the real failure points. 320px, 375px, the awkward 768px tablet middle, long content, and a hard check for no horizontal scroll at any width.
• Review mode. Point it at existing layout code and it scans for the usual offenders (fixed widths, missing min-width: 0, desktop-first max-width queries, fixed heights, unconstrained images) and fixes them.
• Tailwind-aware. Maps each rule to the right utilities and flags the common footguns: w-[1200px], missing min-w-0, w-screen, and min-h-screen for heroes.

File structure

doesntbreak/
├── .claude-plugin/
│   ├── plugin.json       # Claude plugin manifest
│   └── marketplace.json  # Claude marketplace
├── .codex-plugin/
│   └── plugin.json       # Codex plugin manifest
├── .agents/plugins/
│   └── marketplace.json  # Codex marketplace
├── hooks/
│   ├── hooks.json        # Claude startup update check
│   └── codex-hooks.json  # Codex startup update check
├── skills/
│   └── doesntbreak/
│       ├── SKILL.md      # the skill instructions Claude loads
│       └── references/
│           └── patterns.md  # detailed CSS mechanics + annotated example
├── commands/
│   ├── audit.md          # /doesntbreak:audit, report-only responsive audit
│   ├── fix.md            # /doesntbreak:fix, apply the fixes, leave them for review
│   └── screenshot-check.md  # /doesntbreak:screenshot-check, measured browser overflow check
├── examples/
│   ├── broken.html       # demo page seeded with all 9 rule violations
│   ├── fixed.html        # same content, each rule corrected
│   └── banner.svg        # deterministic offline fixture media
├── scripts/
│   ├── check-update.js       # committed update-check runtime
│   └── responsive-check.js   # committed system-Chrome runner
├── src/
│   ├── check-update.ts       # strict TypeScript updater source
│   └── responsive-check.ts   # strict TypeScript browser-check source
├── test/
│   ├── check-update.test.mjs
│   ├── responsive-check.test.mjs  # unit + real-browser smoke tests
│   └── tooling.test.mjs           # typecheck + generated-runtime parity
├── tooling/              # repository-only validation scripts
├── tsconfig.json         # strict build into scripts/
├── package.json          # build, validation, and test commands
├── README.md             # this file
├── LICENSE               # MIT
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── SECURITY.md
└── CITATION.cff

skills/doesntbreak/SKILL.md carries the rules and triggers. skills/doesntbreak/references/patterns.md holds the deeper mechanics (the flexbox min-width: 0 trap, clamp() typography, auto-fit grids, container queries, mobile viewport-height units (dvh/svh/lvh), safe-area insets, contained-scroll patterns for wide content (tables, <pre>, code), a Tailwind cheat sheet, and a fully annotated example), which Claude reads when it needs the details.

The skill remains Markdown-first. Its two executable helpers are authored in strict TypeScript under src/ and compiled to committed ESM JavaScript under scripts/. Plugin users run that JavaScript directly, so installation requires no TypeScript runtime. playwright-core remains the only runtime library used by the browser check; the startup update check uses only Node.js APIs.

Install

Two ways to install, depending on whether you want a managed plugin or a plain skill.

As a Claude Code plugin

In Claude Code, add the marketplace and install the plugin:

/plugin marketplace add Kyaa-A/doesntbreak
/plugin install doesntbreak@doesntbreak

Plugin skills are namespaced by the plugin name, so the command is /doesntbreak:doesntbreak.

As a Codex plugin

Add the Git-backed marketplace and install the plugin:

codex plugin marketplace add Kyaa-A/doesntbreak
codex plugin add doesntbreak@doesntbreak

Codex plugins include the skill and the startup update check. After installation, open /hooks in a fresh Codex session, review the command, and trust it before expecting update notices. Codex does not provide the updater with an interactive yes/no prompt.

As a plain skill (for a bare /doesntbreak)

Copy the skill folder into your personal skills directory:

git clone https://github.com/Kyaa-A/doesntbreak.git
cp -r doesntbreak/skills/doesntbreak ~/.claude/skills/doesntbreak

Installed this way the command is simply /doesntbreak. Skill directories under ~/.claude/skills/ are not namespaced.

Claude Code and Codex discover the skill automatically via the description field in SKILL.md. No configuration is needed.

Updates

Managed Claude Code and Codex plugin installs can check for a newer release at startup. Claude Code asks you to trust the plugin when it is installed. In Codex, open /hooks in a fresh session, review the startup command, and trust it. The check is best-effort, runs at most once every 24 hours after a successful check, and never downloads, installs, or modifies the plugin. Network errors and malformed responses stay silent.

When a newer version exists, the terminal shows the installed and latest versions plus the manual commands.

Claude Code:

claude plugin marketplace update doesntbreak
claude plugin update doesntbreak@doesntbreak

Restart Claude Code or run /reload-plugins afterward.

Codex 0.147:

codex plugin marketplace upgrade doesntbreak
codex plugin remove doesntbreak@doesntbreak
codex plugin add doesntbreak@doesntbreak

Start a new Codex session afterward and review/trust the command in /hooks. Codex does not show an interactive updater yes/no prompt; update notices are informational and updates remain manual.

Plain skill copies cannot run plugin startup hooks or check for updates automatically. Re-copy the skill from a fresh clone, or pull the repository and copy skills/doesntbreak again. Set DOESNTBREAK_UPDATE_CHECK=0 to disable managed-plugin checks.

Usage

You don't have to invoke it manually. Just ask Claude to build or fix any web UI and it applies the rules on its own:

• "Build a pricing page."
• "This page breaks on my phone. Fix it."

Claude triggers the skill whenever it writes or reviews layout code, even if you never say the word "responsive." To run it deliberately, type the command from your install method above (/doesntbreak for a plain skill, /doesntbreak:doesntbreak for the plugin) and you can pass context after it, e.g. /doesntbreak audit my dashboard layout.

Examples

examples/ holds a deliberately broken page and its corrected twin, so you can watch the audit fire and compare before/after.

Audit the broken page: expect Critical findings (fixed 1200px width, 100vh hero, uncontained wide table, an unbroken overflowing URL), plus Risk findings (unwrapped flex row, unconstrained image, sub-44px tap target, sub-16px input):

/doesntbreak:audit examples/broken.html

Audit the corrected page: expect a clean sweep:

/doesntbreak:audit examples/fixed.html

Both pages render the same content (hero, feature cards, data table). Open them in your browser's device toolbar at 320 / 375 / 768px: broken.html scrolls sideways while fixed.html reflows.

To prove it in a real headless browser instead of by eye, run the measured check. It loads the page at 320 / 375 / 768 / 1440px, reports horizontal overflow with the offending element, and saves a screenshot per width:

/doesntbreak:screenshot-check examples/broken.html
/doesntbreak:screenshot-check examples/fixed.html

screenshot-check also takes a live URL (http://localhost:3000) for checking a running app. Path B requires Node 20+, playwright-core, and an installed system Chrome or Chromium. Run it directly with:

npm install
npm run check:responsive -- --target examples/fixed.html --expect pass

Screenshots default to a new OS temporary directory. The runner checks page-level horizontal overflow; it does not prove that elements never overlap or that visual and touch behavior is correct. For pages with delayed client-side layout, pass --settle-ms N (an integer from 0 through 10000; default 100).

To apply the fixes instead of just reporting them, run fix. It edits the source for the high-confidence rules, flags the judgment calls (such as flex-wrap versus an auto-fit grid), verifies the result in the browser, and leaves the changes unstaged for you to review with git diff. It never commits:

/doesntbreak:fix examples/broken.html

The three commands form a loop: audit reports, fix applies, screenshot-check proves.

License

MIT. Copyright (c) 2026 Asnari (Kyaa-A). See LICENSE.