html-to-flutter

A Claude Code (and compatible agent) skill that converts HTML UI/UX prototypes + API docs + requirement specs into a working Flutter project. This npm package is the installer: it drops the skill into a project's .claude/skills/ folder so any Claude-powered agent in that project can use it.

The skill itself is an orchestrator: it parses your HTML + API + requirements into a blueprint, then drives whatever Flutter skills the project provides (e.g. the Very Good Ventures / VGV plugin) for project creation, state management, architecture, navigation, theming, and testing.

Quick start

In the root of your Flutter project (or any folder where you want the skill enabled):

# one-off, no global install needed
npx html-to-flutter init

This creates:

.claude/skills/html-to-flutter/
├── SKILL.md
├── assets/
└── references/

Restart Claude Code so it discovers the new skill, then just describe what you want:

"Convert these HTML prototypes into a Flutter app" — and hand over the folders of HTML mockups, API docs, and requirements.

The skill auto-triggers whenever HTML prototypes and a Flutter target appear together (even without the word "convert").

Requirements

• Node.js ≥ 14 (only to run the installer; zero runtime dependencies)
• The installer works on macOS, Linux, and Windows

CLI

Usage:
  npx html-to-flutter              Install into ./.claude/skills/html-to-flutter
  npx html-to-flutter init         Same as above (explicit form)
  npx html-to-flutter init <dir>   Install into <dir>/.claude/skills/html-to-flutter
  npx html-to-flutter init --force Overwrite an existing install
  npx html-to-flutter --version
  npx html-to-flutter --help

Behavior notes:

• Idempotent & safe — if the skill is already installed, it prints a hint instead of clobbering. Use --force to refresh files in place.
• No postinstall hooks — nothing happens automatically on npm install; the skill is only copied when you explicitly run init.

Global install (optional)

If you prefer a local command instead of npx:

npm install -g html-to-flutter
html-to-flutter init

What the skill does (once installed)

It runs a phased pipeline over your inputs (see references/ inside the installed skill):

1. Parse HTML prototypes → component inventory, navigation graph, design tokens.
2. Map HTML elements/API shapes to Flutter widgets / Dart models (references/html-to-widget-map.md, references/api-to-dart-map.md).
3. Orchestrate the project's own Flutter skills (VGV: create-project, layered-architecture, navigation, theming, testing…) for the heavy lifting.
4. Fallback — when no creation skill exists, it uses the bundled assets/project-template/ (Riverpod + feature-first + dio + go_router + flutter_screenutil + flutter_svg + intl) so it can still scaffold a project on its own.

Tip: it's most powerful when paired with the VGV Flutter plugin skills in the same project — the orchestrator defers to them whenever they exist.

Programmatic usage

The skill files are plain markdown + templates. If you want to copy them without the CLI, the files live under the skill/ directory of this package:

# from a project that has this package installed
node -e "console.log(require('path').join(require.resolve('html-to-flutter'), '..', 'skill'))"

Troubleshooting

• Agent doesn't see the skill → restart Claude Code after running init; skills are loaded at startup.
• npx ran the wrong version → pin with npx html-to-flutter@latest init.
• Already installed warning → re-run with --force to refresh.
• Wrong directory → pass a target explicitly: npx html-to-flutter init path/to/project.

License

MIT © smartyu1993