core-components

Core Components - 核心组件库与设计系统

技能概述

Core Components 是一个基于 design tokens 的 UI 组件库，提供统一的布局组件、表单控件和样式系统，帮助开发者构建一致性的 React Native 应用界面。

适用场景

构建 React Native 应用界面：当你需要创建移动端 UI 时，使用核心组件库可以确保样式和行为的一致性，避免重复编写布局代码。

需要统一的设计规范：当团队需要维护多个页面或应用的视觉一致性时，通过 design tokens 管理颜色、间距、字体等设计变量，实现全局统一的设计系统。

表单与列表布局开发：当你需要快速实现表单输入、卡片容器、列表项等常见 UI 模式时，核心组件提供了开箱即用的布局模式和验证支持。

核心功能

Design Tokens 设计令牌系统

提供 $1-$8 间距令牌、语义化颜色令牌（如 $textPrimary、$statusError）以及 $xs-$2xl 字体令牌。通过使用令牌替代硬编码值，确保全应用样式一致性，支持主题切换和响应式调整。

核心布局组件库

包含 Box 基础布局容器、HStack/VStack 弹性布局组件、Text 排版组件、Button 多变体按钮、Input 表单输入和 Card 内容容器等组件。所有组件均支持 design tokens 属性，提供统一的 API 风格。

布局模式与最佳实践

预置 Screen、Form、List Item 等常见布局模式，并提供反模式示例（如避免硬编码、避免平台原生组件）。同时包含与其他技能（如 react-ui-patterns、testing-patterns、storybook）的集成指南。

常见问题

什么是 design tokens，为什么要用？

Design tokens 是设计系统中的命名变量，如 $4 代表 16px 间距、$textPrimary 代表主要文字颜色。使用 design tokens 可以避免硬编码样式值，当设计规范变更时只需修改令牌定义，全应用自动更新。同时，令牌提供了语义化命名（如 $statusError），使代码更易理解和维护。

如何避免硬编码样式值？

核心组件库提供了所有常用的 design tokens 属性。对于间距，使用 $1-$8 令牌（如 padding="$4"）；对于颜色，使用语义化令牌（如 backgroundColor="$backgroundPrimary"）；对于字体，使用字号令牌（如 fontSize="$lg"）。所有核心组件（Box、Text、Button 等）都直接支持这些令牌属性，无需编写内联样式。

Box 组件和平台原生 View 有什么区别？

Box 是基于平台 View 封装的基础布局组件，增加了对 design tokens 的原生支持。你可以直接使用 padding="$4" 而非 style={{ padding: 16 }}，使用 backgroundColor="$primary500" 而非 style={{ backgroundColor: '#3b82f6' }}。Box 还提供了更一致的 API 风格，与其他核心组件（HStack、VStack、Card）配合使用更加顺畅。

核心组件库包含哪些常用组件？

核心组件库包含 Box（基础布局容器）、HStack/VStack（横向/纵向弹性布局）、Text（排版组件）、Button（支持 solid/outline/ghost/link 四种变体）、Input（带验证的表单输入）、Card（内容容器）、Screen/ScreenHeader/ScreenContent（页面布局组件）等。所有组件都支持 design tokens 属性，提供统一的交互状态（如 isLoading、isDisabled）。

如何使用 HStack 和 VStack 实现布局？

HStack 用于横向排列子元素，VStack 用于纵向排列。两者都支持 gap 属性控制子元素间距（使用 design tokens，如 gap="$3"），以及 alignItems、justifyContent 等弹性布局属性。例如：<HStack gap="$3" alignItems="center"><Icon /><Text>内容</Text></HStack> 可以实现图标和文字的横向排列。

Button 组件有哪些变体，什么时候用哪个？

Button 提供四种变体：solid（实心按钮，用于主要操作）、outline（描边按钮，用于次要操作）、ghost（幽灵按钮，用于第三级或微妙操作）、link（链接按钮，用于行内操作）。每个变体还支持 size 属性控制大小、isLoading 显示加载状态、isDisabled 禁用状态。

如何实现带验证的表单输入组件？

Input 组件内置了验证支持，接受 error 属性显示错误状态、label 属性显示字段标签。通常与表单库配合使用：<Input value={value} onChangeText={setValue} placeholder="输入文本" error={touched ? errors.field : undefined} label="字段名称" />。核心组件库还提供了表单布局模式示例，使用 VStack + gap 属性可以快速排列多个表单项。

核心组件库与测试模式如何集成？

核心组件支持在测试中进行 mock，可以模拟组件行为而不依赖真实渲染。与 testing-patterns 技能配合时，可以创建核心组件的测试替身。同时，与 storybook 技能配合可以可视化展示组件的各种变体状态，帮助团队文档化和复用组件。