core-components

用途

Core Components 是一套核心组件库与设计系统模式，目标是在构建 UI 时使用核心库中的组件，而不是平台原生组件，从而保证样式与行为的一致性。它同时规定了设计令牌（Design Tokens）的使用方式，要求绝不硬编码数值。

主要能力

设计令牌

间距令牌：使用令牌而非硬编码值。

// 正确 - 使用令牌
<Box padding="$4" marginBottom="$2" />

// 错误 - 硬编码值
<Box padding={16} marginBottom={8} />

间距令牌对照：$1 = 4px，$2 = 8px，$3 = 12px，$4 = 16px，$6 = 24px，$8 = 32px。

颜色令牌：使用语义化令牌而非硬编码颜色。

// 正确 - 语义令牌
<Text color="$textPrimary" />
<Box backgroundColor="$backgroundSecondary" />

// 错误 - 硬编码颜色
<Text color="#333333" />
<Box backgroundColor="rgb(245, 245, 245)" />

语义令牌用途：$textPrimary 用于主文本，$textSecondary 用于辅助文本，$textTertiary 用于禁用/提示文本，$primary500 用于品牌/强调色，$statusError 用于错误状态，$statusSuccess 用于成功状态。

排版令牌：

<Text fontSize="$lg" fontWeight="$semibold" />

字号令牌对照：$xs = 12px，$sm = 14px，$md = 16px，$lg = 18px，$xl = 20px，$2xl = 24px。

核心组件

Box：支持令牌的基础布局组件。

<Box
  padding="$4"
  backgroundColor="$backgroundPrimary"
  borderRadius="$lg"
>
  {children}
</Box>

HStack / VStack：水平与垂直弹性布局。

<HStack gap="$3" alignItems="center">
  <Icon name="user" />
  <Text>Username</Text>
</HStack>

<VStack gap="$4" padding="$4">
  <Heading>Title</Heading>
  <Text>Content</Text>
</VStack>

Text：支持令牌的排版组件。

<Text
  fontSize="$lg"
  fontWeight="$semibold"
  color="$textPrimary"
>
  Hello World
</Text>

Button：带变体的交互按钮。

<Button
  onPress={handlePress}
  variant="solid"
  size="md"
  isLoading={loading}
  isDisabled={disabled}
>
  Click Me
</Button>

变体用途：solid 用于主要操作，outline 用于次要操作，ghost 用于三级/弱化操作，link 用于内联操作。

Input：带校验的表单输入。

<Input
  value={value}
  onChangeText={setValue}
  placeholder="Enter text"
  error={touched ? errors.field : undefined}
  label="Field Name"
/>

Card：内容容器。

<Card padding="$4" gap="$3">
  <CardHeader>
    <Heading size="sm">Card Title</Heading>
  </CardHeader>
  <CardBody>
    <Text>Card content</Text>
  </CardBody>
</Card>

使用方式

布局模式

屏幕布局：

const MyScreen = () => (
  <Screen>
    <ScreenHeader title="Page Title" />
    <ScreenContent padding="$4">
      {/* Content */}
    </ScreenContent>
  </Screen>
);

表单布局：

<VStack gap="$4" padding="$4">
  <Input label="Name" {...nameProps} />
  <Input label="Email" {...emailProps} />
  <Button isLoading={loading}>Submit</Button>
</VStack>

列表项布局：

<HStack
  padding="$4"
  gap="$3"
  alignItems="center"
  borderBottomWidth={1}
  borderColor="$borderLight"
>
  <Avatar source={{ uri: imageUrl }} size="md" />
  <VStack flex={1}>
    <Text fontWeight="$semibold">{title}</Text>
    <Text color="$textSecondary" fontSize="$sm">{subtitle}</Text>
  </VStack>
  <Icon name="chevron-right" color="$textTertiary" />
</HStack>

反模式

// 错误 - 硬编码值
<View style={{ padding: 16, backgroundColor: '#fff' }}>

// 正确 - 设计令牌
<Box padding="$4" backgroundColor="$backgroundPrimary">

// 错误 - 平台原生组件
import { View, Text } from 'react-native';

// 正确 - 核心组件
import { Box, Text } from 'components/core';

// 错误 - 内联样式
<Text style={{ fontSize: 18, fontWeight: '600' }}>

// 正确 - 令牌属性
<Text fontSize="$lg" fontWeight="$semibold">

组件属性模式

创建组件时使用基于令牌的属性：

interface CardProps {
  padding?: '$2' | '$4' | '$6';
  variant?: 'elevated' | 'outlined' | 'filled';
  children: React.ReactNode;
}

const Card = ({ padding = '$4', variant = 'elevated', children }: CardProps) => (
  <Box
    padding={padding}
    backgroundColor="$backgroundPrimary"
    borderRadius="$lg"
    {...variantStyles[variant]}
  >
    {children}
  </Box>
);

与其他技能的集成

react-ui-patterns：使用核心组件处理 UI 状态
testing-patterns：在测试中模拟核心组件
storybook：记录组件变体

适用场景

当任务明确匹配上述范围时适用，例如构建 UI、使用设计令牌或使用组件库时。

限制

仅在任务明确匹配上述范围时使用本技能。
不要将输出视为环境特定验证、测试或专家评审的替代品。
如果缺少必需的输入、权限、安全边界或成功标准，应停止并请求澄清。