# travel-plan-viz: the trip planner that ships a page and a validator

> travel-plan-viz is a Skill for Claude Code and Codex that turns a spoken trip request into one mobile-first HTML file, and its interesting part is the split between the error-prone mechanical work, which is three tested JavaScript engines, and the visual layer, which is regenerated every time.

**zexuanw958-svg/travel-plan-viz** — Migo · 旅行领航 —— 把旅行行程生成为单文件、可离线、手机优先的 HTML（交互地图+每日时间轴+出发前提醒）。Claude Code / Codex 通用 Skill（travel-plan-viz）。

- Repository: https://github.com/zexuanw958-svg/travel-plan-viz
- Stars: 397 · Forks: 17
- Language: JavaScript
- License: MIT
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/zexuanw958-svg-travel-plan-viz

## The skill is one instruction file and three JavaScript engines

The architecture is a deliberate split, described in the documentation as freezing the error-prone mechanical logic into a reusable engine while handing the visual presentation to a design step that regenerates each time. What ships under `travel-plan-viz/` is therefore small and legible. `SKILL.md` orchestrates the workflow, judging which mode to use, researching, then generating. Three plain JavaScript engines sit in `assets/`: a map engine, a reminders engine, and a validation engine, each of them unit tested, with the validator also exposing a CLI. Alongside them is a content contract file that tells the design step what data each block of the page needs, and a `references/` directory holding an online research guide, a set of built-in aesthetic rules, and a guide for porting the skill to other agents. That structure is also why the skill is described as platform-agnostic: an agent with no skills mechanism can simply be handed the SKILL.md as an instruction.

## validate.js checks the coordinates because models get them wrong

The validator exists because of a stated distrust of careful generation. The requirement is phrased as mechanical checking after generation rather than relying on the generator being attentive while it writes. Three classes of check are named. Missing fields, so a block that was supposed to carry a rating or a photo does not silently render empty. Coordinate problems, specifically out-of-range values and outliers, with the examples given being a swapped latitude and longitude and a lookup that landed in the wrong city, which is exactly the class of error a model makes when it pattern-matches a plausible coordinate instead of looking it up. And required blocks, so a page cannot go out missing the timeline or the reminder list. Errors have to be fixed before the page is considered done. The engines are tested with a single command:

```bash
node --test test/*.test.js
```

## GCJ-02 to WGS-84 is the correction that stops pins drifting

The map engine's most concrete job is a coordinate correction, and it is worth understanding why it exists. Mainland Chinese map providers return coordinates in the GCJ-02 system, which is deliberately offset from the global WGS-84 standard, so a pin copied from one of them lands tens or hundreds of metres from the place it names. The engine converts those automatically, which the documentation describes as keeping pins from drifting. The reverse case is why overseas plans are simpler: coordinates outside China are already in WGS-84 and need nothing. Tiles come from OpenStreetMap through Leaflet with no API key, stops are numbered, the route between them is drawn as an ordered dashed line, and each stop links out to phone navigation, with Apple Maps on iOS, a geo: deep link on Android, and key-free map links per stop, Amap for mainland points and Google Maps elsewhere. All of those are described as official key-free URIs rather than hand-built strings.

## A single file is not the same as a file that works offline

The offline claim needs reading carefully, and the documentation is precise about it. Everything lands in one `.html`, laid out as a single column on a phone and multiple columns on a desktop. The text of the itinerary is readable with no network. The map and the images are not, and they are described as degrading gracefully rather than showing broken images when a request fails. So the offline promise covers the part you would actually read on a train, not the pictures. The other half of the single-file decision is what makes iteration work: the complete itinerary data is embedded in the page as JSON, so handing the file back with a request like moving something from day three to day four edits the data and re-renders the presentation, which the documentation points out as the reason no fields are lost. That data/presentation split is the structural idea behind the whole project.

## Reminders are worked backwards from the departure date

The reminders engine computes deadlines from the departure date rather than asking you to track them, producing a checklist at the top of the page and warning badges in the timeline next to whatever has to be booked by when. Several surrounding features exist to make the page usable as an actual trip document rather than a list of sights. Pre-trip notes are tailored to the season you are travelling in and cover weather, what to wear, typhoon reminders, how to pay, which apps to have installed, and when tickets tend to sell out. If nothing is booked, the page offers three to five real candidate flights with backups in case those are gone. Accommodation is suggested by area derived from where the stops are, with an economic, mid-range and premium option per area. Food gets a recommendation per meal plus the dishes worth ordering and reference prices.

## Every external dependency is optional and explicitly unendorsed

Nothing outside the repository is required, and the documentation is unusually careful about the boundary. Design skills are a soft dependency: if `frontend-design` or `huashu-design` happen to be installed they are called automatically and the page looks better, and if neither is present the built-in aesthetic rules are used instead, which is the stated reason the skill installs on its own. Official travel skills are the same pattern. With skills for services such as Fliggy, Amap, Tencent Maps or Didi installed, the page can be enriched with live flights, hotels, route planning and weather, and gets links for booking, navigating and hailing a car. Without them, online research fills in and no block of the page goes missing. The caveat is stated in the same breath twice: the real-time accuracy and authenticity of that data belongs to those skills, and this project only adapts and presents it without vouching for it. The research guide adds that images must be verified as loadable and that ticket prices are not checked in real time.

## Two modes, and a health check meant to stay restrained

There are two entry points, and the second one does more than formatting. In one mode you give only a destination and a number of days and the skill plans the trip. In the other you hand it an existing plan, as text or HTML, and it renders the page. That second mode also compares what you gave it against an internal checklist for improving an itinerary and offers a few optional suggestions, with the tone specified as restrained and not pushy. The FAQ draws the distinction from asking a general model the same question, which returns a block of text or a single throwaway page. The claimed differences are the reusable process, the itinerary health check, the offline single file, the one-tap navigation links, the booking countdown, and the ability to iterate afterwards without losing fields. One other answer in that section is worth repeating to yourself before you book anything.

## Installation is a symlink, and the samples are the real documentation

For anyone comfortable with a terminal, installing means linking the skill directory into an agent's skills folder:

```bash
# Claude Code
ln -sfn "$(pwd)/travel-plan-viz" ~/.claude/skills/travel-plan-viz
# OpenAI Codex
ln -sfn "$(pwd)/travel-plan-viz" ~/.codex/skills/travel-plan-viz
```

A separate INSTALL.md is written for people who do not code, starting from what GitHub is and how to download, and ending with what to say to the agent once it is installed. The samples directory is the better reference for what the output looks like, holding four generated pages that between them cover both modes: a four-day Chengdu plan built from a destination and a day count that includes a day trip to the Dujiangyan and Qingchengshan area plus a choose-one-of-two option, a Hong Kong page built on real online data, a three-day Shenzhen page generated from a day count alone, and a five-day Tokyo page produced from a rough plan in the second mode. The repository is JavaScript, MIT licensed, and the English half of the README cuts off mid-sentence inside the features table.

## Conclusion

travel-plan-viz fits someone planning a short trip who wants one file they can open on a phone, screenshot and keep, and who will still check prices on an official site, since the project says so itself rather than pretending otherwise. It fits badly as a trip-planning authority, because the disclaimers state plainly that times, prices and ratings are AI-organized and may be out of date. Three things to know before relying on it. Offline means the text only, since the map and the photographs need a connection and are designed to fail quietly. Every external system is optional, which is a deliberate choice and also means that any real-time flight or hotel data comes from another vendor's skill that this project explicitly declines to vouch for. And the validator covers fields, coordinates and required blocks, which is a real safety net for generated output but is not a check on whether the advice is any good. MIT licensed, last pushed on 1 October 2026, no tagged releases.

## FAQ

### What is travel-plan-viz?

A Skill for Claude Code and Codex, portable to other agents, that turns a trip request into a single-file, mobile-first HTML page with an interactive map, a daily timeline and pre-departure booking reminders. The itinerary is researched online, the page is MIT licensed, and the text is written to be readable offline.

### How is travel-plan-viz installed?

By linking the skill directory into an agent's skills folder, with one command for Claude Code writing into ~/.claude/skills and one for Codex writing into ~/.codex/skills. An agent with no skills mechanism can instead be handed the SKILL.md file as an instruction, and a separate INSTALL.md walks non-technical users through every step.

### What does travel-plan-viz check after generating a page?

A validation engine checks for missing fields, coordinates that are out of range or look like outliers, which catches a swapped latitude and longitude or a lookup in the wrong city, and required page blocks. Errors have to be fixed, and the three JavaScript engines have unit tests run with node --test.

### Does travel-plan-viz work offline?

Partly. The text of the itinerary is readable with no network because everything lives in one HTML file, but the map and the photographs do need a connection and are designed to fail quietly rather than show broken images. Every page also carries a disclaimer that prices, hours and schedules must be checked on official channels.

### Can travel-plan-viz plan a trip outside China?

Yes, and the samples include a five-day Tokyo itinerary. The map uses OpenStreetMap tiles, and coordinates outside China are already in the WGS-84 standard so they need no correction, while coordinates from mainland Chinese map providers are converted automatically so pins do not drift.

## Sources

- [Issues](https://github.com/zexuanw958-svg/travel-plan-viz/issues)
- [License: MIT](https://github.com/zexuanw958-svg/travel-plan-viz/blob/main/LICENSE)
- [README](https://github.com/zexuanw958-svg/travel-plan-viz/blob/main/README.md)
- [zexuanw958-svg/travel-plan-viz on GitHub](https://github.com/zexuanw958-svg/travel-plan-viz)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zexuanw958-svg-travel-plan-viz