Responsify

Deterministic responsiveness fixer for frontend projects.

Responsify scans your website source code, detects common responsive layout problems, applies safe AST-based fixes, generates a report, and can validate pages in a real browser. It does not use AI, LLMs, remote APIs, or network services for transformations.

npx @divi-24/responsify . --dry-run

Why Responsify?

Responsiveness issues are repetitive:

• fixed desktop widths
• oversized grids
• huge text on mobile
• images without fluid sizing
• tables that overflow
• forms with cramped inputs
• buttons with small tap targets
• Tailwind classes without breakpoints
• dynamic className strings hidden inside cn, clsx, cva, and variant maps

Responsify automates the boring, deterministic part so developers can focus on the layout decisions that actually need human judgment.

Install

Run without installing:

npx @divi-24/responsify . --dry-run

Install in a project:

npm install -D @divi-24/responsify

Then run:

npx responsify . --dry-run

Quick Start

1. Create a config:

npx @divi-24/responsify init

2. Preview changes safely:

npx @divi-24/responsify . --dry-run

3. Generate a report and apply fixes:

npx @divi-24/responsify . --report --preset next --confidence review

4. Roll back if needed:

npx @divi-24/responsify . --rollback

What It Does

Responsify works in four stages:

1. Scan supported frontend files.
2. Analyze responsiveness risks.
3. Transform safe and review-approved patterns.
4. Report fixes, score, warnings, and validation results.

It can also capture before/after screenshots for changed local HTML pages:

npx @divi-24/responsify . --dry-run --visual-diff

Supported files:

• .tsx
• .jsx
• .ts
• .js
• .css
• .scss
• .sass
• .html

Ignored by default:

• node_modules
• dist
• build
• coverage
• .next
• .git
• .responsify
• responsify-report.html

Features

Static Responsiveness Detection

Responsify detects:

• fixed pixel widths and heights
• width: 100vw overflow risks
• large fixed typography
• no-wrap text
• absolute positioning risks
• large translateX(...) movement
• unresponsive images
• overflowing tables
• fixed Tailwind grids
• arbitrary Tailwind widths like w-[900px]
• small tap target risks

Deterministic Transformations

Examples:

width: 900px;

becomes:

max-width: 900px;
width: 100%;

class="grid grid-cols-4 text-7xl"

becomes:

class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 text-3xl md:text-7xl"

Images receive safe responsive defaults:

<img loading="lazy" style="max-width:100%;height:auto">

Tailwind Support

Responsify understands common Tailwind layout utilities:

• grid-cols-*
• w-*, min-w-*, max-w-*
• arbitrary values like w-[720px]
• h-*
• text-6xl through text-9xl
• spacing like p-20, px-24
• flex, flex-row, shrink-0
• whitespace-nowrap
• overflow-x-auto, overflow-hidden
• container
• basis-*
• translate-x-*

Dynamic JSX Class Parsing

Modern React apps rarely use only plain strings. Responsify supports static class strings inside:

• cn(...)
• clsx(...)
• classnames(...)
• twMerge(...)
• cva(...)
• tv(...)
• tailwindVariants(...)
• arrays
• conditionals
• &&
• object keys
• template literal static chunks
• variant maps
• compound variants

Example:

const card = cva("grid grid-cols-4", {
  variants: {
    size: {
      hero: "text-7xl w-[720px]"
    }
  }
});

Responsify can safely rewrite the static class strings without executing your code.

Framework-Aware Presets

npx @divi-24/responsify . --preset next
npx @divi-24/responsify . --preset tailwind
npx @divi-24/responsify . --preset dashboard
npx @divi-24/responsify . --preset ecommerce

Presets tune file discovery, plugin markers, and confidence defaults for common project types.

Confidence Levels

Every change has a confidence level:

• safe: low-risk automatic fix
• review: useful fix that should be reviewed
• risky: report-only unless explicitly allowed

Run only safest fixes:

npx @divi-24/responsify . --confidence safe

Run safe plus review-needed fixes:

npx @divi-24/responsify . --confidence review

Safer Rule Engine

Every transformation has a stable rule ID. You can list and explain rules:

npx @divi-24/responsify explain
npx @divi-24/responsify explain css.fixed-width

Run only specific rules:

npx @divi-24/responsify . --only css.fixed-width tw.grid-responsive

Disable specific rules:

npx @divi-24/responsify . --disable tw.overflow html.table

Generated configs also include ruleIds so teams can keep project-specific policy in version control.

Component Library Awareness

Responsify includes review markers for:

• Shadcn/UI
• Bootstrap
• MUI
• Chakra UI
• Ant Design

These markers help identify component-library layout areas that need responsive review.

Visual Validation

Responsify can use Playwright to validate pages in a real browser:

npx @divi-24/responsify . --validate --app-url http://localhost:3000

It checks:

• mobile, tablet, and desktop viewport widths
• horizontal overflow
• oversized elements
• small tap targets

You can also validate plain HTML files:

npx @divi-24/responsify . --validate --page index.html

Before/after visual comparison for changed local HTML files:

npx @divi-24/responsify . --visual-diff --report

This stores screenshot artifacts under .responsify/visual-diff. Browser validation remains a responsiveness health check for remote app URLs unless a before-change baseline is available.

Page Discovery

Responsify discovers routes from:

• Next.js app/**/page.tsx
• Next.js pages/**/*.tsx
• Vite-style src/pages
• Vite-style src/routes
• plain .html files

Reports

Generate an HTML report:

npx @divi-24/responsify . --report

The report includes:

• responsiveness score
• score breakdown
• detected risks
• fixes applied
• confidence labels
• rule IDs
• manual review items
• line-level diff preview
• before/after visual diff artifact links
• discovered pages
• visual validation results

JSON and CI

Machine-readable output:

npx @divi-24/responsify . --json

CI mode:

npx @divi-24/responsify . --ci --min-score 85

CI mode exits with a failing status if the score is below the minimum.

CLI Reference

npx @divi-24/responsify [target]

Common commands:

npx @divi-24/responsify init
npx @divi-24/responsify . --dry-run
npx @divi-24/responsify . --report
npx @divi-24/responsify . --score
npx @divi-24/responsify . --rollback

Scoped fixes:

npx @divi-24/responsify . --fix-grid
npx @divi-24/responsify . --fix-flex
npx @divi-24/responsify . --fix-images
npx @divi-24/responsify . --fix-overflow
npx @divi-24/responsify . --fix-spacing
npx @divi-24/responsify . --fix-typography

Rule-level controls:

npx @divi-24/responsify explain
npx @divi-24/responsify explain tw.grid-responsive
npx @divi-24/responsify . --only css.fixed-width
npx @divi-24/responsify . --disable tw.overflow

Safety and workflow:

npx @divi-24/responsify . --dry-run
npx @divi-24/responsify . --interactive
npx @divi-24/responsify . --max-changes 50
npx @divi-24/responsify . --changed
npx @divi-24/responsify . --staged
npx @divi-24/responsify . --no-cache

Validation and CI:

npx @divi-24/responsify . --validate --app-url http://localhost:3000
npx @divi-24/responsify . --visual-diff --report
npx @divi-24/responsify . --json
npx @divi-24/responsify . --ci --min-score 85

Configuration

Create responsify.config.json:

{
  "include": ["src/**/*.{tsx,jsx,css,html}"],
  "ignore": ["**/*.generated.*"],
  "maxFileSizeBytes": 750000,
  "maxChanges": 100,
  "requireCleanGit": false,
  "preset": "tailwind",
  "confidence": "review",
  "validate": false,
  "minScore": 85,
  "rules": {
    "grid": true,
    "flex": true,
    "image": true,
    "overflow": true,
    "spacing": true,
    "typography": true
  },
  "ruleIds": {
    "css.fixed-width": true,
    "tw.grid-responsive": true,
    "html.image-defaults": true
  },
  "pluginsEnabled": ["shadcn"],
  "plugins": []
}

Safety Model

Responsify is designed to be safe by default:

• --dry-run writes nothing.
• backups are created before real writes.
• rollback restores the latest backup.
• backups include SHA-256 integrity checks.
• .responsify and reports are ignored during scans.
• --max-changes prevents unexpectedly large writes.
• --confidence safe limits changes to lowest-risk fixes.
• --only and --disable control exact rule IDs.
• --changed and --staged support smaller git-based runs.

Rollback:

npx @divi-24/responsify . --rollback

Recommended Workflow

# 1. Start with a dry run
npx @divi-24/responsify . --dry-run

# 2. Generate a reviewable report
npx @divi-24/responsify . --report --preset next --confidence review

# 3. Run your app and validate visually
npm run dev
npx @divi-24/responsify . --validate --app-url http://localhost:3000

# 4. Roll back if needed
npx @divi-24/responsify . --rollback

Non-AI Guarantee

Responsify does not use:

• OpenAI
• Anthropic
• LLMs
• remote transformation APIs
• network services for code modification

All transformations are deterministic and reproducible.

Limitations

Responsify fixes common responsive issues automatically, but it cannot understand every product design decision. Review changes involving:

• absolute positioning
• complex animations
• custom canvas/WebGL layouts
• third-party component internals
• deeply dynamic class generation
• layout code that depends on runtime measurements

Development

npm install
npm run build
npm test
npm run test:playwright
npm audit

Community

• Contributing: see CONTRIBUTING.md
• Security: see SECURITY.md
• Support: see SUPPORT.md
• GitHub setup: see docs/GITHUB.md

License

MIT