跳转至

Code 组件契约

契约概览

区域 契约
公共契约 Code 从 @astryxdesign/core/Code 导出;它要求 children,默认将 color 设为 primary,可选接受 secondary 或 inherit,并接受 size="inherit"。
行为 Code 渲染一个语义化的 <code> 元素,默认使用代码类型尺度,并可通过显式 props 继承周围环境的颜色或排版。
最终用户影响 读者获得可识别的行内代码,它会换行而不是迫使正文容器变宽。
构建者影响 无;该记录描述已发布的行为。简短的行内引用使用 Code;独立或多行代码片段使用 CodeBlock。
兼容性/就绪状态 已发布的行为记录为当前状态;无 API、默认值或输出变更。
审查检查 拒绝非 code 根元素、丢弃的内容或根 props、未指向根元素的 ref、未反映在 code 目标上的视觉 prop、未记录的已发布 props/默认值,或将行内组件变成块级代码替代品的变更。
治理规则 architecture:public-component-api/INV1,INV5,INV6,INV8–INV9;architecture:component-theming-surface/INV3–INV7;architecture:component-test-sufficiency/INV1–INV7,INV10–INV11。

此表是审查预览;以下正文具有权威性。

意图

在正文中以原生代码语义呈现简短的技术引用,并提供紧凑、可主题化的行内处理方式。

兼容性与迁移

  • 已发布的默认值保留:是
  • 兼容性类别:记录已发布的行为;无运行时、类型、默认值、样式、目标或导出变更
  • 受控/非受控行为:不适用;Code 不拥有任何状态
  • 迁移决策:无

消费者迁移说明属于消费者文档和发布说明。

所有权边界

拥有

  • 语义化的行内代码根元素、代码排版与换行、primary/secondary/inherited 文本颜色、可选的继承字号、受支持的根 props 和 ref,以及 code 主题目标。

不拥有 / 非目标

  • 语法高亮、行号、复制行为、标题、围栏或多行呈现 — 由 component:CodeBlock 拥有。
  • 调用方提供的代码内容的含义、本地化或双向排序 — 由产品调用点和平台文本引擎拥有。
  • 交互操作或导航契约 — 构建者在 Code 之外组合适当的 Button 或 Link。

公共概念

概念 封闭值或状态 含义 可用性 默认值 所有者 稳定性 无效值行为
color primary、secondary、inherit 选择行内代码文本颜色的来源。 每次渲染 primary component:Code 稳定 被公共类型拒绝
size 代码尺度、继承 省略时使用代码类型尺度,继承时使用周围环境的排版。 每次渲染 代码尺度 component:Code 稳定 被公共类型拒绝
code content 调用方提供的 React 内容 提供语义化 code 元素内部的内容。 每次渲染 必需 产品调用点 稳定 普通 React 渲染

行为与布局契约

ID 不变量 依据
FR1 Code 渲染一个包含调用方内容的语义化 <code> 根元素。 已发布的源码、测试、文档和 HTML 语义
FR2 根元素使用代码字体族,当省略 size 时,使用 --text-code-size 及周围环境的行高;size="inherit" 还会继承周围环境的字号。color 选择主文本(默认)、次要文本或继承的颜色。 已发布的公共类型、源码、测试和 stories
FR3 根元素以 --radius-inner 圆角绘制 --color-background-muted,内联方向使用逻辑 --spacing-1、块方向使用 --spacing-0 内边距;长内联内容断行换行,而不是加宽其正文容器。 已发布源码与代表性正文故事
FR4 受支持的 DOM props、className、style 和 xstyle 组合于根元素上,且公共 ref 可达该根元素。code 目标与 data-color 反射在调用方 DOM props 之后应用;xstyle、className 和 style 按 ORD1 规定的顺序组合。 architecture:public-component-api/INV5,INV6,INV8;已发布源码与测试
FR5 已绘制的根元素承载公共 code 目标并反映 color 视觉轴。已发布表面不包含任何内部目标或独立状态目标。 architecture:component-theming-surface/INV3–INV7;源码与目标清单

允许的变化

  • AV1 — 主题绘制。 code 目标可变更受支持的排版、颜色、背景、内边距、圆角及其他可接受的绘制,而不改变语义内容或内联归属。
  • AV2 — 调用方内容。 Code 内容可包含已发布 children 类型接受的任何 React 内容;其含义仍归调用方所有。
  • AV3 — 周围排版。 构建者可显式继承周围颜色或字号;省略时保留组件默认值。

代表性状态

状态 必需不变式 允许的变化
默认 语义化代码根元素、主色、代码字阶字号。 调用方内容与主题绘制。
次要颜色 相同根元素与布局,使用次要文本颜色来源。 调用方内容与主题绘制。
继承颜色 相同根元素与布局,使用周围文本颜色。 周围颜色与调用方内容。
继承字号 相同根元素与绘制,使用周围字体大小与行高。 周围排版与调用方内容。
长内联内容 内容换行,不依赖组件自有的物理方向几何。 调用方内容中的可断行位置。

转换与优先级顺序

  • ORD1 — 根元素 props。 受支持的调用方 DOM props → 组件目标与视觉轴反射 → base/color/size/xstyle 类 → 使用方 class 与内联样式组合。
  • ORD2 — 排版。 省略 size → 代码字阶字号;显式 inherit → 周围字体大小与行高。

性能与资源

  • PR1 — 纯渲染。 Code 不拥有任何状态、Effect、监听器、观察器、定时器、外部资源或异步工作。

无障碍契约

  • AR1 — 原生语义。 根元素保持为语义化 <code> 元素,不添加任何交互角色、焦点目标或组件撰写的可访问名称。
  • AR2 — 调用方内容。 调用方提供的内容保持为可访问内容;Code 不翻译、隐藏或复制它。

设计关系

解剖结构或状态 设计要求 表现权威 层级角色 组件契约
容器 通过代码排版与紧凑背景处理区分短技术文本。 已观察到的发布表现 内联技术内容 FR1–FR5, AR1–AR2

当前没有设计记录规定 Code 的具体像素;精确调优保留在代码与视觉证据中。

主题解剖结构

{
  "Container": {"target": "code"}
}

家族与系统关系

  • architecture:public-component-api 负责导出可达性、受支持的根元素 props、样式组合、ref 可达性、已发布默认值与使用方文档。
  • architecture:component-theming-surface 负责目标限定、目标放置、视觉轴反射与元数据归属。
  • architecture:component-test-sufficiency 负责合理证据集。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1, AR1, AR2 Code.test.tsx 渲染测试 默认 非 code 根元素或内容缺失会失败。缺口:当包装器成为根元素时渲染测试仍然通过,并且如果 Code 添加了角色、Tab 停靠点或名称,没有测试会失败,同时也没有无障碍树检查来证明暴露的内容(spec:AST-009 FR3)。 audit:Code/a11y
FR2, ORD2 Code.test.tsx 颜色测试;Code.stories.tsx 的 Colors 和 TextSizes 在故事播放守卫中的播放检查 主色、次色、继承色;四种文本大小下的继承尺寸 缺少 data-color 反射、次色与主色相同、继承的颜色或尺寸与父级不匹配,或所有继承尺寸都坍缩为同一个值,都会失败。缺口:代码字体族和默认 --text-code-size 除视觉基线外没有自动化检查。 audit:Code/behavior
FR3 Code.stories.tsx 的 LongInlineContent 播放检查;稳定的视觉基线 core-code--default 受约束的散文文本中含有一个不间断的标识符;默认 如果 Code 停止换行或撑宽其容器,播放检查会失败;背景、圆角或内边距发生变化时会以变更后的状态返回以供审查。缺口:没有单元测试对绘制或内边距进行断言。 audit:Code/responsive
FR4, ORD1 Code.test.tsx 的 ref 与透传测试 Ref;aria-label、className、style、xstyle ref 丢失,或调用方的 prop、类、内联样式或 xstyle 类丢失,都会失败。缺口:当包装器接收到 ref 时 ref 测试仍然通过,并且没有测试断言 target 和 data-color 会覆盖调用方的 DOM props,或断言调用方的 xstyle 遵循基础样式。 audit:Code/api
FR5 themingTargets.test.ts;Code.test.tsx 颜色测试 每个颜色值 缺少 target 或 data-color 反射会失败。 audit:Code/theming
RTL 不适用 @astryx/no-physical-properties lint 规则;apps/storybook/rtl-audit/verified-not-applicable.json 条目 每个故事 该 lint 规则会使 Code 样式中的物理 left/right 属性或值失败。缺口:没有浏览器从右到左检查覆盖 Code;该条目记录了这一决定。 audit:Code/rtl
PR1 源码审查 每个状态 缺口:如果 Code 添加了状态、副作用或监听器,没有自动化检查会失败。 audit:Code/behavior

决策日志

无记录。该记录描述的是已发布的行为。

未决问题

无。

内容边界

本文件不重复使用方示例、当前审计得分、实施步骤、CodeBlock 行为或排版策略草案。它链接到各自的所有者。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx