HTML 设计 · 美学经验库

这个文件夹装的是「设计 HTML」这件事本身的经验：一个具体风格（构成主义）的美学考据， 加上从实现过程中沉淀出来的、可跨项目复用的规则与踩坑。

边界：动画 / 视频那条线不在这里。动效短片、片头、motion 相关的美学积累属于独立轨道 （在 C:\...\视频工作流\ 下的 docs\constructivism-video\ 与 constructivism-motion-*.html）。两者共享"构成主义"这个主题，但交付物、技术栈、 评审标准都不同，所以分开。

目录结构#

工作目录和上线目录是分开的：.md 是源，产物里只有网页文件。

下面画的是「本机源项目」的布局。 在 look4end-site 仓库里，这个目录是 src/notes/，产物目录是仓库根的 notes/ —— 构建脚本会自己判断该写哪儿，不用手改路径。 仓库层面的完整工作流见仓库根的 WORKFLOW.md。

结构主义html/
├── README.md                    本文件
│
│   ── A 组：构成主义美学考据（这个风格为什么长这样）──
├── 01-美学谱系与形式法则.md        源流、代表作字典、九条形式法则、五个典型误用
├── 02-设计系统规格.md             色板/字体/网格/质感/动效 + StyleKit 规则对照
├── 03-资源清单.md                GitHub 资源、字体、史料、参考站点、公有领域素材
├── 04-技术实现手册.md             逐条可复制 CSS 配方 + 兼容性 + 踩坑
├── 05-前端技术方案.md             深度技术方案（BCD/caniuse 版本号、真实站点 CSS 取证）
├── 06-素材情报报告.md             字体二进制 cmap 实测、授权原文、CC0 纹理源
│
│   ── B 组：可复用设计工程经验（跟风格无关，换项目照样用）──
├── 07-设计规则速查.md             对比度纪律、尺寸阈值、质感上限、动效规则
├── 08-交互模式.md                 history 驱动的多级返回（ESC = 后退键）
├── 09-踩坑清单.md                 本次抓到的每个真实 bug：现象→原因→修法
├── 10-验证工作流.md               什么该用什么手段验 + 可直接跑的流程
│
├── kit/                          可运行的样式套件与样式指南
│   ├── kv.css                     完整设计系统实现（令牌 + 组件 + 无障碍降级）
│   └── index.html                 活的样式指南页（浏览器直接打开）
│
├── verify/                       配套验证脚本
│   ├── static-check.ps1           HTML/CSS/JS 静态检查 + id 引用 + 文档链接
│   ├── shot.ps1                   多状态无头截图
│   ├── flow-test.ps1              交互链路功能测试
│   ├── example-flow-test.js       功能测试模板
│   └── route-test.js              纯逻辑单元测试（不需要浏览器）
│
├── build.py                      把 .md 构建成上线目录
│
└── 上线/                          ★ 上线目录：只有 .html 和 .css
    ├── index.html                 站点首页
    ├── 01-…html … README.html     各篇文档（由 .md 生成）
    ├── doc.css                    文章版面
    └── kit/                       样式指南 + 设计系统

上线时只传 上线/ 这个目录。 里面只有 .html 和 .css，不含 Markdown 源、 不含验证脚本、不含构建脚本 —— 工作用的东西不会跟着上公网。 改完 .md 之后重跑一次 python build.py 即可重新生成。

两组内容的关系#

先读 B 组的 09-踩坑清单.md —— 它是本次最硬的东西，20 多个真实 bug，每条都有现象、原因、修法。

最快的上手路径#

最重要的实测结论#

这条是最容易被"看起来还行"骗过的：

已落地的原型#

原型在另一个工作区（本目录刻意与它解耦，方便单独分享/带走）：

C:\...\视频工作流\soviet-press\index.html

用 A 组美学 + B 组规则做的第一个页面：报纸首页 → 三个板块转场进入三张海报 → 底部挂着文章条 → 点击上滑展开 → ESC 收回文章 → 再按 ESC 退回报纸（与浏览器后退键同一条路径）。

自包含，双击即可在浏览器打开。同目录的 _shots\ 里有各状态截图。

已验证 vs 未验证#

已直接验证（有可复现的方式）： - 字体西里尔覆盖 —— Google Fonts 官方元数据 + 字体二进制 cmap 解析 - 色彩对比度 —— WCAG 相对亮度公式精算 - GitHub 仓库星数与许可证 —— api.github.com 实际返回 - CSS 兼容性 —— MDN Baseline 标识 + MDN BCD / caniuse 原始 JSON - 公有领域图像 —— Wikimedia Commons API 逐件查询 + 直链实测 200 - 参考站点技术令牌 —— 直接抓取其生产 CSS 提取字体/色板/clip-path - 交互链路 —— 无头浏览器 --dump-dom 功能测试 + 纯逻辑单元测试 - 页面实际长相 —— 无头截图逐张审

未能验证： - 各作品逐件的精确版权状态（Commons 的 PD 标记是社区判定，不是法律意见） - 俄文论文《构成主义对现代网页设计的影响》全文（PDF 无法读取） - @property / animation-timeline / text-spacing-trim 的兼容性 - 厂商中文字体（阿里普惠体 / MiSans / HarmonyOS Sans）的官方授权页 - StyleKit 构成主义规则的原文 —— 由用户提供并声明已抓取确认，本环境未二次核验，记为「用户实测来源」

详见 03-资源清单.md 的「交付缺口清单」。

怎么用 src/verify/ 里的脚本#

⚠️ Windows 默认禁止运行未签名的 .ps1。下面统一加 -ExecutionPolicy Bypass。 脚本本身都带 UTF-8 BOM（PowerShell 5.1 读无 BOM 的 UTF-8 会乱码 —— 见 09-踩坑清单.md F6）。

cd C:\...\结构主义html

# 原型页在另一个工作区 —— 用变量指过去，脚本本身与项目解耦
$proj = 'C:\...\视频工作流\soviet-press'

# 静态检查（每次改完都跑）
powershell -ExecutionPolicy Bypass -File .\verify\static-check.ps1 -Dir $proj

# 纯逻辑单元测试（不需要浏览器）
node .\verify\route-test.js

# 交互链路 —— 先跑快路径验状态机
powershell -ExecutionPolicy Bypass -File .\verify\flow-test.ps1 `
  -Page "$proj\index.html" -TestScript .\verify\example-flow-test.js

# 再跑一次真实动画路径
powershell -ExecutionPolicy Bypass -File .\verify\flow-test.ps1 `
  -Page "$proj\index.html" -TestScript .\verify\example-flow-test.js -NoStub

# 截图（记得逐张看）
powershell -ExecutionPolicy Bypass -File .\verify\shot.ps1 `
  -Page "$proj\index.html" -Out "$proj\_shots"

脚本都以 -Dir / -Page 参数化，换项目直接改路径即可。

这套脚本自身的实测状态#

开发这套脚本的过程本身踩了 4 个坑（测试桩注入顺序、异步断言没轮询、.ps1 丢 BOM、-replace 参数解析）， 全部记在 09-踩坑清单.md 的 F 节。