html-to-flutter

HTML/CSS/JavaScript → Flutter

Rebuild the source application according to Flutter's rendering, state, and platform models. Preserve product intent, behavior, semantics, and visual system; do not recreate the DOM in widgets.

Operating model

Treat the source as four overlapping systems:

• HTML → semantic structure, information hierarchy, controls, content relationships.
• CSS → layout intent, constraints, responsive behavior, design tokens, interaction states, typography, decoration, animation.
• JavaScript/TypeScript → state transitions, business rules, data access, events, routing, persistence, async behavior, browser integrations.
• Flutter/Dart → declarative widgets, constraint-driven layout, typed state/data models, explicit architecture, platform adaptation.

Remember the Flutter box-layout rule:

Constraints go down. Sizes go up. Parents set positions.

Model UI as UI = f(state), not as a mutable collection of elements.

Non-negotiable rules

1. Translate intent, semantics, behavior, and constraints, not syntax.
2. Analyze the source before writing Flutter code.
3. Never assume div = Container or any universal tag-to-widget mapping.
4. Rebuild architecture rather than reproducing the DOM/component hierarchy mechanically.
5. Convert DOM/CSSOM mutation into explicit state changes and declarative composition.
6. Preserve semantic intent: buttons stay buttons, links stay links, headings remain headings, labels remain associated with fields, and dialogs retain modal/focus behavior.
7. Extract repeated colors, typography, spacing, radius, elevation, component variants, and relevant breakpoints into a Flutter design system before styling pages repeatedly.
8. Keep network, repositories, persistence, and non-trivial business logic out of widget build() methods.
9. Keep build() side-effect free. Create futures, subscriptions, controllers, timers, focus nodes, and animation controllers at appropriate ownership/lifecycle boundaries.
10. Keep state as local as ownership permits and maintain a clear source of truth for shared state.
11. Do not force a state-management package unless the project already uses one or the problem genuinely requires it.
12. Distinguish responsive layout changes from adaptive platform/input behavior.
13. Prefer LayoutBuilder for decisions based on a component's available parent constraints.
14. Prefer narrow MediaQuery accessors for window/environment characteristics such as size, padding, text scaling, accessibility settings, and display features.
15. Derive breakpoints from where the composition stops working well; do not rely only on mobile/tablet/desktop labels.
16. Prefer semantic framework controls over decorated gesture surfaces when the source represents a standard control.
17. Do not use Container as Flutter's default <div> equivalent. Use the narrowest widgets that express layout/decoration intent.
18. Do not use Stack merely because the source used CSS positioning. Use it when overlap or shared-box anchoring is intrinsic.
19. Do not copy CSS pixel dimensions mechanically. Preserve fixed dimensions only where the product requirement is genuinely fixed.
20. Do not add scrolling merely to silence overflow. Fix the layout model and choose wrapping, truncation, recomposition, or scrolling according to source intent.
21. Use lazy lists/grids/slivers for large or unbounded collections.
22. Avoid unnecessary intrinsic measurement, clipping, opacity layers, large blurred shadows, and other expensive rendering constructs unless required.
23. Use const where configuration is genuinely immutable, but do not treat it as a substitute for correct state boundaries.
24. Do not claim rebuilds are inherently expensive. Distinguish build, layout, paint, compositing, and rasterization.
25. Profile before performance optimization and measure in profile/release conditions on relevant targets.
26. Rewrite ordinary application logic in Dart. Keep JavaScript only where a browser API or JS-only SDK makes interop the better boundary.
27. For modern Dart web interop, prefer current dart:js_interop and package:web APIs; do not add deprecated legacy web/JS libraries to new code.
28. Do not assume Flutter Web should replace document-centric, SEO-heavy websites. Decide product fit explicitly.
29. Embed HTML/platform views only when preserving the existing implementation is more valuable than native Flutter reimplementation.
30. Preserve text scaling, keyboard/focus behavior, semantics, and platform usability even when pixel fidelity is a goal.
31. Make visual fidelity measurable against known viewports, states, fonts, and interaction modes.
32. Verify current APIs against the project's installed Flutter/Dart SDK before finalizing production code.