唯一稳定引入css的方式是在web/index.html的中用，路径须相对于web/目录，如href="css/custom.css"；其他方式不可靠且不作用于全局dom。
直接在 web/index.html 的 里加 <link rel="stylesheet"> 是唯一稳定、可预测、无需额外依赖的引入方式。其他方法（比如 flutter_html 加载内联样式、JS 动态注入、flutter_css_style 等）要么只作用于特定 HTML 片段，要么根本无法影响全局 DOM 行为，更无法控制字体、重置样式或媒体查询。
路径必须相对于 web/ 目录，不是 assets/
Flutter Web 构建后，HTTP 服务根路径就是 web/ 文件夹。浏览器请求 CSS 时，路径解析完全由 Web Server 决定，和 Dart 的 asset bundle 机制无关。
-
href="css/custom.css"→ 正确：文件需放在web/css/custom.css -
href="assets/css/custom.css"→ 错误：浏览器会尝试请求http://localhost/assets/css/custom.css，404 -
href="/assets/css/custom.css"→ 错误：开头的/表示站点根目录，但 Flutter Web 默认不暴露assets/下的静态资源 -
href="packages/my_app/assets/styles.css"→ 错误：该路径仅在 Dart 层通过rootBundle可读，不对应真实 HTTP 路径
CSS 只对 DOM 元素生效，不影响 Canvas 渲染的 Widget
Flutter Web 默认用 CanvasKit 渲染大多数 Widget（如 Container、Text），它们不生成标准 DOM 节点，因此你写的 div.my-card { color: red } 不会改变任何 Flutter 文本颜色。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 真正能被 CSS 控制的，只有显式创建的 DOM 元素：比如
HtmlElementView、IFrameElement、自定义<div id="chart-container"> 等 <li>全局样式（如 <code>body { margin: 0 }、@font-face、@media (prefers-color-scheme)）依然有效，因为它们作用于 document 根节点或字体注册表 - 不要试图用 CSS 选择器匹配 Flutter 内部 class 名（如
shrink-wrap-render-box），这些是私有实现细节，随时可能变 - DevTools 的 Network 面板里看 CSS 请求是否返回 200 —— 这是验证路径是否正确的第一手依据
- 如果样式没生效，打开 Elements 面板，检查目标 DOM 节点是否真的被选中（右键 → “Force element state” 或查看 Computed 样式）
- 遇到覆盖问题，临时加
!important快速验证；长期应提升选择器 specificity，比如用body .my-widget button替代button - 字体类 CSS（如
@font-face）务必声明font-display: swap，否则首屏文字会白屏等待加载
修改后必须手动刷新浏览器，热重载不触发
web/index.html 不属于 Dart 源码，Flutter 的 hot reload 完全不监听它。哪怕只改了一个空格，也得按 Ctrl+R（Windows/Linux）或 Cmd+R（macOS）硬刷。
最容易被忽略的是：CSS 和 Flutter 主题（ThemeData）、平台亮度（MediaQuery.platformBrightnessOf）之间没有自动同步。比如你在 CSS 里写了 @media (prefers-color-scheme: dark) { body { background: #121212 } }，但 Flutter 侧仍用 ThemeMode.light，视觉就会割裂。这类协调必须手动做。
