Improve README with examples

[Naveenkm07]

📖 README Enhancement

Description

The README could be enhanced with more practical examples and use cases.

Suggested improvements:

• Add code examples
• Include screenshots or demos
• Add a "Quick Start" section
• Include common use cases

Benefits:

• Better onboarding experience
• Clearer project understanding
• More engaging for new contributors

Type

• [ ] Documentation
• [ ] Enhancement
• [ ] Good first issue

---

I'd be happy to help create these examples and improve the README!

[ggauravky]

Responsively App

A must-have dev-tool: preview and develop responsive websites faster by mirroring user interactions across multiple device viewports.

[Website ↗︎](https://responsively.app) • [Issues](https://github.com/responsively-org/responsively-app/issues) • [Contributing guide](CONTRIBUTING.md)

---

Why Responsively?

Building responsive web UIs is a constant loop of resizing browser windows, reloading pages, and checking layout across devices. Responsively collapses that loop by showing many device viewports at once and mirroring your interactions across them — so you edit once and see results everywhere.

Quick wins:

• Save manual steps — preview your app across many devices at once.
• Debug layout and interactions simultaneously.
• Capture consistent screenshots across devices.

---

Features (at a glance)

• Mirrored user-interactions across all connected viewports (clicks, scrolls, typing).
• Customizable preview layout (grid, rows, columns).
• Single elements inspector for all viewports (unified DOM/CSS inspection).
• 30+ built-in device profiles + add custom devices.
• One-click screenshots for all devices.
• Hot-reload friendly for local development.
• Cross-platform desktop app (macOS / Windows / Linux) + browser extension for quick URL sending.

---

Quick Download

• Visit the official website for installers and releases: https://responsively.app/

macOS (Homebrew):

brew install --cask responsively

Windows (Chocolatey):

choco install responsively

Windows (winget):

winget install ResponsivelyApp

---

Quickstart — Preview your project (example)

This example walks through previewing a local React app (or any web server) in Responsively.

1. Start your web app normally, e.g. (React Create App):

cd my-react-app
npm install
npm start      # runs dev server on http://localhost:3000 (example)

2. Open Responsively App (or the desktop binary).
3. Click + Add URL and enter the address of your dev server, e.g. http://localhost:3000.
4. Press Enter — your application will load in all device viewports.
5. Toggle Mirror interactions (🔁) — now click, type or scroll in any viewport and the action is mirrored to all.
6. Use the Inspector (Elements) to inspect a DOM node — changes in your dev tools will be visible across viewports.

Result: Make a CSS change in your editor (hot-reload enabled) — see the change happen across every viewport instantly.

---

Example workflows & tips

1) Test a responsive header quickly

• With your dev server running and the URL added to Responsively, click Inspector → Select Element and pick your header.
• Try updating the CSS in your editor (e.g., change flex-direction or padding).
• Observe effects across mobile and desktop device previews — fix spacing issues faster.

2) Capture consistent screenshots for marketing or QA

• Arrange the preview layout you like.
• Click the Camera icon (top bar) → Capture screenshots for all devices.
• Exported images will be saved to your chosen folder (you can then batch-compress or attach to tickets).

3) Test touch and scroll behaviors across multiple devices

• With Mirror interactions ON, emulate touch scrolling on mobile viewport — verify parallax, sticky headers, or lazy-loading across other viewports.

4) Speed up cross-browser checks with the browser extension

• Use the browser extension to instantly send the current tab's URL to Responsively, without copy/paste.
• Great when you want to preview production/staging pages quickly.

---

Developer — Run from source (build & dev)

These are general steps — the repository has separate folders for the desktop app and the browser extension. See CONTRIBUTING.md for details.

1. Clone the repo

git clone https://github.com/responsively-org/responsively-app.git
cd responsively-app

2. Install dependencies & run desktop app (example)

# from the repo root — try one of your package managers
# You may need to change into subfolders like desktop-app/ depending on the repo layout
npm install
# or
yarn
# Start the app (check package.json scripts in the repo root or desktop-app/)
npm start
# or
npm run dev

3. Browser extension (local development)

cd browser-extension
npm install
npm run build   # usually emits a dist/ you can load as an unpacked extension
# Open your browser's extension/devtools page and 'Load unpacked' the extension folder

If you see npm script names different from above, use cat package.json (or open it in your editor) to check exact scripts (e.g. dev, start, build, make).

---

Contributing

We ❤️ contributions — small fixes, docs, or code. Please read the repository's [CONTRIBUTING.md](https://chatgpt.com/c/CONTRIBUTING.md) before opening a PR.

A helpful sequence for new contributors:

1. Look for issues labeled good first issue or help wanted.
2. Fork the repository and create a branch for your work.
3. Run the app locally and add tests for code changes where applicable.
4. Open a PR with a clear summary & link to related issues.

See the full guide: CONTRIBUTING.md

---

Troubleshooting

Q: The app shows a blank/white preview for localhost.

• Ensure your dev server accepts connections from other hosts. Try HOST=0.0.0.0 npm start (or your framework's equivalent).
• Check firewall rules that may block local ports.

Q: Browser extension can't send URL to the app.

• Make sure the desktop app is running.
• Reinstall the extension or restart the app.

Q: Hot reload isn't working.

• Confirm your dev server is configured for hot module reload and is rebuilding on file changes.
• Check the DevTools Console for errors that might break hot-reload.

---

FAQ

Q: Does Responsively replace browser devtools? Not entirely — Responsively speeds up multi-device preview and basic inspection. For deep profiling or advanced debugging (e.g. performance tracing), open the devtools of the embedded preview.

Q: Can I add a custom device? Yes — you can add custom device profiles (width, height, DPR) and save them for later.

---

Authors & License

Maintained by the Responsively community. See MAINTAINERS.md for the current maintainers.

Licensed under the AGPL-3.0 License. See LICENSE for details.

---

Want help polishing this README?

If you'd like, I can:

• Add step-by-step screenshots or GIFs (need example assets),
• Add exact npm/yarn/pnpm commands copied from the repo's package.json,
• Produce a short CONTRIBUTING summary for new contributors.

[kishansinghifs1]

@Naveenkm07 kindly review and merge https://github.com/responsively-org/responsively-app/pull/1427