# Salesforce Lightning 设计系统

## Salesforce Lightning 设计系统界面预览

更改优先级或状态，验证更新说明，保存一条本地活动记录；之后还可以放弃草稿，且不影响已保存的记录。

## Salesforce Lightning 设计系统设计参考

已发布的 @salesforce-ux/design-system 2.264.1 原生 CSS 和 ui-force 令牌导出。这是固定版本的经典蓝图参考，并不表示兼容较新的 SLDS 2 设计语言或 Lightning Web Components 运行时。上游历史仓库已归档。

### 记录界面表面与语义化文字

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| COLOR_BACKGROUND | rgb(243, 243, 243) | 已发布的程序包参考。保留文本、界面表面或操作的既定角色，而不是到处使用同一种品牌色。 |
| COLOR_BACKGROUND_ALT | rgb(255, 255, 255) | 已发布的程序包参考。保留文本、界面表面或操作的既定角色，而不是到处使用同一种品牌色。 |
| COLOR_TEXT_DEFAULT | rgb(3, 45, 96) | 已发布的程序包参考。保留文本、界面表面或操作的既定角色，而不是到处使用同一种品牌色。 |
| COLOR_TEXT_WEAK | rgb(116, 116, 116) | 已发布的程序包参考。保留文本、界面表面或操作的既定角色，而不是到处使用同一种品牌色。 |
| COLOR_BORDER | rgb(201, 201, 201) | 已发布的程序包参考。保留文本、界面表面或操作的既定角色，而不是到处使用同一种品牌色。 |
| COLOR_BORDER_ERROR | rgb(234, 0, 30) | 已发布的程序包参考。保留文本、界面表面或操作的既定角色，而不是到处使用同一种品牌色。 |
| COLOR_BORDER_SELECTION | rgb(1, 118, 211) | 已发布的程序包参考。保留文本、界面表面或操作的既定角色，而不是到处使用同一种品牌色。 |
| COLOR_BACKGROUND_BUTTON_BRAND | rgb(1, 118, 211) | 已发布的程序包参考。保留文本、界面表面或操作的既定角色，而不是到处使用同一种品牌色。 |
| COLOR_BACKGROUND_BUTTON_BRAND_HOVER | rgb(1, 68, 134) | 已发布的程序包参考。保留文本、界面表面或操作的既定角色，而不是到处使用同一种品牌色。 |
| COLOR_BACKGROUND_BUTTON_BRAND_ACTIVE | rgb(3, 45, 96) | 已发布的程序包参考。保留文本、界面表面或操作的既定角色，而不是到处使用同一种品牌色。 |
### 经典间距比例

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| SPACING_X_SMALL | 0.5rem | 经典 SPACING_* 导出。这不是另一个独立的紧凑型 VAR_SPACING_* 集合。 |
| SPACING_XXX_SMALL | 0.125rem | 经典 SPACING_* 导出。这不是另一个独立的紧凑型 VAR_SPACING_* 集合。 |
| SPACING_XX_SMALL | 0.25rem | 经典 SPACING_* 导出。这不是另一个独立的紧凑型 VAR_SPACING_* 集合。 |
| SPACING_SMALL | 0.75rem | 经典 SPACING_* 导出。这不是另一个独立的紧凑型 VAR_SPACING_* 集合。 |
| SPACING_MEDIUM | 1rem | 经典 SPACING_* 导出。这不是另一个独立的紧凑型 VAR_SPACING_* 集合。 |
| SPACING_NONE | 0 | 经典 SPACING_* 导出。这不是另一个独立的紧凑型 VAR_SPACING_* 集合。 |
| SPACING_X_LARGE | 2rem | 经典 SPACING_* 导出。这不是另一个独立的紧凑型 VAR_SPACING_* 集合。 |
| SPACING_XX_LARGE | 3rem | 经典 SPACING_* 导出。这不是另一个独立的紧凑型 VAR_SPACING_* 集合。 |
| SPACING_LARGE | 1.5rem | 经典 SPACING_* 导出。这不是另一个独立的紧凑型 VAR_SPACING_* 集合。 |
### 字体阶梯

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| FONT_SIZE_1 | 0.625rem | 根据用途选择字号，确保案例备注和字段标签易于阅读。 |
| FONT_SIZE_2 | 0.75rem | 根据用途选择字号，确保案例备注和字段标签易于阅读。 |
| FONT_SIZE_3 | 0.8125rem | 根据用途选择字号，确保案例备注和字段标签易于阅读。 |
| FONT_SIZE_4 | 0.875rem | 根据用途选择字号，确保案例备注和字段标签易于阅读。 |
| FONT_SIZE_5 | 1rem | 根据用途选择字号，确保案例备注和字段标签易于阅读。 |
| FONT_SIZE_6 | 1.125rem | 根据用途选择字号，确保案例备注和字段标签易于阅读。 |
| FONT_SIZE_7 | 1.25rem | 根据用途选择字号，确保案例备注和字段标签易于阅读。 |
| FONT_SIZE_8 | 1.5rem | 根据用途选择字号，确保案例备注和字段标签易于阅读。 |
| FONT_SIZE_9 | 1.75rem | 根据用途选择字号，确保案例备注和字段标签易于阅读。 |
| FONT_SIZE_10 | 2rem | 根据用途选择字号，确保案例备注和字段标签易于阅读。 |
| FONT_SIZE_11 | 2.625rem | 根据用途选择字号，确保案例备注和字段标签易于阅读。 |
### 圆角

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| BORDER_RADIUS_SMALL | 0.125rem | 已发布的圆角参考。圆形状态标记与矩形表单控件并不相同。 |
| BORDER_RADIUS_MEDIUM | 0.25rem | 已发布的圆角参考。圆形状态标记与矩形表单控件并不相同。 |
| BORDER_RADIUS_LARGE | 0.5rem | 已发布的圆角参考。圆形状态标记与矩形表单控件并不相同。 |
| BORDER_RADIUS_CIRCLE | 50% | 已发布的圆角参考。圆形状态标记与矩形表单控件并不相同。 |
### 原生 CSS 蓝图结构

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| slds-page-header | Record context | 将案例标识和摘要放在编辑表单上方。 |
| slds-card | Grouped content region | 案例详情和活动记录分别放在独立的语义区域中。 |
| slds-form-element | Label + control + help | 将每个可编辑值封装在结构完整的字段中。 |
| slds-has-error | Invalid field modifier | 与 aria-invalid 和具体的错误信息一同设置。 |
| slds-button_brand | Primary action | 保存本地更新；该类提供样式，不负责持久化。 |
| slds-button_neutral | Secondary action | 放弃草稿并恢复上次保存的本地值。 |
## Salesforce Lightning 设计系统完整指南

实用指南，介绍如何为真实界面选择、应用和评审此系统。

完整指导、实现起点和源代码链接。

## Salesforce Lightning 设计系统记录布局与上下文

### 将记录标识置于本地任务上方

> 页面标题区域包含案例编号、主题、账户和负责人。在用户修改字段之前，这些信息用于标识对象。状态徽标是本地已保存记录的摘要，因此应在点击“保存”后才更新，而不是随尚未提交的选择值变化。

### 将详情与活动记录分开

较宽的区域组合呈现客户背景信息和编辑表单。次要区域则显示按顺序排列的历史记录。这样的分区让用户无需切换屏幕，就能对照待处理事项与已记录的更改。移动端布局会按相同的语义顺序纵向排列这些区域。

## Salesforce Lightning 设计系统语义色与状态

### 将令牌名称视为角色

ui-force 导出区分默认文字、弱化文字、选中边框和品牌按钮背景。此示例将正文保持为深色、元数据处理得更克制，并使用蓝色作为主要操作色。红色用于无效字段及其文字说明的恢复方式，而不是用于所有未保存的值。

### 不要只靠颜色传达状态

摘要和新增活动记录中，优先级与状态均以文字显示。错误状态结合原生 slds-has-error 修饰类、aria-invalid 属性，以及与文本区域关联的提示信息。本地确认信息会在状态区域中以文字呈现；仅使用绿色点缀无法告知用户保存了什么。

## Salesforce Lightning 设计系统字号比例与记录密度

### 运用层级，避免标题过度放大

已发布的编号字号比例从 0.625rem 延伸至 2.625rem。案例工作区无需在每个区域都使用最大字号。原生页面标题用于标识记录，卡片标题用于区分区域，常规正文则承载客户请求和备注内容。

### 保留较长记录主题的完整内容

自定义布局允许页面标题换行，而非在窄屏幕上截断主题。元数据也可以换到后续行。不要为了容纳较长的账户名称而缩小所有文字；应先使用实际长度的主题和负责人姓名进行测试，再决定在何处截断，以及如何提供安全的完整文本替代方案。

## Salesforce Lightning 设计系统间距与蓝图结构

### 不要合并经典间距导出与变量间距导出

本指南列出了 ui-force 中的 SPACING_*。单独导出的 var-spacing 包含不同的紧凑值；VAR_SPACING_MEDIUM 与 SPACING_MEDIUM 并非同一引用。仅凭相似名称混用数值，可能导致表单布局不均匀。请选择预期的密度系统，并沿用其来源。

### 统一使用字段包装器

每个标签和控件都应放在 slds-form-element 中，输入框和帮助文本则应放在 slds-form-element__control 中，帮助文本紧接输入框之后。原始网格将两个相关的选择字段并排排列，并在窄屏上改为堆叠布局。网格属于应用布局，字段结构则来自原生蓝图。

## Salesforce Lightning 设计系统草稿与已保存记录行为

### 将已保存记录与控件分开管理

脚本会在记录对象中保留上次保存的优先级和状态。修改选择框只会更新草稿。保存时，脚本会将值复制到该对象、更新摘要并添加一条活动记录。这样，在多次成功编辑之后，“丢弃草稿”仍能按预期工作。

### 不要虚构后端操作成功

此示例没有记录 ID 查询、权限模型、API 或数据库。按钮和确认信息都明确说明操作仅在本地进行。若要在生产环境中集成 Salesforce，必须先接入相应的数据 API 并获取服务器响应，才能更新确定的记录状态。CSS 类无法提供这些保障。

## Salesforce Lightning 设计系统字段验证与活动记录

### 让备注说明变更内容

规则要求备注去除首尾空格后至少包含 10 个字符，且文本区域最多允许输入 300 个字符。备注为空或过短时，不会更改任何记录；系统会显示字段错误并将焦点移至备注框。编辑时会清除过时的错误；下次保存时，会重新验证当前值。

1. 不填写备注并提交，确认已保存的摘要值没有变化。

2. 输入有用的备注并保存，然后检查最新的活动记录。

3. 再次修改字段，丢弃草稿，并确认字段已恢复为上次保存的值。

### 添加清晰易读的变更记录

本地更新成功后，系统会根据已保存的状态和优先级生成活动标题，并将原样备注作为文本内容添加到标题之后。新记录会添加在列表顶部，因此最新变更会最先显示。备注绝不会被解释为 HTML，静态初始活动记录仍会显示在用户本地添加的记录下方。

## Salesforce Lightning 设计系统无障碍表单与恢复操作

### 使用真实标签和明确的说明

选择框和文本区域都有可见标签，并通过 for 和 id 关联。备注框会引用帮助文本和错误文本，必填标记也设有易读的标题。主要操作和丢弃操作使用按钮，并设置适当的 submit 和 button 类型，避免用户丢弃草稿时意外提交表单。

### 丢弃草稿后返回可预期的位置

丢弃操作会恢复已保存的优先级和状态，清空备注和字段错误，并将焦点移至优先级控件。它不会删除活动记录，也不会将记录重置为初始状态。如果用户先保存一次，再尝试另一项更改并取消第二份草稿，这一区别就很重要。

## Salesforce Lightning 设计系统 CSS 集成与版本范围

### 安装已发布的样式包

完整源代码导入固定版本的 CSS 分发包和一个小型应用样式表。Vite 会解析软件包中的字体和图片 URL。HTML 和 JavaScript 则提供记录行为；这是基于 CSS 蓝图的实现，并非 lightning-record-edit-form 的包装器。

- 原生软件包 CSS 提供字段、按钮和卡片样式。

- 原始 HTML 提供记录结构和标签。

- 原始 JavaScript 负责草稿状态、验证和本地活动记录。

### 将已归档源代码视为特定版本的参考

官方 GitHub 仓库已归档，因此本页面会标明实际使用的软件包，而不会将其称为仍在维护的最新推荐方案。请针对目标环境核查 Salesforce 平台组件、较新的设计系统指南以及样式钩子支持情况。明确记录所选的 CSS 软件包和框架集成方案。

## Salesforce Lightning 设计系统组件示例

### index.html — 完整案例工作区

使用语义化 HTML 编写的记录摘要、表单和初始活动记录。

```
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Local case workspace</title>
<body>
<main class="slds-example">
  <header class="slds-page-header">
    <p class="slds-text-title_caps">Service workspace · fictional record</p>
    <div class="record-title">
      <div>
        <h1 class="slds-page-header__title">
          Case 004218 · Delivery address update
        </h1>
        <p class="slds-text-body_small">
          Northstar Studio · Opened today · Owner: Maya Chen
        </p>
      </div>
      <span id="status-badge" class="slds-badge">New</span>
    </div>
  </header>
  <div class="record-grid">
    <section class="slds-card">
      <div class="slds-card__header">
        <h2 class="slds-card__header-title">Case details</h2>
      </div>
      <div class="slds-card__body slds-card__body_inner">
        <div class="summary">
          <div>
            <span class="slds-text-title">Contact</span>
            <p>Alex Morgan</p>
          </div>
          <div>
            <span class="slds-text-title">Channel</span>
            <p>Email</p>
          </div>
          <div>
            <span class="slds-text-title">Priority</span>
            <p id="read-priority">Medium</p>
          </div>
          <div>
            <span class="slds-text-title">Status</span>
            <p id="read-status">New</p>
          </div>
        </div>
        <div class="slds-box slds-theme_shade slds-m-top_medium">
          <h3 class="slds-text-heading_small">Customer request</h3>
          <p class="slds-m-top_small">
            Please update the delivery location for order NS-1842 before it
            leaves the warehouse. The contact is available to confirm the new
            address.
          </p>
        </div>
        <form id="case-form" class="slds-m-top_large" novalidate>
          <h3 class="slds-text-heading_small slds-m-bottom_medium">
            Update the local case
          </h3>
          <div class="field-grid">
            <div class="slds-form-element">
              <label class="slds-form-element__label" for="priority"
                >Priority</label
              >
              <div class="slds-form-element__control">
                <div class="slds-select_container">
                  <select class="slds-select" id="priority">
                    <option>Low</option>
                    <option selected>Medium</option>
                    <option>High</option>
                  </select>
                </div>
              </div>
            </div>
            <div class="slds-form-element">
              <label class="slds-form-element__label" for="case-status"
                >Status</label
              >
              <div class="slds-form-element__control">
                <div class="slds-select_container">
                  <select class="slds-select" id="case-status">
                    <option>New</option>
                    <option>Working</option>
                    <option>Escalated</option>
                    <option>Closed</option>
                  </select>
                </div>
              </div>
            </div>
          </div>
          <div id="note-field" class="slds-form-element slds-m-top_medium">
            <label class="slds-form-element__label" for="case-note"
              ><abbr class="slds-required" title="required">*</abbr> Update
              note</label
            >
            <div class="slds-form-element__control">
              <textarea
                class="slds-textarea"
                id="case-note"
                rows="3"
                maxlength="300"
                aria-describedby="note-help note-error"
              ></textarea>
            </div>
            <p id="note-help" class="slds-form-element__help">
              Explain the change in 10–300 characters. Nothing is sent to
              Salesforce.
            </p>
            <p id="note-error" class="slds-form-element__help" hidden>
              Enter an update note of at least 10 characters.
            </p>
          </div>
          <div class="form-actions">
            <button
              type="button"
              id="cancel"
              class="slds-button slds-button_neutral"
            >
              Discard draft</button
            ><button type="submit" class="slds-button slds-button_brand">
              Save local update
            </button>
          </div>
          <p id="save-result" class="slds-m-top_small" role="status"></p>
        </form>
      </div>
    </section>
    <aside class="slds-card">
      <div class="slds-card__header">
        <h2 class="slds-card__header-title">Case activity</h2>
      </div>
      <div class="slds-card__body slds-card__body_inner">
        <p class="slds-text-body_small slds-m-bottom_medium">
          Newest updates first
        </p>
        <ol id="activity" class="activity">
          <li>
            <span class="activity-dot"></span>
            <div>
              <h3 class="slds-text-heading_small">Case opened</h3>
              <p>Customer requested a delivery address change.</p>
              <small>Initial example activity</small>
            </div>
          </li>
        </ol>
      </div>
    </aside>
  </div>
  <footer>
    Native SLDS 2.264.1 CSS with original HTML and JavaScript. Local
    demonstration; no Salesforce record or message is created.
  </footer>
</main>

<script type="module" src="/src/main.js"></script>
</body></html>
```

代码参考

- 保存在 Vite 项目根目录。

### main.js — 草稿、验证与活动记录

完整的应用行为和原生 CSS 导入。

```
import "@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.css";
import "./slds.css";
let record = { priority: "Medium", status: "New" };
const form = document.querySelector("#case-form"),
  priority = document.querySelector("#priority"),
  status = document.querySelector("#case-status"),
  note = document.querySelector("#case-note"),
  field = document.querySelector("#note-field"),
  error = document.querySelector("#note-error"),
  result = document.querySelector("#save-result");
function clearError() {
  field.classList.remove("slds-has-error");
  error.hidden = true;
  note.removeAttribute("aria-invalid");
  result.textContent = "";
}
form.addEventListener("input", clearError);
form.addEventListener("submit", (e) => {
  e.preventDefault();
  const text = note.value.trim();
  if (text.length < 10) {
    field.classList.add("slds-has-error");
    error.hidden = false;
    note.setAttribute("aria-invalid", "true");
    note.focus();
    return;
  }
  record = { priority: priority.value, status: status.value };
  document.querySelector("#read-priority").textContent = record.priority;
  document.querySelector("#read-status").textContent = record.status;
  document.querySelector("#status-badge").textContent = record.status;
  const li = document.createElement("li"),
    dot = document.createElement("span"),
    body = document.createElement("div"),
    h = document.createElement("h3"),
    p = document.createElement("p"),
    small = document.createElement("small");
  dot.className = "activity-dot";
  h.className = "slds-text-heading_small";
  h.textContent = record.status + " · " + record.priority + " priority";
  p.textContent = text;
  small.textContent = "Local update · this session";
  body.append(h, p, small);
  li.append(dot, body);
  document.querySelector("#activity").prepend(li);
  note.value = "";
  clearError();
  result.textContent = "Local case updated. No server request was made.";
});
document.querySelector("#cancel").addEventListener("click", () => {
  priority.value = record.priority;
  status.value = record.status;
  note.value = "";
  clearError();
  priority.focus();
});
```

代码参考

- 保存为 src/main.js。所有更新仅在本地进行。

### slds.css — 响应式布局

仅包含原始记录网格、历史记录装饰和移动端布局。

```
[hidden] { display: none !important; }
body {
  margin: 0;
}
.slds-example {
  background: #f3f3f3;
  padding: 24px;
  min-height: 680px;
}
.record-title {
  display: flex;
  align-items: flex-start;
  justify-content: space-between;
  gap: 24px;
  margin-top: 12px;
}
.record-title h1 {
  white-space: normal;
}
.record-grid {
  display: grid;
  grid-template-columns: minmax(0, 1.7fr) minmax(260px, 1fr);
  gap: 20px;
  margin-top: 20px;
}
.record-grid > .slds-card {
  margin: 0;
  min-width: 0;
}
.summary,
.field-grid {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 16px;
}
.summary p {
  font-weight: 600;
  margin-top: 4px;
}
.form-actions {
  display: flex;
  justify-content: flex-end;
  flex-wrap: wrap;
  gap: 8px;
  margin-top: 20px;
}
.activity {
  list-style: none;
  padding: 0;
  margin: 0;
}
.activity li {
  display: flex;
  gap: 12px;
  padding-bottom: 24px;
  position: relative;
}
.activity li:not(:last-child):before {
  content: "";
  position: absolute;
  left: 5px;
  top: 12px;
  bottom: 0;
  border-left: 1px solid #c9c9c9;
}
.activity-dot {
  flex: none;
  width: 11px;
  height: 11px;
  background: #0176d3;
  border-radius: 50%;
  margin-top: 5px;
}
.activity p {
  margin: 8px 0;
}
.activity small {
  color: #747474;
}
.slds-example footer {
  font-size: 12px;
  color: #747474;
  margin-top: 20px;
}
.slds-form-element.slds-has-error #note-help {
  color: #444;
}
@media (max-width: 760px) {
  .slds-example {
    padding: 12px;
  }
  .record-grid {
    grid-template-columns: 1fr;
  }
  .record-title {
    gap: 12px;
  }
  .field-grid {
    grid-template-columns: 1fr;
  }
  .form-actions {
    justify-content: flex-start;
  }
}
```

代码参考

- 保存为 src/slds.css；软件包样式保持独立。

## Salesforce Lightning 设计系统 AI Agent 设置

### 实现起点

固定版本的原生 CSS 示例，并非 Salesforce 组织部署。重新分发捆绑资源时，请保留软件包和资源声明。

```
npm create vite@latest slds-case -- --template vanilla
cd slds-case
npm install
npm install @salesforce-ux/design-system@2.264.1
# Replace index.html; add src/main.js and src/slds.css from the complete examples.
npm run dev
```

### 适用于你项目的提示词

```
使用固定版本的 SLDS CSS 蓝图，构建专注于案例处理的工作区。区分记录标识、客户背景、已保存状态和编辑草稿。使用准确的字段结构、真实的设计令牌引用以及此处提供的完整源代码。更改摘要前先验证备注，丢弃草稿后保留本地活动记录，并且不要暗示已连接 Salesforce 后端。
```

## Salesforce Lightning 设计系统来源与范围

OpenDesign 固定版本 SLDS CSS 软件包指南。预览使用原生 CSS，搭配原始 HTML 和 JavaScript、虚构案例数据以及本地状态。它不会加载 Lightning Web Components，也不会连接 Salesforce。上游仓库已归档；用于生产环境时，请评估 Salesforce 当前的平台指南。

- 官方源代码仓库 已归档的源代码、蓝图和软件包历史。

- 固定版本的令牌导出 精确的经典间距、字体、圆角和颜色值。

- 组件蓝图 原生标记和修饰符模式。

## Salesforce Lightning 设计系统相关资源

### Samsung One UI

通过完整的原创阅读偏好预览，了解 One UI 的浏览与交互结构、24dp 边距建议、200% 文本缩放要求，以及深色外观和明确的重置恢复方式。

### SAP Fiori

通过 UI5 Web Components 使用 SAP Fiori 的 Horizon 主题：采用真实的主题参数、明确的内容密度、语义化的值状态，以及带本地验证的采购申请布局。

### SEEK Braid

通过原创的求职界面设计了解 Braid：按主题作用域划分的变量、四个真实断点、结合上下文的文本、不同色调的按钮，以及会说明验证原因而非禁用操作的受控字段。


- [实现参考](https://github.com/salesforce-ux/design-system)
- [来源](https://cdn.jsdelivr.net/npm/@salesforce-ux/design-system@2.264.1/design-tokens/dist/ui-force.json)
- [来源](https://github.com/salesforce-ux/design-system/tree/main/ui/components)
- [代码参考](https://github.com/salesforce-ux/design-system)
- [官方源代码仓库 已归档的源代码、蓝图和软件包历史。](https://github.com/salesforce-ux/design-system)
- [固定版本的令牌导出 精确的经典间距、字体、圆角和颜色值。](https://cdn.jsdelivr.net/npm/@salesforce-ux/design-system@2.264.1/design-tokens/dist/ui-force.json)
- [组件蓝图 原生标记和修饰符模式。](https://github.com/salesforce-ux/design-system/tree/main/ui/components)