# @financial-times/o3-foundation 中文文档

规范地址：https://npmcn.com/package/%40financial-times/o3-foundation/

版本：3\.14\.0
npm 元数据更新时间：2026-10-06T13:40:00.225Z
中文译文更新时间：2026-11-14T18:27:51.387Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40financial-times/o3-foundation
原文对照：https://npmcn.com/package/%40financial-times/o3-foundation/?lang=original
项目主页：https://registry.origami.ft.com/components/o3-foundation

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：575 kB，37 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-03-20T15:27:53.725Z
- 最新版本发布：2026-03-31T10:32:17.495Z
- 近 30 天下载量：14178（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 5 个）

## 中文简介

带有设计标志的折纸地基

## 安装

```sh
npm install @financial-times/o3-foundation
```

也可以使用：`pnpm add @financial-times/o3-foundation`、`yarn add @financial-times/o3-foundation`、`bun add @financial-times/o3-foundation`

## README

# o3 创建

-   [o3 创建](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-o3-foundation)
    -   [CSS 托肯斯语](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-css-tokens)
    -   [联合来文:托肯斯](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-JS-tokens)
    -   [类型](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-typography)
        -   [标题](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-headings)
        -   [机构/段落](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-bodyparagraphs)
        -   [链接](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-links)
        -   [列表](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-list)
        -   [包装](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-wrapper)
        -   [自定义属性](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-custom-properties)
    -   [正常化](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-normalisation)
    -   [与 Z 索引相叠](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-stacking-with-z-index)
    -   [焦点环](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-focus-rings)
    -   [字体](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-fonts)
    -   [图标](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-icons)
    -   [颜色](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-colours)
    -   [间距](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-spacing)
    -   [网格](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-grid)
    -   [助教课程](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-helper-classes)
    -   [移徙](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-migration)
    -   [联系人](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-contact)
    -   [许可证](https://npmcn.com/package/%40financial-times/o3-foundation/#readme-licence)

# CSS 托肯斯语

`o3-foundation` 提供CSS自定义属性,用于代表颜色,打字尺度,间距,图标,网格和打字组件,如标题,正文,链接等的设计符号.

`o3-foundation` 支持品牌: `core`, (中文(简体) ), `internal`, (中文(简体) ), `professional`, (中文(简体) ), `sustainable-views` 财务报告和审定财务报表 `whitelabel`。 。 。 .

导入您所选的品牌开始在您的 CSS/ SCSS 中使用符号 :

```css
@import '@financial-times/o3-foundation/css/core.css';

body {
    background-color: var(--o3-color-use-case-page-background);
    font-size: var(--o3-font-size-1);
    line-height: var(--o3-font-lineheight-0);
}
```

为了增加另一个品牌的支持, 导入其标志:

```diff
+@import '@financial-times/o3-foundation/css/core.css';
+@import '@financial-times/o3-foundation/css/internal.css';

.example-custom-link {
 color: var(--o3-color-link);
 font-size: var(--o3-font-size-3);
 line-height: var(--o3-lineheight-3);
}
```

然后应用品牌数据选择器 `data-o3-brand="[BRAND]"` 在 HTML 中的容器元素上.

```html
<body data-o3-brand="core">
    <a href="#" class="example-custom-link">Example</a>
</body>
```

参见所有 CSS 每个品牌的托肯 `_variables.css` 文件 :

-   [FT平克 (核心)](https://npmcn.com/package/%40financial-times/o3-foundation/src/css/tokens/core/_variables.css)
-   [FT 专业人员](https://npmcn.com/package/%40financial-times/o3-foundation/src/css/tokens/core/professional/_variables.css)
-   [白色标签](https://npmcn.com/package/%40financial-times/o3-foundation/src/css/tokens/white-label/_variables.css)
-   [内部](https://npmcn.com/package/%40financial-times/o3-foundation/src/css/tokens/internal/_variables.css)
-   [可持续观点](https://npmcn.com/package/%40financial-times/o3-foundation/src/css/tokens/sustainable-views/_variables.css)

# 联合来文:托肯斯

基础令牌也作为JavaScript提供. 有两种形式:

1.  以 kebab 实例符号命名的 ESM 默认导出.
2.  无害环境管理为每个标志指定了出口名称,并命名了骆驼案例标志.

每个格式提供两个符号文件:

1.  图标标志.
2.  其他所有品牌的标志.

## 默认导出

-   `esm/tokens/[brand].js`
-   `esm/tokens/icons.js`

Pro:与CSS自定义属性相同的代号命名惯例,用于可发现性和重构. 共通: 未使用的令牌无法通过 [树摇](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking),因此可以增加最后捆绑大小.

```js
import tokens from '@financial-times/o3-foundation/esm/tokens/[brand].js';

const example = `The hex for FT Pink is ${tokens['o3-color-palette-ft-pink']}`;
```

## 命名导出

-   `esm/tokens/[brand]-named.js`
-   `esm/tokens/icons-named.js`

赞成:支持 [树摇](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) 为了最小的捆绑大小. Con:使用蛇案标志名,使得无法在JS和CSS之间搜索一个标志.

```js
import {o3_color_palette_ft_pink} from '@financial-times/o3-foundation/esm/tokens/[brand]-named.js';

const example = `The hex for FT Pink is ${o3_color_palette_ft_pink}`;
```

## 类型

### 资源

-   折纸站 [https://zeroheight.com/04668e87f/v/latest/p/03a2c7-打字法](https://zeroheight.com/04668e87f/v/latest/p/03a2c7-typography)
-   故事书-https://o3.origami.ft.com/?path=/docs/o3-foundation-o3-typography-readme-jsx-documentation (中文(简体) )
-   Figma - https://www.figma.com/design/VVM0PixrY3IRZq2ZUTdWfU/%F0%9F%92%A0-Core--Origami-o3-?node-id=3-2&p=f&m=dev 互联网档案馆的存檔,存档日期2013-12-2

### 列表

`o3-foundation` 提供有序和无序清单的样式:

#### HTML 语言

```html
<ul class="o3-typography-ul">
    <li>Item 1</li>
    <li>Item 2</li>
    <li>Item 3</li>
</ul>

<ol class="o3-typography-ol">
    <li>Item 1</li>
    <li>Item 2</li>
    <li>Item 3</li>
</ol>
```

#### 联合来文十

```jsx
import { List } from '@financial-times/o3-foundation/cjs'; // or esm;

<UnorderedList>
 <li>Item 1</li>
 <li>Item 2</li>
 <li>Item 3</li>
</UnorderedList>

<OrderedList>
 <li>Item 1</li>
 <li>Item 2</li>
 <li>Item 3</li>
</OrderedList>
```

### 包装

包装可以用于给身体的块作样式而不需要将类应用于每个元素. 当许多组件的大型体需要造型时,这一点可能有用:

#### HTML 语言

```html
<div class="o3-typography-wrapper"></div>
```

```jsx
import {Wrapper} from '@financial-times/o3-foundation/cjs'; // or esm

<Wrapper>
    <h1>This heading gets styled.</h1>
    <p>And so does this paragraphy of text.</p>
    <h2>This gets styled also</h2>
</Wrapper>;
```

### 突出显示 (粗体)

使用打字法使用大小写来给身体内容以更粗体的样式:

```html
<p class="o3-type-body-base">
    This is <strong class="o3-type-body">really</strong> important.
</p>
```

### 自定义属性

#### 最大行宽度

`o3-foundation` 包括 CSS 自定义属性 `--o3-typography-max-line-width` 为可读性限制打字行长度. 举个例子.

```css
.my-selector {
    max-width: var(--o3-typography-max-line-width);
}
```

您可能想根据我们 [设计准则](https://origami-for-everyone.ft.com/guides/typography/)为此,我们建议使用 [c 相对单位](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units#distance_units)。 。 。 .

举个例子.

```css
.my-selector {
    max-width: 70ch;
}
```

## 正常化

`o3-foundation` 提供了一组CSS自定义属性,用于实现默认浏览器样式的常态化,并对元素应用了一组默认. 这是为了确保所有项目和各自品牌有一个一致的起点。 正常化清单包括:

-   规范样式 `<html>, <body>`
-   在 Mozilla 和 WebKit 浏览器中添加字体吸附
-   减少提出动议的用户
-   连接正常化
-   文本相关要素的正常化
-   规范形式元素

## 与 Z 索引相叠

我们建议避免设置 `z-index`。在必要时, Origami 提供了一些标准值作为自定义属性。 这有助于防止项目内部的冲突.

1.  [没有 Z 索引属性的堆栈](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_without_z-index) 在可能的情况下.
2.  目标减少 `z-index` 而不是自己养活自己 `z-index` 数值.
3.  何处 `z-index` ,使用以下标准值。 记住,虽然, `z-index` 不是一种全球价值,只适用于 [堆叠上下文( mdn)](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context)你可能会找到乔什·W·克莫的 [什么地狱,Z指数?](https://www.joshwcomeau.com/css/stacking-contexts/) 一个很好的介绍.

-   `--o3-z-index`: 如果 `z-index` 这是不可避免的.
-   `--o3-z-popover`: 覆盖内容的弹出式, 如选择、 自动完成下拉、 日历部件、 工具提示 .
-   `--o3-z-navigation-popover`:导航会覆盖内容,例如粘贴头和抽屉.
-   `--o3-z-message-polite-popover`:非模式性,非批判性的信息覆盖,如营销旗.
-   `--o3-z-message-service-popover`: 吐司等重要服务或状态信息的非模式,信息覆盖.
-   `--o3-z-modal-dialog`: Modal 对话框 / 覆盖,防止与基本内容的互动.

如果两个要素属于同一类别并相互重叠,可递增一个:

```css
.navigation-drawer {
    z-index: calc(var(--o3-z-navigation-popover) + 1);
}

.navigation-sticky {
    z-index: var(--o3-z-navigation-popover);
}
```

## 焦点环

`o3-foundation` 以两种风格提供焦点环.

1.  默认情况下一个单一的大纲,例如关于锚地元素的大纲,它是无侵扰性的.
2.  按钮和窗体元素的双聚焦环,无论元素颜色和背景如何,这都确保了对比.

双焦环由两个环组成:外黑环和内白环. 默认外环为黑色,外环为白色. 然而,如果使用反向主题,颜色会被倒转.

如果需要将焦点环应用到与上述元素不同的元素上,可以使用 `o3-apply-focus-ring` 课上的元素.

用户也可以通过使用 `o3-revert-focus` 课在元素.

## 字体

`o3-foundation` 定义 2 `@font-face`第一个是 `Metric2-VF` 并用于所有品牌。 第二个是 `FinancierDisplayWeb` 目前仅由核心品牌使用.

## 图标

CSS 自定义图标属性以格式包含每个品牌: `--o3-icon-[ICON NAME]`。 。 。 .

图标 CSS 自定义属性是 [url () CSS 函数](https://developer.mozilla.org/en-US/docs/Web/CSS/url) 用于编码的图标 SVG。 它可能在任何地方使用 [url( )](https://developer.mozilla.org/en-US/docs/Web/CSS/url) 可能用于例如: `background-image` 财务报告和审定财务报表 `mask`。 。 。 .

例如,创建 `1rem` 从当前文本颜色继承颜色的大小图标 :

```css
.example-icon-use {
    /* Create a square the size we want an icon */
    display: inline-block;
    width: 1rem;
    height: 1rem;
    /* Set the icon colour, In this case match the
     current foreground text colour. */
    background-color: currentColor;
    /* Mask the square with an Origami icon. */
    mask-image: var(--o3-icon-plus);
    mask-repeat: no-repeat;
    mask-size: contain;
}
```

### 资源

-   折纸站 [https://zeroheight.com/04668e87f/v/latest/p/48c763-摄影](https://zeroheight.com/04668e87f/v/latest/p/48c763-iconography)
-   故事书-https://o3.origami.ft.com/?path=/story/o3-foundation-o3-icon-icon - C

## 颜色

o3- foundation 为三种颜色提供了 CSS 自定义属性:

-   调色板: 底色, 如 `--o3-color-palette-paper`, (中文(简体) ), `--o3-color-palette-teal`。 。 。 .
-   使用大小写: 语义颜色, 如 `--o3-color-use-case-page-background`, (中文(简体) ), `--o3-color-use-case-page-inverse-background`。 。 。 .
-   调色板颜色: 调色板颜色 `--o3-color-palette-black-10`, (中文(简体) ), `--o3-color-palette-teal-100`。 。 。 .

我们建议在存在使用大小写符号的地方使用该符号,因为这使我们能够灵活地根据使用方式更新基本颜色。 然而,最好直接使用调色板或锡克颜色,而不是错误地使用用例符号.

示例

```css
.example-text {
    color: var(--o3-color-palette-black);
}
```

### 资源

-   折纸站 [https://zeroheight.com/04668e87f/v/latest/p/22a635-彩色](https://zeroheight.com/04668e87f/v/latest/p/22a635-colour)
-   故事书-https://o3.origami.ft.com/?path=/story/o3-foundation-o3-color-primary-palette 页面存档备份,存于互联网档案馆
-   Figma - https://www.figma.com/design/VVM0PixrY3IRZq2ZUTdWfU/%F0%9F%92%A0-Core--Origami-o3-?node-id=0-1&p=f&m=dev

## 间距

o3- foundation 为格式的标准间距值提供 CSS 自定义属性 : `--o3-spacing-[spacing size]`。这些随T恤大小从 `5xs` 改为 `4xl`。 。 。 .

示例

```css
.example-spacing {
    margin: var(--o3-spacing-2xs);
}
```

见文件a [完整间隔符号列表](https://npmcn.com/components/o3-foundation/docs/spacing.md)。 。 。 .

### 资源

-   折纸站 [https://zeroheight.com/04668e87f/v/latest/p/43ea5b-scale (中文(简体) )](https://zeroheight.com/04668e87f/v/latest/p/43ea5b-scale)
-   故事集-https://o3.origami.ft.com/?path=/story/o3-foundation-o3-相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相距相
-   Figma - https://www.figma.com/design/VVM0PixrY3IRZq2ZUTdWfU/%F0%9F%92%A0-Core--Origami-o3-?node-id=5499-2000&p=f&m=dev

## 网格

这个 `o3-grid` 系统,由 `o3-foundation`,规范跨英尺网格的使用。 这个 `o3-grid` 在不同屏幕大小上响应,并与 [`o-grid`](https://o2-core.origami.ft.com/?path=/docs/maintained-o-grid-readme--docs) 组件。 关于电网系统的更详细准则,请检查我们的文档 [`o3-grid`](https://origami-beta.ft.com/guides/grid/)。 。 。 .

对于方便和标准化的网格布局,应用 `o3-grid` 分类到元素 :

```html
<div class="o3-grid">
    <!-- Grid Items -->
</div>
```

这个 `o3-grid` 布局模板遵循特定结构:

```txt
`bleed-start content-start [REST_OF_THE_COLUMNS] content-end bleed-end`,
```

O3-网格系统适应不同的屏幕大小,列的数量根据取景器大小而变化,参见设计指南 [细节](https://origami-beta.ft.com/guides/grid/)。 。 。 .

-   内容领域 : 网格的主要内容区域由 `content-start` 财务报告和审定财务报表 `content-end` 边框.
-   扩展版式所覆盖的列 : `bleed-start` 打开 `bleed-end`:这些特殊的柱子延伸出十二柱网格之外,到达了取景口的边缘. 这使得您可以创建内容从屏幕上延伸出"充血"的布局. 这些柱子被用作边距区域,提供围绕您中心内容的可视呼吸空间.
-   `[REST_OF_THE_COLUMNS]`: 这是您在网格中可能需要的任何额外的列.

### 资源

-   折纸站 [https://origami.ft.com/foundations/grid/ (中文(简体) )](https://origami.ft.com/foundations/grid/)
-   故事书-https://o3.origami.ft.com/?path=/story/o3-foundation-o3-grid-grid-grid 互联网档案馆的存檔,存档日期2013-12-22

### 定位网格项目

您可以使用 `grid-column` 样式或 css 属性 :

```html
<div class="o3-grid">
    <div style="grid-column: content-start / content-end;">
        Spans the entire content area
    </div>
    <div style="grid-column: content-start / span 4;">
        Starts at `content-start`, spans 4 columns
    </div>
    <div style="grid-column: content-start / span 2;">
        Starts at `content-start`, spans 2 columns
    </div>
    <div style="grid-column: span 1 / content-end;">
        Ends at `content-end`, spans 1 column back
    </div>
    <div style="grid-column: bleed-left / bleed-right;">
        Spans the entire viewport (full bleed)
    </div>
    <div style="grid-column: bleed-left / content-end;">
        Starts at the left edge, ends at `content-end`
    </div>
</div>
```

### 使用有巢子的网格

在某些情况下,一个元素可能被深深地嵌入并无法进入电网. o3- foundation 提供了 CSS 自定义属性, 帮助将元素与网格对齐 :

```css
.my-nested-class {
    --o3-grid-columns-to-span-count: 6;
    width: var(--o3-grid-columns-to-span-width);
}
```

使用 `--o3-grid-columns-to-span-count` 以控制您想要元素覆盖多少列。 在这个例子中 `my-nested-class` 相当于6个栏. `--o3-grid-columns-to-span-count` 必须定义为 `.o3-grid-columns-to-span-width` 工作的时候.

### 网格的高级使用

高级用途 `o3-foundation` 为您可以设置在类上的网格提供 CSS 自定义属性 :

```css
.example-class {
    display: grid;
    /* Controls the column structure of your grid. */
    grid-template-columns: var(--o3-grid-template);
    /* Defines named areas for grid item placement. */
    grid-template-areas: var(--o3-grid-area);
    /* Manages the spacing between grid columns. */
    column-gap: var(--o3-grid-gap);
}
```

## 助教课程

`o3-foundation` 提供一套助教课程,帮助完成共同的任务。 助教课程列表包括:

-   `o3-visually-hidden`: 隐藏一个可视化的元素, 但留给屏幕阅读器使用
-   `o3-box-sizing-border-box`: 应用 `box-sizing: border-box` 及其所有子女的权利

## 移徙

| 状态 | 主要版本 | 最后一个小版本 | 移徙指南 |
| :-: | :-: | :-: | :-: |
| 活动 | 3个 | 不详 | [迁移到 v3](https://npmcn.com/package/%40financial-times/o3-foundation/MIGRATION.md#migrating-from-v2-to-v3) |
| 已贬值 | 2个 | 第2.3条 | [迁移到 v2](https://npmcn.com/package/%40financial-times/o3-foundation/MIGRATION.md#migrating-from-v1-to-v2) |
| 已贬值 | 1个 | \- 说吧 | 不详 |

## 联系人

如果您对本部分有任何问题或评论,或需要帮助使用本部分,请 [提出问题](https://github.com/Financial-Times/origami/issues/new?labels=o3-foundation,components)访问 [#origami - 支持](https://financialtimes.slack.com/messages/#origami-support/) 或电子邮件 [折纸. support@ft.com](mailto:origami.support@ft.com)。 。 。 .

## 许可证

本软件由金融时报根据以下规定出版: [麻省理工学院许可证](http://opensource.org/licenses/MIT)。 。 。 .

## 常见问题

### @financial-times/o3-foundation 是什么？

带有设计标志的折纸地基

### 如何安装 @financial-times/o3-foundation？

在项目目录运行 npm install @financial-times/o3-foundation，或使用 pnpm add / yarn add / bun add。

### @financial-times/o3-foundation 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @financial-times/o3-foundation 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @financial-times/o3-foundation 可以商用吗？

@financial-times/o3-foundation 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @financial-times/o3-foundation 的下载量有多少？

根据 npm 官方下载统计，@financial-times/o3-foundation 在 2026/10/15 – 2026/11/13 这 30 天内被下载 14,178 次，日均约 473 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @financial-times/o3-foundation 还在维护吗？

最新版本 3\.14\.0 发布于 2026/03/31（7 个月前）；至今共发布 55 个版本，其中过去 12 个月发布了 5 个；首次发布于 2024/03/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

