Loongship UI

Appearance

Light / Dark 主题与设计变量 ​

Loongship UI 使用原生 CSS 自定义属性，提供 Light 和 Dark 两套主题。

全局主题入口 ​

应用入口导入初始化生成的文件：

ts
import '@/styles/loongship.css'
import { setTheme, type Theme } from '@/styles/theme'

const theme: Theme = 'dark'
setTheme(theme)

也可以由应用在首屏 HTML 直接设置根节点属性：

html
<html data-theme="dark"></html>

回退与浮层同步

缺失主题时默认使用 Light。非法运行时值回退到 Light，并在开发环境输出警告。Portal/Teleport 浮层挂载到 body 后仍继承 html[data-theme] 上的 Token，因此已打开的浮层会随根主题同步更新。

SSR 需提前设置主题

系统主题检测、偏好保存和切换 UI 由应用负责。SSR 应在首屏渲染前写入 data-theme，避免闪烁。

Token 分层 ​

不随主题变化的基础 Token 定义在 :root，包括：

  • --ls-space-*：间距
  • --ls-radius-*：圆角
  • --ls-font-*、--ls-line-height-*：排版
  • --ls-control-*、--ls-icon-size：组件尺寸
  • --ls-button-*、--ls-input-*、--ls-card-*、--ls-table-*：组件级尺寸
  • --ls-duration-*、--ls-easing-standard：动效
  • --ls-z-index-*：堆叠层级

Light 和 Dark 分别定义外观语义 Token：

Token用途
--ls-color-background/canvas应用画布
--ls-color-surface/surface-secondary内容表面及次级表面
--ls-color-elevated/surface-elevated/surface-overlay弹窗、菜单、浮层表面
--ls-color-text-primary/secondary/tertiary/disabled主要、次要、辅助、禁用文本
--ls-color-border-subtle/control/strong、divider表面、控件、强调边界与分隔线
--ls-color-fill/fill-hover/fill-active/fill-selected中性填充与交互状态
--ls-color-accent/accent-hover/accent-active/accent-foreground强调操作及其前景色
--ls-color-success/warning/error/info状态色及对应 hover/foreground
--ls-color-focus/focus-ring/focus-error焦点环
--ls-color-overlay、--ls-shadow-*遮罩与阴影

组件样式约束

组件样式只使用这些语义 Token，不根据主题名称分支，也不在组件内提供颜色兜底。

视觉尺度 ​

  • 间距：0 / 2 / 4 / 6 / 8 / 12 / 16 / 20 / 24 / 32 / 40 / 48 / 64px。
  • 控件高度：Small 28px、Default 36px、Large/Touch 44px。
  • 圆角：细节 4px、紧凑元素 8px、默认控件 10px、大型控件 12px、Card/Popover 16px、Modal 20px。
  • 排版：系统字体栈，业务正文 14px，辅助信息 12–13px，标题 16–24px。
  • 动效：Hover 120ms、控件 180ms、浮层 240ms，统一使用 cubic-bezier(0.2, 0.8, 0.2, 1)；Reduced Motion 下关闭非必要过渡。

密度 ​

密度与主题相互独立，可继续在统一根节点或业务容器设置：

html
<div data-ls-density="compact"></div>
<div data-ls-density="comfortable"></div>