# Farstrides 个人网站视觉系统

本项目为视觉系统与可交互样张，线上入口为 [me.farstrides.com](https://me.farstrides.com/)。`tokens.css` 是唯一变量源，`specimen.css` 展示变量的使用方式，`index.html` 是页面入口。源码通过 Vite 构建为静态文件；开发、预览和发布方式见项目根目录 `README.md`。页面没有 UI 框架、外部字体、图标库或动画依赖。

设计面向作品介绍、项目详情和长文阅读。以有秩序的作品目录为方向：清楚的标题、舒适的正文、有限的强调。个人首页可沿用“简短介绍 → 项目列表 → 必要的个人说明”的内容顺序。样张中的介绍文案是排版示例，未作为用户身份或正式品牌定位。

## 设计依据与边界

- 实际查看了 [Physics Lab 模型库](https://physics-lab.farstrides.com/)：课堂模型按学科与章节组织。个人站采用准确、直接的工具介绍，避免夸大模型覆盖与验收情况。
- 定向读取 `D:/Code/Goal-Task-Todo/README.md`、`PROGRESS.md` 和 `apps/web/src/tokens.css`：Farstride 以行动、目标和计划为核心，已有纸色背景与绿色强调。个人站保留相近气质，但不更改两个产品的独立视觉系统。
- 配色以 [Radix Colors](https://www.radix-ui.com/colors/docs/palette-composition/understanding-the-scale) 的 Sand / Jade 为基础，数值参考 `@radix-ui/colors@3.0.0` 的 sRGB CSS。浅色 accent 从 Jade 11 深化为 `#1e7a61`，使其在 background 和 surface 上都满足普通文字 4.5:1。未安装依赖。

## 1. Typography scale

系统无衬线承担标题、正文和控件；系统衬线仅承担极少量 Display；系统等宽仅用于代码与数值标记。中英文字体依设备而变，这是零字体下载的有意取舍。中文标题不加负字距，英文标题可用 `-.025em`，Display 英文可用 `-.035em`。

下表范围以根字号 16px、视口约 320–1320px 为参照。所有实际尺寸使用 rem，支持用户调整字号。

| Token | CSS 值 | 用途 |
| --- | --- | --- |
| `--text-display` | `clamp(2.75rem, 2.03rem + 3.6vw, 5rem)` | 44–80px，每页至多一处品牌表达；行高 1.22，字重 400 |
| `--text-h1` | `clamp(2.25rem, 1.69rem + 2.8vw, 4rem)` | 36–64px，页面主标题 |
| `--text-h2` | `clamp(1.625rem, 1.345rem + 1.4vw, 2.5rem)` | 26–40px，主要章节 |
| `--text-h3` | `clamp(1.25rem, 1.19rem + .3vw, 1.4375rem)` | 20–23px，项目与次级章节 |
| `--text-body` | `clamp(1rem, .96rem + .2vw, 1.125rem)` | 16–18px，正文 |
| `--text-small` | `.875rem` | 14px，控件与辅助信息 |
| `--text-caption` | `.8125rem` | 13px，图注、日期和技术标记 |

Heading 行高 1.3、字重 600；正文行高 1.8、字重 400；辅助文字行高 1.6。常规页面优先使用 Body / H2 / H3 三档；H1 只用于页首，Caption 仅在必要时使用，展示全部刻度不代表每页都要用完。

中文正文 `max-width:36em`，约 36 个全角字符；英文正文 `max-width:65ch`。混排或代码可按内容缩短行宽。页面外框最多 75rem，宽屏不无限拉长正文。语义与视觉分离：每页一个 H1，H2/H3 顺序清楚，Display 类不决定 HTML 标签。

## 2. Spacing scale

使用 4px 基准，对应 rem：`0 / 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 / 128`。变量名为 `--space-0/1/2/3/4/6/8/12/16/24/32`，数字表示 4px 单位。

关联信息 8–16px；组件内部 16–24px；组件之间 24–32px；章节使用 `--section-space:clamp(3rem, 2rem + 5vw, 6rem)`，从 48px 增至 96px。页面边距 `--gutter:clamp(1.25rem, .65rem + 3vw, 3rem)`，从 20px 增至 48px。通过间距表达内容关系，不在每个 section 中重复眉题、卡片和说明。

## 3. Color roles

| Role | Light | Dark | 用途 |
| --- | --- | --- | --- |
| `background` | `#fdfdfc` | `#111110` | 全页底色 |
| `surface` | `#f9f9f8` | `#191918` | 补充信息、代码块等局部底色 |
| `text-primary` | `#21201c` | `#eeeeec` | 标题、正文 |
| `text-secondary` | `#63635e` | `#b5b3ad` | 辅助说明 |
| `muted` | `#63635e` | `#b5b3ad` | 日期、图注等元信息；不通过降低 opacity 弱化 |
| `border` | `#dad9d6` | `#3b3a37` | 非交互分隔线 |
| `accent` | `#1e7a61` | `#1fd8a4` | 链接、焦点、主要动作 |
| `accent-foreground` | `#ffffff` | `#0d1512` | accent 背景上的文字 |

补充：控件边框 `border-control` 为浅色 `#82827c`、深色 `#7c7b74`；按钮与链接 hover 分别为 `#1d3b31` / `#adf0d4`；focus-ring 跟随 accent。secondary 与 muted 语义不同、数值相同，层级通过字号、位置和间距区分。border 不用于表达选中、错误或焦点。

默认跟随系统；`<html data-theme="light">` / `dark` 可显式覆盖；移除属性即恢复系统偏好。页面头部的最小脚本在绘制前读取已保存的选择，`theme.js` 负责主题控件、保存选择和色值样张。存储键由 HTML 的 `data-theme-storage-key` 单点定义；存储不可用时保留本次选择。即使 JavaScript 不可用，内容与系统明暗主题仍可使用。

## 4. Border / radius

线宽 1px；需要明确强调时 2px。`--radius-none:0`、`--radius-sm:4px`（控件）、`--radius-md:8px`（有限容器）、`--radius-lg:12px`（图片）、`--radius-pill:999px`（仅适合确有需要的状态标签）。本系统不要求为文字内容包卡片，不新增装饰性的彩色侧边条。

## 5. Shadow

默认 `--shadow-none:none`。浅色 `--shadow-popover:0 4px 16px rgb(33 32 28 / .1), 0 1px 3px rgb(33 32 28 / .06)`；`--shadow-dialog:0 16px 48px rgb(33 32 28 / .16)`。深色分别采用黑色 28% / 20% 和 40% 的同类投影。

只用于浮层与对话框的真实层叠关系，并保留边框。项目列表、普通章节和默认按钮无投影；不使用有色光晕。

## 6. Motion duration

`instant:0ms`（主题切换、焦点）、`fast:120ms`（hover）、`base:200ms`（局部状态）、`slow:280ms`（必要展开）。按需为具体属性写 transition，不写 `transition:all`。

文字内容初始可见，不等待滚动触发，不做全站 fade-up，不使用视差与无限背景动画。示例仅对按钮背景执行 hover 过渡。未来动态内容的忙碌状态需有文字反馈，不能只用旋转图标传达。

## 7. Easing / spring

进入与局部反馈：`--ease-out:cubic-bezier(.16,1,.3,1)`。往返切换：`--ease-in-out:cubic-bezier(.65,0,.35,1)`。

可选弹簧参数：mass 1、stiffness 300、damping 34.7，接近临界阻尼，用于直接操作对象的拖拽归位。仅在实际使用物理弹簧的实现中读取这些数值；CSS transition 不直接消费它们。本样张没有拖拽需求，不加载弹簧引擎。reduced-motion 下直接到终态。

## 8. Responsive breakpoints

| 名称 | 边界 | 布局行为 |
| --- | --- | --- |
| Base | 0 | 单栏，导航自然换行 |
| sm | 40rem / 640px | 排版标签与样本并列 |
| md | 48rem / 768px | 项目分列，介绍可并排 |
| lg | 64rem / 1024px | 增加列间距，正文保持行宽 |
| xl | 80rem / 1280px | 保持最多 1200px 外框 |

px 仅为默认 16px 的换算。`--breakpoint-*` 是供文档和 JS 读取的命名值；标准 CSS media query 不支持 `var()`，样式中明确使用 `@media(min-width:48rem)` 等字面量。根据内容是否放得下决定断点，不按设备型号强行分类。

## 可访问性与性能使用规则

按 [WCAG 2.2 AA 文字对比度](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) 约束配色：普通文字至少 4.5:1，大字至少 3:1；本次主副正文与 accent 文字均以 4.5:1 为目标。控件识别边框与焦点按 3:1 处理。完整 WCAG AA 还涉及内容、交互和最终页面，不能仅靠 tokens 宣称全站达标。

使用原生链接、按钮与表单，所有操作可通过 Tab / Shift+Tab 到达；按钮使用 Enter / Space，链接使用 Enter，select 沿用平台方向键。提供跳转主内容入口，focus-visible 使用 2px outline + 4px offset，不移除焦点，不依赖颜色单独传达状态。独立控件目标至少 44px；正文行内链接不为触摸尺寸破坏阅读。默认不新开浏览器标签。

未来实际增加表单、异步加载或弹窗时，补齐对应标签、禁用、忙碌、空态、错误文字和焦点返回；本次不为不存在的功能制作占位流程。减少动态规则同时清零 timing tokens 并关闭动画、过渡和平滑滚动；系统高对比度模式保留控件边界。

样张源码不引入远程字体、图片或统计脚本。正式域名通过 Cloudflare 的仅主机名匹配规则关闭默认 RUM 注入，使页面直接使用构建产物；该设置不影响其他子域名。未来实际项目截图必须给出 width/height 或 aspect-ratio；首屏关键图按需优先加载，其余图 lazy-load；不在首屏挂载两个项目的 iframe 或实验运行时。避免主线程动画和全站滚动监听，按需用 transform/opacity，不对大面积阴影和滤镜做动画。

[Core Web Vitals](https://web.dev/articles/vitals) 目标为真实用户第 75 百分位 LCP ≤ 2.5s、INP ≤ 200ms、CLS ≤ 0.1，移动和桌面分开统计。本次本地预览不能替代上线后的真实用户测量。

## 接入

业务网站引入 `tokens.css` 后，用语义变量组合现有组件；不需要照搬样张的章节。中文和英文阅读容器分别使用 `--content-reading-cjk`、`--content-reading`。主题控件 ID 为 `theme`，存储键通过 HTML 定义。设计变量、交互和部署各有独立入口；本文件只维护视觉与使用规范，发布说明维护在项目根目录 `README.md`。