equinor-design-system

Equinor 设计系统 — 设计规则

EDS 设计令牌和 Equinor 品牌限制的精简参考。所有规则均来自 eds.equinor.com 和 Equinor Communication Toolbox。

此文件是从属查询参考。其中没有工作流步骤。使用方 Agent 应查询相关章节并直接应用规则。

---

颜色令牌

所有颜色值均使用 EDS CSS 自定义属性（--eds-color-*）。Fusion 应用代码中不得使用原始 hex、rgb() 或 CSS 命名颜色。以下所有令牌均来自 Fusion 应用所依赖的 @equinor/eds-tokens v2.x。

令牌命名模式：--eds-color-<layer>-<semantic>-<variant>

• bg = 背景填充
• text = 前景文本 / 图标
• border = 描边 / 分隔线

背景令牌

用途	EDS 令牌
页面 / 应用画布	--eds-color-bg-canvas
表面（卡片、面板）	--eds-color-bg-surface
输入字段背景	--eds-color-bg-input
浮动表面（下拉菜单、工具提示）	--eds-color-bg-floating
背景遮罩 / 模态框遮罩	--eds-color-bg-backdrop
主要操作填充（默认）	--eds-color-bg-fill-emphasis-default
主要操作填充（悬停）	--eds-color-bg-fill-emphasis-hover
主要操作填充（激活）	--eds-color-bg-fill-emphasis-active
柔和填充（默认）	--eds-color-bg-fill-muted-default
柔和填充（悬停）	--eds-color-bg-fill-muted-hover
禁用表面	--eds-color-bg-disabled
成功表面（柔和背景）	--eds-color-bg-success-surface
成功填充（强调）	--eds-color-bg-success-fill-emphasis-default
警告表面	--eds-color-bg-warning-surface
警告填充（强调）	--eds-color-bg-warning-fill-emphasis-default
危险 / 错误表面	--eds-color-bg-danger-surface
危险填充（强调）	--eds-color-bg-danger-fill-emphasis-default
信息表面	--eds-color-bg-info-surface
信息填充（强调）	--eds-color-bg-info-fill-emphasis-default
强调色表面	--eds-color-bg-accent-surface
强调色填充（强调）	--eds-color-bg-accent-fill-emphasis-default

文本令牌

用途	EDS 令牌
主要正文文本	--eds-color-text-strong
强调 / 填充背景上的文本	--eds-color-text-strong-on-emphasis
柔和 / 次要文本	--eds-color-text-subtle
禁用文本	--eds-color-text-disabled
链接	--eds-color-text-link
成功文本	--eds-color-text-success-strong
成功文本（柔和）	--eds-color-text-success-subtle
警告文本	--eds-color-text-warning-strong
危险 / 错误文本	--eds-color-text-danger-strong
信息文本	--eds-color-text-info-strong
强调色文本	--eds-color-text-accent-strong

边框令牌

用途	EDS 令牌
默认分隔线 / 边框	--eds-color-border-medium
柔和边框	--eds-color-border-subtle
强边框	--eds-color-border-strong
焦点环	--eds-color-border-focus
禁用边框	--eds-color-border-disabled
成功边框	--eds-color-border-success-medium
警告边框	--eds-color-border-warning-medium
危险边框	--eds-color-border-danger-medium
信息边框	--eds-color-border-info-medium
强调色边框	--eds-color-border-accent-medium

品牌限制：Equinor 红色（#FF1243）仅用于主徽标，绝不能用作 UI 操作色或语义色。所有可点击表面和语义表面均使用 EDS 颜色令牌。

在代码中访问令牌

在可能的情况下，优先在 styled-components 中使用 EDS CSS 自定义属性，而不是 @equinor/eds-tokens JS 对象——它们会自动遵循系统深色 / 浅色模式。

import styled from 'styled-components';

const Card = styled.div`
  background: var(--eds-color-bg-surface);
  border: 1px solid var(--eds-color-border-medium);
  color: var(--eds-color-text-strong);
`;

const PrimaryButton = styled.button`
  background: var(--eds-color-bg-fill-emphasis-default);
  color: var(--eds-color-text-strong-on-emphasis);

  &:hover {
    background: var(--eds-color-bg-fill-emphasis-hover);
  }

  &:disabled {
    background: var(--eds-color-bg-disabled);
    color: var(--eds-color-text-disabled);
  }
`;

---

排版

所有文本渲染均使用 @equinor/eds-core-react 中的 Typography。不要手动设置原始 font-size、font-family 或 line-height，应使用 EDS 的 variant 属性。

Variant 层级

级别	variant	用途
Display	h1	主视觉标题（应用中很少使用）
页面标题	h2	页面顶级标题
区块标题	h3	区块标题、卡片标题
子标题	h4	子区块、面板标题
上眉标题	overline	类别标签、面包屑层级文本
正文	body_long	多行正文
短正文	body_short	单行正文、表格单元格
说明文字	caption	元数据、时间戳、辅助文本
标签	label	表单字段标签

import { Typography } from '@equinor/eds-core-react';

// Correct
<Typography variant="h3">Section heading</Typography>
<Typography variant="body_short">Table cell value</Typography>
<Typography variant="caption">Last updated 2 hours ago</Typography>

// Wrong — never do this
<p style={{ fontSize: '14px' }}>…</p>

品牌限制

Equinor 品牌字体为 Equinor（用于营销场景）。Fusion 应用必须使用 @equinor/eds-core-react 定义的 EDS 系统字体，不要在应用 CSS 中导入或覆盖 Equinor 品牌字体。

---

间距令牌

对于 margin、padding 和 gap，请使用 @equinor/eds-tokens v2 中的 --eds-spacing-horizontal-<size> 和 --eds-spacing-vertical-<size>。不要使用任意像素值。

水平和垂直刻度共用相同的尺寸级别，但每个级别的数值可能相差几像素；请使用对应轴向的令牌（左右方向使用水平令牌，上下方向使用垂直令牌）。

尺寸	水平值	垂直值	用途
4xs	2 px	2 px	极小间隙、紧凑的图标内边距
3xs	4 px	4 px	XS 间隙
2xs	6 px	6 px	小型内嵌填充
xs	8 px	8 px	SM 间隙、紧凑列表间距
sm	12 px	12 px	内边距（标签、徽章）
md	16 px	16 px	标准内容内边距
lg	20 px	20 px	LG 间隙、区块间距
xl	24 px	24 px	XL 间隙、卡片间距
2xl	28 px	28 px	主要区块分隔
3xl	32 px	32 px	区块级留白

const Section = styled.section`
  padding-inline: var(--eds-spacing-horizontal-md);
  padding-block: var(--eds-spacing-vertical-lg);
  gap: var(--eds-spacing-vertical-sm);
`;

边框圆角

令牌 / 值	用途
--eds-shape-corners-border-radius	标准圆角（卡片、按钮）
border-radius: 0	锐利 / 方形边角
border-radius: 9999px	完全胶囊形（标签、芯片）

---

海拔与阴影

EDS v2（@equinor/eds-tokens ^2）不会将海拔作为 CSS 自定义属性公开。对于带海拔的表面，请使用 EDS Paper 组件，它会根据其 variant 应用正确的阴影；或者在 styled-components 中需要原始值时，通过 JS 对象导入使用 EDS Elevation 令牌。

import { Paper } from '@equinor/eds-core-react';

// Prefer Paper for cards/panels — elevation is handled automatically
<Paper elevation="raised">
  <CardContent />
</Paper>

如果需要从 JS 获取原始 box-shadow 值（很少见），请从 @equinor/eds-tokens 导入，不要硬编码值。

---

图标用法

请将 @equinor/eds-icons 与 EDS Icon 组件搭配使用。不要直接导入 SVG，也不要使用第三方图标集。始终通过 data 属性传递图标数据，不要使用字符串形式的 name 属性。@equinor/eds-icons 中的图标名称采用 snake_case。

import { Icon } from '@equinor/eds-core-react';
import { add, close, settings } from '@equinor/eds-icons';

// Pass icon data object via the `data` prop; provide `title` for accessibility
<Icon data={add} title="Add" />
<Icon data={close} title="Close" size={16} />
<Icon data={settings} title="Settings" />

图标尺寸遵循固定刻度：16、24（默认值）、32、40、48。不要设置任意尺寸。

---

页面布局区域

Fusion Portal 应用运行在 Fusion Portal shell 中，由其负责顶部导航、左侧栏和外边距。应用不得复制这些区域的功能或与之冲突。

三分区应用 shell

区域	组件	说明
顶部栏 / 标题栏	由 Fusion Portal shell 提供	应用不渲染全局标题栏
主内容区	<main> 或顶层应用 <div>	占用全部可用宽度和高度
侧面板 / 详情	@equinor/fusion-react-side-sheet	从右侧滑入；不要使用自定义定位的叠加层

布局约束

• 不要在根应用组件上添加外部 margin 或 padding——门户外壳会提供内容内边距。
• 内部区块间距请使用 --eds-spacing-horizontal-<size> / --eds-spacing-vertical-<size> 令牌。
• 不要在根容器上使用固定的 height——应允许内容延展至可用视口高度。
• 不要创建包裹整个页面的自定义可滚动容器——浏览器滚动是标准滚动方式。
• 固定高度的网格／表格区域可以使用嵌套的可滚动区域，但应审慎使用并明确界定范围。

空状态和加载状态

状态	模式
加载中	在内容区域居中显示 EDS CircularProgress 或 @equinor/fusion-react-progress-indicator ProgressIndicator
空（无数据）	使用 EDS Typography，可选用 EDS Button 作为主要操作；居中或顶部对齐
错误	使用颜色为 --eds-color-text-danger-strong 的 EDS Typography variant="body_short"，并提供重试操作

---

来源

• EDS 设计资源：https://eds.equinor.com/docs/resources/
• EDS 组件库：https://eds.equinor.com/components/
• Equinor 品牌颜色：https://communicationtoolbox.equinor.com/point/en/equinor/component/default/100056
• Equinor 品牌字体排印：https://communicationtoolbox.equinor.com/point/en/equinor/component/default/100059
• Equinor 品牌布局：https://communicationtoolbox.equinor.com/point/en/equinor/component/default/100061