Index of every page on this site: llms.txt
All skills
nangohq avatar

/ui-visual-debugging

@0c949ea
by Nangonangohq/nango13k stars
1,543
Run it yourself

Use when modifying or visually debugging Nango frontend UI, including packages/webapp, packages/connect-ui, browser interactions, screenshots, and visual regressions. Prefer browser-controlled or headless Playwright checks; use Peekaboo only for native macOS, visible-browser, or Accessibility tree inspection.

Use this Skill: https://skilld.dev/gh/nangohq/nango/ui-visual-debugging

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈83 tokens for metadata: the name and description. ≈1.2k when used: this file.

Description uses 4.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈332 characters, or 4.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

UI Visual Debugging

Core Rules

  • Use a browser-controlled or headless context for routine web UI checks. Do not open tabs in the user's existing browser unless explicitly asked.
  • Save screenshots, traces, and throwaway Playwright scripts under .context/; do not commit them.
  • Use Peekaboo only when the task needs the real macOS desktop, native windows, a visible browser session, or Accessibility tree inspection.
  • For local startup details, use running-and-testing-locally as the source of truth.

Nango Targets

Surface URL Common command
Dashboard webapp http://localhost:3000 npm run dev:watch:web
API server http://localhost:3003 npm run server:dev:watch
Connect UI http://localhost:3009 npm run dev:watch:web or npm run connect-ui:dev:watch

For most frontend work, run:

npm run dev:docker
npm run dev:watch
npm run dev:watch:web

npm run dev:watch and npm run dev:watch:web are long-running commands. Keep them in separate sessions and wait for the initial TypeScript build before browser testing.

Standard Screenshot Workflow

  1. Start or reuse the relevant local services.

  2. Capture a desktop baseline with a browser-controlled tool. If a Playwright MCP/browser tool is available, use it. Otherwise use headless Playwright without modifying repo dependencies:

    npx playwright screenshot --browser=chromium --viewport-size=1512,862 http://localhost:3000 .context/nango-webapp-desktop.png

    For Connect UI:

    npx playwright screenshot --browser=chromium --viewport-size=1512,862 http://localhost:3009 .context/nango-connect-desktop.png

    If Playwright reports that the Chromium executable is missing, install the browser cache without adding repo dependencies:

    npx playwright install chromium
  3. Inspect screenshots with view_image, then edit the smallest relevant files.

  4. Verify after edits:

    npm run ts-build

    For webapp-only visual work, cd packages/webapp && npm run build is also useful. For Connect UI, run npm run connect-ui:build.

  5. Capture fresh desktop screenshots and compare them before finishing.

Headless Interaction

For clicks, form filling, authentication flows, or multi-step checks, create a temporary Playwright script in .context/, run it, and save screenshots there.

Use stable selectors and visible text where possible. Avoid relying on the user's browser state.

Common flows:

  • Dashboard sign-in/sign-up at http://localhost:3000.
  • Dashboard pages after authentication: Integrations, Connections, Logs, Metrics, and Environment settings.
  • Connect UI at http://localhost:3009.

When auth is needed, follow the local credentials and verification-log workflow in running-and-testing-locally.

Startup Troubleshooting

If server startup fails with a Knex error like The migration directory is corrupt, the following files are missing, the local database has migrations from another branch (see Migration mismatch in running-and-testing-locally to tell a branch behind master from an unmerged one). Do not reset the user's database without confirmation. For visual validation only, use a temporary database:

docker exec nango-db psql -U nango -d postgres -c "DROP DATABASE IF EXISTS nango_ui_skill_validation WITH (FORCE)"
docker exec nango-db psql -U nango -d postgres -c "CREATE DATABASE nango_ui_skill_validation"
NANGO_DB_NAME=nango_ui_skill_validation npm run dev:watch:web

After stopping the dev server, clean up the temporary database:

docker exec nango-db psql -U nango -d postgres -c "DROP DATABASE IF EXISTS nango_ui_skill_validation WITH (FORCE)"

Peekaboo Workflow

Use Peekaboo only after checking permissions:

peekaboo permissions status

Required:

Screen Recording (Required): Granted
Accessibility (Required): Granted

Prefer targeted captures by window id. Capturing by app name can hang.

peekaboo list windows --app "Google Chrome" --json
peekaboo image --mode window --window-id <window_id> --retina --path .context/nango-window.png --json-output
peekaboo see --app "Google Chrome" --json-output

Avoid peekaboo open http://... --app "Google Chrome" for routine checks because it creates tabs in the user's existing browser.

Review Checklist

  • Baseline screenshot captured before UI edits when layout risk is meaningful.
  • Desktop screenshots captured after edits.
  • Screenshots, traces, and throwaway scripts stay under .context/.
  • Browser automation does not depend on the user's existing browser state.
  • npm run ts-build or the relevant package build was run after frontend changes.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides instructions for visually debugging the Nango frontend using browser automation and screen capture tools. It follows best practices by using isolated environments and local directories for temporary files.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

Signed by skilld at 0c949ea. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago

README badge

README badge for nangohq/nango/ui-visual-debugging