panelui

PanelUI

一个面向 Expo 的 React Native 组件库，通过 Uniwind 使用 Tailwind CSS 进行样式设计，并由 Reanimated 在 UI 线程上执行动画。纯 TypeScript，无原生模块，可在 Expo Go 中运行。

所有 CLI 命令都要使用项目自己的运行器——npx panelui-cli@latest、 pnpm dlx panelui-cli@latest 或 bunx panelui-cli@latest，并与项目的 packageManager 匹配。 以下示例使用 npx。

样式是否生效？

如果用户说没有任何样式、className 不起作用、屏幕是空白的，或 Uniwind 找不到 --color-background：直接查看 setup.md。这不会触发任何错误，而且几乎每次都是 metro.config.js 中的路径不正确。不要开始阅读组件代码。

首先，弄清楚项目如何使用它

有两种接入方式，而且都完全受支持，因此不要想当然：

npx panelui-cli@latest mcp   # the MCP server, if the agent supports it

或者，不使用 MCP 时，读取 package.json 并查找 panelui.json：

找到的内容	含义	导入方式
依赖项中有 panelui-native	组件包。默认方式。	import { Button } from 'panelui-native'
有一个 panelui.json	源码已复制到仓库中，由项目自行拥有并编辑	import { Button } from '@/components/ui/button'
两者都有	正常情况——使用组件包，但有一个组件是分叉版本	根据文件选择

如果两者都没有，则项目尚未安装它：新建应用请运行 npx create-panelui-app@latest，已有应用请查看 setup.md。不要在尚未完成设置的项目中手写组件源码——这样不会有任何样式，而且原因并不明显。

原则

1. 构建之前先查找。 components.md 列出了所有组件，数量超过一百个。编写自定义 UI 之前先搜索一下——所谓的“自定义”弹层、选择器、图表或聊天记录，几乎总能找到现成组件。
2. 根据本技能文档读取属性，不要凭记忆。 每个组件都在 components/<slug>.md 中有对应文件，其中包含组件结构、每个属性的类型和默认值、变体及组成部分，这些内容由库的 TypeScript 代码生成。使用组件前先阅读对应文件。记忆中的属性名称通常不准确，而且此处的任何内容都不需要网络请求。
3. 组合使用各个部分。 设置界面由 Frame + Frame.Panel + Frame.Row 组成。聊天界面由 MessageScroller + Message 组成。recipes.md 展示了这些界面的完整写法。优先使用复合组件部分，而不是 View。
4. 绝不硬编码颜色。 所有颜色都是语义令牌，例如 bg-card、 text-muted-foreground、border-border。字面量颜色会同时破坏全部六种主题。

关键规则

每条规则都链接到一个包含错误／正确示例的文件。

样式 → rules/styling.md

• 只使用语义令牌。 使用 bg-card，不要用 bg-neutral-900。不要覆盖 dark:——令牌已经能自动适配，而且在命名主题中 dark: 完全无法解析。
• 使用 gap-*，绝不使用 space-y-*。 React Native 不支持 space-*。
• className 用于布局，不要用它重新设置组件的颜色或字体样式。
• 条件类名使用 cn()，不要使用模板字符串三元表达式。
• 使用 useCSSVariable 解析动态颜色，绝不要从主题中读取十六进制颜色值。
• 新增任意值后需要重启。 如果运行中的开发服务器启动后，才在文件中加入 h-[330px]，它将无法编译——不会报错，也不会发出警告，该元素会悄无声息地失去此属性。

组合 → rules/composition.md

• 在根节点放置一个 PanelUIProvider，且只能有一个。 覆盖层会渲染到它的 portal 容器中；没有它，Dialog、BottomSheet、Popover、Select 和 Toast 会挂载但不会显示。
• 复合组件的各部分必须属于其根组件。 Card.Header 放在 Card 内，Select.Item 放在 Select.Content 内。在根组件外使用会抛出包含该部分名称的错误。
• 覆盖层使用 open + onOpenChange 控制，或使用 defaultOpen 以非受控方式运行。 不要通过条件渲染覆盖层来关闭它——它需要完成退出动画。
• 字段由 Field + Label + 控件组成，而不是在 View 中放一个 Text。

动画 → rules/animation.md

• 仅使用 Reanimated 4。 绝不要使用 React Native 核心 Animated——两者无法组合，而且核心 Animated 会让工作回到 JS 线程，而避免这种情况正是这个库的用途。
• 使用共享值和 useAnimatedStyle，不要在动画循环中使用状态。
• 在模块作用域调用 tv()，不要在渲染期间调用。

原生控件 → rules/native.md

• “原生”在 iOS 上指 Liquid Glass。 仅传入 native 不够——还要传入 glass。
• 原生控件会忽略 className 和所有 token。 外观由平台决定；间距必须由容器提供。
• 绝不要在带标签的原生按钮内放置元素。 它没有确定的宽度，应用会在原生代码中崩溃，JS 的 try 无法捕获。

主题

共有六种主题，分属三个系列——Panel、Moon、Grass——每个系列各有浅色和深色主题。每个系列除了调色板，还会设置自己的圆角比例，因此切换主题也会改变 UI 的形状。使用 useThemeMode() 在运行时切换；必须先在 metro.config.js 的 extraThemes 中列出命名主题，然后重启开发服务器。请参阅 theming.md。

添加组件

npx panelui-cli@latest add bottom-sheet     # copies the source in
npx panelui-cli@latest list                 # everything available

项目使用这个包时无需安装任何内容——导入即可使用。完整命令参考见 cli.md；MCP 服务及其工具见 mcp.md。

该用哪个组件

完整列表、各组件的简要说明及参考链接见 components.md。常见场景：

需求	使用
一个操作	Button；若要创建分段按钮组或拆分按钮，则使用 ButtonGroup
从底部边缘弹出的面板	BottomSheet
模态框	Dialog
锚定到打开它的元素的面板	Popover；若要显示操作列表，则使用 Menu
从列表中选择一个值	Select；若需要筛选，则使用 Combobox
搜索内容	SearchBar，其结果会显示在字段和键盘上方
文本输入	Input、Textarea、InputGroup、NumberInput、OtpInput、TagInput
日期或时间	Calendar、DatePicker、TimePicker、DateTimePicker
表单状态和验证	Form + Field
列表行	Item；若行后有操作，则使用 Swipe
设置页面	Frame + Frame.Panel + Frame.Row
指标	Kpi
系列数据	LineChart、AreaChart、BarChart、PieChart、RingChart，以及另外十一种
对话	MessageScroller + Message，在轮次之间使用 Marker
助手输出	Response、Reasoning、Sources、Task、Plan、CodeBlock
加载	布局占位使用 Skeleton，工作状态使用 Spinner 或 Loader，流式文本使用 Shimmer
无内容可显示	EmptyState
临时消息	Toast
Hook、工具函数、原语	hooks.md

详细参考

• setup.md — 安装，以及样式无法生效的所有原因
• components.md — 每个组件，以及包含完整 API 的对应文件
• recipes.md — 完整页面：设置、表单、聊天、筛选器、列表、图表、搜索
• hooks.md — hooks、工具、主题 API 和基础组件
• theming.md — tokens、三个系列、圆角、useCSSVariable
• cli.md — init、add、list、mcp、panelui.json、注册表
• mcp.md — MCP 服务及其六个工具
• rules/styling.md、rules/composition.md、 rules/animation.md、rules/native.md

以上内容都在此文件夹中。文档也以 Markdown 格式发布在网上，如果你需要包含所有示例的页面： https://panelui.dev/llms.mdx/<group>/<slug>，索引位于 https://panelui.dev/llms.txt。