Apple-Style

Apple HIG 与 Liquid Glass 的四个 Agent 技能，主要用于指导 Agent 做 Apple 风格的网站（产品官网、落地页、文档、博客），其次是 Web 应用，原生 SwiftUI/UIKit/AppKit 作为次要分支。技能提供的是判断依据、结构约定、可复制的参考代码和验证脚本，不是 UI 组件库。Web 参考代码无运行时依赖、无构建步骤；Node、Playwright 和 Python 仅用于维护与回归验证。

English summary · 在线演示 · 演示源码 · 验证记录 · 变更说明

安装

建议先检出并审查代码，再安装：

git clone https://github.com/Tsdsj/Apple-Style.git
cd Apple-Style
./install.sh

git clone https://github.com/Tsdsj/Apple-Style.git
cd Apple-Style
powershell -ExecutionPolicy Bypass -File .\install.ps1

远程一行安装仍支持，执行的是所请求地址返回的脚本；需要固定版本时使用经审查的 tag/commit 脚本地址：

curl -fsSL https://raw.githubusercontent.com/Tsdsj/Apple-Style/main/install.sh | bash

irm https://raw.githubusercontent.com/Tsdsj/Apple-Style/main/install.ps1 | iex

用途	macOS / Linux	PowerShell
链接（默认）	--link	-Link（Windows junction，不可用时明确回退复制）
复制	--copy	-Copy
当前项目	--project	-Project
指定目标	--to "DIR"，可重复	-To "DIR1", "DIR2"
创建所有 Agent 目录	--all	-All
使用本地源	--dir "CHECKOUT"	-Dir "CHECKOUT"
更新远程缓存	--update	-Update
下载分支或标签	--ref REF	-Ref REF
卸载	--uninstall	-Uninstall
帮助 / 静默	--help / --quiet	-Help / -Quiet

默认选择已存在的 ~/.claude、~/.codex、~/.agents 下的 skills 目录；一个都没有时提示并使用 ~/.claude/skills。远程缓存位于 ~/.local/share/apple-style（遵循 XDG_DATA_HOME），Windows 为 %LOCALAPPDATA%\apple-style。

环境：Bash 3.2+、shasum 或 sha256sum；远程需要 Git，或 curl + tar。PowerShell 5.1+/7，Git 可选。无 Git 时使用通用 archive endpoint 支持分支和标签；本地夹具验证了两种引用与失败保留，不代表所有远程引用已在线验证。路径含空格受支持；Shell 路径/引用不支持换行。

--ref 作用于远程下载；在克隆中直接运行默认使用该克隆。--update 在未指定 --dir 时刷新受管理的远程缓存。显式 --dir 始终使用给定源：本地源码更新由你执行 git pull 或切换引用，再重新运行复制安装；链接会直接看到源变化。

安装保护与旧版本迁移

• 每个目标目录的 .apple-style-install/ 保存外置安装记录。复制记录包含来源和内容指纹，链接记录包含确切链接目标。目录名称或 SKILL.md 本身不证明归属。
• 安装、更新和卸载只替换/删除记录匹配且未修改的安装。未知归属、用户修改、缺失/损坏记录和外来链接会保留并提示；出现保留项退出码为 2，其他错误为 1，完整成功为 0。
• 替换先准备暂存副本；移动失败恢复原内容。安装按目标加锁；中断后若留下锁/暂存目录，先检查和备份，不要直接删除。来源与目标重叠（包括解析后的路径别名）会被拒绝。
• 卸载链接仅移除链接，不删除源检出。复制安装的新增/修改文件会阻止整个技能目录被删除。记录用于防误删，不是防御具有同一用户权限的恶意篡改的安全边界。
• 旧安装没有可靠记录时一律不自动认领。 先检查、备份，再由你把旧目录/链接移出目标位置，重新安装到空位置；合并个人修改前保留备份。旧缓存同理，或用 --dir 指向明确的检出。
• 复制模式不提供强制覆盖未知目录的开关。PowerShell 复制源含嵌套链接时拒绝复制，避免不同版本的递归差异；可选择链接模式。

技能与规则

技能	内容
Apple-Style	入口：先判断页面类型（内容网站 / Web 应用 / Mac 窗口 / 原生），再读对应文件；网站模式、参考站、Web 代码
Apple-Style-HIG	离线参考和来源检索
Apple-Style-Liquid-Glass	材质实现和参数调节
Apple-Style-Review	有证据的只读审查与修复建议；网站检查清单与 scripts/check-site/

分别判断目标平台、应用类型、输入方式、可用容器空间。1366px 的 iPad 不是 Mac，700px 的 Mac 窗口也不是 iPhone；普通网页无需模拟原生窗口。768/1024/1280px 是本项目布局默认值。data-platform="macos" 是显式密度选择，.as-window、侧栏、检查器按产品需要选用。

规则强度与证据 区分官方要求、官方建议、项目默认和视觉经验。Review 用“已检查（通过/失败）／未检查／不适用”，不能把读完文字清单当作验证通过。固定的 Skill 启用/关闭比较任务见 evals；已执行的探索性对比见 2026-10-19 完整官网 与 网站优先改造后的重测（样本少，只作方向参考）。

网站使用

内容网站只复制需要的部分，不整包引入：

• 样式：按顺序拼接公共层 skills/Apple-Style/web/css/ 下的 tokens.css、base.css、glass.css、controls.css、preferences.css（压缩后约 20 KB），再加页面用到的 web/patterns/*.css。<body class="as-body">。
• 脚本：默认不需要；窄屏导航用 web/js/site-nav.js（defer，并在 <head> 里用一行内联脚本给 <html> 加 as-js，避免布局偏移），表单用 web/js/site-form.js。折射效果是可选增强。
• 写法与约定：website.md（加载、元数据、多页维护、字体、深色模式、部署、性能预算）和 website-patterns.md（14 个网站模式）。完整示例：参考站。
• 验证：Review 技能的网站检查清单与 check-site（13 项检查，没测的项记为未检查）。

apple-style.css / apple-style.min.css 由 web/css/ 生成（python3 scripts/build-css.py），供 Web 应用整包使用；修改请改 web/css/ 源文件。

Web 应用使用与生命周期

复制 skills/Apple-Style/web/apple-style.css 和 liquid-glass.js，直接引入：

<link rel="stylesheet" href="apple-style.css">
<main id="app">
  <button class="as-glass as-glass-interactive as-button">普通操作</button>
  <button class="as-button as-button-filled">保存</button>
  <div class="as-segmented" role="radiogroup" aria-label="地图样式">
    <button class="as-segment is-selected" role="radio" aria-checked="true">地图</button>
    <button class="as-segment" role="radio" aria-checked="false">公交</button>
  </div>
  <button class="as-toggle" role="switch" aria-checked="false" aria-label="Wi-Fi">
    <span class="as-knob"></span>
  </button>
</main>
<script src="liquid-glass.js"></script>
<script>
  const app = document.querySelector('#app');
  const runtime = LiquidGlass.init(app);
  // 在组件或路由卸载前：runtime.destroy(); 或 LiquidGlass.destroy(app);
</script>

• init(root = document) 包含 root 自身，重复调用不会重复绑定；只自动初始化作用域内新增节点。移除节点后异步清理；移除整个 root 后，重新挂载需再次 init(root)。
• destroy(root = document) 释放该作用域的 Observer、监听、定时器、动画帧、JS 动画和生成的滤镜/控件节点。detach(el) 清理单组件/子树；显式卸载前调用清理最确定。父级即使已初始化，也不会立即重新绑定已销毁子树；再次 init(root) 才恢复该组件。
• attach(el, { scale: 12, rim: 14, chroma: false, lens: true, adapt: true }) 只处理一块玻璃。重复 attach 合并显式参数，并在 resize、外观变化及滤镜重新生成时保留配置；scale: 0 有效。
• refresh() 刷新滤镜与背景采样；morph / materialize 返回 Promise，销毁期间取消不会造成未处理的 rejection。直接操作原有 helper 的 API 仍保留。
• radiogroup 选择值；tablist 切换内容，作者必须提供每个 tab 的 aria-controls 与对应 panel。默认箭头同步焦点和选择；data-activation="manual" 的 tabs 用 Enter/Space 激活。禁用项跳过，click/键盘/拖拽均可用，取消不提交。
• 控件维护 DOM 状态并发出冒泡 change；不要在 click 中再次切换同一状态。React/Vue 请在 mount 后 init、unmount 前 destroy；完整示例。
• 打包工具与框架：把 liquid-glass.mjs 与 liquid-glass.js 放在同一目录，import LiquidGlass, { init } from './liquid-glass.mjs'。服务端渲染、Worker 和无 DOM 的测试环境中导入不会报错（API 为空操作）；同一页面同时用 <script> 和模块时只有一个运行时。
• Tailwind v4 / 级联层：样式表默认不分层，普通 <link> 行为不变；需要让工具类覆盖组件时，用 @import "./apple-style.css" layer(components); 导入到工具类之下的层。
• data-shortcuts：⌘ 在 Apple 平台为 Command、其他平台为 Ctrl；焦点在文本框或富文本中时，全选、复制/剪切/粘贴、撤销/重做、光标移动与删除留给输入框，其他命令（如 ⌘S）照常执行。
• 强制颜色（Windows 对比度主题）下，开关、分段选中、滑块与选中的标签/行改用系统色绘制；dir="rtl" 下滑块与开关按 HIG 镜像。
• 尺寸档：默认是 iOS 档（17px 正文、44px 控件）；跨平台桌面 Web 应用在 <html> 上设 data-density="desktop"（14/20 正文、32px 控件，触屏时仍保持 44px 命中区）；Mac 风格界面用 data-platform="macos"。三者都按产品与输入方式选择，不按宽度推断。
• Web 应用组件：表单字段 .as-form-field + .as-input（文本框、文本区、<select> pop-up 按钮；有指针时用可定制 select 选单，触屏保留系统选择器）、可选择列表 .as-listbox / .as-option（运行时提供单选键盘模型：一个 Tab 停靠点、方向键、Home/End、按字母跳转；选中状态就是 aria-selected）、<dialog class="as-dialog"> 不透明模态（showModal() 负责焦点、Esc 和背景不可操作）、LiquidGlass.toast('已保存')（role="status" 播报，有模态时放进对话框内）、空状态 .as-empty、骨架屏 .as-skeleton、状态标签 .as-pill。全部跟随尺寸档，并处理强制颜色、减弱动态效果与增强对比度。用法见 Web 应用速查，表单见 Web 实现速查。

系统蓝色样本 --as-blue 保留；普通白字操作面使用 --as-action-bg / --as-action-fg，默认浅深色均满足 4.5:1。自定义 tint、透明度、图片背景和辅助文字仍应检查实际组合。增强对比度、降低透明度、减弱动态效果是额外支持，不是默认可读性的替代。

演示与兼容范围

python3 -m http.server 8765 --bind 127.0.0.1
# http://127.0.0.1:8765/          演示首页：先是参考网站，再是组件工作台
# http://127.0.0.1:8765/demo/index.html   组件工作台

演示首页的第一个入口是 参考网站（虚构产品的官网与博客，用到全部网站模式；源码是根相对路径，单独检查时以它的目录为站点根启动服务）。组件工作台保留移动组件、同心圆角和无障碍模拟，并链接 桌面窗口 与 最小组件示例。示例共用本体 CSS/JS。检查清单只记录人工检查状态，不自动证明质量。

本次实际浏览器验证为 Chromium，详见 验证记录。SVG backdrop lensing 使用 Chromium 启发式检测，不等于逐浏览器的渲染能力证明；其他引擎走 CSS blur/highlight 路径。Safari、Firefox、VoiceOver 目前未验证。现代 CSS（如 light-dark()、color-mix()）、Observer 与 Pointer Events 是使用前提，不承诺旧浏览器完整兼容。

这是 Web 近似实现，不是 Apple 原生渲染器。没有性能提升、低端机帧率或长期稳定性测试结论。减少滤镜可用 data-perf="lite"；自动色散预算为 8，显式 chroma: true 可覆盖。.as-window 的窄窗口堆叠保留平台属性和内容。

可重复验证

npm ci
npx playwright install chromium
npm test
python3 -m unittest discover -s tests -p 'test_*.py' -v
git diff --check

PowerShell 用例自动发现 pwsh/powershell；也可通过 APPLE_STYLE_PWSH=/absolute/path/pwsh 指定。缺少运行时会明确 skip。CI 覆盖 Linux/macOS Chromium，以及 Windows PowerShell 5.1/7 安装器。实际运行链接与结果见 发布验证记录。

覆盖安装归属/修改/更新/卸载、分支/标签下载夹具，浏览器键盘/click/拖拽/取消/焦点/ARIA，资源计数/卸载/重挂载/配置，浅深色对比度、偏好与三个示例的 320/390/768/1024/1440/2000px 布局。保存示例截图，另用 ARIA snapshot、尺寸/溢出断言和重复 init 的控件像素一致性作可重复检查；不宣称已有跨平台全页面像素黄金基线。

参考库维护

INDEX 由脚本生成；sources.json 记录 210 个来源的规范 URL、抓取入口、抓取时间与 SHA-256；其中 208 个于 2026-10-17 实际重新抓取，2 个 App Store 营销页（marketing/）于 2026-10-19 新增抓取。

skills/Apple-Style/scripts/update-reference.sh --index-only
skills/Apple-Style/scripts/update-reference.sh --only hig/layout.md --report /tmp/reference-check.json
# 全量刷新（可能耗时；覆盖所有分类，发现新增 HIG 链接）：
skills/Apple-Style/scripts/update-reference.sh --report /tmp/reference-update.json

仅需 Python 3 标准库。下载/解析先在暂存中完成，任一失败则整批不写入有效参考；提交失败恢复旧目录。报告区分新增、修改、未变、下线和失败；Apple 移动页面时失败项给出 moved_to，可更新该条目地址，或在新页面已被发现时用 --retire PATH 在同一事务中移除旧页。recheck_reasons 按“速查表 → 其引用的变化页面”列出待复核内容。更新参考不等于自动证明速查表仍正确。网络故障、HTTP 错误、无效 JSON、解析失败及回滚先由本地夹具覆盖，在线验证限制为少量来源。

发布准备与许可

CHANGELOG、发布检查项、Pages 部署工作流 已启用为手动触发，模板仍保留作参考。scripts/prepare-demo.sh NEW_DIRECTORY 只打包演示首页、组件工作台、参考网站和 Web 资产，排除 Apple 离线参考和本机文件；参考网站的根相对路径在打包副本中由 scripts/relativize-site.py 改写为相对路径，以便部署在 Pages 子路径下。本次按作者授权发布 v0.1.0，演示站通过 Actions 部署。后续部署使用手动触发；正式许可证保持原有声明。

Apple 参考文本版权归 Apple Inc.，保留来源记录；未捆绑 SF 字体与 SF Symbols。原项目声明“本仓库自身的代码（CSS / JS / 脚本 / 速查表写作）可自由使用”保持不变。当前没有标准 LICENSE，本次不新增授权范围。正式许可证由作者选择，见 许可证决策。

English

Four Apple design skills whose main use is guiding agents to build Apple-style websites (product, landing, docs and blog sites), then web apps, with native SwiftUI/UIKit/AppKit as a secondary branch. The skills supply decisions, contracts, small copyable reference code and verification scripts, not a component library: a content site copies the ~20 KB core layers and the website patterns it uses (cheatsheets/website.md, website-patterns.md, reference site in web/examples/site/), and the Review skill's scripts/check-site/ checks the result. Dependency-free, build-free CSS/JS. Install from a reviewed checkout with ./install.sh or install.ps1. Install receipts protect unowned or modified directories; legacy installations are never silently adopted. Exit 2 means content was preserved and needs review. Copy updates and uninstall require a matching fingerprint; links are only unlinked, never recursively removed through their target.

Choose platform, app type, input methods and container size independently. A wide iPad is not a Mac, and a desktop web page does not require a native window. Rules distinguish official constraints, recommendations, project defaults and visual heuristics.

Call LiquidGlass.init(root) after mount and destroy(root) before unmount. Bundlers import liquid-glass.mjs; importing is safe during server rendering. To let Tailwind v4 utilities adjust components, import the stylesheet into a layer below utilities. Initialization is idempotent and scoped; single surfaces support attach(el, options) / detach(el). Options survive resize and appearance regeneration. Radio groups select values; tabs require linked panels. Keyboard, click and drag are supported without duplicate activation; cancellation does not commit. Default white-text actions use accessible semantic colors while retaining Apple system swatches.

Run npm ci, npx playwright install chromium, npm test, and python3 -m unittest discover -s tests -p 'test_*.py' -v. See validation for executed checks and explicit gaps. Windows-native junctions are covered by the Windows CI jobs, separately from macOS copy fallback tests. Safari, Firefox and VoiceOver remain unverified; the skill on/off comparisons in evals/runs/ are exploratory (small samples). See the linked release verification record for actual CI and deployment runs.

Reference refreshes use a source manifest, hashes, timestamps, local fixtures and a transactional commit; every source was re-fetched on 2026-10-17. Moved pages are reported with moved_to, --retire removes a replaced page in the same transaction, and the report maps each cheatsheet to the changed pages it cites. Apple reference content is not relicensed. The existing free-use statement for original project code is retained; choosing a standard LICENSE remains the author's decision.