Gopeed 文件分类图标风格指南：从 24×24 SVG 到 Flutter 图标字体的设计规范

Gopeed 文件分类图标风格指南从 24×24 SVG 到 Flutter 图标字体的设计规范【免费下载链接】gopeedA fast, modern download manager for HTTP, BitTorrent, Magnet, and ed2k. Cross-platform, built with Golang and Flutter.项目地址: https://gitcode.com/GitHub_Trending/go/gopeedGopeed 作为一个跨平台下载工具其 Flutter 客户端在任务卡片、文件树与扩展分类中大量依赖一套统一语义的文件分类图标。本指南以仓库内 .agent/skills/gopeed-file-category-icons/references/style-guide.md 为骨架结合源物料目录与生成脚本系统讲解这套「文件/文件夹外壳 分类标记」的视觉语言、几何约束与审查标准。读完你将掌握如何设计符合规范的文件分类 SVG、如何通过确定性流水线把 SVG 构建为 TTF 图标字体与 FlutterIconData常量以及如何在 16~32px 多尺寸下做一致性验收。一、构成规则一套可判定的分类语法风格指南开篇定义了整套图标系统的构成语法Composition它规定了任何图标应该由什么元素组成、什么元素绝对不允许出现未知文件只有空文件外壳不加任何内部标记已知文件文件外壳 一个分类标记通用文件夹只有空文件夹外壳已知类型或带协议的文件夹文件夹外壳 一个分类标记状态与动作永远不属于分类字形——暂停、失败、完成、下载中等状态不得替换或混入文件字形。这条规则在技能定义文件 .agent/skills/gopeed-file-category-icons/SKILL.md 中被表述为「分类语法Classification grammar」目录永远是文件夹轮廓仅当类型或协议已知时才追加标记非目录永远是文件轮廓加分类标记未知文件就是空文件轮廓不得臆造通用内部标记传输状态与分类彼此独立绝不能用暂停/失败/完成/下载中的图形替换文件字形。从源码结构看这套语法被实际落地为 manifest 中的 22 个图标条目见 design/file-category-icons/manifest.json2 个协议标记protocol_bt、protocol_ed2k、2 个文件夹folder、folder_bt其余 18 个为文件类图标file与file_installer、file_android、file_ios、file_disk_image、file_web、file_text、file_pdf、file_document、file_spreadsheet、file_presentation、file_archive、file_image、file_audio、file_video、file_code、file_ebook、file_font、file_database。这一一对应的关系印证了「一个分类 一个外壳 一个标记」的原子化设计。二、几何规范24×24 画布内的安全区几何章节是风格指南中约束最硬核的部分直接决定了图标在像素层面的一致性画布与安全区使用0 0 24 24的 viewBox光学绘制内容保持在两轴2…22范围内共享外壳是唯一真相源既有文件外壳约覆盖x3…21轮廓为 1.5 单位不得悄悄引入更粗的一次性边框装饰标记安全区标记大致保持在x6.2…17.8、y9.2…19内外壳内侧边缘更近处至少保留 1.5 单位的可见间距细节下限圆角半径优先取 1.5–2 单位终端形状保持一致、轮廓尽量简单低于 1.25 单位的细节或间隙一律避免光学居中当形状带标签页tab、箭头或不对称标签时按光学质量居中而非包围盒算术居中镂空与孔洞计数器与孔洞使用非零环绕规则non-zero winding需要开孔时反转内轮廓方向。这些几何要求并非纸面文章——构建脚本 .agent/skills/gopeed-file-category-icons/scripts/build_icon_font.py 在parse_view_box约第 53~89 行中对每个 SVG 做了强制校验viewBox 必须恰好包含 4 个数字、宽高必须为正且相等图标必须正方形、只允许svg/g/path三种标签、禁止任何 live strokestroke必须为none、每个path必须有路径数据且必须是填充轮廓fill不得为none。也就是说风格指南里「把描边和文字转成路径、只用闭合填充路径」的要求在构建阶段是硬性报错的无法绕过。模板 .agent/skills/gopeed-file-category-icons/assets/folder-symbol-template.svg 是几何规范的直接示范两条路径分别是文件夹外壳与内部装饰全部为闭合填充路径无任何text、描边或滤镜可供新图标作为结构起点。三、分类标记语义几何优先于字母「用形状说话而不是用文字」是分类标记章节的核心立场一个主导标记而非多个微型物体优先使用语义几何视频用播放键play、音频用音符note、图片用图像剪影、电子表格用网格grid、压缩/归档文件用拉链zipper、数据库用圆柱cylinder字母是最后手段当语义标记更清晰时避免字母若必须保留约定俗成的标签如 PDF每个字母都要建成填充几何笔画stem至少 1.25 单位字母间必须有明确的间隙——而不是把文字缩放塞进可用空间空文件必须真正为空问号、星号或扩展名文字都会改变其「未知文件」的含义被明确禁止。对照 design/file-category-icons/manifest.json 的图标命名可以确认这套语义分类的落点file_video、file_audio、file_image、file_spreadsheet、file_archive、file_database、file_code、file_ebook等一一对应。技能不变量SKILL.md还补充了一条可操作性极强的验收标准如果必须使用字母要证明它在 16px 下仍然可读像 PDF 这种多字母标记需要刻意设计间距而不是把文字缩放进可用区域。四、协议标记文件夹先保剪影再放符号Gopeed 支持 HTTP、BitTorrent/Magnet 与 ed2k 协议因此存在带协议标记的文件夹图标如folder_bt。风格指南对此给出专门约束先保证文件夹剪影可识别再加协议符号协议符号放在文件夹下半部分的体内采用简洁的填充符号并与每个边缘保持足够留白语义优先BitTorrent 用磁铁/群集magnet/swarm图形ED2K 用驴子/服务器-网络donkey/server-network图形不要默认使用缩写字母占用比例可见文件夹约占 24 单位画布的80~85%不要在 SVG 光学边距之上再加生成器 padding——双重 padding 会让 Flutter 中的图标看起来偏小对照验证在真实 widget 尺寸下与 Flutter 的folder_outlined比较光学中心与占用面积而不仅仅在大尺寸预览里看。protocol_btUE900与protocol_ed2kUE901即按此规则生成并在 ui/flutter/lib/features/tasks/domain/task_record.dart约第 242~246 行中映射到TaskAssetType.torrentFolder、TaskAssetType.torrent、TaskAssetType.ed2k等资产类型。五、一致性检查接触表驱动的多尺寸验收风格指南把「一致性检查」列为正式流程要求并排对比新图标至少与一个现有文件夹图标、一个现有文件类型图标并排比较接触表审查检查生成的接触表contact sheet在16、20、24、32px四种尺寸、明暗两种色板下的表现拒绝清单依赖颜色才能辨识、包含活文字/描边、基线或字重不一致、偏离中心、在 16px 下变得含糊、或与外壳间距小于共享安全区的图标一律拒绝双向对照空壳装饰图标要同时与空文件壳和空文件夹壳对比内部标记绝不能因并入边框而让外壳看起来更重。预览脚本 .agent/skills/gopeed-file-category-icons/scripts/preview_icon_font.py 把这个检查过程自动化它从 manifest 读取fontOutput指向的 TTF为每个图标生成一行标签图标名 U码位并把每个尺寸单元横向切成左半白底黑字、右半黑底浅字第 84~91 行从而在同一张接触表里同时暴露浅色与深色背景下的可辨识度。仓库已生成的接触表见 design/file-category-icons/preview/gopeed_icons_preview.png。技能工作流SKILL.md 第 6~8 步进一步要求重建完整 TTF 与生成的 Dart 类后先生成多尺寸接触表再检查 16/20/24/32px 明暗色板若真实任务卡片与任务详情文件树的尺寸与接触表不同还要到真实 widget 上复核最后运行分类相关测试、flutter analyze与flutter test。六、Flutter 使用规范走图标管线不走文本管线风格指南最后给出了 Flutter 侧的三条铁律注册字体在flutter.fonts下注册生成的 TTFfontFamily必须与 manifest 中的完全一致用生成的 Dart 常量使用生成的 Dart 常量而非裸码位raw codepoint用Icon渲染图标字体字形必须通过Icon组件渲染不要用Text因为图标尺寸与语义应跟随 Flutter 的图标管线icon pipeline。仓库中的实际注册与使用完全吻合字体注册见 ui/flutter/pubspec.yaml约第 141~144 行fonts: - family: GopeedIcons fonts: - asset: assets/fonts/GopeedIcons.ttf生成常量的真实形态见 ui/flutter/lib/core/icons/gopeed_icons.dart例如static const IconData fileArchive IconData(0xe90f, fontFamily: _fontFamily); static const IconData fileDatabase IconData(0xe916, fontFamily: _fontFamily);该文件首行明确标注// Generated by gopeed-file-category-icons. Do not edit by hand.——它是构建脚本的产物任何手改都会在下一次重建时被覆盖因此在技能不变量中被称为「manifest 是唯一真相源不要手改生成的 Dart 常量或补丁二进制字体」。生成器侧build_icon_font.pywrite_dart约第 249~271 行会从 manifest 的dartClass生成abstract final class并自动把snake_case图标名转换为 lowerCamelCase 的 Dart 字段如file_archive→fileArchive还支持可选的fontPackage字段为跨包引用自动追加fontPackage: ...参数。此外manifest 的codepointStart默认为0xE900码位必须落在 BMP 私用区 UE000…UF8FF 内校验见validate_icons第 147~148 行。七、落地流水线与维护纪律从设计到上屏整套流水线是确定性的 SVG → TTF → Dart三阶段过程完整流程见 design/file-category-icons/README.md该目录是位于 Flutter 工程之外的唯一源物料目录严禁加入 ui/flutter/pubspec.yaml 的assets使用 gopeed-file-category-icons 技能修改 SVG/manifest → 重新生成完整 TTF 和 Dart 常量 → 检查多尺寸明暗预览 → 运行 Flutter 静态分析与测试环境准备依赖版本由 .agent/skills/gopeed-file-category-icons/scripts/requirements.txt 固定fonttools4.59.2、Pillow11.3.0python3 -m venv .agent/skills/gopeed-file-category-icons/.venv .agent/skills/gopeed-file-category-icons/.venv/bin/pip install -r .agent/skills/gopeed-file-category-icons/scripts/requirements.txt构建与预览manifest 路径使用源物料目录中的 design/file-category-icons/manifest.json.agent/skills/gopeed-file-category-icons/.venv/bin/python .agent/skills/gopeed-file-category-icons/scripts/build_icon_font.py --manifest design/file-category-icons/manifest.json --allocate-codepoints .agent/skills/gopeed-file-category-icons/.venv/bin/python .agent/skills/gopeed-file-category-icons/scripts/preview_icon_font.py --manifest design/file-category-icons/manifest.jsonbuild_icon_font.py的构建细节值得说明build_font约第 173~246 行它把 24×24 的 viewBox 按unitsPerEm - 2 * padding的可用空间等比缩放、垂直翻转并居中到 1024 单位的 UPM 网格贝塞尔曲线统一转二次曲线Cu2QuPen后写入 glyf 表再以 manifest 的fontFamily、version配置 Name 表。因此 manifest 中的几个关键字段直接决定产物形态字段当前值含义fontFamilyGopeedIcons字体族名须与 pubspecfonts.family完全一致unitsPerEm1024字体设计网格绘制安全区经缩放后映射到此网格ascent/descent896/-128垂直度量二者跨度必须等于unitsPerEmpadding0网格内额外留白SVG 光学边距之外不应再加version1.3.2视觉修订时递增codepointStart0xE900新图标自动分配码位的起点**维护纪律不变量**是这套体系长期稳定的关键其中最重要的是既有码位是 API绝不重排或复用除非用户明确批准破坏性迁移manifest 是唯一真相源SVG 与 manifest 只通过技能流程修改禁止手改生成产物图标命名保持小写snake_caseDart 字段由生成器自动转换同一修订版内文件壳与文件夹壳必须共享轮廓粗细、基线、折角/标签页几何与光学尺度新增分类组必须同时具备扩展名/域映射与字形——不允许生成没有任何分类器可达的字形每次源变更后重建完整字体保证所有平台消费同一个二进制。结语这份风格指南的价值在于把「好看」翻译成了可执行、可校验的规则从「一个外壳 一个分类标记」的构成语法到 1.25 单位细节下限、1.5 单位安全间距、非零环绕镂空等几何约束再到 16/20/24/32px 明暗接触表的自动化审查最终以确定性脚本产出全平台一致的 TTF 与 Dart 常量。对想要为 Gopeed 贡献或自建图标体系的开发者而言style-guide.md、manifest.json 与两个构建脚本build_icon_font.py、preview_icon_font.py构成了一整套可以直接上手复用的参考实现。【免费下载链接】gopeedA fast, modern download manager for HTTP, BitTorrent, Magnet, and ed2k. Cross-platform, built with Golang and Flutter.项目地址: https://gitcode.com/GitHub_Trending/go/gopeed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考