css-toolkit-free

CSS 工具箱免费版是一份面向前端开发者的 CSS 常见陷阱速查手册，聚焦层叠上下文、Flexbox/Grid 布局陷阱、现代选择器与响应式设计基础。Use，可自发提升工作效率 when 需要代码产出、编程辅助、调试测试、开发部署时使用。不适用于无明确技术栈的模糊需求。Use when 需要代码产出、编程辅助、调试测试、开发部署时使用。不适用于无明确技术栈的模糊需求.

CSS 工具箱（免费版）

概述

本工具箱是一份系统化的 CSS 常见陷阱速查手册，覆盖层叠上下文、布局模型、现代选择器与响应式设计四大核心领域。每个陷阱均配有问题复现、原因分析与修复方案，帮助开发者在编码阶段直接规避高频踩坑点，减少调试时间. 免费版聚焦日常开发最常遇到的陷阱与基础现代特性，适合个人开发者快速查阅。专业版在此基础上扩展性能优化、无障碍设计、设计系统模式等进阶内容.

核心能力

能力项	说明	适用场景
层叠上下文陷阱	z-index 失效原因与修复	弹窗层级混乱
Flexbox 陷阱	flex 简写、min-width、basis	弹性布局错乱
Grid 陷阱	fr 单位、auto-fit vs auto-fill	网格布局溢出
现代选择器	:is / :where / :has / :focus-visible	选择器简化
尺寸函数	clamp / min / max / fit-content	流式排版
响应式基础	移动优先与容器查询入门	多端适配

核心功能执行

用input_params参数进行配置.

处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志.

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置.

处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志.

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置.

处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志.

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：CSS、常见陷阱速查手册、覆盖层叠上下文、布局陷阱与现代选、工具箱免费版是一、份面向前端开发者、聚焦层叠上下文、布局陷阱、现代选择器与响应、式设计基础、Use、when、需要代码生成、编程辅助、调试测试、开发部署时使用、不适用于无明确技、术栈的模糊需求、适用于独立开发者、企业团队和自动化、工作流场景等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

使用场景

场景一：弹窗层级混乱（开发者）

开发者在实现模态弹窗时发现 z-index: 9999 仍然被遮挡。根因是父级元素设置了 transform 或 opacity < 1，创建了新的层叠上下文，导致子元素的 z-index 被困在父级范围内. 修复方案：使用 isolation: isolate 在需要隔离层级的容器上显式创建上下文，避免 transform 意外创建：

css

.modal-wrapper {
  isolation: isolate;
}
.modal {
  z-index: 9999;
}

场景二：Flex 子项文本截断失效（开发者）

在 Flex 布局中对子项使用 text-overflow: ellipsis 不生效，文本溢出容器。原因是 Flex 子项的默认 min-width 为 min-content，不会收缩到内容宽度以下. 修复方案：在 Flex 子项上设置 min-width: 0：

css

.flex-child {
  min-width: 0;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

场景三：Grid 网格列不等宽（开发者）

使用 grid-template-columns: 1fr 1fr 期望两列各占 50%，实际发现宽度不等。原因是 fr 单位分配的是剩余空间，若某列内容超出会撑开轨道. 修复方案：使用 minmax 确保最小宽度不被内容撑破：

css

.grid {
  display: grid;
  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
}

快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

60 秒上手

本工具箱为纯文档型 Skill，无需安装依赖。直接向 Agent 描述你的 CSS 问题即可获得陷阱分析与修复方案. 示例提问：

text

我的弹窗 z-index 设了 9999 还是被遮挡，怎么回事？

text

Flex 布局里子元素文字溢出了怎么处理？

text

grid 1fr 1fr 两列宽度不一样怎么修？

快速查阅表

问题关键词	对应章节	核心修复
z-index 失效	层叠上下文陷阱	isolation: isolate
Flex 文字溢出	Flexbox 陷阱	min-width: 0
Grid 列宽不等	Grid 陷阱	minmax(0, 1fr)
选择器太长	现代选择器	:is() 分组
字号不自适应	尺寸函数	clamp()

响应解析: 完成完成后,查看输出响应确认任务状态。成功时输出包含解析摘要和响应数据;失败时根据错误信息排查问题,查阅错误解析章节获取恢复步骤.

示例

层叠上下文陷阱清单

css

/* z-index 仅对定位元素或 flex/grid 子项生效 */
.positioned { position: relative; z-index: 1; }
// ...
/* isolation: isolate 显式创建上下文，无需 position */
.context { isolation: isolate; }
// ...
/* 以下属性会意外创建层叠上下文 */
.opacity-trap { opacity: 0.99; }
.transform-trap { transform: translateZ(0); }
.filter-trap { filter: blur(0); }

Flexbox 陷阱清单

css

/* flex: 1 等于 flex: 1 1 0%，basis 为 0 而非 auto */
.grow { flex: 1 1 0%; }
// ...
/* gap 在 Flex 中已支持，无需 margin hack */
.flex-gap { display: flex; gap: 16px; }
// ...
/* flex-basis 优先于 width，在 grow/shrink 之前计算 */
.basis-first { flex-basis: 200px; }

Grid 陷阱清单

css

/* auto-fit 折叠空轨道，auto-fill 保留空轨道 */
.responsive-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
}
// ...
/* 隐式轨道可能出乎意料：超出显式网格的项仍会显示 */
.implicit-trap {
  grid-template-columns: 1fr 1fr;
  grid-template-rows: auto;
  /* 第三行项目会进入隐式轨道 */
}

现代选择器

css

/* :is() 分组，减少重复 */
:is(h1, h2, h3) + p { margin-top: 1em; }
// ...
/* :where() 零特异性，便于覆盖 */
:where(.card) p { color: inherit; }
// ...
/* :has() 父选择器 */
.card:has(img) { padding: 0; }
// ...
/* :focus-visible 仅键盘聚焦显示轮廓 */
button:focus-visible { outline: 2px solid blue; }

尺寸函数

css

/* clamp 流式排版 */
h1 { font-size: clamp(1.5rem, 4vw, 3rem); }
// ...
/* min 替代媒体查询 */
.container { width: min(100%, 1200px); margin: 0 auto; }
// ...
/* fit-content 按内容收缩 */
.tag { width: fit-content; }

优秀实践

1. 用 isolation 替代 z-index 滥用

不要靠堆高 z-index 解决层级问题。在需要隔离的容器上使用 isolation: isolate，将层级问题收敛在局部范围内.

2. Flex 子项始终设置 min-width: 0

Flex 子项默认 min-width: min-content 会导致内容撑破容器。养成在需要收缩的子项上设置 min-width: 0 的习惯.

3. 优先使用逻辑属性

使用 margin-inline、margin-block、inset 等逻辑属性替代物理属性，天然支持书写方向与 RTL 布局：

css

.dialog { inset: 0; }
.sidebar { margin-inline-end: 16px; }

4. 容器查询替代部分媒体查询

组件级响应式优先使用容器查询，让组件自适应容器宽度而非视口宽度：

css

.card-container { container-type: inline-size; }
@container (min-width: 400px) {
  .card { flex-direction: row; }
}

常见问题

Q1：z-index 设了很大还是被遮挡？

检查祖先元素是否设置了 transform、opacity < 1、filter、will-change 等属性，这些会创建新的层叠上下文，将子元素的 z-index 困在父级范围内。解决方案是在合适的祖先上使用 isolation: isolate 显式管理上下文边界.

Q2：flex: 1 的子项宽度不对？

flex: 1 等价于 flex: 1 1 0%，其中 flex-basis 为 0（而非 auto），意味着子项从零宽度开始按比例分配空间。若希望保留内容最小宽度，改用 flex: 1 1 auto.

Q3：grid 的 1fr 1fr 两列不等宽？

fr 分配的是剩余空间，若某列内容超出 min-content 会撑开轨道。使用 minmax(0, 1fr) 允许列收缩到 0，确保等宽.

Q4：:has() 选择器兼容性如何？

:has() 已在 Chrome 105+、Safari 15.4+、Firefox 121+ 支持。对于需兼容旧浏览器的项目，建议作为渐进增强使用，搭配 @supports 检测.

Q5：clamp 的中间值用什么单位？

中间值通常使用视口单位（如 vw）实现流式缩放，两端为固定值作为上下限。例如 clamp(1rem, 2.5vw, 2rem) 在 1rem 到 2rem 之间随视口缩放.

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• 浏览器：Chrome 105+ / Safari 15.4+ / Firefox 121+（部分现代特性）

依赖详情

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由 Agent 平台内置 LLM 提供
浏览器开发者工具	工具	推荐	浏览器内置

API Key 配置

• 本工具箱为纯文档型 Skill，无需额外 API Key
• 无需网络请求，所有内容离线可用

可用性分类

• 分类：MD（纯 Markdown 指令，无需 exec 命令行执行能力）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 提供 CSS 知识咨询

已知限制

本免费体验版限制以下高级功能：

• 不包含性能优化章节（contain、content-visibility、will-change 深度指南）
• 不包含无障碍设计基线（prefers-reduced-motion、forced-colors 等）
• 不包含设计系统与主题模式（CSS 变量架构、暗色模式策略）
• 不包含滚动行为与滚动捕获深度指南
• 不包含跨浏览器兼容性矩阵与降级方案
• 不提供优先技术支持与定制化咨询

解锁全部功能请使用专业版：css-toolkit-pro

• 当前为免费版本,如需完整功能请升级到付费版获取全部能力

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

输出格式

json

{
  "success": true,
  "data": {
    "result": "CSS工具箱(免费版)处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "csskit"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}