flutter-custom-design-system

Flutter 自定义设计系统

这里不应默认使用标准 Material/Cupertino 风格。如果此仓库已经命名了颜色、字体、圆角、动效或可按压控件，请使用这些名称和值。除非用户要求弃用现有系统，否则不要将应用改成 FilledButton / NavigationBar / ColorScheme.fromSeed 风格。

配套技能：flutter-native-ui —— 仅适用于确实需要 Material 3 或 Cupertino 外观的应用。

参考资料

references/
  tokens.md      ThemeExtension mount, context accessor, 1:1 rule
  pressable.md   Scale/sink press, NoSplash, focus ring, semantics

先检测设计系统

编写组件前，先在仓库中搜索：

• ThemeExtension<
• 返回颜色或设计令牌的 extension <Name> on BuildContext
• 名为 *tokens*、*semantics*、*theme*、WIDGETS.md、DESIGN-SYSTEM.md 的文件
• 名为 *Pressable 的组件
• NoSplash.splashFactory / splashFactory: NoSplash

然后打开一个附近的生产页面，并照着使用其中的访问器（context.pt、St6Theme.of(context)、context.colors 等）。产品代码必须使用该访问器，不能另起一个。

如果尚无设计系统，而用户希望建立一个：按照 references/tokens.md 和 references/pressable.md 中的模式实施。一个令牌模块、一个扩展、一个可按压控件。不要添加第三方 UI 套件。

硬性规则

设计令牌

• 所有值必须集中在一个来源中（Dart 令牌文件、由 CSS/JSON 生成的文件，或经批准的 tokens.dart）。组件中不得包含原始十六进制颜色值、随意设定的圆角或临时添加的时长。
• 运行时通过 ThemeExtension<T> 挂载到 ThemeData.extensions，并提供一个统一的上下文访问器。不要在随机组件中导入 FooColors 类，与扩展并用。
• 与系统文件 1:1 对应。如果交接文档写的是 #C9A24B，令牌就必须是 #C9A24B。不要“改进”对比度、臆造浅色主题，或添加系统未命名的角色。
• 缺少某个角色时：将其同时添加到令牌来源和扩展中，或者提出询问。绝不能为了省事直接在组件中写 #hex。
• 只有系统本身提供了深色模式，才可以实现深色模式。不要臆造深色调色板。

界面外观

• 外行不应看出这是默认的 Flutter Material 应用。除非系统明确规定，否则不要使用墨水波纹、M3 主容器胶囊样式或标准 NavigationBar 指示器。
• 所有点击操作都必须通过项目自有的 Pressable（仓库中没有时就创建）。按压时缩放和／或下沉。主题和可按压控件上都要设置 splashFactory: NoSplash.splashFactory 及透明叠加层。
• 不要为了“免费获得无障碍功能”而用 FilledButton / ElevatedButton / InkWell 包裹品牌控件，然后再设法去除水波纹。应将语义信息放在可按压控件上。
• 使用 Material 的行为（焦点、媒体查询、文本缩放器、Shortcuts），不要使用 Material 的外观。

字体与间距

• 字体角色应来自系统（或扩展中的文本样式），除非系统已映射到 TextTheme，否则不要使用 TextTheme.of(context).titleLarge。
• 间距、圆角和动效时长应使用令牌中的数值（space200、radiusControl、durationPress）。不要在调用处臆造 EdgeInsets.all(13) 或 Duration(milliseconds: 180)。

键与调试

• 交互控件：使用 const ValueKey<String>('kebab-name')，以便测试能调用 find.byKey 查找。
• 上帝模式、画廊、预填内容、跳转芯片：仅限 kDebugMode，且仍必须通过真实的身份验证／会话路径。不得设置发布版本后门。

不要

• 如果系统已经自带字体文件，就不要添加 google_fonts。如果需要比对图，应使用 FontLoader 加载这些字体——Roboto 比对图不代表产品字体。
• 不要添加 flutter_screenutil、GetX 或第二套设计包。
• 不要以“就这一次”为由，在品牌化界面上混用标准 M3 组件。

构建屏幕

1. 阅读 token 文件、扩展、pressable，以及一个现有屏幕。
2. 使用项目的 shell（自定义应用栏／标签栏）搭建，不要重新创建 AppBar + NavigationBar。
3. 颜色、字体、间距、圆角、动效：仅使用扩展／tokens。
4. 点击：使用项目的 pressable。图标：使用系统的图标集，除非 Icons.favorite 就是系统指定图标。
5. 安全区域和键盘：在内容上使用 SafeArea，以及 MediaQuery.sizeOf / viewInsetsOf / textScalerOf。如果系统定义了窗口宽度断点，就使用这些断点；否则沿用现有 shell 的规则。
6. 使用项目的分析器和运行中的画面进行验证。

何时拒绝 Material 默认样式

除非系统的组件清单列出了以下组件，否则不要在品牌化界面上使用：

FilledButton、NavigationBar、NavigationRail、NavigationDrawer、SnackBar（如果系统有 toast）、FloatingActionButton、Chip、Card、带 elevation tint 的 Material、使用默认 splash 效果的 InkWell。

如果系统未指定替代方案，不属于界面装饰的 OS 原生控件仍可使用 .adaptive()（Switch.adaptive、Checkbox.adaptive）。

验证

1. 对你修改过的文件执行 grep，查找 Color(0x / Color.from / #。匹配项应放在 token 文件中，而不是组件中。
2. 每个新增的点击目标都必须使用项目的 pressable。
3. 分析器检查通过。执行热重载。将运行中的画面与附近的品牌化屏幕进行比较，而不是凭对 Material 3 Gallery 的印象来判断。
4. 只要存在 key，组件测试就使用 find.byKey，不要使用可见文案。