跳至主要内容
使用文档

使用文档

从零开始把 EDIC 设计系统接入任意项目——纯静态、零依赖、令牌驱动。下面的每个片段都可直接复制。

简介与设计哲学

EDIC 设计系统是一套纯静态、零构建的设计系统：所有视觉决策都被沉淀为 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?v=1.10.2">
  </head>
  <body>
    <!-- 你的内容 -->
    <script src="scripts.js?v=1.10.2"></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>

全部 20 个核心 + 5 个附加组件的 live 形态、变体与状态，请见视觉手册 · 组件库。

响应式导航 · Mobile Drawer

导航栏 .ds-navbar 在桌面端为水平毛玻璃浮动导航，在移动端与平板（<1024px）自动转为右侧滑出抽屉。整套移动端导航严格遵循已有设计令牌。

设计决策与使用令牌

  • 顶部导航栏（移动端）：切换为实底 --ds-color-surface-raised，禁用毛玻璃。移动设备上 backdrop-filter 性能开销大且文字可读性不可控，因此移动端一律实底。
  • 汉堡按钮：44×44px 触控目标、圆角 --ds-radius-md、3 条线到 X 的状态动画；悬停/按下时使用 --ds-accent-soft 背景与 --ds-accent 图标色。
  • 遮罩层：使用 --ds-color-overlay-light（12% 黑色）——提供微妙的层级暗示但不会让整页变暗。不使用 --ds-color-overlay（40%）——那是模态框专用的重级遮罩。动画使用 --ds-duration-300 + --ds-ease-out。
  • 抽屉面板：实底 --ds-color-surface-raised、左侧边框 --ds-color-border、阴影 --ds-shadow-2xl（最深级别，表达最高抬起层级）。滑入动画使用 --ds-duration-300 + --ds-ease-out。
  • 导航链接：遵循 ds-nav-item 模式——padding --ds-space-3 / --ds-space-4（≥44px 触控目标）、圆角 --ds-radius-lg、悬停态 --ds-accent-soft 背景 + --ds-accent 文字。活跃态使用 --ds-accent-muted 浅底。
  • 层级：遮罩 z-index: var(--ds-z-overlay)，打开态导航壳 z-index: var(--ds-z-modal)，抽屉与触发按钮在导航壳内递进抬升。
  • 键盘可达：按 Escape 关闭，点击链接关闭，aria-expanded 同步。
html
<nav class="ds-navbar">
  <div class="ds-navbar-inner">
    <a href="/" class="ds-logo">…</a>
    <button class="ds-mnav-trigger" id="mnav-trigger"
            aria-label="打开导航菜单" aria-expanded="false"
            aria-controls="mnav-panel">
      <span class="ds-mnav-trigger-bar"></span>
      <span class="ds-mnav-trigger-bar"></span>
      <span class="ds-mnav-trigger-bar"></span>
    </button>
    <div class="ds-navbar-links" id="mnav-panel">
      <a href="#" class="ds-navbar-link ds-navbar-link--active">首页</a>
      <a href="#" class="ds-navbar-link">文档</a>
    </div>
  </div>
</nav>
<div class="ds-mnav-backdrop" id="mnav-backdrop"></div>

令牌对照表

元素令牌桌面端移动端
导航栏背景--ds-glass-bg / --ds-color-surface-raised毛玻璃（55% + blur）实底表面，禁用 blur
触发按钮ds-mnav-trigger隐藏44px · 3-bar → X 动画
遮罩--ds-color-overlay-light无12% 黑色 · 点击关闭
抽屉阴影--ds-shadow-2xl无最深投影
动画时长--ds-duration-300—300ms
动画缓动--ds-ease-out—cubic-bezier(.16,1,.3,1)
移动端规范
  • 移动端与平板窄屏导航禁止使用毛玻璃（--ds-glass-bg）——低端设备性能差且文字可读性不足。
  • 遮罩层使用 --ds-color-overlay-light（12%），不使用 --ds-color-overlay（40%）——后者是模态框级别。
  • 触控目标不小于 44×44px（符合 WCAG 2.5.5）。

动效与滚动揭示

动效统一由 --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——用户开启「减少动态效果」时会自动停用，内容立即可见。

代码样式

本站所有代码块使用 Prism.js 做语法高亮，配合一套定制橄榄绿主题。代码块统一使用 <figure class="ds-code"> 结构，由语言标签栏 + 可复制代码区组成。

基本用法

在 <pre> 或 <code> 上添加 class="language-xxxx"（如 language-html、language-css），Prism.js 会自动识别并高亮：

html
<figure class="ds-code">
  <pre><code class="language-html">
    &lt;!-- 代码内容 —— 需转义 &lt; &amp; ——&gt;
  </code></pre>
</figure>

支持的语言

默认支持 HTML（含 SVG/XML）、CSS、JavaScript 等常见语言。如需其他语言，引入对应的 Prism 组件即可。主题配色通过 CSS 变量 --ds-token-* 统一控制，与设计系统的 OKLch 色彩体系一致。

主题令牌

语法高亮颜色由以下 CSS 变量定义，可通过覆盖变量整体换肤：

令牌用途浅色模式值（暗底）暗色模式值（暗底）
--ds-code-bg代码块背景oklch(14% 0.025 60)oklch(18% 0.01 75)
--ds-code-text基础文字色oklch(90% 0.015 85)oklch(88% 0.01 85)
--ds-token-comment注释oklch(55% 0.035 130)同浅色
--ds-token-keyword关键字oklch(78% 0.10 25)同浅色
--ds-token-string字符串oklch(82% 0.10 130)同浅色
--ds-token-function函数 / 类名oklch(85% 0.08 85)同浅色
--ds-token-number数字 / 布尔oklch(80% 0.09 60)同浅色
--ds-token-tagHTML 标签oklch(78% 0.09 60)同浅色
--ds-token-attr-name属性名oklch(75% 0.06 180)同浅色
--ds-token-operator运算符oklch(70% 0.02 80)同浅色
--ds-token-punctuation标点oklch(65% 0.02 80)同浅色

代码块背景始终为暗色（不随页面主题反转），因此语法令牌的暗色模式值与浅色模式相同——在两种主题下均保持一致的编辑体验。

代码块组件

使用 ds-code 系列 class 构建代码块。推荐的结构：

  • .ds-code — 容器（圆角 + 暗背景 + 边框）
  • .ds-code-bar — 顶栏（语言标签 + 复制按钮）
  • .ds-code-lang — 语言标签（大写小字，mono 字族）
  • .ds-copy-btn[data-copy="#id"] — 复制按钮（关联 <pre id="...">）
  • <pre><code class="language-*"> — Prism 高亮代码区

Prism.js 通过 cdnjs 加载（[email protected]，含 SRI 完整性校验防 CDN 篡改），零安装、零构建，与设计系统的纯静态哲学一致。建议在自有项目中同样锁定版本号与 SRI：

html
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.30.0/prism.min.js"
        integrity="sha384-xAgN7OCsK5s0d3G18tqRYrxy8hWsPA14E26TMh7Mi9ZM09vaz4EA0DBTl+80F5yC"
        crossorigin="anonymous"
        defer></script>

图标用法

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 定义。

中性色 — Neutral

Background
oklch(97% 0.012 80)
Surface
oklch(99% 0.005 80)
Surface Raised
oklch(100% 0 0)
Border Subtle
oklch(92% 0.012 80)
Border
oklch(89% 0.012 80)
Border Strong
oklch(82% 0.015 75)
Muted Text
oklch(48% 0.015 60)
FG Subtle
oklch(35% 0.018 60)
Foreground
oklch(20% 0.02 60)
FG Strong
oklch(14% 0.025 60)

强调色 — Olive Green

Olive 50
oklch(90% 0.025 115)
Olive 100
oklch(82% 0.035 115)
Olive 200
oklch(72% 0.05 115)
Olive 300
oklch(62% 0.065 115)
Olive 400 ★
oklch(52% 0.08 115)
Olive 500
oklch(45% 0.085 115)
Olive 600
oklch(38% 0.08 115)
Olive 700
oklch(30% 0.07 115)
Olive 800
oklch(22% 0.055 115)
Olive 900
oklch(15% 0.04 115)

语义色 — Semantic

Success
oklch(55% 0.1 145)
Warning
oklch(65% 0.1 85)
Error
oklch(50% 0.14 30)
Info
oklch(55% 0.08 240)

视觉手册 · 字体系统

衬线 Display + 无衬线 Body 经典编辑主义搭配。

Display

Iowan Old Style / Charter / Georgia

标题用衬线，克制且自信

Body

SF Pro / system-ui / Noto Sans SC

正文无衬线，确保可读性

Mono

JetBrains Mono / IBM Plex Mono

const token = "ds-system"

UI

system-ui / Noto Sans SC

Button / Input / Nav

Type Scale — 比例尺

Hero / 4.5 rem · 72 px 700 ／ --ds-leading-tight 1.1 ／ --ds-tracking-tight -0.02 em

AG 设计系统

Display / 3.75 rem · 60 px 700 ／ --ds-leading-tight 1.1 ／ --ds-tracking-tight -0.02 em

阅读是设计

H1 / 3 rem · 48 px 700 ／ --ds-leading-tight 1.1 ／ --ds-tracking-tight -0.02 em

色彩定义情绪

H2 / 2.25 rem · 36 px 700 ／ --ds-leading-snug 1.25 ／ --ds-tracking-normal 0

文字承载信息

H3 / 1.875 rem · 30 px 700 ／ --ds-leading-snug 1.25 ／ --ds-tracking-normal 0

小组件标题

H4 / 1.5 rem · 24 px 700 ／ --ds-leading-snug 1.25 ／ --ds-tracking-normal 0

卡片标题

Body / 1rem · 16 px 400 ／ --ds-leading-normal 1.5 ／ --ds-tracking-normal 0

正文文本，行长受 65ch 约束。中英混排优化字距与标点悬挂。

Body SM / 0.875 rem · 14 px 400 ／ --ds-leading-normal 1.5 ／ --ds-tracking-normal 0

辅助说明、图注、表单提示。

Caption / 0.75 rem · 12 px 400 ／ --ds-leading-normal 1.5 ／ --ds-tracking-wide 0.08 em

LABEL / 标签大写更清晰

段落间距规范

The quick brown fox

Jumps over the lazy dog. This is body text.

The second paragraph continues.

margin-bottom: var(--ds-space-2) · 8px

Text Align

text-align: left
The quick brown fox
text-align: center
The quick brown fox
text-align: right
The quick brown fox

字体组合参考

Gravitas 5
Display · Heading · Hero
Glow Sans
Heading · Title · Sub
Source Han Sans
Body · Content · Code
Noto Sans
UI · Caption · Label

排版规范

Line Height
1.2Heading
1.5Body
1.6Content
Letter Spacing
-0.02emDisplay
-0.01emHeading
0emBody
0.08emCaption / Label
Blockquote

Design is the silent ambassador of your brand.

视觉手册 · 间距 & 尺寸

基于 4px 系统，所有值为 4 的倍数。

间距比例尺

--ds-space-1 · 4 px
--ds-space-2 · 8 px
--ds-space-3 · 12 px
--ds-space-4 · 16 px
--ds-space-6 · 24 px
--ds-space-8 · 32 px
--ds-space-12 · 48 px
--ds-space-16 · 64 px
--ds-space-24 · 96 px

阴影

xs
sm
md
lg
xl
2xl

圆角

0
sm
md
lg
xl
2xl
∞

视觉手册 · 组件库

20 个核心 UI 组件 + 5 个附加组件，包含所有变体状态。

01 · Button
02 · Card

Card Title

A raised card with border.

Hover Card

Hover for shadow transition.

Flat Card

Borderless with subtle shadow.

03 · Text Input

At least 8 characters

Please enter a valid email

04 · Select
05 · Checkbox
06 · Radio
07 · Toggle / Switch
08 · Badge
Default New Live Pending Error
09 · Chip / Pill
React Vue Svelte × Angular ×
10 · Alert
Info
Your session expires in 5 min.
Saved
Changes saved successfully.
Warning
Storage almost full.
Error
Something went wrong.
11 · Modal

Confirm Delete

Delete "Draft-03"? This cannot be undone.
12 · Tabs
13 · Avatar
ED
EDIC
Design System
14 · Progress
15 · Tooltip
Hover me
16 · Skeleton
17 · Divider
Above content
Below content
18 · Breadcrumb
19 · Pagination
20 · Empty State

No items yet

Create your first item to get started.

21 · Accordion
What is this design system?▾
Design tokens and components for EDIC. OKLch color, editorial type, olive green accent.
22 · Table
NameRoleStatusActive
Elena ChenDesignerActive2 min ago
Marcus LiuDeveloperOnlineJust now
Sofia ParkPMAway1 hour ago
23 · Navigation & Dropdown
Edit
Duplicate
Delete
24 · Icon Button / Toolbar
25 · Slider
65%
0%100%
40%
0%100%
26 · Date / Time Picker
五月 2026
一二三四五 六日
27282930123 45678910 11121314151617 18192021222324 25262728293031 1234567
27 · Article TOC
附加 · Contact Form

视觉手册 · 图表库

10 种图表类型（环形图含单值与多组双变体）由统一 SVG 引擎渲染，零运行时依赖，支持 hover tooltip、键盘聚焦与过渡动画。视觉样式通过 --ds-chart-* 配置变量调整。

柱状图 · Bar
月度销售额柱状图：一月 65，二月 80，三月 45，四月 92，五月 70，六月 88
条形图 · Bar (Horizontal)
设备使用分布：桌面端 55%，移动端 35%，平板 10%
堆叠柱状图 · Stacked Bar
季度营收堆叠柱状图：Q1 产品A 40 产品B 30，Q2 产品A 50 产品B 45
饼图 · Pie
流量来源分布：搜索引擎 35%，社交媒体 30%，直接访问 20%，其他 15%
环形图 · Donut
完成率 73%
多组环形图 · Donut (Multi)
月度完成率：1月 75%，2月 42%，3月 完成60% 进行30% 失败10%
迷你趋势图 · Sparkline
近 7 日趋势：上升趋势
+12.4%
折线图 · Line
7 天用户活跃度趋势：从 30 逐步上升至 72
面积图 · Area
月访问量面积图，从 40 增长至 85
多系列折线图 · Multi-line
桌面端和移动端用户数趋势对比
组合图 · Combo (Bar + Line)
收入与增长率组合图

视觉手册 · 图标库

100 枚 SVG 图标，24×24 viewBox，1.5 px 描边。供浏览参考，文件统一在 downloads 页面下载。

完整图标文件：icons.svg（配套生成）— 可直接导入 Penpot。

视觉手册 · Overlay & Blur

透明度和背景模糊在编辑风格中的正确用法。全部基于 OKLch alpha 通道和 backdrop-filter，与系统色彩体系无缝衔接。

遮罩层 — Scrim
40%
--ds-color-overlay — oklch(0% 0 0 / 40%)
12%
--ds-color-overlay-light — oklch(0% 0 0 / 12%)
玻璃卡片 — Glass Card

Olive Grove

玻璃卡片使用 backdrop-filter: blur(24px)，背景为系统色盘中相邻色的渐变。

EDIC Design System v1.10.2
毛玻璃导航 — Frosted Nav
通知弹层 — Toast
操作成功 · 设计系统已更新
这是一条普通通知，毛玻璃背景衬托
出错了 · 请检查后重试
玻璃按钮 — Glass Button

视觉手册 · 时间轴

Timeline 组件展示设计系统发展历程。

发布
2026.06 — v1.10.2
编辑主义暗色深化

暗色模式 Gravitas & Glow、Prism 代码高亮主题适配、统一页面目录组件、6 个验证器全部 exit 0。

迭代
2026.05 — v1.1.0
多页站点与动效系统

6 页静态网站、品牌 Logo、动效系统、暗色模式完善、AI 协作交付物（提示词 + Skill）、icons.svg 图标 sprite。

设计
2026.05 — v1.0.0
设计系统正式发布

200+ 设计令牌，20 核心 + 5 附加组件，100 枚 SVG 图标，OKLch 色彩体系，暗色模式，GitHub Pages 部署。

视觉手册 · 联系表单

Contact Form 组件完整展示。

令牌索引

全部 200+ CSS 自定义属性汇总。可直接复制使用。

TokenValue