tinte

Tinte - 设计系统基础设施

从单一事实来源生成、编译、安装和预览设计系统。

Tinte 通过 13 个语义化 OKLCH 颜色令牌维护主题图谱，并将其编译为 shadcn/ui 预设、VS Code 主题、终端配置及其他 19 种以上格式。

预设 API（兼容 shadcn v4）

所有公开的 Tinte 主题都可以作为 shadcn registry:base 项目安装。

安装主题

npx shadcn@latest add https://tinte.dev/api/preset/{slug}

安装主题字体

npx shadcn@latest add https://tinte.dev/api/preset/{slug}/font?variable=sans
npx shadcn@latest add https://tinte.dev/api/preset/{slug}/font?variable=mono

获取完整预设包（基础 + 字体 + 安装命令）

GET https://tinte.dev/api/preset/{slug}?type=pack

响应：

{
  "base": { "$schema": "...", "name": "...", "type": "registry:base", "cssVars": { "light": {...}, "dark": {...} } },
  "fonts": [{ "$schema": "...", "name": "font-inter", "type": "registry:font", "font": {...} }],
  "slug": "theme-slug",
  "install": {
    "base": "npx shadcn@latest add https://tinte.dev/api/preset/{slug}",
    "fonts": ["npx shadcn@latest add https://tinte.dev/r/font/inter?variable=sans"]
  }
}

浏览主题

GET https://tinte.dev/api/themes/public?search={query}&limit=20&page=1

可选筛选条件：?vendor=tinte|tweakcn|rayso

响应包含带有 slug、name、concept 和颜色令牌的 themes[]。

获取主题详情

GET https://tinte.dev/api/themes/slug/{slug}

返回完整主题数据，包括浅色／深色颜色块和覆盖项。

注册表路由（兼容 shadcn）

这些路由提供原始的 registry:base 和 registry:font 项目：

GET https://tinte.dev/r/{slug}                    # registry:base or registry:theme
GET https://tinte.dev/r/{slug}?type=registry:base  # explicit base type
GET https://tinte.dev/r/font/{family}?variable=sans # registry:font

从图像提取主题

上传屏幕截图或设计图像，以提取颜色主题：

curl -s -X POST https://ray.tinte.dev/api/v1/extract-theme \
  -F "[email protected]" | jq

高保真 AI 模式：

curl -s -X POST "https://ray.tinte.dev/api/v1/extract-theme?mode=ai&model=anthropic/claude-haiku-4.5" \
  -F "[email protected]" | jq

响应：

{
  "dark": { "bg": "#0a0a12", "bg_2": "#0f0f18", "ui": "...", "tx": "...", "pr": "...", "sc": "...", "ac_1": "...", "ac_2": "...", "ac_3": "..." },
  "light": { "bg": "#fafafa", "bg_2": "#f0f0f0", ... },
  "name": "Extracted Theme Name",
  "gradient": "linear-gradient(...)",
  "swatches": { "vibrant": { "hex": "#e84393" }, ... }
}

屏幕截图预览

生成应用任意 Tinte 主题的代码屏幕截图：

curl -s -X POST https://ray.tinte.dev/api/v1/screenshot \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "const x = 42;",
    "language": "typescript",
    "theme": "{slug}",
    "title": "preview.ts"
  }' -o preview.png

Agent 工作流

1. 浏览并安装设计系统

1. GET https://tinte.dev/api/themes/public?search=minimal → pick theme
2. GET https://tinte.dev/api/preset/{slug}?type=pack → get install commands
3. npx shadcn@latest add https://tinte.dev/api/preset/{slug} → install base
4. npx shadcn@latest add https://tinte.dev/api/preset/{slug}/font?variable=sans → install fonts
5. npx shadcn info --json → verify

2. 从屏幕截图提取设计系统

1. POST ray.tinte.dev/api/v1/extract-theme -F [email protected] → get TinteBlock
2. Use extracted colors to search for matching themes or create new one
3. Install via preset API

3. 切换设计系统

1. npx shadcn info --json → read current project config
2. GET https://tinte.dev/api/themes/public?search=dark+minimal → browse alternatives
3. npx shadcn@latest add https://tinte.dev/api/preset/{new-slug} → overwrite with new theme

4. 预览结果

1. POST ray.tinte.dev/api/v1/screenshot with theme slug → get PNG
2. Open screenshot to verify visual result

颜色模型

Tinte 为每种模式（浅色／深色）使用 13 个语义化 OKLCH 令牌：

令牌	作用
bg	背景
bg_2	高层级表面
ui	边框、分隔线
ui_2	细微边框
ui_3	悬停状态
tx	主要文本
tx_2	次要文本
tx_3	弱化文本
pr	主要强调色
sc	次要强调色
ac_1	强调色 1
ac_2	强调色 2
ac_3	强调色 3

这些令牌会编译为 30 个以上的 shadcn CSS 变量（background、foreground、card、primary、secondary、muted、accent、destructive、chart-1..5、sidebar-* 等），并采用 OKLCH 色彩空间格式。

设计系统编译器（Agent 插件）

tinte 会将项目身份编译为可安装的 Agent 插件（agent-plugins.org 1.0.0）， 让编码 Agent 生成符合品牌风格的 UI，而不是默认的粗劣界面。

tinte build --plugin --config tinte.config.json --out ./acme-plugin
# emits: plugin.json + skills/<name>-design/SKILL.md (composition law + identity)
#        + references/tokens.css (OKLCH token API from the theme graph)

tinte lint src/            # scan for hex/rgb/hsl literals and Tailwind palette classes
tinte lint --json          # machine-readable; exit 1 on violations (CI gate)

从参考网站提取身份

CLI 从不猜测颜色。Agent 负责观察，CLI 负责计算：

tinte from --emit-script > extract.js
agent-browser open https://example.com && agent-browser wait --load networkidle
agent-browser eval "$(cat extract.js)" > candidates.json
# The agent (vision) reviews a screenshot to assign semantic roles if needed.
tinte from --normalize candidates.json --name example --out draft-identity.json
# Draft only: fill voiceWords/dosDonts by hand, then validate strictly via tinte build.

--normalize 会检测 primaryStyle: "inverted"（CTA 采用前景色／背景色组合而非色相的网站），并规范化药丸形圆角。需要用于应用状态的令牌（destructive、ring、input）会作为警告报告，不会凭空编造。