immersive-cultural-ui

沉浸式传统文化界面

这个 skill 管一种风格：夜色里的一幕。主体用发光的细金线画在深色上；四周是少量竖排的字；背后是压暗的星空、薄雾和宣纸纹理；最淡的一层是和主题相关、有真实出处的书法批注。它来自一个已经上线的命理历法应用（见文末「来源与维护」），用户前后调过好几轮。

一句话原则：主体清楚，氛围退后。 氛围、装饰、动效都是为了让主体更好看。哪一样和主体抢眼，就压暗、删掉或关掉它。

和 web-design-engineer 一起用

• 装了 web-design-engineer 时：
  • 它管通用流程：理解需求、Design Read、写代码前先声明设计系统、浏览器验收。
  • 这个 skill 管这一种风格。
  • 走到它选配方那一步（Step 2/3），读这里的 references/recipe-tianshu.md。它和那边的 style-recipes 格式相同。在 Design Decisions 里写 Anchor / recipe: tianshu（immersive-cultural-ui）。
  • 不要再从那边 25 个配方里混一个进来。那边自己也反对两套配方混用。
• 没装时： 照下面的流程走。
• 不要改 web-design-engineer 本身。 它是第三方 skill，更新时会覆盖本地改动。要补充什么，写在这里。

什么时候不用

• 以表格、表单为主、天天要用的工具页：只借「安静控件」和「详细」的写法，不加氛围层。
• 用户要明亮、轻快或商务的感觉，或者品牌已经有自己的视觉规范。
• 内容和东方、古典、神秘学都不沾边。硬套古风只会显得做作。

流程

1. 先出概念，再实现。

   • 新页面或大改版，先做两三个能看的概念让用户挑。一个静态 HTML 加一张 1440×900 截图就够，不接数据，不写交互。
   • 概念之间要真的不同：主体的形式不同（例如罗盘式圆图、卷轴横展、册页翻看），而不只是换颜色。
   • 为什么：这种风格好不好全靠眼睛看，文字描述对不齐。先出概念，返工最少。
   • 用户已经说清楚要什么样子，或者只是小改，就跳过。没法等用户回复时（例如在自动化任务里），说明选了哪个、为什么，然后直接做。

2. 定两种看法： 简洁和详细，见下文。

3. 定配方：

   • 读 references/recipe-tianshu.md。
   • 选东方暖夜（墨色、朱红、琥珀）或西方星空（深靛、紫）。主题需要别的主色，照那里「换主色」一节改。
   • 把数值写成 CSS 变量。references/code/tianshu.css 第一节已经写好。

4. 搭层次： 从后往前依次是：

   1. 底色和星空；
   2. 光雾、雾、光点、宣纸纤维、颗粒；
   3. 一层暗纱，盖住上面所有背景层；
   4. 跟随鼠标的烛光、偶尔的流星；
   5. 内容；
   6. 装饰。

   references/code/ 里都有现成的。

5. 加动效： 读 references/motion.md。

6. 加装饰： 最后加，嫌多时最先删。读 references/decoration.md。

7. 交付前过清单： 逐条核对 references/checklist.md，用截图作证据。装了 frontend-verification skill 时，截图和量尺寸用它的脚本。

核心做法

两种读者，两种看法

• 简洁是一幕展示：
  • 主体占满第一屏。默认版式是主体约 600px 见方摆在中间，四角放少量要紧的信息：右上是主语（这是什么），左上是来历和背景，左下是组成它的几样要素，右下是要素之间的关系。四角离边 3%。另一种版式见下面「一幕的两种版式」。
  • 一幕第一次出现时逐层亮起，像有人一层层讲给你听。
  • 给新手看：要好看，读起来不吃力。进阶内容不放这里。
• 详细是完整视图：
  • 表格和所有区块齐全，给熟手读。
  • 不播开场动画，直接全部显示。
• 一幕上方不放表单。 要输入的东西（出生信息、日期）收进抽屉，或者变成一行可以点的小字。页面一打开就是主体。
• 切换： 用 View Transition 交叉淡入淡出：旧的 0.3s 淡出，新的 0.45s 淡入、延迟 0.15s。
• 检查：
  • 1440×900 上，简洁这一幕不用滚动就完整可见；
  • 手机上依次排成一列，没有横向滚动；
  • 英文界面下，四角的字不压到主体上。
• 不是每页都要切换按钮。 介绍页、展品页可以是「第一屏一幕，往下滚是完整内容」。要紧的是第一屏是一幕，不是一堆卡片。

一幕的两种版式

• 四角版（默认，来源项目验证过）：
  • 主体居中，约 600px 见方，信息分到四角。
  • 适合主体本身是一张「图」的页面：罗盘、命盘、星图。四角的字和主体互相说明。
• 主体做大（tianshu.css 的 ④b，还没在真实项目里用过）：
  • 主体占一大半宽度，偏到一侧；信息收进另一侧的一栏；从上方落下一束很淡的光，脚下一圈落地的光。
  • 适合主体本身就有分量的页面：一件器物、一幅画、一尊像、一张牌。四角版会把它压小。
  • 来由：后母戊鼎展品页的测试里，不用这个 skill 的那版把鼎做成大图，比照搬四角版的那版更有气势。
  • 做法：
    • 主体按屏幕高度封顶（--ratio 写主体的宽高比），1280×720 上也整个放得下；
    • 信息栏靠着主体；
    • 装饰只放在信息栏外侧的留白里，留白不够的宽度（1100–1280）就不放；
    • 手机上排成一列，主体在前。
• 怎么选： 遇到实物、作品这类页面，两种版式各出一个概念让用户挑（流程第 1 步），不要直接定成哪一种。主体做大这一种用过几次、确认好用之后，再把这条改成明确的规则。

背景比你以为的要暗

• 星空、光雾、雾、纸纹各自都很淡，叠在一起就会抢内容。
• 做法：在所有背景层上盖一层统一的暗纱，东方用 rgb(5 4 3 / .3)，西方用 rgb(3 3 12 / .28)。然后问用户「背景抢不抢内容」，调到对方说不抢为止。
• 起点就比直觉暗一档。来源项目调了两轮才定下来：
  • 纸纹 .16 → .07；
  • 雾 .34 → .24；
  • 背后的星空 .92 → .62；
  • 再加上暗纱。

装饰只做视觉辅助

• 很淡： 不透明度约 .06 到 .6。越大越淡：大字铺底 .06，书法批注 .55–.62。
• 对读屏软件不存在： 加 aria-hidden="true"、pointer-events: none、user-select: none。
• 只在宽屏显示： 留白里的批注和线描 1100px 以上才出现，手机上没有留白。压在主体中心背后、极淡的那个大字不占留白，手机上可以保留（来源项目就是这样）。打印时都不出现。英文界面不显示中文书法批注。
• 不能让读者以为是主要信息：
  • 颜色用褐色墨或淡金，不用正文色；
  • 放在留白里，不压在内容上；
  • 比正文小，或者大得多但极淡。
• 和主题相关，内容真实，有出处：
  • 引文要能说出书名和篇名，例如八字页用《滴天髓》论日主的四句，节气页用当天的七十二候。
  • 拿不准原文就不放，或者问用户。不编古文。 编出来的「古语」会被懂行的人一眼看穿，整页的可信度跟着塌掉。

动效：有景深，不拖慢

• 景深： 各层随鼠标（手机上随倾斜）以不同速度错开。
  • 最远的星空逆着鼠标移得最多，雾次之，主体最近、顺着鼠标微微移动。
  • 用 CSS 的 translate 属性移动，不碰 transform，各层自己的动画（雾的漂移、刻度的旋转）就不受影响。
• 只动 transform 和 opacity，以及独立的 translate、scale、rotate 属性。这样不会重绘页面。页面静止时不跑任何逐帧脚本。
• 优先用 CSS：
  • 区块进入视野时浮起：滚动驱动动画 animation-timeline: view()，不支持的浏览器直接显示；
  • 换页、切换看法：View Transitions；
  • SVG 描线：pathLength="1" 加 stroke-dasharray: 1。
• 仪式感的动画（例如盖印）每天只播一次，日期记在 localStorage。天天看同一段动画会烦。
• prefers-reduced-motion： 打开时全部关掉，包括视差、吸附时的滑动和流星。开场的逐层亮起直接全部显示。
• 分段吸附不用 CSS scroll-snap。 它的回弹生硬，长区块读到一半会被拽走。用 references/code/ 里自写的吸附：
  • 停在离某个区块顶部 22% 视口高度以内时才吸过去，520ms 缓出；
  • 滚轮、触摸、指针或按键一有动作就放手；
  • 抽屉和弹窗里的区块不算。

具体时长、缓动、深度见 references/motion.md。

竖排中文

• 只给东方主题用。 西方主题（占星、塔罗、西方星座）按西方的习惯横着读：四角是拉丁小标加横排的中文，不竖排。来源项目的西洋星盘页就是这样做的；在塔罗页上竖排中文会显得错位。
• 用 writing-mode: vertical-rl，每一列一个元素，列从右往左排。
• 数字写成汉字。 阿拉伯数字竖排会躺倒：「第三天」「十五时〇二分」「二〇二六年」。
• 长列表： 用 word-break: keep-all，并给列设 max-height，让它只在项与项之间折到下一列。长列表竖排时容易相互重叠，要逐项检查。
• 英文界面一律改横排。 手机上短的标题列可以保留竖排，长列表改横排。

细节和字体见 references/type-and-vertical.md。

字体

• 分工：
  • 一幕里的字：站酷小薇（ZCOOL XiaoWei）。笔画纤细、收笔利落，近于瘦金。它只有一个字重，不要加粗。一幕里的短标签可以用它；要细读的小字（表格、密集的星曜、长说明）它太细，换思源宋体。
  • 标题和导航：思源宋体（Noto Serif SC）。
  • 西文和数字：Cormorant Garamond，加 font-variant-numeric: lining-nums。
  • 书法装饰：马善政（Ma Shan Zheng）。
  • 正文：无衬线。
• 按需加载：
  • 只装用到的字重。
  • 中文字体按 unicode-range 切片，只下载页面上出现的字：用 @fontsource 包，或 Google Fonts。
  • 装饰用的书法字体可以用 Google Fonts 的 text= 参数，只取那几个字。
  • 这些字体不进 PWA 预缓存。
• 繁體： 马善政只有简体字形。繁體界面下，批注整段改用系统楷体，不要半段书法半段回退。
• 易误读的字形： 站酷小薇的「农」像「衣」；Cormorant 的旧式数字「1」像「I」。上线前把页面上的字过一遍。

交互细节

• 父元素 opacity 的陷阱： 给一组工具按钮整体调淡时，opacity 放到按钮本身上，不要放在父元素上。否则从这组按钮弹出的面板也跟着半透明，后面的字透上来。
• 拖动不选中文字： 导航、日历网格、场景画面加 user-select: none。只有内容区和输入框保留可选。
• 滑动的指示（例如导航里当前页前的 ◆）：在 layout effect（或 requestAnimationFrame 之前）量位置，窗口尺寸变化时重算，从别的页切过来时再核对一次。
• 安静控件：
  • 按钮写成字，平时淡色，悬停时下方描出一道两端渐隐的金线；
  • 选中的是金字，金线常在，背后一抹中间实、两侧渐隐的淡金；
  • 主按钮是夹在上下两道金线之间的金字；
  • 输入框只留下方一道细线，使用时变金。
  • 不用胶囊、方框、实底和阴影。

文案

• 标题照人们平常的说法： 「太阳射手 · 上升双子」比「射手之心 雙子之貌」顺。氛围靠画面，不靠拗口的措辞。
• 英文界面单独过一遍。 常见问题：
  • 文字溢出；
  • 中文的大字距没收（.3em 在英文里要改成 .06em）；
  • 单复数（「1 patterns」）；
  • 中英文直接拼接（「丙午Year」）；
  • 术语直译生硬（「borrows opposite」）。

参考文件

文件	什么时候读
references/recipe-tianshu.md	定色板、字体、间距和标志性做法时
references/motion.md	加动效时，要具体时长、缓动、深度
references/type-and-vertical.md	用竖排、书法字体，处理繁體和英文时
references/decoration.md	加装饰时：选什么、出处怎么找、怎么写得够淡
references/checklist.md	交付前
references/code/README.md	要用现成代码时先看：哪个文件管什么、怎么接、哪些要换

references/code/starter.html 是一页能直接打开的骨架，所有层次和动效都接好了。从它开始最快，但它只是骨架：主体图、四角的字、装饰都要换成这个页面自己的。

来源与维护

• 来源： ChroniQ（星曆，RedCarpG/ChroniQ）的「天书」界面风格，2026-11，PR #160–#187。
  • 样式：src/tianshu.css，src/styles.css 的「静」一节（安静控件）。
  • 组件：src/components/TianshuAtmosphere.tsx、useParallax.ts、useSectionSnap.ts、useCasting.ts、CastLine.tsx、smoothUpdate.ts。
  • 一幕：BaziHero.tsx、ZiweiScene.tsx、TodayScene.tsx。
  • 其他：src/lib/hanNumber.ts、src/lib/ditiansui.ts、scripts/pwa.ts（字体不进预缓存）。
  • 文档：docs/development.md 的「命理页：简洁与详细」，docs/features.md 的「界面风格：天书」。
  • 经验：私人 repo 的 lessons/immersive-web-design.md、lessons/frontend-verification.md。
• 源头： RedCarpG/redcarpg-skills 的 skills/immersive-cultural-ui/。~/.claude/skills/ 里的是安装出来的副本，不要直接改。ChroniQ 里的代码是它的来源，两边不会自动同步。
• 怎么改：
  • 在 redcarpg-skills 里改，走 PR；manifest.json 版本加一，node scripts/validate.mjs 通过后发版（tag immersive-cultural-ui-v<版本>），再重装本机副本。
  • 先看 lessons/immersive-web-design.md 有没有新条目可以收进来。
  • 改了 references/code/ 之后，在浏览器里打开 starter.html 检查一遍：桌面、手机宽度、减少动态效果。
  • 某条做法在别的项目上被推翻了，就改掉它，并在更新记录里写明。
• 更新记录：
  • 2026-11-12 · 1.0.0，搬进 redcarpg-skills 公开发布。改掉本机绝对路径，来源项目写成链接；内容不变。
  • 2026-11-10 · ChroniQ · 初版：天书配方；两种看法、背景压暗、装饰、动效、竖排、字体、交互细节的做法；交付前检查清单；可复用代码（氛围层、景深视差、分段吸附、逐层亮起、View Transition、汉字数字）和骨架页；evals/ 里三个测试提示。
  • 2026-11-10 · ChroniQ · 按三个测试提示的结果修订：
    • immersive.js 注释里去掉结束 script 标签的原文，它会让内联后的脚本被截断；清单加一条。
    • 西方主题四角横排，竖排只给东方主题。
    • 站酷小薇的小字规则改成按用途分：一幕里的短标签可以用，要细读的小字不用。原来写的「14px 以下」不是来源项目的做法。
    • 写明主体背后的极淡大字在手机上可以保留。
    • motion.md 加上整页截图时滚动驱动区块空白的坑。
    • .ts-scene 加 box-sizing: border-box。
  • 2026-11-10 · ChroniQ · 加「主体做大」版式（tianshu.css ④b：.ts-hero、.ts-spot、.ts-floor），标明还没在真实项目里验证，实物类页面两种版式各出概念让用户挑。效果图用后母戊鼎做，在 1440×900、1280×720、1100×760、375 宽和打印下看过。清单加两条：主体做大版的尺寸和装饰；页面样式里不写死浅色。