dotsharp

主题 ​

@sharpdotnut/dotsharp 通过 useTheme() 管理主题：模式可以是 system（默认，跟随系统）、light 或 dark。 组合式函数会把解析后的结果写到 <html data-theme="light|dark"> 上，组件样式据此切换设计变量。

一个颜色，一整套配色 ​

整套配色只由一个源色生成：

  1. 源色在 HCT 色空间里读出色相、彩度和明度；
  2. 生成 primary / secondary / neutral / neutral-variant / error 五条 tonal palette（色相固定、彩度按色域收窄、 明度从 0 到 100 排列）；
  3. 每个 --ds-* 令牌从中取一个固定 tone，明暗两套各自一套映射。

因此换源色时色相关系、层级和对比度都保持一致，不需要手工调每个令牌：

ts
import { useTheme } from "@sharpdotnut/dotsharp";

const { sourceColor, setSourceColor } = useTheme();

setSourceColor("#0e9f8f"); // '#rrggbb'、'rrggbb'、'#rgb' 均可

当前源色：#a855f7。选择会持久化到 localStorage，刷新后保留。

样式与变量 ​

安装与样式引入见快速开始。与主题相关的是：style.css 里定义 --ds-* 变量， 再由 Tailwind 的 @theme inline 映射成 bg-ds-primary、text-ds-fg 这类工具类——工具类引用的是变量本身， 所以切换 data-theme 或换源色只改变量值，组件类名保持不变。

样式表内置的是默认源色（#a855f7）生成的明暗两套值，未调用 setSourceColor() 或禁用 JavaScript 时同样正确 显示。调用 setSourceColor() 后，生成结果以行内自定义属性写到 <html> 上（恢复默认源色时移除这些行内值）， 因此默认主题仍可在自己的样式表里覆盖 --ds-*；持久化的自定义源色要等脚本执行后才生效，首帧仍是默认配色。

  • 使用方无需安装 Tailwind，也无需配置 @source 扫描 node_modules。
  • 样式表不含 Tailwind preflight，不会重置应用自身的页面样式。
  • 颜色令牌来自 @material/material-color-utilities 的 HCT / tonal palette 实现（随包安装，无需额外配置）。

层级与涟漪 ​

阴影层级与点按涟漪是两套独立于配色的公共能力：层级用 shadow-ds-* 表达容器之间的距离，涟漪用 v-ripple 提供点按反馈。分别见层级与涟漪。

使用 ​

ts
import { useTheme } from "@sharpdotnut/dotsharp";

const { theme, resolvedTheme, setTheme } = useTheme();

setTheme("dark"); // 'system' | 'light' | 'dark'

当前状态：模式 system，解析结果 light。

API ​

名称类型说明
themeComputedRef<'system' | 'light' | 'dark'>当前模式，默认 system
resolvedThemeComputedRef<'light' | 'dark'>实际生效的主题，system 模式下取系统偏好
sourceColorComputedRef<string>当前源色，形如 #a855f7
setTheme(mode: 'system' | 'light' | 'dark') => void切换模式并立即写入 DOM 与本地存储
setSourceColor(color: string) => void由单个颜色重建全部令牌并立即写入 DOM；非法颜色抛 TypeError

说明 ​

  • 默认模式为 system；系统偏好变化时，只有 system 模式会跟着变。
  • 模式持久化到 localStorage 的 dotsharp-theme 键，源色持久化到 dotsharp-source-color 键。
  • 组合式函数只写 data-theme="light|dark" 与 --ds-* 行内变量，不写 .dark 类，因此不绑定任何特定文档框架。
  • 服务端渲染时不会访问 window，也不会写 DOM；界面首帧主题请自行在页面 head 中提前设置，本站的做法见本站配置。