387 lines
14 KiB
Markdown
387 lines
14 KiB
Markdown
# WarmIsland 暖屿 主题 Spec
|
||
|
||
## Why
|
||
|
||
Halo 默认主题及社区主题多为传统博客布局，缺乏品牌气质与情绪温度。WarmIsland 暖屿旨在打造一座"深夜里温暖、安静、治愈的小岛"——一个具有独特品牌记忆点、杂志化排版、情绪化 UI 的高端生活方式博客主题，而非普通博客模板。
|
||
|
||
## What Changes
|
||
|
||
- 基于 `halo-sigs/theme-astro-starter` 模板，从 0 重构全部页面与组件
|
||
- **BREAKING**: 完全替换现有 Astro 组件结构、样式系统、页面布局
|
||
- 新增 Hero 首屏模块（超大标题 + 情绪文案 + 岛屿氛围背景 + 呼吸动画）
|
||
- 新增杂志化首页布局（Editorial Design、不规则高级布局、大图排版）
|
||
- 新增悬浮毛玻璃导航栏（Apple/Raycast 风格、胶囊圆角、滚动吸附）
|
||
- 新增文章卡片设计（大封面图、毛玻璃、hover 微浮动、高级圆角）
|
||
- 新增低饱和暖色配色系统（奶油暖白、日落橘、焦糖棕、雾粉、海盐灰）
|
||
- 新增杂志排版字体方案与阅读舒适度优化
|
||
- 新增克制柔和动效系统（呼吸动画、hover 浮动、页面渐隐、光感移动）
|
||
- 新增移动端原生 App 级体验重新设计
|
||
- 新增 6 个 Halo 插件专属 UI 适配（友链、图库、瞬间、朋友圈、评论、搜索）
|
||
- 新增留言板自定义页面模板
|
||
- 新增完整 settings.yaml 配置系统（19 个分组、模块化首页系统）
|
||
- 新增深色模式完整适配
|
||
- 新增默认 Logo 与 favicon 资源
|
||
- 更新 theme.yaml 元数据与兼容版本至 Halo >= 2.24.0
|
||
|
||
## Impact
|
||
|
||
- Affected specs: 全部页面模板、全部组件、全部样式、主题配置系统
|
||
- Affected code:
|
||
- `theme.yaml` — 元数据、customTemplates、requires 版本
|
||
- `settings.yaml` — 新增（原模板无此文件）
|
||
- `astro.config.mjs` — base 路径、插件配置
|
||
- `src/layouts/Layout.astro` — 完全重写
|
||
- `src/components/Header.astro` — 完全重写为悬浮毛玻璃导航
|
||
- `src/components/Footer.astro` — 完全重写
|
||
- `src/components/` — 新增大量组件
|
||
- `src/pages/index.astro` — 完全重写为杂志化首页
|
||
- `src/pages/post.astro` — 完全重写
|
||
- `src/pages/page.astro` — 完全重写
|
||
- `src/pages/` — 新增多个页面模板
|
||
- `src/styles/` — 完全重写为 SCSS 模块化架构
|
||
- `public/` — 新增资源文件与 Thymeleaf fragments
|
||
- `package.json` — 新增依赖（SCSS 等）
|
||
|
||
---
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: 品牌识别系统
|
||
|
||
主题 SHALL 具有极强的品牌识别度，用户一眼即可辨识"WarmIsland 暖屿"的品牌气质。
|
||
|
||
#### Scenario: 品牌首屏印象
|
||
- **WHEN** 用户首次访问 WarmIsland 站点
|
||
- **THEN** 第一屏即传达"深夜、温暖、安静、治愈"的品牌氛围，包含品牌名称、情绪化文案、岛屿氛围视觉元素
|
||
|
||
#### Scenario: 品牌一致性
|
||
- **WHEN** 用户浏览站内任意页面
|
||
- **THEN** 所有页面保持统一的品牌视觉语言（配色、字体、动效、留白节奏）
|
||
|
||
---
|
||
|
||
### Requirement: Hero 首屏模块
|
||
|
||
系统 SHALL 提供全屏 Hero 区域作为首页第一视觉焦点。
|
||
|
||
#### Scenario: Hero 展示
|
||
- **WHEN** 用户访问首页
|
||
- **THEN** 显示全屏 Hero 区域，包含：超大品牌标题、情绪化副标题文案、岛屿氛围背景（柔和光斑 + 模糊层次）、呼吸动画、高级 CTA 按钮、页面滚动引导
|
||
|
||
#### Scenario: Hero 可配置
|
||
- **WHEN** 管理员在后台 settings 中配置 Hero 文案、背景图、按钮文字
|
||
- **THEN** 前端 Hero 区域相应更新
|
||
|
||
---
|
||
|
||
### Requirement: 杂志化首页布局
|
||
|
||
首页 SHALL 采用 Editorial Design 杂志化布局，而非传统博客列表。
|
||
|
||
#### Scenario: 首页模块化展示
|
||
- **WHEN** 用户访问首页
|
||
- **THEN** 首页由可配置模块组成：Hero、Featured（置顶文章）、Latest（最新文章）、Moments（瞬间）、Photos（图库）、Friends（友链）、Links（链接）、Quote（语录）、Timeline（时间线）、About（关于）、Music（音乐）、Message Wall（留言墙）
|
||
- **AND** 每个模块可在后台独立开启/关闭、排序、配置样式
|
||
|
||
#### Scenario: 文章展示
|
||
- **WHEN** 首页展示文章列表
|
||
- **THEN** 采用杂志化大图排版，具有呼吸感留白、内容节奏感、不规则高级布局，而非密集信息流或普通卡片堆叠
|
||
|
||
---
|
||
|
||
### Requirement: 悬浮毛玻璃导航栏
|
||
|
||
导航栏 SHALL 采用悬浮毛玻璃设计，具有 Apple/Raycast/Linear/Arc 级别的高级导航体验。
|
||
|
||
#### Scenario: 导航栏展示
|
||
- **WHEN** 用户浏览任意页面
|
||
- **THEN** 导航栏呈现：悬浮效果、毛玻璃背景、胶囊圆角容器、半透明、滚动吸附顶部、柔和 hover 动效
|
||
|
||
#### Scenario: 移动端导航
|
||
- **WHEN** 用户在移动端访问
|
||
- **THEN** 导航栏适配为移动端菜单，保持品牌感与高级感
|
||
|
||
#### Scenario: 导航栏可配置
|
||
- **WHEN** 管理员在后台配置导航 Logo、菜单项
|
||
- **THEN** 导航栏相应更新，支持自定义 Logo 替换
|
||
|
||
---
|
||
|
||
### Requirement: 文章卡片设计
|
||
|
||
文章卡片 SHALL 采用杂志化高级设计。
|
||
|
||
#### Scenario: 卡片展示
|
||
- **WHEN** 文章以卡片形式展示
|
||
- **THEN** 卡片具有：大封面图、柔和阴影、半透明层次、毛玻璃效果、hover 微浮动、缓动动画、高级圆角、情绪化摘要
|
||
|
||
#### Scenario: 卡片交互
|
||
- **WHEN** 用户 hover 文章卡片
|
||
- **THEN** 卡片产生柔和上浮效果，封面图轻微放大，阴影加深
|
||
|
||
---
|
||
|
||
### Requirement: 低饱和暖色配色系统
|
||
|
||
主题 SHALL 使用低饱和暖色体系。
|
||
|
||
#### Scenario: 亮色模式配色
|
||
- **WHEN** 主题处于亮色模式
|
||
- **THEN** 使用奶油暖白背景、日落橘强调色、焦糖棕文字色、雾粉辅助色、海盐灰边框色
|
||
|
||
#### Scenario: 深色模式配色
|
||
- **WHEN** 主题处于深色模式
|
||
- **THEN** 配色自动切换为深色暖调版本，保持温暖感而非冰冷科技感
|
||
|
||
#### Scenario: 配色可自定义
|
||
- **WHEN** 管理员在后台 settings 中修改主色调
|
||
- **THEN** 前端配色系统相应更新
|
||
|
||
---
|
||
|
||
### Requirement: 杂志排版字体方案
|
||
|
||
主题 SHALL 采用高级生活杂志 / 日系 Editorial 级别的排版方案。
|
||
|
||
#### Scenario: 标题排版
|
||
- **WHEN** 页面渲染标题
|
||
- **THEN** 标题具有明确的视觉层级、合适的字重与字号、letter-spacing 调整、杂志排版感
|
||
|
||
#### Scenario: 正文阅读
|
||
- **WHEN** 用户阅读文章正文
|
||
- **THEN** 正文具有舒适的行高、段间距、留白节奏、呼吸感，阅读体验优于传统博客
|
||
|
||
---
|
||
|
||
### Requirement: 克制柔和动效系统
|
||
|
||
主题 SHALL 实现克制、柔和、高级的动效。
|
||
|
||
#### Scenario: 呼吸动画
|
||
- **WHEN** 页面加载完成
|
||
- **THEN** Hero 区域背景光斑呈现缓慢呼吸动画，营造"活着"的氛围感
|
||
|
||
#### Scenario: 页面过渡
|
||
- **WHEN** 用户在页面间导航
|
||
- **THEN** 页面切换呈现柔和渐隐渐显过渡
|
||
|
||
#### Scenario: 卡片交互动效
|
||
- **WHEN** 用户 hover 交互元素
|
||
- **THEN** 产生柔和缓动动画（浮动、阴影变化、颜色过渡），而非廉价炫酷动画
|
||
|
||
#### Scenario: 动效可配置
|
||
- **WHEN** 管理员在后台关闭动效
|
||
- **THEN** 所有动画效果禁用，保持静态展示
|
||
|
||
---
|
||
|
||
### Requirement: 移动端原生 App 级体验
|
||
|
||
移动端 SHALL 重新设计为原生 App 级体验，而非简单缩放。
|
||
|
||
#### Scenario: 移动端导航
|
||
- **WHEN** 用户在移动端访问
|
||
- **THEN** 导航栏变为沉浸式移动菜单，具有品牌感
|
||
|
||
#### Scenario: 移动端阅读
|
||
- **WHEN** 用户在移动端阅读文章
|
||
- **THEN** 排版适配移动端，保持高级感、品牌感、情绪感
|
||
|
||
#### Scenario: 移动端卡片
|
||
- **WHEN** 移动端展示文章卡片
|
||
- **THEN** 卡片布局适配竖屏，保持大图氛围与留白节奏
|
||
|
||
---
|
||
|
||
### Requirement: 插件适配 — plugin-links（友链）
|
||
|
||
主题 SHALL 完整适配 plugin-links 友链插件，并提供专属 UI。
|
||
|
||
#### Scenario: 友链页面展示
|
||
- **WHEN** 用户访问友链页面且 plugin-links 已安装
|
||
- **THEN** 友链以 WarmIsland 风格的卡片网格展示，具有毛玻璃效果、柔和阴影、hover 微交互
|
||
|
||
---
|
||
|
||
### Requirement: 插件适配 — plugin-photos（图库）
|
||
|
||
主题 SHALL 完整适配 plugin-photos 图库插件，并提供专属 UI。
|
||
|
||
#### Scenario: 图库页面展示
|
||
- **WHEN** 用户访问图库页面且 plugin-photos 已安装
|
||
- **THEN** 图库以瀑布流 / 杂志化网格展示，具有大图预览、柔和过渡、灯箱效果
|
||
|
||
---
|
||
|
||
### Requirement: 插件适配 — plugin-moments（瞬间）
|
||
|
||
主题 SHALL 完整适配 plugin-moments 瞬间插件，并提供专属 UI。
|
||
|
||
#### Scenario: 瞬间页面展示
|
||
- **WHEN** 用户访问瞬间页面且 plugin-moments 已安装
|
||
- **THEN** 瞬间以时间线 + 卡片形式展示，具有情绪化排版、呼吸感留白
|
||
|
||
---
|
||
|
||
### Requirement: 插件适配 — plugin-friends-new（朋友圈）
|
||
|
||
主题 SHALL 完整适配 plugin-friends-new 朋友圈插件，并提供专属 UI。
|
||
|
||
#### Scenario: 朋友圈页面展示
|
||
- **WHEN** 用户访问朋友圈页面且 plugin-friends-new 已安装
|
||
- **THEN** 朋友圈以 WarmIsland 风格的卡片流展示，具有品牌统一感
|
||
|
||
---
|
||
|
||
### Requirement: 插件适配 — plugin-comment-widget（评论组件）
|
||
|
||
主题 SHALL 适配 plugin-comment-widget，评论区风格与 WarmIsland 保持统一。
|
||
|
||
#### Scenario: 评论区展示
|
||
- **WHEN** 文章/页面下方显示评论区
|
||
- **THEN** 评论区具有：毛玻璃层次、半透明背景、柔和阴影、hover 微交互、深色模式适配
|
||
|
||
#### Scenario: 评论功能兼容
|
||
- **WHEN** 用户使用评论功能
|
||
- **THEN** 保留插件默认评论输入框结构，不破坏插件功能逻辑与兼容性
|
||
|
||
---
|
||
|
||
### Requirement: 插件适配 — plugin-search-widget（搜索组件）
|
||
|
||
主题 SHALL 适配 plugin-search-widget，搜索体验设计为"WarmIsland 的内容探索空间"。
|
||
|
||
#### Scenario: 搜索触发
|
||
- **WHEN** 用户点击搜索按钮或使用快捷键（Cmd/Ctrl + K）
|
||
- **THEN** 弹出 Spotlight/Raycast 风格的悬浮搜索层，具有毛玻璃弹层、模糊背景、平滑动画
|
||
|
||
#### Scenario: 搜索结果展示
|
||
- **WHEN** 搜索结果返回
|
||
- **THEN** 结果以情绪化方式展示，保持 WarmIsland 品牌风格
|
||
|
||
---
|
||
|
||
### Requirement: 留言板自定义页面模板
|
||
|
||
主题 SHALL 提供留言板自定义页面模板。
|
||
|
||
#### Scenario: 留言板模板注册
|
||
- **WHEN** 主题安装后
|
||
- **THEN** 在 theme.yaml 的 customTemplates.page 中注册留言板模板
|
||
|
||
#### Scenario: 留言板页面展示
|
||
- **WHEN** 用户访问使用留言板模板的页面
|
||
- **THEN** 显示 WarmIsland 风格的留言板，具有情绪化排版、评论组件集成
|
||
|
||
---
|
||
|
||
### Requirement: 完整 settings.yaml 配置系统
|
||
|
||
主题 SHALL 基于 Halo 2.x 的 FormKit Schema 提供完整配置系统。
|
||
|
||
#### Scenario: 配置分组
|
||
- **WHEN** 管理员进入主题设置页面
|
||
- **THEN** 可见以下配置分组：basic、hero、layout、style、animation、article、navbar、footer、home、moments、photos、friends、links、comment、search、messageboard、mobile、advanced
|
||
|
||
#### Scenario: 首页模块化配置
|
||
- **WHEN** 管理员在 home 分组中配置首页模块
|
||
- **THEN** 可对每个模块进行：开启/关闭、排序、独立配置、样式切换
|
||
|
||
#### Scenario: 配置生效
|
||
- **WHEN** 管理员保存配置
|
||
- **THEN** 前端通过 `theme.config.[group].[name]` 读取配置并相应渲染
|
||
|
||
---
|
||
|
||
### Requirement: 默认主题资源
|
||
|
||
主题 SHALL 包含默认 Logo 与 favicon 资源。
|
||
|
||
#### Scenario: 默认资源加载
|
||
- **WHEN** 主题首次安装
|
||
- **THEN** 使用默认 Logo（Logo.png）与 favicon（Logo.ico）
|
||
|
||
#### Scenario: 资源可替换
|
||
- **WHEN** 管理员在后台 settings 中上传自定义 Logo/favicon
|
||
- **THEN** 前端使用自定义资源替代默认资源
|
||
|
||
---
|
||
|
||
### Requirement: Astro 架构
|
||
|
||
主题 SHALL 基于 Astro 架构实现现代化开发。
|
||
|
||
#### Scenario: 组件化开发
|
||
- **WHEN** 开发主题功能
|
||
- **THEN** 使用 Astro Components + Vue Islands 架构，动态组件拆分，SCSS 模块化
|
||
|
||
#### Scenario: 构建输出
|
||
- **WHEN** 执行 `astro build`
|
||
- **THEN** 输出到 `templates/` 目录，静态资源输出到 `templates/assets/`
|
||
|
||
---
|
||
|
||
### Requirement: 深色模式
|
||
|
||
主题 SHALL 完整支持深色模式。
|
||
|
||
#### Scenario: 深色模式切换
|
||
- **WHEN** 用户切换深色模式
|
||
- **THEN** 全站配色切换为深色暖调版本，所有组件（导航、卡片、评论区、搜索等）适配深色模式
|
||
|
||
#### Scenario: 系统偏好跟随
|
||
- **WHEN** 用户未手动设置主题模式
|
||
- **THEN** 主题跟随系统深色/亮色偏好
|
||
|
||
---
|
||
|
||
### Requirement: Halo 版本兼容
|
||
|
||
主题 SHALL 兼容 Halo >= 2.24.0。
|
||
|
||
#### Scenario: 版本声明
|
||
- **WHEN** 主题安装
|
||
- **THEN** theme.yaml 中 `spec.requires` 声明为 `">=2.24.0"`
|
||
|
||
#### Scenario: API 使用
|
||
- **WHEN** 主题调用 Halo API
|
||
- **THEN** 使用 Halo 2.24+ 最新主题开发规范和 API，不使用过时 API
|
||
|
||
---
|
||
|
||
### Requirement: SEO 与性能
|
||
|
||
主题 SHALL 具备良好的 SEO 与首屏性能。
|
||
|
||
#### Scenario: SEO 基础
|
||
- **WHEN** 页面渲染
|
||
- **THEN** 包含正确的 meta 标签、语义化 HTML、合理的标题层级
|
||
|
||
#### Scenario: 首屏性能
|
||
- **WHEN** 用户首次访问
|
||
- **THEN** 首屏内容快速渲染，关键 CSS 内联，非关键资源延迟加载
|
||
|
||
---
|
||
|
||
## MODIFIED Requirements
|
||
|
||
### Requirement: 主题元数据
|
||
|
||
theme.yaml 元数据更新为 WarmIsland 暖屿品牌信息。
|
||
|
||
- `metadata.name`: `warm-island`
|
||
- `spec.displayName`: `WarmIsland 暖屿`
|
||
- `spec.requires`: `>=2.24.0`
|
||
- `spec.settingName`: `warm-island-setting`
|
||
- `spec.configMapName`: `warm-island-configMap`
|
||
- `spec.customTemplates.page`: 新增留言板模板
|
||
|
||
---
|
||
|
||
## REMOVED Requirements
|
||
|
||
### Requirement: 原始 Astro Starter 模板 UI
|
||
|
||
**Reason**: 完全替换为 WarmIsland 品牌化 UI，原始模板 UI 不再使用
|
||
**Migration**: 所有原始组件、样式、页面布局将被完全重写，无需迁移
|