main：语义化圆角从视觉约定变成仓库契约

Buffin · b3a13bd → 14dcbfe · 2026-07-17 · 自包含，读完即弃

写法说明：本文按「逐跳走读」展开——每个机制都给真实代码片段（取自分支、经裁剪，青色斜体注释为解读所加，灰色斜体是源码原注释的保留或意译），每段代码标注所在文件。每条旅程结尾有一张「排查路标」：将来出问题时，症状对应去哪个文件看哪个函数。

1TL;DR

这组变更把 renderer 的圆角从 rounded-md、rounded-full 和任意值，迁移成按角色命名的 Tailwind v4 token。组件现在表达“我是控件、表面、浮层、消息、Composer、圆点或胶囊”，不再表达“我要第几个尺寸”。

同一份 tokens.css 既生成 Tailwind utility，也是检查器的事实源。检查器覆盖 TS/JS AST、CSS、HTML、动态字符串和 inline style；裸值只有在相邻真实注释里写明理由才可通过。

后续审查把第一版的宽松 scope、可伪造注释和多种动态绕过收紧，并把 JS-family 文件改成一次解析、一次 AST 遍历。最终专项测试为 37/37，通过 live renderer 扫描。

2变更地图

3当前契约：名字描述角色

Tailwind v4 的 @theme 是唯一事实源。默认的 xs 到 4xl 被显式清空，随后定义 11 个语义圆角；raised、floating、overlay 三个阴影 token 与它们同处一个静态设计层。

@theme {
  --radius-xs: initial;
  --radius-sm: initial;
  /* 其余 Tailwind 默认圆角同样 reset */

  /* radius-token-scope: components/ui/highlighted-text */
  --radius-mark: 0.125rem;
  --radius-indicator: 0.1875rem;
  --radius-compact: 0.25rem;
  --radius-control: 0.375rem;
  --radius-surface: 0.5rem;
  --radius-overlay: 0.625rem;
  --radius-tab: 0.75rem;
  --radius-message: 1rem;
  --radius-composer: 1.25rem;
  --radius-circle: 9999rem;
  --radius-pill: 9999rem;
}

4旅程 A：一个组件如何选到合法圆角

这条旅程从设计角色开始，经过 Tailwind utility，最后落到具体组件。关键变化不是像素，而是源码开始保存“为什么是这个圆角”。

A.1事实源同时服务构建与检查

以前的简单检查器从 TypeScript Tailwind 配置里找 borderRadius 表；当前实现改为用 PostCSS 读取 tokens.css 的 @theme。因此 CSS 生成 utility 的来源与检查允许表是同一个文件。

export function parseRadiusPolicy(content, filePath) {
  const root = postcss.parse(content, { from: filePath })
  const policy = new Map()
  let previousValue = -1

  root.walkAtRules('theme', (theme) => {
    theme.walkDecls((declaration) => {
      const name = declaration.prop
        .match(/^--radius-([a-z][a-z0-9-]*)$/)?.[1]
      if (name === undefined) return
      if (defaultRadiusNames.test(name)) {
        throw new Error(`${filePath}: radius token ${name} must use a semantic name`)
      }
      // 名称、单位、顺序和 scope 都在这里进入 policy
    })
  })
  return policy
}

A.2消费者迁移保存了视觉角色

const CARD_SURFACE =
  '... rounded-surface border border-border bg-card ...'

className={cn(
  'composer-shell w-full rounded-composer border border-accent bg-content',
  density === 'narrow' ? '' : 'max-w-[45rem]',
)}

active
  ? 'rounded-t-tab bg-content text-ink'
  : 'text-ink-soft hover:text-ink'

A.3强语义 token 绑定精确源码 ID

mark、tab、message、composer 的定义前带 radius-token-scope:。检查时，文件路径被归一化为 renderer 相对路径并只移除最后一个真实扩展名；同名备份文件与点号后缀文件不会冒充正式消费者。

const rendererRelative = normalizedPath.includes(rendererMarker)
  ? normalizedPath.slice(normalizedPath.indexOf(rendererMarker) + rendererMarker.length)
  : normalizedPath
const segments = rendererRelative.split('/')
segments[segments.length - 1] = segments.at(-1)
  .replace(/\.(?:[cm]?[jt]sx?)$/i, '')
const sourceId = segments.join('/')

if (definition.scopes.length > 0 && !definition.scopes.includes(sourceId)) {
  return 'semantic radius token outside its source scope'
}

5旅程 B：一次全仓检查如何走完

这条旅程从 bun run check 进入，先读取 policy，再按扩展名分流。JS-family 走 ts-morph，CSS 走 PostCSS，HTML 走属性提取加 PostCSS inline declaration 解析。

B.1扫描集合包含未提交新文件

文件发现使用 git ls-files --cached --others --exclude-standard，因此新建但尚未 git add 的 renderer 文件也在门禁内；随后用文件系统状态剔除已删除的 tracked path。

const paths = execFileSync(
  'git',
  ['ls-files', '--cached', '--others', '--exclude-standard', '--', ...scanRoots],
  { cwd: rootDir, encoding: 'utf8' },
)
  .split('\n')
  .filter(Boolean)
  .filter((path) => scanExtensions.test(path))
  .filter((path) => {
    const absolute = join(rootDir, path)
    return existsSync(absolute) && statSync(absolute).isFile()
  })

B.2JS-family 文件只解析一次

createSourceScan() 在一次 AST 遍历中收集字符串、模板、二元表达式、调用表达式与 style 属性节点。class 检查和 inline style 检查复用同一个索引，避免同一文件重复 parse。

function createSourceScan(content, filePath) {
  const sourceFile = parser.createSourceFile(filePath, content, { overwrite: true })
  const scan = {
    binaryExpressions: [],
    callExpressions: [],
    propertyAssignments: [],
    shorthandPropertyAssignments: [],
    stringLiterals: [],
    templateExpressions: [],
  }
  sourceFile.forEachDescendant((node) => {
    // 每个相关 SyntaxKind 只在这里入桶一次
  })
  return scan
}

静态字符串直接检查 rounded-*；模板插值、+、concat() 与空分隔符 join('') 则进入动态序列检查。style 路径覆盖对象属性、计算属性、简写属性和 element.style.borderRadius = ...。

for (const call of sourceScan.callExpressions) {
  const callee = call.getExpression().asKind(SyntaxKind.PropertyAccessExpression)
  if (callee?.getName() === 'concat') {
    scanDynamicSequence(
      [callee.getExpression(), ...call.getArguments()],
      call.getStartLineNumber(),
    )
    continue
  }
  if (callee?.getName() !== 'join') continue
  // ['rounded-', radius].join('') 也不能绕过
}

B.3CSS 与 HTML 各用自己的语法边界

CSS declaration 由 PostCSS 提供属性名、值、兄弟节点和源码行。普通 CSS 属性按大小写不敏感处理；包含 radius 的自定义属性保留自己的名称规则；@apply 参数回到 Tailwind class 扫描。

HTML 支持 quoted、unquoted 与大小写属性名，同时用属性名前置边界排除 data-class 和 data-style。style 属性的内容被包进临时 rule，再交给 PostCSS 解析。

const hits = path.endsWith('.css')
  ? findCssRadiusViolations(content, path, policy)
  : path.endsWith('.html')
    ? findHtmlRadiusViolations(content, path, policy)
    : findSourceRadiusViolations(content, path, policy)

for (const hit of hits) {
  violations.push(`${path}:${hit.line} ${hit.reason}: ${hit.value}`)
}

B.4逃逸不是禁止，而是必须留下理由

裸几何需要相邻上一行的 radius-token-exception:。JS/TS 使用 TypeScript scanner 确认它是真实注释，CSS 使用 PostCSS sibling，HTML 使用 HTML comment；普通字符串里的伪造前缀不会放行。

corner-shape 使用独立的 radius-corner-shape:，并要求先有 radius fallback。Tailwind 下 fallback 与 corner-shape 的 variant chain 必须完全一致，基础态不会借用 hover 态的 fallback。

// radius-token-exception: derives from the parent radius and inset
const style = { borderRadius: computedRadius }

// radius-corner-shape: branded media thumbnail
const className = 'rounded-surface [corner-shape:squircle]'

6旅程 C：两轮审查怎样收紧第一版

主提交先建立完整门禁，随后 worktree 中的修复把它从“能发现常规违规”推进到“常见逃逸写法也无法静默通过”。这部分最适合用旧假设与当前结果对照。

数值契约也发生了一个重要调整：第一版禁止两个语义 token 共享同值；当前允许同值不同义，于是圆点使用 circle，可变宽胶囊使用 pill。角色可以以后独立演化，而无需先伪造数值差异。

it('rejects radius utilities assembled through concat and join', ...)
it('requires restricted semantic tokens to stay in their declared source scope', ...)
it('checks computed style keys and DOM style assignments', ...)
it('checks case-insensitive CSS radius and corner-shape properties', ...)
it('ignores class and style text inside data attributes', ...)
it('requires a corner-shape fallback under the same Tailwind variants', ...)

7计划与实际落地的偏差

随附的 Visual Surface Token Design 是 proposed 设计稿；当前代码保留其“按角色命名”的核心，但实现已经根据真实消费者细化。

8心智模型补丁

9测试与风险地图

10当前检查器判定为不合法的全部情况

这里的“全部”指 14dcbfe 中检查器已经编码的违规分支，不把尚未覆盖的运行时写法假装成已检测能力。同一条底层规则会在不同语法入口分别列出，便于看到具体代码形态会收到什么诊断。

10.1Tailwind v4 Token 定义

10.2Tailwind Utility 与动态 class

10.3React Style、CSS 与 HTML

10.4豁免、Scope 与 Corner Shape 凭据

11覆盖声明

本报告以 b3a13bd 为 base，覆盖三个圆角相关提交，共 69 个文件。主力逐行阅读了 799 行检查器、550 行测试、tokens 与 package 接线，以及所有 renderer 消费者迁移。

明确排除了工作区中与 Session Markdown 播放相关的四个 tracked 文件和一个 untracked hook；它们不属于语义化圆角旅程。消费者区域的 class 替换全部进入阅读范围，但报告只展开能更新心智模型的代表样本。

Buffin · main · b3a13bd → 14dcbfe · 69 files · +1556/−171 · 本报告为一次性理解辅助，不维护、不作为真相源。