# @cssints/ramp 中文文档

规范地址：https://npmcn.com/package/%40cssints/ramp/

版本：0\.35\.1
npm 元数据更新时间：2026-11-07T14:56:19.945Z
中文译文更新时间：2026-11-11T03:53:35.066Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cssints/ramp
原文对照：https://npmcn.com/package/%40cssints/ramp/?lang=original
项目主页：https://cssints.dev/
源码仓库：https://github.com/alexeiaccio/css-in-ts-compiler

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

- 包体积（解压后）：16.6 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：cssints ^0\.35\.0
- 首次发布：2026-10-10T20:57:56.840Z
- 最新版本发布：2026-11-07T14:56:19.398Z
- 近 30 天下载量：7158（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 42 个）

## 中文简介

作为 DTCG 数据的 OKLCH 彩色坡道: 轻度坡道, 或 WCAG 2 与背景对比所选择的阶梯

## 安装

```sh
npm install @cssints/ramp
```

也可以使用：`pnpm add @cssints/ramp`、`yarn add @cssints/ramp`、`bun add @cssints/ramp`

## README

# @ cssints/ ramp (英语)

OKLCH 彩色坡道,用于 [点缀](https://npmcn.com/package/README.md),在构建时计算. `ramp(base, options)` 返回纯 DTCG 数据 (颜色组, 步骤) `"1"` 改为 `"N"`,每个十六进制颜色在 SRGB 中) `createTokens` 自己,还有 `overrides(ramp)` 将斜坡变成覆盖对象 `createGlobalTheme`。软件包没有运行时间也没有 `scope()`: 像套装 [@ cssints/ tokens (英语)](https://npmcn.com/package/%40cssints/tokens/README.md),一个斜坡是数据,所以它去 任何组名,坐 除了一个呼叫中的其他标志, 它的步骤得到 `@property` 规则、主题和 `check.contrast` 从csints.

```ts
// tokens.ts
import { createGlobalTheme, createTokens, media } from "cssints" with { type: "cssints" };
import { overrides, ramp } from "@cssints/ramp";

const ratios = [1.2, 1.5, 3, 4.5, 7] as const;

export const t = createTokens({
  bg: { $type: "color", $value: "#ffffff" },
  blue: ramp("#2563eb", { mode: "contrast", ratios, background: "#ffffff" }),
  gray: ramp("#6b7280", { mode: "lightness", steps: 9 }),
});

// the same ratios on the dark background, under the same condition as it
createGlobalTheme(t, media("(prefers-color-scheme: dark)"), {
  bg: "#111111",
  blue: overrides(ramp("#2563eb", { mode: "contrast", ratios, background: "#111111" })),
});
```

```ts
// text.ts
import { bg, check, cn, color } from "cssints" with { type: "cssints" };

import { t } from "./tokens.ts";

check.contrast(t.blue._3, t.bg, { min: 3 }); // borders, large text
check.contrast(t.blue._4, t.bg, { min: 4.5 }); // body text, light and dark
export const text = cn(color(t.blue._4), bg(t.bg));
```

说明 `text.ts`数字 :

```css
@property --bg {
  syntax: "<color>";
  inherits: true;
  initial-value: #ffffff;
}
@property --blue-4 {
  syntax: "<color>";
  inherits: true;
  initial-value: #356fec;
}
@layer _.k {
  @media (prefers-color-scheme: dark) {
    :root {
      --bg: #111111;
      --blue-1: #041e59;
      --blue-2: #092d7c;
      --blue-3: #1855db;
      --blue-4: #3d76ed;
      --blue-5: #719df2;
    }
  }
}
@layer _.a {
  ._1od4w7v {
    color: var(--blue-4);
  }
  ._q77new {
    background-color: var(--bg);
  }
}
```

## 模式

每一步都保持基座的OKLCH花和它的染色体 _相对于 sRGB 游戏_ (nutelch的主意):基地的染色体 超过最 铬 sRGB 在基地的轻而易举。 在另一个光线上的一步 得到同样的份额 所以一个活生生的基地 紧贴着它的胸口 向着白色和黑色 以及每一步 以构造方式在 sRGB 中(六进制是八位相舍入相色,从不剪入相舍入相)。 灰底给一个 中性斜坡。 基地本身不一定是一个步骤.

-   **`{ mode: "lightness", steps, lightness? }`**数字 : `steps` 颜色在 OKLCH 光度中均匀相差,从 `lightness[0]` 改为 `lightness[1]` (默认) `[0.97, 0.25]`首先,最轻的. `#2563eb` 有9个步骤: `#f1f5fe`, (中文(简体) ), `#c6d8f9`, (中文(简体) ), `#9cbbf5`, (中文(简体) ), `#719df2`, (中文(简体) ), `#467cee`, (中文(简体) ), `#1a59e6`, (中文(简体) ), `#1143b2`, (中文(简体) ), `#092f81`, (中文(简体) ), `#041b53`。 。 。 .
    
-   **`{ mode: "contrast", ratios, background }`** (Leonardo的主意):按给定的顺序,每分一分. 一个步骤 查找光度( 分节, 在它输出的十六进制值上) , 以查找最接近背景的颜色, WCAG 2 比率 在目标或以上。 台阶在浅色背景上变暗,在暗色背景上变浅(侧面) - 和更多的房间. `#2563eb` 与 `[1.2, 1.5, 3, 4.5, 7]`数字 :
    
    | 背景情况 | 1个 | 2个 | 3个 | 页:1 | 页:1 |
    | --- | --- | --- | --- | --- | --- |
    | `#ffffff` | `#e1ebfc` 1.20 联合国 | `#bfd3f9` 1.51 联合国 | `#6593f0` 3.00 (中文(简体) ) | `#356fec` 4.52 (简体中文) | `#164ecc` 7.00 (中文(简体) ) |
    | `#111111` | `#041e59` 1.20 联合国 | `#092d7c` 1.50 (中文(简体) ) | `#1855db` 3.02 (中文(简体) ) | `#3d76ed` 4.50 (中文(简体) ) | `#719df2` 7.02 (中文(简体) ) |
    

数字是决定性的:相同的基数和选项在每个机器上给出相同的六分法(没有随机性,一个固定 双节步骤的数目).

## 对比度

如何对比斜坡的承诺,确切地说:

-   **每个步骤 `i` 已经 `ratio(step, background) >= ratios[i]`**,以 `check.contrast` 计算它: 库罗里 `wcagLuminance` 用于剪接到 SRGB 的颜色, `(L1 + 0.05) / (L2 + 0.05)`,没有四舍五入。 测量的 脚步输出六分之一,所以 `check.contrast(t.blue._4, t.bg, { min: 4.5 })` 当 `t.bg` 持有相同的 `background`。搜索只保留过关的颜色,所以这不在于搜索的趋同.
-   **一点点.** 台阶是沿坡道最接近背景的通向颜色, 在8位阶内: 在测试中 4个背景的8个步骤如下 `ratio * 1.02`。所以,一个支票 持有超过该步骤 失败 : `check.contrast(t.blue._4, t.bg, { min: 4.6 })` 实值 `contrast 4.52 is below 4.6: blue.4 #356fec on bg #ffffff, in the default values`,在黑暗的主题中也是如此 (4.50) (中文(简体) ). 按自己的比例检查每个步骤.
-   **就在这个背景下.** 保持比例 `background` 坡道是用来建造的。 在另一个背景下 (a) 主题,为它作一个坡道,比例相同,并设置在同一条件或选择器下,如上; `check.contrast` 然后对照主题的背景检查每个步骤.
-   **灯光斜坡保证不占比**;检查所使用的对.
-   **仅限WCAG 2**而不是非洲足协。 WCAG 2出道口不是APCA出道口,特别是对于暗地上发光文字.

## 限制

-   **出现错误** 当对模块进行评估时,它们就是构建错误:一个基础或背景不是 颜色( r)`@cssints/ramp: the base "banana" is not a colour`或半透明, `steps` 这不是一个完整的数字来自 1,0.1外的光度和1.21外或背景上无法达到的比例 (单位:千美元)`ratio 21 is out of reach on #111: at most 18.88 (white)`) (中文(简体) ). 中灰背景在两侧都留下了很小的空间.
    
-   **分级比例的分数.** 升起比率让台阶远离背景,但坡道不排序 给你的 光度是OKLCH光度,不是光度:一个光度的两个克有不同的比例.
    
-   **仅限SRGB.** P3变体(`color(display-p3 …)`未发运 : `check.contrast` 剪辑到 sRGB 的颜色, 所以是一个 P3 步骤将被检查为显示的颜色之外的另一颜色,以及 `color()` 值按类型排列颜色语法 (千分百的即兴表演是标志) 一种六分之一的便宜。 SRGB 外部的基数被读取,其染色体份额被封顶 在游戏中.
    
-   **编辑器显示 `#${string}`。 。 。 .** 当模块运行时计算出一步的值,所以其类型是 `` `#${string}` ``, (中文(简体) ), 不是字面的六进制( 显示) ``Token<"color", true, `#${string}`>``) (中文(简体) ). 它的类型仍然是一种颜色符号,步骤是 已知(`t.blue._6` ),建筑则检查数值.
    
-   **类型成本** (tsgo,每行一个文件):
    
    | 打电话 | 证据 | 检查时间 |
    | --- | --- | --- |
    | `color("red")` (基线) | 0.16门 | 0.09 (英语) |
    | 10个坡道,10个台阶(100个道具) | 0.15海里 | 0.09 (英语) |
    | 100个坡道,10个台阶(1 000个道具) | 0.16门 | 零点10分 |
    | 同样的1000个符号和它们的主题 | 0.24门 | 0.13s (中文(简体) ) |
    
    步骤成本约为10个即时符号(每个值都有一个类型) `` `#${string}` ``),作为主题约80个 覆盖, 因此一个坡道 和 @ cssints/ tokens 的十六进制一样便宜 .
    

```bash
cd packages/ramp && bun run test        # the ramp maths, then a fixture through the engine (check.contrast passes, a tight pair fails)
cd packages/ramp && bun run typecheck   # the type test (test/types/ramp.ts)
```

## 贷项

两个想法,在这里写着: 相对于 sRGB 游戏的染色体 [坚果](https://github.com/meodai/nutelch) (麻省理工学院, 大卫·艾恩(David Aerne),以及寻找符合对比比的光度,来自 [莱昂纳多](https://github.com/adobe/leonardo) (阿帕切-2.0,阿多贝. 颜色数学是 [库罗里语name](https://culorijs.org/) (麻省理工学院,丹·伯佐),一个附属公司. 没有代码 复制.

## 常见问题

### @cssints/ramp 是什么？

作为 DTCG 数据的 OKLCH 彩色坡道: 轻度坡道, 或 WCAG 2 与背景对比所选择的阶梯

### 如何安装 @cssints/ramp？

在项目目录运行 npm install @cssints/ramp，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：cssints（^0\.35\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cssints/ramp 支持 TypeScript 吗？

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

### @cssints/ramp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cssints/ramp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cssints/ramp 可以商用吗？

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

### @cssints/ramp 的下载量有多少？

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

### @cssints/ramp 还在维护吗？

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