RustUI/CONVENTIONS.md

Pika 开发约定

目录结构

• 组件目录使用 kebab-case：display/avatar/、entry/tree-select/
• 组件文件使用 PascalCase：Avatar.tsx
• 每个组件目录包含：*.tsx、*.module.css、index.ts、*.test.tsx

导出规范

• 组件 TSX 使用 named export
• barrel index.ts 统一 re-export 类型与组件

Props 规范

• 接口中只声明已实现的 props，避免 AI 生成无效代码
• 暂未实现的 API 不要提前写入类型定义

样式规范

层级	前缀	示例
全局 token	--nv-	--nv-color-primary
组件动态值	--_*	--_height、--_padding

• 优先使用 CSS Module + var(--nv-*)
• className 拼接使用 cn() from shared/utils/classNames

共享层

模块	用途
shared/hooks/useControllableState	受控/非受控状态
shared/hooks/usePikaContext	ConfigProvider 上下文
shared/hooks/useClickOutside	下拉/浮层点击外部关闭
shared/overlay/useOverlay	Tooltip/Popover 浮层逻辑
shared/utils/cn	className 合并
shared/utils/getSemanticProps	semantic DOM 样式

类型

• 统一使用 PikaSize、PikaStatus（shared/types/common.ts）
• Entry 组件通过 DataEntrySize / DataEntryStatus 别名引用

测试

• 每个主组件至少一个 *.test.tsx
• 测试交互行为，而非实现细节