内容 Content

Markdown 与 MDX 的真实排版规范。每个区块展示规范参数与.sx-article 内的实际渲染效果。

排版容器 Typography container

所有文章正文内容统一包裹在 .sx-article 中。它定义了阅读宽度、字号与行高, 由 --sx-article-* token 驱动。使用 :where() 零特异性选择器, 确保组件与 overrides 能干净地覆盖。

Token用途
--sx-article-width-reading46rem阅读宽度
--sx-article-width-tutorial68rem教程宽度(代码 + 文字并排)
--sx-article-font-size1.0625rem正文字号
--sx-article-line-height1.8正文行高

SchemaX 是一个 Schema 驱动的静态内容平台。它用 Schema 定义站点自身的内容、设计令牌、组件契约和消息格式,并在构建时校验。

这段文字展示了 .sx-article 容器的默认排版效果:46rem 阅读宽度、1.0625rem 字号、1.8 行高。所有排版元素都在这个容器内被样式化。

标题层级 Heading hierarchy

.sx-article 内定义 h1–h6 六个级别的排版。h1 通常出现在文章头部(.sx-article 外),h2–h4 是正文最常用的标题层级,h5/h6 为小节标注。

元素font-sizeweightline-heightletter-spacingmargin-block
<h1>2.5rem8001.1-0.02em4rem 1.5rem
<h2>2rem8001.2-0.01em4rem 1.5rem
<h3>1.5rem8001.2502.5rem 1rem
<h4>1.2rem8001.302rem 0.75rem
<h5>uppercase1rem7001.30.05em2rem 0.5rem
<h6>uppercase · 70% opacity0.9rem7001.30.08em2rem 0.5rem

h1 · 一级标题 Level 1

一级标题通常出现在文章头部,正文内较少使用。最大字号 2.5rem,极粗字重 800。

h2 · 二级标题 Level 2

二级标题是正文中最常用的章节标题。2rem 字号,与 h1 同样的极粗字重。

h3 · 三级标题 Level 3

三级标题用于子章节。1.5rem 字号,仍然保持极粗字重以确保层级清晰。

h4 · 四级标题 Level 4

四级标题用于更细的分区。1.2rem 字号。

h5 · 五级标题 Level 5

五级标题为大写小节标注,uppercase + letter-spacing。

h6 · 六级标题 Level 6

六级标题为最小标注,uppercase + 更大 letter-spacing + 降低透明度。

正文元素 Inline & body

段落与行内元素的排版。链接使用 action-primary 蓝,行内代码使用等宽字体 + 边框,<kbd> 模拟物理按键,<mark> 使用品牌黄色高亮。

元素关键样式示例
<strong>font-weight: 700加粗
<em>font-style: italic斜体
<a>color: --sx-sys-color-action-primary · underline · 600链接文本
<mark>background: --sx-sys-color-accent高亮标记
<code>monospace · border · surface bg行内代码
<kbd>monospace · border + 1px shadow · 2px radiusCtrl + S

Schema 是连接意图与执行的结构化桥梁。它让不确定性的系统输出,变成可验证、可依赖的输入。

了解 设计令牌系统 如何驱动整站的视觉一致性。当你在代码中写入--sx-sys-color-accent,它将在构建时被替换为真实的颜色值。

在编辑器中按下 Ctrl + S 保存文件。这是 SchemaX 强调的 确定性:每一处取值都有明确来源。

列表 Lists

无序列表(disc)、有序列表(decimal)和嵌套列表。 列表项间距 margin-block: 0.4rem,左侧缩进 1.5rem

无序列表 Unordered

  • Schema 定义数据结构
  • Validator 校验输入是否符合 Schema
  • Parser 将原始数据转换为结构化对象
    • JSON Schema 是最通用的描述语言
    • TypeScript 类型是编译期的 Schema
    • Zod 在运行时提供类型安全的校验
  • Runtime 根据校验结果决定执行路径

有序列表 Ordered

  1. 用户发出自然语言请求
  2. 模型根据 Tool Schema 生成结构化参数
  3. 运行时校验参数是否符合 Schema
  4. 校验通过 → 调用工具执行
  5. 返回结果给模型,进入下一轮

引用 Blockquotes

左侧 4px solid --sx-sys-color-action-primary 蓝色竖线 + 斜体。 适用于引用、注释、重要摘录等场景。

Schema 看起来很小,但它处在多个系统的关键连接处:提示词与工具、模型与 API、前端与后端、人类意图与机器执行之间。

引用块左侧有蓝色竖线标识,正文使用斜体以区别于普通段落。上下的 margin-block: 1.5rem 提供足够的呼吸空间。

代码 Code

行内代码与代码块。代码块由 Expressive Code处理,自带 Shiki 语法高亮、文件名、行号、行高亮、复制按钮。

行内代码 Inline code

等宽字体 ui-monospacefont-size: 0.9em, surface 背景色 + 1px 边框。

代码块 Code block

以下代码块由 Expressive Code 渲染,展示 Shiki 语法高亮、文件名、行高亮等能力。 在实际 MDX 文件中使用三反引号语法即可触发。

在 TypeScript 中,Zod 的 z.object() 可以定义一个工具参数的 Schema:

tool-schema.ts
import { z } from 'zod';
const weatherSchema = z.object({
city: z.string().describe('城市名称'),
unit: z.enum(['celsius', 'fahrenheit']).default('celsius'),
});

代码块自带 Shiki 语法高亮、文件名标签、行高亮(ins 标记新增行)和复制按钮。在 MDX 内容中,三反引号语法会自动触发同样的渲染。

表格 Tables

全框线 border-collapse: collapse,表头使用 page 背景色 + 大写小号字。 所有单元格 1px 黑边框,--sx-ref-space-2 × --sx-ref-space-3 内边距。

页面视觉强度分级

页面RetroUI 强度说明
设计系统最强完整展示视觉语言与组件
首页Hero 区强表现力
课程正文中等保留结构感,降低装饰
博客正文克制以阅读为中心,最小视觉干扰

图片与媒体 Images & media

<img> 自带 1px 黑边框 + max-width: 100%<figure> 提供外边距,<figcaption> 居中 + 降低透明度。

占位图示例
图 1:占位图示例。实际图片自动继承 1px 黑边框与 max-width: 100%。

图片使用 <figure> + <figcaption> 语义包裹。figcaption 使用 0.85rem 字号 + 70% 透明度居中显示。

分隔线与折叠 Rules & disclosure

<hr> 渲染为 1px 黑色上边框,margin-block: 2rem<details> + <summary> 渲染为可折叠区块, 1px 黑边框 + 内边距,summary 加粗 + pointer 光标。零 JS 实现。

段落之间的分隔线:


分隔线使用纯 CSS border-top,无额外元素。

折叠区块 Details

点击展开:什么是 Schema?

Schema 是一种描述数据结构的形式化语言。它可以定义字段类型、必填规则、取值范围和嵌套关系。

在 AI Agent 场景中,Schema 告诉模型「工具需要什么参数、什么格式、什么约束」,从而将自由文本转换为可执行的结构化输入。

点击展开:为什么用 :where() 选择器?

:where() 的特异性为 0,这意味着组件层的样式(如 .btn.card)和 overrides 层的样式可以干净地覆盖文章排版样式,无需关心优先级竞争。

定义列表 Definition lists

<dl> / <dt> / <dd> 用于术语定义。<dt> 加粗,<dd> 左侧缩进 1.5rem + 85% 透明度。

Schema
描述数据结构的形式化语言,定义字段、类型、约束与嵌套关系。
Token
设计令牌。以 DTCG JSON 格式定义的视觉变量(颜色、间距、阴影等),由 Style Dictionary 构建为 CSS 自定义属性。
:where()
CSS 选择器函数,特异性为 0。用于 article 层,确保组件和 overrides 层能干净地覆盖排版样式。
Neo-brutalism
新粗野主义设计风格。特征为低圆角、粗边框、实心硬阴影、高对比度,追求物理裁切般的视觉质感。

MDX 组件 MDX components

以下组件在规范 §11 中定义,允许在 MDX 内容中使用。它们目前处于规划阶段, 尚未实现。每个组件的排版样式将在实现后同步更新到本页。

CalloutPlanned

提示框:idea / warning / danger / note 四种类型

StepsPlanned

步骤列表:有序流程编排

FigurePlanned

带标题的图片/代码插图容器

CodeComparePlanned

左右对比:Before / After · 输入 / 输出

CodePreviewPlanned

代码 + 实时效果并排展示

PlaygroundPlanned

sandbox iframe 中运行用户 HTML/CSS/JS

ExercisePlanned

课程练习题交互组件

KnowledgeCheckPlanned

知识点测验组件

TabsPlanned

标签切换,桌面端左右、移动端上下

VideoPlanned

视频嵌入容器