主题

主题决定了应用的外观。它设置颜色、字体、控件形状、页面质感以及终端颜色。它是一个很小的 JSON 文件。Collie 内置了四个主题。你可以从文件导入更多主题，也可以导出任何主题进行复制和编辑。主题是单台设备的设置，保存在该设备的浏览器中，不会更改 bridge 上的任何内容。

每个主题都有两部分。浅色部分是浅色模式的颜色集合。深色部分是深色模式的集合。主题中的颜色都有一个名称，例如 background 或 primary，该名称即为一个 token。

四种主题

Collie 内置了四种主题，其中三种使用了主题文件的所有部分。每张图片都展示了 Dashboard，左侧为浅色，右侧为深色。

• —
  Collie 是应用一直以来的外观。它是默认主题，选择它会取消所有自定义主题设置。它没有指定形状、外观和调色板，因此它的每个字段都是对应列表中的默认值。

  !Dashboard 上的 Collie 主题，浅色和深色。

• —
  Nightwatch 适用于夜间在床上值班的手机。深色部分是纯黑配微暗琥珀色，浅色部分是温暖的黄昏纸张色。它是平整的直角风格，具有粗线条、粗体文本，以及页头和工具栏后面的暗琥珀色条带。终端在纯黑背景上呈现琥珀色调色板。

  !Dashboard 上的 Nightwatch 主题，浅色和深色。

• —
  Daylight 适用于强光直射和低视力场景。正文文本对比度达到 7:1 或更高，边框更强，阻止状态为橙色而完成状态为蓝色，因此无需红绿即可区分两者。它采用圆角设计，行以悬浮卡片形式呈现，页面朝底部渐变，浅色模式下更深，深色模式下更浅，各步骤间距更宽松。终端呈现鲜艳的高对比度调色板。

  !Dashboard 上的 Daylight 主题，浅色和深色。

• —
  Harbour 适用于常驻终端的用户。以冷蓝灰色搭配青色点缀，类似 Nord 和 Solarized 风格，代码颜色类似编辑器。它采用柔和圆角，页面底部带有细微纹理，并配有纤细图标。终端呈现基于 Solarized 的调色板。

  !Dashboard 上的 Harbour 主题，浅色和深色。

表格列出了每个主题使用的所有关键字。每个列表的第一个词是当前外观：sharp、default、flat、page、rules 和 caps。这些词在 形状、外观 和 终端调色板 下有详细说明。

选择主题

在 Settings → Appearance 中选择一个主题，整个应用会立即改变。

主题 卡片是第一张卡片。点击名称，应用会立即切换。每个名称都带有对应主题的圆角和字重样式，点击前即可预览外观。该卡片位于包含“系统”、“浅色”和“深色”选项的 外观 卡片上方。这是两组独立的设置：主题决定颜色、轮廓和外观风格，而“系统”、“浅色”或“深色”则决定显示其中的浅色还是深色配色。

指定了字体的主题会在你选择该主题时，将其写入 字体 卡片一次。此后以“字体”卡片的设置为准：在此处选择其他字体后将保持生效，直到你再次选择主题。主题的展示字体不属于该卡片：标题会始终保留展示字体。字体 拥有独立的设置区域。

这些主题使用的字体仅包含拉丁字母及拉丁字母扩展-A，因此在这些主题下，西里尔字母和 CJK 文本会回退到系统字体（Collie 主题保留其配套的西里尔字体）。

导入主题

在 主题 卡片中导入一个 .json 文件，查看预览，然后点击 应用。

1. 01
   在 主题 卡片中，点击 导入 并选择一个 .json 文件。
2. 02
   Collie 会读取该文件并显示预览。预览包含名称、作者、以色块呈现的两种模式、每种模式对应的小页面、示例上的形状、终端颜色以及对比度报告。
3. 03
   点击 应用 保留并切换到该主题，或点击 取消 放弃更改。

警告 是一行对比度报告内容，例如 "dark: status-blocked chip on card measures 3.9. The floor is 4.5"。这表示主题在某处的辨识度较低。应用 仍可点击，由你自行决定。

出现 拒绝 表示文件违反了规则。Collie 会列出原因，不保存任何内容，也不应用任何更改。列表最多显示 25 条原因，超出部分显示为一行 "and N more"。出现以下任一情况时，文件会被拒绝：

• —
  不是 JSON 对象，或大小超过 64 KiB。
• —
  未设置任何颜色。
• —
  包含未知键、Collie 无法读取的版本、非颜色值或 Collie 未内置的字体。
• —
  形状词不在预设列表中，或在需要填入词的位置填入了数字。
• —
  声明为版本 1，但包含 surface 块、fonts.display 字体或 ansi 块。
• —
  其 ansi 块缺少键、包含带 alpha 通道的颜色，或未通过 终端调色板 下的门禁检查。
• —
  包含无效的 id、name 或 author，或者 id 属于内置主题。
• —
  导入后将成为第九个导入的主题。Collie 会在点击 导入 时（选择文件前）拒绝，并在 应用 时再次拒绝。

Collie 会在 应用 时多检查一项。如果文件的 id 已存在于设备上，会被拒绝并提示 "already imported"。请先移除旧主题，或更改 id。

主题仅改变应用的外观，不产生其他影响。它无法执行代码、加载文件或访问服务器。

一台设备最多可保存八个导入的主题。移除 仅在当前启用了导入的主题时生效。它会删除该主题，应用随即恢复为默认的 Collie 外观。字体保持不变。

对比度报告

该报告会测量主题在两种模式下的颜色，未通过的行仅作为警告，你可以选择忽略并接受。

终端调色板是唯一的例外，未通过其门禁检查会导致文件被拒绝。下表列出了其他部分的对比度下限。下限为对比度比值，数值越大越容易辨识。

• —
  保留原色时，破坏性操作文本受限于 Collie 测得的数值。 Collie 页面自带的浅红色测得 4.38。同时保留该配对中两种颜色的主题受限于该值，且绝不低于 3。更改其中任一颜色的主题则受限于 4.5。
• —
  渐变或纹理在其远端进行测量。 该报告测量页面文本、标签、destructive 文本、status-blocked 文本，并在渐变底部或纹理线条颜色上再次测量 rule，采用相同的下限。
• —
  色带也会被测量。 在 chrome: band 下，foreground、muted-foreground 和 status-blocked 在色带颜色 secondary 上的测量值为 4.5。

导出并分享主题

选择主题，然后点击 导出。Collie 会保存 <id>.collie-theme.json。无法保存文件的浏览器会在动作表中显示文本，并附带复制按钮。要基于内置主题创建自定义主题：

1. 01
   导出 Nightwatch、Daylight、Harbour 或 Collie。
2. 02
   更改 id 和 name。内置主题的 id 会被拒绝。
3. 03
   编辑颜色和字词，并删除任何不想更改的 token。
4. 04
   将文件发送到手机，然后导入。

导出操作会写入容纳该主题内容的最低 version。

编写主题

文件仅包含这些键，不能包含其他键。任何位置出现未知键都会连同其名称一起被拒绝。这是一个完整的版本 2 文件：它是颜色列表更短且包含完整调色板的 Daylight。

{
  "version": 2,
  "id": "my-day",
  "name": "My day",
  "author": "Sam",
  "light": { "background": "oklch(0.985 0 0)", "primary": "oklch(0.18 0 0)" },
  "dark": { "background": "oklch(0.12 0 0)", "status-blocked": "oklch(0.81 0.13 60)" },
  "fonts": { "ui": "geist", "display": "atkinson" },
  "surface": {
    "radius": "round", "shadow": "lifted", "density": "roomy",
    "weight": "default", "border": "default", "ground": "gradient",
    "chrome": "page", "rows": "cards", "icons": "default", "labels": "sentence"
  },
  "ansi": {
    "0": "#3a332c", "1": "#ff5f56", "2": "#5fd068", "3": "#ffd84a",
    "4": "#5aa9ff", "5": "#e07ce8", "6": "#3fd6d0", "7": "#f2efe9",
    "8": "#8a827a", "9": "#ff8a80", "10": "#7ad683", "11": "#ffeb8a",
    "12": "#8cc4ff", "13": "#f0a6f5", "14": "#6ad8d2", "15": "#ffffff",
    "ink": "#f5f0e8", "ground": "#1a1612"
  }
}

• —
  version 为 1 或 2。参见 版本。任何其他数字都会被拒绝。
• —
  id 为 1 到 32 个字符：小写字母、数字和连字符，以字母或数字开头。
• —
  name 为 1 到 40 个字符，author 最多 60 个字符。两者都不能包含控制字符。
• —
  light 和 dark 是 token 对象。可以提供其中一半或全部提供。省略的一半以及省略的任何 token 会采用 Collie 主题的值。如果只有一半设置了某个 token，另一半会获取 Collie 主题中该 token 的值。
• —
  fonts.ui 为可选项：system、grotesk、aldrich、plex、geist 或 atkinson。
• —
  fonts.display 为可选项，接受相同的六个名称。参见 外观。
• —
  surface 为可选项。其中的每个键也都是可选项，省略的键会采用其列表的默认字词。参见 形状 和 外观。
• —
  ansi 是可选的，它要么包含全部 18 个键，要么完全不包含。参见 终端调色板。
• —
  允许使用 $schema，该项会被忽略。文件大小不能超过 64 KiB。

值为 #rrggbb、#rrggbbaa，或使用纯数字的 oklch(L C H) 和 oklch(L C H / A)。L 取值范围为 0 到 1，C 为 0 到 0.5，H 为 0 到 360，A 为 0 到 1 或百分比。不支持其他格式：不能使用具名颜色，不能使用 rgb()、var() 或 url()。ansi 中的颜色不含 alpha。

版本

文件会声明自身所属的版本，Collie 会写入能容纳该文件内容的最早版本。

• —
  包含 surface 块、fonts.display 字形或 ansi 块的文件必须声明版本为 2。声明版本为 1 却包含这些内容的文件会被拒绝。
• —
  没有这些块的文件声明任一版本均可。Collie 支持读取这两个版本，导出仅包含颜色和 fonts.ui 的主题时版本声明为 1。
• —
  版本 2 的文件需要 Collie 1.22.0 或更高版本。
• —
  版本 1 的文件意味着 surface 的每个 token 均使用各列表的默认值。

43 个 token

每一半均可使用这些项，共分四组。

形状

surface 块中的五个词用于设置控件形状，每个键从固定列表中选取一个词。

词是一个名称，不能是数字。自定义圆角或间距级数可能会破坏最小点击区域，或把方形控件变成体育场形。每个列表的首个词即为应用在版本 2 之前的外观。

• —
  圆形保持为圆形。 宽高相等的形状（如状态圆点）不属于圆角级数，因此 radius 不会改变它。
• —
  标记行沿用圆角设置。 在 sharp 下，选中或被阻止的行左边缘带有一条 2px 的指示条。在 soft 和 round 下，四周带有 2px 的外框和柔和阴影，因为左侧指示条不与圆角搭配。
• —
  roomy 绝不低于默认值。 点击目标保持在 44px 或以上。页眉中的图标和狗保持原尺寸，仅扩大周围间距。

外观

surface 块中的另外五个键和一个字体键用于设置页面外观。它们遵循相同的封闭词规则。

fonts.display 为页面标题和页眉中的名称指定六种字体之一。未指定字体的基本主题会沿用原有字体绘制标题。只有在主题明确指定时，Collie 才会拉取显示字体。

• —
  底色不绘制任何图像文件。 渐变与噪点由主题自身的颜色生成。应用的面板不透明，因此底色会从面板间的缝隙中显露出来。
• —
  页面文字基于底色进行对比度测量。 对比度报告 会检查渐变末端以及噪点的线条颜色，确保底色不会遮挡文字。
• —
  在渐变背景下，各操作栏保持单色页面颜色。 在平板设备上，页眉和各操作栏可能会呈现为页面顶部的一个区块，而下方颜色变深。文字无法改变这种显示效果。
• —
  状态栏跟随色带颜色。 在 chrome: band 下，浏览器的状态栏采用色带颜色；在 page 下，则采用页面颜色。
• —
  rows 作用于每一个列表分组。 这包含 Settings 索引内部的列表。

终端调色板

ansi 块为终端镜像提供专属的 16 色、前景色与底色。

该块必须包含全部 18 个键或完全不包含："0" 到 "15" 对应 16 个色位，ink 对应文字，ground 对应背景。仅配置半套调色板会导致单个窗格中混用两套调色板。每个颜色值须为 #rrggbb 或 oklch()，不带 alpha 通道。

注意。 请针对深色模式编写调色板。镜像始终绘制在深色底色上，在浅色模式下，Collie 会将整个镜像反转而不是重新着色（原因）。浅色模式显示的是颜色的镜像映射。选取一个能反转为你主题中浅色 background 的 ground，镜像即可在两种模式下与页面保持一致。

未通过校验的颜色会被拒绝并标明其键名。这不是警告，因为终端是阅读最频繁的区域。

高亮集合是一个固定列表：Muse 镜像将这四个插槽视作高亮前景。其他 12 个插槽保持在该界限之下，因此该列表在你的调色板下始终保持有效。

主题无法更改的内容

主题可以更改颜色值、字体、控件形状、页面质感以及终端的调色板。除此以外不能更改任何内容。

• —
  布局与点击区域尺寸。 手机端布局很容易损坏。圆角、阴影、密度、字重和边框都采用闭合词汇，绝非自由值，且 roomy 绝不能低于默认值。
• —
  字号与动态效果。 主题可以选择字体和字重，但不能选择字号，也不能更改任何动画效果。
• —
  Collie 标志狗。 顶部栏、主屏幕图标和启动屏在每个主题下均保持一致。
• —
  状态的含义。 其图标和文本保持原样，因此你选择的红色或橙色绝不会将 blocked 显示得像 done 一样。
• —
  自由值、原生 CSS、远程字体。 每个键都取自列表中的颜色或预设词，字体则来自 Collie 自带的列表。

首次渲染与状态栏

你选择的主题会从第一帧开始显示在屏幕上。应用加载前会有一个脚本读取它，因此自带的主题不会先闪烁默认样式。导入的主题也是如此，但有一种例外情况。如果某个 token 仅在其中一半中设置，该 token 会在第一帧显示默认颜色。应用加载时会重新检查该主题。未通过检查的已存储主题会被丢弃，设备将显示 Collie，并在浏览器控制台中说明原因。状态栏跟随主题的两种页面颜色，或者在主题指定 chrome: band 时跟随其两种色带颜色。

问题排查

以下是用户最常遇到的问题，以及各自的原因和解决方法。

• —
  主题在某个 token 上显示默认颜色。 文件遗漏了该 token，或者遗漏了其中一半。缺失的 token 取自 Collie 主题。请将该 token 添加到所需的一半中。
• —
  字形没有变化。 主题仅在你选择它时写入一次字形。如果你之后在 字体 中选择了其他字形，则以该选择为准。请重新选择字形，或重新选择该主题。
• —
  形状词没有生效。 该词可能是其列表中的默认词，或者该键可能缺失。省略的键会采用默认词。请根据 形状 和 外观 下的表格检查拼写。
• —
  文件被拒绝并指出 ansi。 调色板在暗色空间中包含全部 18 个键，且每种颜色都必须通过检查门槛。拒绝信息会指出该键以及测量得到的数值。
• —
  清除浏览器数据后主题会丢失。 导入的主题仅保存在当前浏览器中。请重新导入该文件。