resp-vw

npm: https://www.npmjs.com/package/resp-vw · v0.1.1 · repo: github.com/MicaBahurlet/MySkills

An agent skill for viewport-proportional responsive design: author sizes in design pixels, resolve them through one bounded fluid unit, and recompose deliberately at a small set of breakpoint ranges.

Ships as an npm package with an installer, so the skill can be dropped into any project for Cursor, Claude Code, Codex, or any agent that reads .agents/skills.

Install in any project

From the root of the project where you want the skill:

npx resp-vw install

That downloads the package from npm and writes the skill into .agents/skills/resp-vw and .cursor/skills/resp-vw.

To keep it as a dev dependency:

npm i -D resp-vw
npx resp-vw install

Optional script:

npm pkg set scripts.skills:install="resp-vw install"
npm run skills:install

More install options

npx resp-vw install --target=all          # .agents, .cursor, .claude, .codex
npx resp-vw install --target=claude       # a single location
npx resp-vw install --home                # into the home directory instead of the project
npx resp-vw install --dir=./apps/web/.agents/skills
npx resp-vw install --dry-run             # show destinations without writing

The idea

A design delivered at a single width encodes proportions, not pixels. Convert them once:

1 design px = 100vw / design-width

Expressed as one custom property, bounded on both ends so it never shrinks below legibility or grows unchecked on a large monitor:

:root {
  --rv-design-width: 1440;
  --rv-floor: 1200;
  --rv-ceil: 1920;

  --rv-dpx: clamp(
    calc(1px * var(--rv-floor) / var(--rv-design-width)),
    calc(100vw / var(--rv-design-width)),
    calc(1px * var(--rv-ceil) / var(--rv-design-width))
  );
}

Then every size reads as the number in the design file:

.hero { font-size: max(2.5rem, calc(180 * var(--rv-dpx))); }
.card { width: calc(490 * var(--rv-dpx)); }

Verified in Chrome across the ranges:

| Viewport | --rv-dpx | calc(180 * var(--rv-dpx)) | | --- | --- | --- | | 390 (mobile anchor) | 1.000px | — | | 1199 (tablet anchor) | 1.171px | — | | 1440 (desktop anchor) | 1.000px | 180px, exactly as designed | | 2560 | 1.333px, capped | 240px instead of an unbounded 320px |

Ranges re-anchor the unit rather than restating every value, and reading text stays rem-anchored so browser zoom keeps working.

What the skill contains

skills/resp-vw/
├── SKILL.md                              Core rule, workflow, non-negotiables
├── assets/
│   └── fluid-scale.css                   Copy-paste foundation: unit, ranges, safety rules
├── references/
│   ├── fluid-scale-model.md              Math, bounds, accessibility limits, token layer
│   ├── breakpoints-and-recomposition.md  Range roles, re-anchoring, boundary continuity, line breaks
│   ├── composition-recipes.md            Heroes, split sections, galleries, sticky stacks, marquees
│   ├── responsive-media.md               Art direction, sizes from proportional widths, video
│   ├── motion-and-scroll.md              Scoped animation, pinned sections, reduced motion
│   ├── stack-adapters.md                 CSS, SCSS, Tailwind v3/v4, React/Next, WordPress
│   └── responsive-qa.md                  Viewport matrix, checklists, debugging by symptom
└── scripts/
    ├── px-to-fluid.mjs                   Design px to unit, vw, or a literal clamp()
    └── responsive-audit.mjs              Overflow, tiny text, tap targets across viewports

Tools

Convert a value, or generate a token block:

npx resp-vw fluid 82 --design=1440
npx resp-vw fluid --from=44@390 --to=180@1440
npx resp-vw fluid --scale=16,20,24,32,48,82,180 --prefix=type

Audit a running site across the viewport matrix. Reports horizontal overflow with the elements responsible, text below a legibility floor, tap targets under 44px, and 100vh usage; exits non-zero on failure, so it can gate CI:

npx resp-vw audit http://localhost:3000
npx resp-vw audit http://localhost:3000 --json --screenshots=./.tmp/shots

The audit needs Playwright in the consumer project:

npm i -D playwright && npx playwright install chromium

Development

npm run check   # syntax check plus the full test suite
npm test

The suite covers the conversion math, the installer across every target, and skill integrity: frontmatter shape, description triggers, reference reachability, and guards against 100vh and width: 100vw creeping into the guidance.

License

MIT © Micaela Bahurlet