# fresh-mint 皮肤包

由 blue-white 派生的清新薄荷风皮肤（**卡片封面版**，docs/10 契约 §5 工作流）。**升级随版本发布，不在站点间复制目录**。

## 风格定位

清爽、亲和，适合职业院校门户：主色薄荷青、圆角 12px、卡片纯白+柔和阴影、细线吸顶顶栏+居中 logo、列表卡片网格（一行 3 张）支持封面图、几何圆点装饰与大留白；无纹理、无通栏大图、无复杂动效。

与 `fresh-mint`（同色系基础版）的差异：列表为带封面的卡片网格（`listLayout=grid`，`decoration=dots`），header 为 3 列网格（左：专业院系 / 中：品牌 / 右：搜索）；`fresh-mint` 采用 top-bar + brand-row 顶栏与纯文字列表卡片。

## 数据契约（模板可取用的 model 属性全集，契约 §3）

| 页面 | 属性 |
| --- | --- |
| 全部 | `site`（快照：config/分类树/轮播/友链组/院系子站）、`url`（PortalUrlHelper：home/category/article/upload/asset/search/siteHome）、`themeBase`（=`themes/fresh-mint`）、`navCategories`、`pageTitle`、`seoDescription`、`canonical`、`themeParams`（微调参数，仅 theme.json 声明过的 key）、`themeVarsCss`（服务端预构建 `:root{}` 覆盖串，无参数为空） |
| home | `banners`（时间窗内 home 位）、`topArticles`（置顶+最新 6）、`categoryBlocks`（LIST 型根栏目块，各 top 8） |
| list / search | `listData`（分页 + `items[].coverImage`）、`category`（list）、`q` + `searchMode`（search） |
| detail | `article`、`prevArticle`、`nextArticle`、`currentCategoryId` |
| single | `category`（含 `content`）、`currentCategoryId` |

原则：皮肤不得假设"首页一定有轮播"、"列表一定有封面"，对空集合优雅降级。

## 轮播图尺寸约定（bannerSize）

1920x560（管理端上传端按此引导裁剪）。

## 可调参数

见 `theme.json` 的 `params`：

- **color**（进 CSS 变量）：`primary` 主色 / `primaryDark` 主色加深（用于品牌文字、悬停加深）/ `primarySoft` 主色浅调（装饰、点缀背景）/ `bg` 页面底色 / `border` 边框色。
- **select**：`listLayout` = `grid`（默认，卡片网格一行 3 张，支持封面）或 `list`（简约列表，封面靠左缩略）；`decoration` = `dots`（默认，背景几何圆点）或 `plain`（纯净无装饰）。

换色建议：主色系三值同步调整（primary / primaryDark / primarySoft），bg 与 border、primarySoft 保持同族浅色调，避免底色与卡片对比失衡。

优先级：`custom_css` > `themeVarsCss` > `main.css`。