Panda CSS 不具备 TypeScript 类型安全，其“类型提示”仅来自 JSON Schema 配置与语言服务器实现的 IDE 补全和错误高亮，无法阻止传入非法 token 值，也不参与 tsc 类型检查；运行时值合法性需靠 resolveStyle 抛异常或手动 as const 约束，且动态拼接 css 调用会导致原子化失效、性能退化。
Panda CSS 里没有“类型安全”这个特性——它根本不是 TypeScript 类型系统的一部分，也不是靠 type 或 interface 校验 CSS 属性的工具。
你看到的所谓“类型提示”，其实是编译时生成的 css 函数参数自动补全 + 错误高亮，底层靠的是 Panda 的 JSON Schema 配置（panda.config.ts）和插件在 VS Code 中调用的 language server。它不阻止你传 { color: "invalid-token" }，也不会在 tsc 检查中报错；真要校验 token 值是否合法，得靠运行时的 resolveStyle 抛异常，或者手动加 as const 配合泛型约束——但这不属于 Panda 自身能力，而是你强行套的 TS 花活。
所以别被文档里“type-safe styling”的表述带偏。它解决的不是“写错属性值会不会编译失败”，而是“写错属性名会不会被 IDE 提示”。
为什么 css 函数看起来像有类型，实际却拦不住运行时错误
因为 Panda 的 css 是一个运行时函数，它的参数 shape 由配置决定，但值合法性完全不介入 TS 类型检查流程：
- 你在
panda.config.ts里定义了colors: { primary: "#007bff" }，IDE 就能提示color: "primary"，但你硬写color: "primary2"，TS 不报错，Panda 也不报错——直到渲染时生成空 class 或 fallback 到未定义值 -
css({ fontSize: "2xl" })能提示，是因为2xl在theme.fontSizes里存在；但如果你删掉配置、保留调用，构建照样过，只是最终没样式 - 所有响应式断点、伪类、容器查询等嵌套写法，都是字符串拼接逻辑，不是类型推导。写成
{ _hover: { bg: "blue.900" } }和{ _hoer: { bg: "blue.900" } }（少个 v），TS 同样不拦
真正影响性能的关键：不要在组件里动态拼接 css 调用
Panda 的高性能来自原子化 CSS 生成和静态提取，但前提是样式必须可静态分析。以下写法会直接让优化失效：
- 把
css放在闭包或条件表达式里：const cls = isDark ? css({ color: "white" }) : css({ color: "black" })→ Panda 无法提前提取原子类，退化为 runtime style 对象 - 用变量传入 key 或 value：
css({ [dynamicProp]: dynamicValue })→ 完全无法静态分析，强制走内联 style - 在循环中反复调用
css：items.map(i => css({ color: i.theme }))→ 每次都生成新 class，class 名爆炸，缓存失效
想兼顾“提示友好”和“运行可靠”，得靠配置层约束，不是靠 TS
真正起作用的是 panda.config.ts 里的显式声明：
立即学习“前端免费学习笔记（深入）”；
- 用
tokens严格定义所有允许的颜色、间距、字体尺寸，避免自由字符串 - 禁用
extendTheme动态扩展，改用theme的完整覆盖式定义，确保所有 token 可穷举 - 开启
strictTokens: true（如果 Panda 版本支持），它会让缺失 token 的调用在构建时报错，而不是静默忽略 - 配合 ESLint 插件
@pandacss/eslint-plugin，拦截明显非法写法，比如css({ display: "flexx" })
最后提醒一句：Panda 的“高性能”本质是构建时确定性输出 + 运行时零计算。一旦你开始用变量、函数、条件去包裹 css，就等于主动放弃这个前提。类型提示只是糖衣，别把它当护栏。
