主题与图标

主题是图级别、由渲染器管理的视觉系统符号引用。图标是在该主题内解析的逻辑名称。两者都不会改变图的语义。

选择主题

在图中最多添加一条 theme 语句：

stack 1.0

diagram "Dark architecture" {
  theme dark

  node api "API"
}

省略时使用 default。Draft Stack 1.0 要求核心 catalog 提供：

Theme	用途
default	适合通用架构图的均衡蓝灰表面
light	适合浅色文档的暖中性色表面
dark	适合深色画布的高对比冷色表面

源文件选择标识符，而不是 catalog package 版本。渲染 metadata 记录 catalog 版本和内容 revision，以标识实际使用的视觉数据。

生成图主题与 Playground 的明暗界面相互独立。主题可改变 palette、字体 metrics、surface、icon、connector 和 background，但不能隐藏或改变节点、分组、连线、标签、kind、方向或布局约束。

回退行为

三个核心主题是渲染器必需资源。当前 catalog 中不存在的非核心主题会发出 STK6001，并使用 default 渲染。引擎不会因为源文件出现主题标识符就从网络下载主题。

主题标识符使用普通 Stack 标识符语法。一旦注册，即使废弃后也不能重新分配给另一个主题。

Kind 回退图标

每个主题为所有节点 kind 提供回退。省略 icon 时渲染器使用它。

Node kind	当前逻辑回退图标
actor	kind-actor
client	kind-client
service	kind-service
function	kind-function
worker	kind-worker
database	kind-database
cache	kind-cache
queue	kind-queue
storage	kind-storage
external	kind-external

当前开放核心 catalog 在 default、light 和 dark 中包含这十个回退标识符，尚不包含 postgresql、aws 或 github 等厂商图标。多数文档应选择语义 kind 并省略 icon。

显式图标

显式图标使用带引号的逻辑标识符：

stack 1.0

diagram "Explicit icon" {
  node gateway "Public API" {
    kind service
    icon "api"
  }
}

图标只装饰节点，不改变 service kind、identity、label 或无障碍说明。同一标识符在不同主题中表示同一个逻辑对象，但颜色与图形可以适配主题。

第一方图标目录

免费核心 catalog 在 default、light 和 dark 中提供以下与厂商无关的显式图标：

ID	Stable subject	主要用途
api	Application programming interface	公共或内部 API
web	Web application	面向浏览器的 Web 体验
mobile	Mobile application	iOS 或 Android 客户端
desktop	Desktop application	原生桌面客户端
server	Server host	虚拟机或物理主机
container	Application container	容器化工作负载
cluster	Compute cluster	编排后的计算集群
cloud	Cloud environment	与厂商无关的云边界
scheduler	Scheduled execution	Cron 任务或定时工作
webhook	Webhook endpoint	入站或出站回调
identity	Identity and access	身份验证或授权
observability	Observability system	指标、日志或链路追踪

切换下方预览的浅色与深色模式即可比较真实输出。每张图片都由已发布的 @stack-sh/engine@0.3.0 在本地渲染；文档没有复制 Theme SVG 资源。选择语法行即可复制。

正在本地渲染图标预览…

apiApplication programming interface

webWeb application

mobileMobile application

desktopDesktop application

serverServer host

containerApplication container

clusterCompute cluster

cloudCloud environment

schedulerScheduled execution

webhookWebhook endpoint

identityIdentity and access

observabilityObservability system

语义 kind 与显式图标应独立选择。例如，icon "web" 可以装饰 client 或 service 节点，但不会改变该节点的含义。

缺失图标与厂商图标

核心 catalog 目前不包含 postgresql、aws、github 或 docker 等厂商或项目标志。如果有效主题没有编写的图标标识符，引擎会继续使用节点 kind 的回退图标渲染，并发出 STK5001。

请优先选择上表中与厂商无关的图标；如果 kind 回退已能表达角色，也可以省略 icon。厂商标志只有在逐项完成资源 license、再分发和商标审查后，才能进入独立 catalog。

Catalog 与资源安全

公共 stack-sh/theme catalog 拥有 palette、确定性字体 metrics、node-kind visual、connector、icon metadata、SVG bytes、来源和再分发许可。Catalog 资源随渲染器打包，编写的标识符绝不会被当成文件路径或 URL。

SVG 验证会拒绝脚本、事件处理器、嵌套 SVG、不安全引用、data/network URL、style 属性和 allowlist 外元素或属性。图标不能成为表达意义的唯一方式，标签和非颜色区分也必须保留。