使用文档 · CGArtLab Design System

简介与设计哲学

CGArtLab 设计系统是一套纯静态、零构建的设计系统：所有视觉决策都被沉淀为 CSS 自定义属性（设计令牌），组件以语义化的 ds-* class 暴露。它的气质是编辑主义 × 橄榄绿——杂志般克制的排版、温暖的暖白纸色基底，以及自信而不喧哗的橄榄绿强调色。

令牌优先：先改变量，再谈样式。不写魔法数字。
框架无关：一份 styles.css 可用于原生 HTML、React、Vue、Svelte、邮件与打印。
双主题：浅色 / 暗色由 [data-theme] 切换，强调色可一键替换。
中英混排：针对 CJK 与拉丁文混排做了字距、行高与标点优化。

设计系统的价值不在于「好看」，而在于「可被一致地复制」——无论复制者是人还是 AI。

安装与引入

无需 npm、无需打包器。把 styles.css 与 scripts.js 拷贝到你的项目，并在页面中引入即可。

html

<!doctype html>
<html lang="zh-CN" data-theme="">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="icon" type="image/svg+xml" href="favicon.svg">
    <link rel="stylesheet" href="styles.css">
  </head>
  <body>
    <!-- 你的内容 -->
    <script src="scripts.js"></script>
  </body>
</html>

scripts.js 是可选的——它负责暗色模式持久化、滚动揭示、复制按钮、标签页与图标渲染等渐进增强。即便不引入，所有样式依然完整可用。

使用设计令牌

令牌定义在 :root 中，命名遵循 --ds-{类别}-{名称}。在任意属性中用 var() 引用，永远不要硬编码具体数值。

css

.promo-card {
  background: var(--ds-color-surface-raised);
  color: var(--ds-color-fg);
  border: 1px solid var(--ds-color-border);
  border-radius: var(--ds-radius-xl);   /* 12px */
  padding: var(--ds-space-6);            /* 24px */
  box-shadow: var(--ds-shadow-md);
  transition: box-shadow var(--ds-duration-200) var(--ds-ease-out);
}
.promo-card:hover { box-shadow: var(--ds-shadow-lg); }

令牌分为这些类别：color、font、text（字号）、weight、leading、tracking、space、radius、shadow、duration、ease、z、blur。完整清单见令牌索引，结构化数据见 tokens.json。

色彩与语义

所有颜色以 OKLch 定义，保证跨设备的感知均匀与可预测的明度阶梯。三大色组：

中性色：从 --ds-color-bg 到 --ds-color-fg-strong，构成背景、表面、边框与文字层级。
橄榄绿：--ds-color-olive-50…900 十级色阶，--ds-accent 默认指向 olive-400。
语义色：success / warning / error / info，各自带 -bg 浅底变体。

需要混色时使用 color-mix(in oklch, …)，以保持色彩空间一致：

css

.ring {
  box-shadow: 0 0 0 3px
    color-mix(in oklch, var(--ds-accent) 15%, transparent);
}

暗色模式

暗色由 <html data-theme="dark"> 触发，整套令牌会被重写为暖灰基底（而非纯黑），强调色自动亮化 5–10%。scripts.js 提供 toggleDarkMode() 并做了系统偏好兜底与 localStorage 持久化。

html

<button onclick="toggleDarkMode()" aria-label="切换主题">切换</button>

<!-- 想默认暗色，直接写在 html 上： -->
<html lang="zh-CN" data-theme="dark">

提示

暗色模式不要使用 #000，请沿用令牌；自定义组件只要使用 var(--ds-*)，即可自动适配深浅两套主题。

排版规范

四个字族：Display（衬线，标题）、Body（无衬线，正文）、UI（控件）、Mono（代码）。字号采用 --ds-text-* 比例尺，从 caption(12px) 到 hero(72px)。

标题用 --ds-font-display + --ds-leading-tight + --ds-tracking-tight。
正文行长控制在 65–75 字符（约 540px 或 72ch）。
段间距用 margin-bottom: var(--ds-space-6)，避免 margin 折叠混乱。
大写小标签（Caption/Eyebrow）加 --ds-tracking-wider。

html

<h1 class="ds-display ds-h1">色彩定义情绪</h1>
<p class="ds-measure">正文使用 Body 字族，行长受 65ch 约束。</p>
<span class="ds-caption">SECTION LABEL</span>

间距与布局

间距基于 4px 系统，所有值均为 4 的倍数（--ds-space-1=4px … --ds-space-32=128px）。布局优先使用内置工具类，减少一次性 CSS：

.ds-wrapper：最大宽度 1200px 的居中容器。
.ds-stack / .ds-cluster：纵向 / 横向自动间距布局。
.ds-grid-2 / .ds-grid-3 / .ds-feature-grid：响应式栅格。
.ds-section：标准纵向区块留白与分隔线。

组件用法

组件以基类 + 修饰符表达：ds-btn 是基类，ds-btn--primary 是变体。下面是按钮、徽章与卡片的组合示例（在浅色与暗色下表现一致）。

Accent Success

html

<button class="ds-btn ds-btn--primary">主要按钮</button>
<span class="ds-badge ds-badge--accent">Accent</span>

<article class="ds-card ds-card--hoverable">
  <h4>卡片标题</h4>
  <p>使用令牌的卡片，悬停浮起。</p>
</article>

全部 25 个组件的 live 形态、变体与状态，请见视觉手册 · 组件库。

响应式导航 · Mobile Drawer

导航栏 .ds-navbar 在桌面端为水平毛玻璃浮动导航，在移动端（≤767px）自动转为右侧滑出抽屉。

抽屉背景：使用 --ds-color-surface-raised（实底不透明），而非毛玻璃——确保移动设备上文字可读性与性能。
遮罩层：.ds-navbar-overlay 使用 --ds-color-overlay（40% 黑色遮罩），点击可关闭。
链接样式：padding 增大至 --ds-space-3 / --ds-space-4，便于手指触控。活跃态使用 --ds-accent-muted 浅底。
动画：transform: translateX 滑入/出，时长 350ms，缓动 cubic-bezier(.16,1,.3,1)。
键盘可达：按 Escape 可关闭，aria-expanded 状态同步。

html

<nav class="ds-navbar">
  <div class="ds-navbar-inner">
    <a href="/" class="ds-logo">…</a>
    <button class="ds-navbar-toggle" id="nav-toggle"
            aria-label="切换导航" aria-expanded="false">☰</button>
    <div class="ds-navbar-links" id="nav-menu">
      <a href="#" class="ds-navbar-link ds-navbar-link--active">首页</a>
      <a href="#" class="ds-navbar-link">文档</a>
    </div>
  </div>
</nav>
<div class="ds-navbar-overlay" id="nav-overlay"></div>

移动端规范

移动端抽屉**必须使用实底背景**（--ds-color-surface-raised），禁止使用毛玻璃（--ds-glass-bg）——因为半透明背景在低端设备上性能差，且文字可读性不足。

动效与滚动揭示

动效统一由 --ds-duration-* 与 --ds-ease-* 令牌驱动。给元素加 .ds-reveal 即可在进入视口时淡入上移；用内联自定义属性 --d 设置错峰延迟。

html

<div class="ds-reveal">进入视口淡入</div>
<div class="ds-reveal" style="--d:80ms">延迟 80ms</div>
<div class="ds-reveal ds-reveal--left">从左滑入</div>
<span class="ds-anim-float">持续漂浮</span>

所有动效都尊重 prefers-reduced-motion: reduce——用户开启「减少动态效果」时会自动停用，内容立即可见。

图标用法

100 枚 1.5px 线性图标，遵循 24×24 视框、currentColor 描边，因此颜色随文字自动变化。直接内联 SVG，或在图标库点击下载单枚。

html

<svg width="20" height="20" viewBox="0 0 24 24" fill="none"
     stroke="currentColor" stroke-width="1.5"
     stroke-linecap="round" stroke-linejoin="round">
  <circle cx="11" cy="11" r="8"/>
  <line x1="21" y1="21" x2="16.65" y2="16.65"/>
</svg>

可访问性

正文与背景对比度满足 WCAG AA（≥ 4.5:1）。
交互元素提供可见的 :focus-visible 焦点环。
图标按钮务必加 aria-label；纯装饰图标加 aria-hidden="true"。
颜色不作为唯一信息载体（语义色配图标 / 文案）。
尊重 prefers-reduced-motion 与 prefers-color-scheme。

定制与扩展

替换强调色只需覆盖橄榄绿色阶与 --ds-accent 系列——其余组件无需改动即可整体换肤：

css

:root {
  /* 改为品牌蓝，色相 H≈250，其余明度/彩度沿用 */
  --ds-color-olive-400: oklch(52% 0.12 250);
  --ds-color-olive-500: oklch(45% 0.13 250);
  --ds-accent: var(--ds-color-olive-400);
  --ds-accent-hover: var(--ds-color-olive-500);
}

新增组件时遵循命名约定：基类 ds-{组件}，变体 ds-{组件}--{变体}，并只使用令牌——这样它会自动获得深浅主题、动效与可访问性的一致行为。

常见问题

需要 npm 或构建工具吗？

不需要。它是纯静态的 CSS + 原生 JS，复制文件、引入即可用。

OKLch 的浏览器兼容性如何？

所有现代浏览器（Chrome/Edge 111+、Safari 15.4+、Firefox 113+）均支持 OKLch 与 color-mix。面向更老环境可在构建期降级为 sRGB 回退。

能用在 React / Vue 里吗？

可以。引入 styles.css 后，把 class 写到 JSX/模板上即可；令牌也可在组件库中以变量形式引用。

如何让 AI 按这套系统输出？

前往提示词页，复制系统提示词或 Skill 粘贴给你的 Agent 即可。