concentric

使用 tailwindcss-concentric 实现同心圆角

当一个圆角元素位于另一个圆角父元素内时，内侧圆角应与外侧圆角保持一致：

inner radius = outer radius - gap        (gap = the distance between the two edges on that side)

tailwindcss-concentric 会在 CSS 中完成这项计算。为子元素添加 rounded-concentric，它便会读取最近的圆角祖先的半径、内边距和边框，中间普通包装元素的内边距和边框、子元素自身的外边距，以及 absolute/fixed 子元素的内边距。计算规则见 references/rules.md；使用前后的示例见 references/examples.md。

该软件包提供三项功能：rounded-concentric 工具类（CSS 导入项）、审计 CLI（npx tailwindcss-concentric audit [paths...] [--json]），以及用于 tailwind-merge 的 tailwindcss-concentric/merge。根据需求选择相应步骤：

• 进行设置（“安装 tailwindcss-concentric”“添加同心圆角”）：执行步骤 1，并安装所有缺少的内容。然后询问是否要运行审计。
• 审计或修复现有 UI：执行步骤 1、运行审计，然后完成步骤 2 至 5。
• 构建新 UI：执行步骤 1，然后为每个嵌套在另一个圆角元素内的圆角元素完成步骤 2 至 4。

1. 先检查设置

1. 仅支持 Tailwind v4。 主 CSS 文件中应包含 @import "tailwindcss";。如果项目使用 Tailwind v3（tailwind.config.js 中含有 @tailwind base; 指令），请停止并告知用户；该插件不支持 v3。
2. 安装并导入。 tailwindcss-concentric 必须列在 package.json 中。如果缺少该依赖，且用户要求设置或使用此插件，请根据锁文件选择项目使用的包管理器并安装（npm i、pnpm add、yarn add 或 bun add tailwindcss-concentric）。如果用户只是要求检查，请告知其缺少该依赖，并询问是否要安装。导入 Tailwind 的 CSS 文件必须紧接在其后导入该插件：

   @import "tailwindcss";
   @import "tailwindcss-concentric";
   

3. tailwind-merge。 如果项目会合并类名（使用 twMerge、extendTailwindMerge 或基于它们构建的 cn() 助手函数），请注册该插件的类名。否则，cn("rounded-lg", "rounded-concentric") 会保留两个类名，并由 rounded-lg 生效：

   import { extendTailwindMerge } from "tailwind-merge";
   import { withConcentric } from "tailwindcss-concentric/merge";
   
   export const twMerge = extendTailwindMerge(withConcentric);
   // with your own config: extendTailwindMerge({ ...yourConfig }, withConcentric)
   

   将 cn() 中使用的所有 twMerge 导入都替换为扩展后的版本。在任何会合并类名的组件中使用 rounded-concentric 之前，先完成此操作。

2. 判断哪些元素应采用同心圆角

插件安装后，先运行审查命令：npx tailwindcss-concentric audit [paths] 会列出与父元素不匹配的嵌套圆角半径，并给出同心圆角值和应使用的类。将其输出视为候选项。它读取的是标记，而不是布局，因此无法判断子元素是否真的位于父元素的角落；对于无法计算的值（自定义主题圆角、CSS 变量、变体类），它会跳过。它还会漏掉通过组件属性跨文件传递的类名。请根据以下规则逐一审查候选项，并仍然亲自查看组件。

仅当以下条件全部满足时，才使用同心圆角类：

• 元素有圆角，且其父元素（或最近一个带有 rounded-* 类的祖先）也有圆角。
• 子元素的角位于父元素的角上：子元素该角与父元素该角之间没有其他元素，因此能同时看到两条曲线。
• 这两个形状应呈现为一个嵌套形状：卡片中的图片、分段控件中的活动标签、搜索栏中的按钮、选中环、带边框卡片中的面板。

以下情况请保留元素原样：

• 元素本身就是独立形状：头像、状态圆点、徽章和标签（rounded-full 药丸形）、图标、内容中间的芯片。
• 元素不接触父元素的角：标题下方的表单字段、卡片中间的列表项、容器没有圆角的网格块。
• 间距至少等于外侧圆角半径（例如 rounded-lg p-6）。此时公式会得出 0，使子元素变成直角。只有在确实需要直角时才应用；否则保留设计圆角，并在报告中注明。
• 元素已经正确（使用了 rounded-concentric，或有意使用普通圆角）。

3. 选择类

情况	类
子元素贴合四个角	rounded-concentric
子元素只贴合部分角（媒体内容与卡片顶部齐平、分组中的第一项／最后一项）	侧边或角落变体：rounded-t-concentric、rounded-b-concentric、rounded-s-concentric、rounded-e-concentric、rounded-tl-concentric、rounded-ss-concentric，……
在可能从右向左布局的应用中，水平分组的起始端／末尾端	逻辑变体 rounded-s-concentric / rounded-e-concentric（起始端／末尾端绝不要使用 -l-/-r-）
一个带内边距的普通包装元素位于圆角父元素和子元素之间，或者子元素为 absolute inset-*，或者带有外边距（-mx-4 溢出）	rounded-concentric；插件会测量这些值
同一侧之间隔着两个带内边距的包装元素，或带外边距的包装元素	也给外层包装元素添加 rounded-concentric，使其加入链条并传递其内部的所有内容
间距来自内联样式或自定义 CSS	显式间距：rounded-concentric-{n}（间距刻度，rounded-concentric-2 = 0.5rem）或 rounded-concentric-[6px]
父元素在不同轴上的内边距不同（px-4 py-2），且角落应同时跟随两个轴	添加 concentric-elliptical
父元素使用 corner-shape: squircle	给子元素添加 concentric-squircle（并给父元素添加该类，或添加 [corner-shape:squircle]）
深层嵌套使最内层角落变成直角	在任意祖先上设置最小值：[--concentric-floor:2px]

保留子元素的其他类。只替换其圆角类（rounded-xl → rounded-concentric、rounded-t-lg → rounded-t-concentric、rounded-[calc(...)] → rounded-concentric）。

4. 了解插件无法检测到的内容

圆角半径取自类名中包含 rounded 的最近元素。间距仅根据 Tailwind 类计算：该元素及其间最近一层包装元素上的内边距（p-*、px-*、ps-* 等）和边框宽度（border、border-x-4 等），子元素上的外边距（m-*、-mt-4 等），以及 absolute / fixed 子元素上的内偏移（inset-*、top-*、start-* 等）。因此：

• 每一侧只计算一层包装元素。 在 rounded-3xl > p-3 > p-2 > rounded-concentric 中，子元素只能检测到 p-2 包装元素。包装元素上的外边距也不会计入。给最外层包装元素添加 rounded-concentric：除非该包装元素有背景、边框或 overflow-hidden，否则不会产生可见效果；即使内边距是响应式的，也能正常工作。也可以显式指定间距。
• 内偏移是从圆角祖先的内边距边缘开始测量的。 这假设该祖先是包含块（relative）。如果中间的某个 relative 包装元素是包含块，请显式指定间距。
• 无法检测内联样式或自定义 CSS 中的内边距。 请使用 Tailwind 类，或显式指定间距。
• 不支持百分比圆角（rounded-[50%]）。 分数内偏移（inset-x-1/4）会回退为使用父元素的内边距，auto 外边距按 0 计算。
• 只有当元素的 class 属性中包含文本 rounded 时，@apply 类才会纳入计算。
• 方向取自 dir 属性，包括 dir="auto"，且在支持 @scope 的浏览器（Chrome 118、Safari 17.4、Firefox 146）中可读取任意深度；旧版浏览器最多读取三层嵌套。仅通过 CSS direction 设置的方向无法检测。
• 深度。 九个堆叠的圆角元素可精确计算；更深的元素会沿用第九层的值。
• 普通的 rounded-* 元素会开启新的链。 其子元素以它为基准测量，而不是以外层同心元素为基准。

5. 验证

每次修改时，手动计算预期圆角半径（参见 references/rules.md）；如果可以运行应用，请在浏览器控制台中检查：

getComputedStyle(document.querySelector("#el")).borderTopLeftRadius

胶囊形元素会显示一个非常大的数值（例如 3.35544e+07px）；这是预期结果。

报告你修改了哪些元素及其原因、有意保留了哪些元素，以及插件无法检测间距的位置（并说明你在那里使用的类）。