kor-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Universal UI Library

Universal UI库

Universal UI (@korsolutions/ui) is a library of unstyled UI primitives for React Native and Expo applications. It provides production-ready components with a focus on minimal dependencies, compound component patterns, and comprehensive theming support.

Universal UI（@korsolutions/ui）是一款为React Native和Expo应用打造的无样式UI基元库。它提供可用于生产环境的组件，主打依赖精简、复合组件模式以及全面的主题支持。

Core Principles

核心原则

Unstyled Primitives: Components are unstyled by default with variant-based styling
Compound Components: All components follow Root + sub-component pattern
Variant System: Each component offers multiple style variants
Minimal Dependencies: Only React Native and Expo core dependencies
Full TypeScript Support: Complete type definitions for all components
Cross-Platform: iOS, Android, and Web support

无样式基元：组件默认无样式，采用基于变体的样式系统
复合组件：所有组件遵循Root + 子组件的模式
变体系统：每个组件提供多种样式变体
精简依赖：仅依赖React Native和Expo核心库
完整TypeScript支持：为所有组件提供完整的类型定义
跨平台：支持iOS、Android和Web端

Quick Start

快速开始

Installation

安装

bash

npm install @korsolutions/ui

bash

npm install @korsolutions/ui

or

yarn add @korsolutions/ui

or

bun add @korsolutions/ui

undefined

bun add @korsolutions/ui

undefined

Provider Setup

Provider配置

Wrap your application with

UIProvider

in your root layout:

tsx

import { UIProvider } from "@korsolutions/ui";
import { useSafeAreaInsets } from "react-native-safe-area-context";

export default function RootLayout() {
  const safeAreaInsets = useSafeAreaInsets();

  return (
    <UIProvider safeAreaInsets={safeAreaInsets}>
      <YourApp />
    </UIProvider>
  );
}

在根布局中使用

UIProvider

包裹你的应用：

tsx

import { UIProvider } from "@korsolutions/ui";
import { useSafeAreaInsets } from "react-native-safe-area-context";

export default function RootLayout() {
  const safeAreaInsets = useSafeAreaInsets();

  return (
    <UIProvider safeAreaInsets={safeAreaInsets}>
      <YourApp />
    </UIProvider>
  );
}

Basic Import Pattern

基础导入模式

tsx

import { Button, Input, Card } from "@korsolutions/ui";

function MyComponent() {
  return (
    <Card.Root>
      <Card.Body>
        <Button onPress={() => console.log("Pressed")}>
          Click Me
        </Button>
      </Card.Body>
    </Card.Root>
  );
}

tsx

import { Button, Input, Card } from "@korsolutions/ui";

function MyComponent() {
  return (
    <Card.Root>
      <Card.Body>
        <Button onPress={() => console.log("Pressed")}>
          Click Me
        </Button>
      </Card.Body>
    </Card.Root>
  );
}

Your First Component

你的第一个组件

tsx

import { useState } from "react";
import { Button } from "@korsolutions/ui";

function SubmitButton() {
  const [loading, setLoading] = useState(false);

  const handleSubmit = async () => {
    setLoading(true);
    await submitForm();
    setLoading(false);
  };

  return (
    <Button variant="default" isLoading={loading} onPress={handleSubmit}>
      Submit
    </Button>
  );
}

tsx

import { useState } from "react";
import { Button } from "@korsolutions/ui";

function SubmitButton() {
  const [loading, setLoading] = useState(false);

  const handleSubmit = async () => {
    setLoading(true);
    await submitForm();
    setLoading(false);
  };

  return (
    <Button variant="default" isLoading={loading} onPress={handleSubmit}>
      Submit
    </Button>
  );
}

Component Overview

组件概览

Layout & Structure

布局与结构

Component	Description	Variants	Reference
Card	Content container with header, body, and footer	default	Layout Components
Separator	Visual divider between content	horizontal, vertical	Layout Components
ScrollBar	Custom scrollbar styling	default	Layout Components
Portal	Render components outside hierarchy	-	Layout Components
List	Performance-optimized list rendering	-	Layout Components

组件	描述	变体	参考文档
Card	包含页眉、正文和页脚的内容容器	default	布局组件
Separator	内容间的视觉分隔线	horizontal, vertical	布局组件
ScrollBar	自定义滚动条样式	default	布局组件
Portal	在组件层级外渲染内容	-	布局组件
List	性能优化的列表渲染	-	布局组件

Form Inputs

表单输入

Component	Description	Variants	Reference
Input	Text input field	default	Input Components
NumericInput	Formatted numeric input (currency, percentage, etc.)	default	Input Components
PhoneInput	Phone number input with country selector (E.164)	default	Input Components
Textarea	Multi-line text input	default	Input Components
Checkbox	Toggle selection with label	default	Input Components
Select	Dropdown selection from a list of options	default	Input Components
Combobox	Autocomplete input with filterable dropdown	default	Input Components
Field	Form field wrapper with label and validation	-	Input Components

组件	描述	变体	参考文档
Input	文本输入框	default	输入组件
NumericInput	格式化数值输入框（货币、百分比等）	default	输入组件
PhoneInput	带国家选择器的电话号码输入框（遵循E.164标准）	default	输入组件
Textarea	多行文本输入框	default	输入组件
Checkbox	带标签的切换选择框	default	输入组件
Select	下拉选择框	default	输入组件
Combobox	带自动补全的可筛选下拉输入框	default	输入组件
Field	包含标签和验证的表单字段包装器	-	输入组件

Display Components

展示组件

Component	Description	Variants	Reference
Typography	Text with semantic variants	heading-xs to 3xl, body-xs to lg, label, code, caption	Display Components
Avatar	User avatar with image and fallback	default	Display Components
Badge	Status indicators and labels	default, secondary, success, warning, danger, info	Display Components
Icon	Icon rendering with render prop pattern	-	Display Components
Empty	Empty state placeholders	default	Display Components
Progress	Linear progress indicators	default	Display Components

组件	描述	变体	参考文档
Typography	带语义变体的文本组件	heading-xs to 3xl, body-xs to lg, label, code, caption	展示组件
Avatar	带图片和回退样式的用户头像	default	展示组件
Badge	状态指示器和标签	default, secondary, success, warning, danger, info	展示组件
Icon	采用渲染属性模式的图标组件	-	展示组件
Empty	空状态占位符	default	展示组件
Progress	线性进度指示器	default	展示组件

Interactive Components

交互组件

Component	Description	Variants	Reference
Button	Action buttons with loading states	default, secondary, ghost	Interactive Components
IconButton	Icon-only pressable button	default, secondary, ghost	Interactive Components
Tabs	Tabbed navigation	default, line	Interactive Components
Menu	Dropdown menus	default	Interactive Components
Popover	Positioned overlay content	default	Interactive Components
Calendar	Date picker with range selection	default	Interactive Components

组件	描述	变体	参考文档
Button	带加载状态的操作按钮	default, secondary, ghost	交互组件
IconButton	仅含图标的可点击按钮	default, secondary, ghost	交互组件
Tabs	标签式导航	default, line	交互组件
Menu	下拉菜单	default	交互组件
Popover	定位式浮层内容	default	交互组件
Calendar	支持范围选择的日期选择器	default	交互组件

Feedback Components

反馈组件

Component	Description	Variants	Reference
Alert	Inline notifications with icons	default, destructive	Feedback Components
AlertDialog	Modal confirmation dialogs	default	Feedback Components
Toast	Transient notifications	default, success, danger	Feedback Components

组件	描述	变体	参考文档
Alert	带图标的内联通知	default, destructive	反馈组件
AlertDialog	模态确认对话框	default	反馈组件
Toast	临时通知	default, success, danger	反馈组件

Compound Component Pattern

复合组件模式

All Universal UI components follow a compound component pattern where a parent component (usually

Root

) provides context to child sub-components.

所有Universal UI组件都遵循复合组件模式，父组件（通常为

Root

）为子组件提供上下文。

Structure

结构

tsx

<Component.Root {...rootProps}>
  <Component.SubComponent1 {...props} />
  <Component.SubComponent2 {...props} />
</Component.Root>

tsx

<Component.Root {...rootProps}>
  <Component.SubComponent1 {...props} />
  <Component.SubComponent2 {...props} />
</Component.Root>

Common Sub-Components

常见子组件

Most components share similar sub-component naming:

Root - Parent container that provides context
Label - Text label for the component
Icon - Icon display with render prop pattern
Description - Secondary descriptive text
Title - Primary heading text
Body - Main content area
Header - Top section
Footer - Bottom section

大多数组件使用相似的子组件命名：

Root - 提供上下文的父容器
Label - 组件的文本标签
Icon - 采用渲染属性模式的图标展示
Description - 辅助描述文本
Title - 主标题文本
Body - 主要内容区域
Header - 顶部区域
Footer - 底部区域

Example: Button

示例：Button

tsx

<Button variant="default" onPress={handlePress} isLoading={loading}>
  Submit Form
</Button>

tsx

<Button variant="default" onPress={handlePress} isLoading={loading}>
  Submit Form
</Button>

Example: Alert with Icon

示例：带图标的Alert

tsx

import { AlertCircle } from "lucide-react-native";

<Alert.Root variant="destructive">
  <Alert.Icon render={AlertCircle} />
  <Alert.Body>
    <Alert.Title>Error</Alert.Title>
    <Alert.Description>Something went wrong</Alert.Description>
  </Alert.Body>
</Alert.Root>;

tsx

import { AlertCircle } from "lucide-react-native";

<Alert.Root variant="destructive">
  <Alert.Icon render={AlertCircle} />
  <Alert.Body>
    <Alert.Title>Error</Alert.Title>
    <Alert.Description>Something went wrong</Alert.Description>
  </Alert.Body>
</Alert.Root>;

Example: Field with Input

示例：带Input的Field

tsx

<Field.Root>
  <Field.Label for="email">Email Address</Field.Label>
  <Input id="email" value={email} onChange={setEmail} placeholder="you@example.com" />
  <Field.Description>We'll never share your email.</Field.Description>
  {error && <Field.Error>{error}</Field.Error>}
</Field.Root>

tsx

<Field.Root>
  <Field.Label for="email">Email Address</Field.Label>
  <Input id="email" value={email} onChange={setEmail} placeholder="you@example.com" />
  <Field.Description>We'll never share your email.</Field.Description>
  {error && <Field.Error>{error}</Field.Error>}
</Field.Root>;

Style Composition

样式组合

Component styles are always composed with variant styles first, allowing user styles to override:

tsx

// Variant styles are applied first
<Button style={{ marginTop: 16 }}>
  Custom Button
</Button>

This ensures your custom styles always take precedence over variant defaults.

组件样式始终先应用变体样式，允许用户样式覆盖：

tsx

// 先应用变体样式
<Button style={{ marginTop: 16 }}>
  Custom Button
</Button>

这确保你的自定义样式始终优先于变体默认样式。

Theme System Basics

主题系统基础

Universal UI includes a comprehensive theming system with light/dark mode support.

Universal UI包含全面的主题系统，支持明暗模式。

Theme Tokens

主题令牌

The theme provides these customizable tokens:

colors - Color palette with light/dark schemes
radius - Border radius (default: 10)
fontSize - Base font size (default: 16)
fontFamily - Font family (default: "System")
letterSpacing - Letter spacing (default: 0)

主题提供以下可自定义的令牌：

colors - 包含明暗配色方案的调色板
radius - 边框圆角（默认值：10）
fontSize - 基础字体大小（默认值：16）
fontFamily - 字体族（默认值："System"）
letterSpacing - 字间距（默认值：0）

Color Tokens

颜色令牌

Each color scheme (light/dark) includes:

background - Main background color
foreground - Main text color
primary - Primary brand color
primaryForeground - Text on primary color
secondary - Secondary brand color
secondaryForeground - Text on secondary color
muted - Muted background color
mutedForeground - Muted text color
border - Border color
surface - Surface/card background
success, warning, danger, info - Semantic colors

每个配色方案（明/暗）包含：

background - 主背景色
foreground - 主文本色
primary - 主品牌色
primaryForeground - 主品牌色上的文本色
secondary - 次品牌色
secondaryForeground - 次品牌色上的文本色
muted - 弱化背景色
mutedForeground - 弱化文本色
border - 边框色
surface - 表层/卡片背景色
success, warning, danger, info - 语义化颜色

Using the Theme

使用主题

Access the theme in your components:

tsx

import { useTheme } from "@korsolutions/ui";

function MyComponent() {
  const theme = useTheme();

  return (
    <View
      style={{
        backgroundColor: theme.colors.background,
        borderRadius: theme.radius,
        padding: 16,
      }}
    >
      <Text
        style={{
          color: theme.colors.foreground,
          fontSize: theme.fontSize,
          fontFamily: theme.fontFamily,
        }}
      >
        Themed Content
      </Text>
    </View>
  );
}

在组件中访问主题：

tsx

import { useTheme } from "@korsolutions/ui";

function MyComponent() {
  const theme = useTheme();

  return (
    <View
      style={{
        backgroundColor: theme.colors.background,
        borderRadius: theme.radius,
        padding: 16,
      }}
    >
      <Text
        style={{
          color: theme.colors.foreground,
          fontSize: theme.fontSize,
          fontFamily: theme.fontFamily,
        }}
      >
        Themed Content
      </Text>
    </View>
  );
}

Color Scheme

配色方案

Toggle between light and dark mode:

tsx

const theme = useTheme();

// Get current scheme
console.log(theme.colorScheme); // "light" | "dark"

// Set color scheme
theme.setColorScheme("dark");

切换明暗模式：

tsx

const theme = useTheme();

// 获取当前配色方案
console.log(theme.colorScheme); // "light" | "dark"

// 设置配色方案
theme.setColorScheme("dark");

Quick Customization

快速定制

Customize the theme via UIProvider:

tsx

<UIProvider
  theme={{
    radius: 12,
    fontSize: 18,
    colors: {
      light: {
        primary: "hsla(220, 90%, 56%, 1)",
        primaryForeground: "hsla(0, 0%, 100%, 1)",
      },
      dark: {
        primary: "hsla(220, 90%, 70%, 1)",
        primaryForeground: "hsla(0, 0%, 100%, 1)",
      },
    },
  }}
  safeAreaInsets={safeAreaInsets}
>
  <App />
</UIProvider>

For detailed theming documentation, see Theme Customization.

通过UIProvider定制主题：

tsx

<UIProvider
  theme={{
    radius: 12,
    fontSize: 18,
    colors: {
      light: {
        primary: "hsla(220, 90%, 56%, 1)",
        primaryForeground: "hsla(0, 0%, 100%, 1)",
      },
      dark: {
        primary: "hsla(220, 90%, 70%, 1)",
        primaryForeground: "hsla(0, 0%, 100%, 1)",
      },
    },
  }}
  safeAreaInsets={safeAreaInsets}
>
  <App />
</UIProvider>

如需详细的主题文档，请查看主题定制。

Common Patterns

常见模式

Form Field with Validation

带验证的表单字段

tsx

import { Field, Input } from "@korsolutions/ui";

<Field.Root>
  <Field.Label for="email">Email</Field.Label>
  <Input id="email" value={email} onChange={setEmail} placeholder="you@example.com" />
  <Field.Description>Enter your email address</Field.Description>
  {error && <Field.Error>{error}</Field.Error>}
</Field.Root>;

tsx

import { Field, Input } from "@korsolutions/ui";

<Field.Root>
  <Field.Label for="email">Email</Field.Label>
  <Input id="email" value={email} onChange={setEmail} placeholder="you@example.com" />
  <Field.Description>Enter your email address</Field.Description>
  {error && <Field.Error>{error}</Field.Error>}
</Field.Root>;

Icons with Render Prop

带渲染属性的图标

Universal UI uses a render prop pattern for icons, supporting any icon library:

tsx

import { AlertCircle, CheckCircle } from "lucide-react-native";
import { Alert } from "@korsolutions/ui";

// With lucide-react-native
<Alert.Icon render={AlertCircle} />

// With custom function
<Alert.Icon render={(props) => <CheckCircle {...props} size={20} />} />

// With @expo/vector-icons
import { MaterialCommunityIcons } from "@expo/vector-icons";
<Alert.Icon render={(props) => (
  <MaterialCommunityIcons {...props} name="alert-circle" />
)} />

Universal UI为图标采用渲染属性模式，支持任何图标库：

tsx

import { AlertCircle, CheckCircle } from "lucide-react-native";
import { Alert } from "@korsolutions/ui";

// 使用lucide-react-native
<Alert.Icon render={AlertCircle} />

// 使用自定义函数
<Alert.Icon render={(props) => <CheckCircle {...props} size={20} />} />

// 使用@expo/vector-icons
import { MaterialCommunityIcons } from "@expo/vector-icons";
<Alert.Icon render={(props) => (
  <MaterialCommunityIcons {...props} name="alert-circle" />
)} />

Icon Button

图标按钮

A pressable button that renders a single icon. Uses the same render prop pattern as Icon:

tsx

import { IconButton } from "@korsolutions/ui";
import { Heart, Settings, Trash } from "lucide-react-native";

// Basic usage
<IconButton render={Heart} onPress={() => console.log("Liked")} />

// Variants (matches Button variants)
<IconButton render={Settings} variant="secondary" />
<IconButton render={Settings} variant="ghost" />

// Custom size and color
<IconButton render={Trash} size={32} color="red" />

// Disabled
<IconButton render={Heart} isDisabled />

仅渲染单个图标的可点击按钮，与Icon组件采用相同的渲染属性模式：

tsx

import { IconButton } from "@korsolutions/ui";
import { Heart, Settings, Trash } from "lucide-react-native";

// 基础用法
<IconButton render={Heart} onPress={() => console.log("Liked")} />

// 变体（与Button组件变体一致）
<IconButton render={Settings} variant="secondary" />
<IconButton render={Settings} variant="ghost" />

// 自定义尺寸和颜色
<IconButton render={Trash} size={32} color="red" />

// 禁用状态
<IconButton render={Heart} isDisabled />

Separator

分隔线

A visual divider between content sections:

tsx

import { Separator } from "@korsolutions/ui";

// Horizontal (default)
<Separator />

// Vertical
<Separator variant="vertical" />

内容区域间的视觉分隔线：

tsx

import { Separator } from "@korsolutions/ui";

// 水平方向（默认）
<Separator />

// 垂直方向
<Separator variant="vertical" />

Controlled State Management

受控状态管理

Most input components use controlled state:

tsx

import { useState } from "react";
import { Input, Checkbox } from "@korsolutions/ui";

function Form() {
  const [text, setText] = useState("");
  const [checked, setChecked] = useState(false);

  return (
    <>
      <Input value={text} onChange={setText} />
      <Checkbox.Root checked={checked} onChange={setChecked}>
        <Checkbox.Indicator />
        <Checkbox.Content>
          <Checkbox.Title>Accept terms</Checkbox.Title>
        </Checkbox.Content>
      </Checkbox.Root>
    </>
  );
}

大多数输入组件使用受控状态：

tsx

import { useState } from "react";
import { Input, Checkbox } from "@korsolutions/ui";

function Form() {
  const [text, setText] = useState("");
  const [checked, setChecked] = useState(false);

  return (
    <>
      <Input value={text} onChange={setText} />
      <Checkbox.Root checked={checked} onChange={setChecked}>
        <Checkbox.Indicator />
        <Checkbox.Content>
          <Checkbox.Title>Accept terms</Checkbox.Title>
        </Checkbox.Content>
      </Checkbox.Root>
    </>
  );
}

Loading States

加载状态

Buttons support loading states with built-in spinner:

tsx

<Button isLoading={isSubmitting} onPress={handleSubmit}>
  Submit
</Button>

When

isLoading

is true, the button displays

ActivityIndicator

and disables interaction.

Button组件支持带内置加载动画的加载状态：

tsx

<Button isLoading={isSubmitting} onPress={handleSubmit}>
  Submit
</Button>

当

isLoading

为true时，按钮会显示

ActivityIndicator

并禁用交互。

Disabled States

禁用状态

Most components support disabled states:

tsx

<Button isDisabled={!formValid} onPress={handleSubmit}>
  Submit
</Button>

<Input isDisabled value={email} onChange={setEmail} />

<Checkbox.Root disabled checked={value} onChange={setValue}>
  <Checkbox.Indicator />
  <Checkbox.Content>
    <Checkbox.Title>Disabled option</Checkbox.Title>
  </Checkbox.Content>
</Checkbox.Root>

大多数组件支持禁用状态：

tsx

<Button isDisabled={!formValid} onPress={handleSubmit}>
  Submit
</Button>

<Input isDisabled value={email} onChange={setEmail} />

<Checkbox.Root disabled checked={value} onChange={setValue}>
  <Checkbox.Indicator />
  <Checkbox.Content>
    <Checkbox.Title>Disabled option</Checkbox.Title>
  </Checkbox.Content>
</Checkbox.Root>

Selecting Variants

选择变体

Most components offer multiple variants:

tsx

// Button variants
<Button variant="default">
  Default Button
</Button>

<Button variant="secondary">
  Secondary Button
</Button>

<Button variant="ghost">
  Ghost Button
</Button>

// Alert variants
<Alert.Root variant="default">
  <Alert.Body>
    <Alert.Title>Info</Alert.Title>
  </Alert.Body>
</Alert.Root>

<Alert.Root variant="destructive">
  <Alert.Body>
    <Alert.Title>Error</Alert.Title>
  </Alert.Body>
</Alert.Root>

// Badge variants
<Badge variant="success">Active</Badge>
<Badge variant="danger">Inactive</Badge>
<Badge variant="warning">Pending</Badge>

大多数组件提供多种变体：

tsx

// Button组件变体
<Button variant="default">
  Default Button
</Button>

<Button variant="secondary">
  Secondary Button
</Button>

<Button variant="ghost">
  Ghost Button
</Button>

// Alert组件变体
<Alert.Root variant="default">
  <Alert.Body>
    <Alert.Title>Info</Alert.Title>
  </Alert.Body>
</Alert.Root>

<Alert.Root variant="destructive">
  <Alert.Body>
    <Alert.Title>Error</Alert.Title>
  </Alert.Body>
</Alert.Root>

// Badge组件变体
<Badge variant="success">Active</Badge>
<Badge variant="danger">Inactive</Badge>
<Badge variant="warning">Pending</Badge>

Style Overrides

样式覆盖

Override component styles using the

style

prop:

tsx

<Button
  style={{
    marginTop: 20,
    backgroundColor: "blue",
  }}
>
  Custom Styled
</Button>

使用

style

属性覆盖组件样式：

tsx

<Button
  style={{
    marginTop: 20,
    backgroundColor: "blue",
  }}
>
  Custom Styled
</Button>

Import Reference

导入参考

Component Imports

组件导入

tsx

// Import individual components
import { Button, Input, Card, Alert } from "@korsolutions/ui";

// Import all components
import * as UI from "@korsolutions/ui";

tsx

// 导入单个组件
import { Button, Input, Card, Alert } from "@korsolutions/ui";

// 导入所有组件
import * as UI from "@korsolutions/ui";

Hook Imports

Hook导入

tsx

// Theme hook
import { useTheme } from "@korsolutions/ui";

// Responsive design hook
import { useScreenSize } from "@korsolutions/ui";

// React Navigation theme integration
import { useReactNavigationTheme } from "@korsolutions/ui";

tsx

// 主题Hook
import { useTheme } from "@korsolutions/ui";

// 响应式设计Hook
import { useScreenSize } from "@korsolutions/ui";

// React Navigation主题集成
import { useReactNavigationTheme } from "@korsolutions/ui";

Provider Import

Provider导入

tsx

import { UIProvider } from "@korsolutions/ui";

tsx

import { UIProvider } from "@korsolutions/ui";

Type Imports

类型导入

tsx

// Component prop types
import type { ButtonRootProps } from "@korsolutions/ui";
import type { InputProps } from "@korsolutions/ui";

// Theme types
import type { ThemeAssets, Colors } from "@korsolutions/ui";

tsx

// 组件属性类型
import type { ButtonRootProps } from "@korsolutions/ui";
import type { InputProps } from "@korsolutions/ui";

// 主题类型
import type { ThemeAssets, Colors } from "@korsolutions/ui";

Quick Troubleshooting

快速故障排查

Provider Not Wrapping App

未用Provider包裹应用

Issue: Components don't render or theme doesn't apply

Solution: Ensure

UIProvider

wraps your app in the root layout:

tsx

// app/_layout.tsx
import { UIProvider } from "@korsolutions/ui";

export default function RootLayout() {
  return (
    <UIProvider>
      <Stack />
    </UIProvider>
  );
}

问题：组件不渲染或主题不生效

解决方案：确保在根布局中使用

UIProvider

包裹应用：

tsx

// app/_layout.tsx
import { UIProvider } from "@korsolutions/ui";

export default function RootLayout() {
  return (
    <UIProvider>
      <Stack />
    </UIProvider>
  );
}

Import Errors

导入错误

Issue: Cannot resolve

@korsolutions/ui

Solution: Install the package and restart your bundler:

bash

npm install @korsolutions/ui

问题：无法解析

@korsolutions/ui

解决方案：安装包并重启打包工具：

bash

npm install @korsolutions/ui

Restart Metro bundler

重启Metro打包工具

undefined

undefined

Theme Not Updating

主题未更新

Issue: Theme changes don't reflect in components

Solution: Ensure theme customization is passed to UIProvider before app renders:

tsx

const customTheme = {
  colors: { light: { primary: "hsla(220, 90%, 56%, 1)" } },
};

<UIProvider theme={customTheme}>
  <App />
</UIProvider>;

问题：主题更改未在组件中反映

解决方案：确保在应用渲染前将主题定制参数传入UIProvider：

tsx

const customTheme = {
  colors: { light: { primary: "hsla(220, 90%, 56%, 1)" } },
};

<UIProvider theme={customTheme}>
  <App />
</UIProvider>;

Styles Not Applying

样式未生效

Issue: Custom styles don't override component styles

Solution: Remember style composition order - user styles always override variant styles:

tsx

// This works - style prop overrides variant
<Button style={{ backgroundColor: "red" }}>
  Red Button
</Button>

For comprehensive troubleshooting, see Troubleshooting Guide.

问题：自定义样式未覆盖组件样式

解决方案：记住样式组合顺序 - 用户样式始终覆盖变体样式：

tsx

// 此写法生效 - style属性覆盖变体样式
<Button style={{ backgroundColor: "red" }}>
  Red Button
</Button>

如需全面的故障排查内容，请查看故障排查指南。

Reference Documentation

参考文档

Consult these detailed references as needed:

按需查阅以下详细参考文档：

Component References

组件参考

Layout Components - Card, ScrollBar, Portal, List
Input Components - Input, NumericInput, Textarea, Checkbox, Select, Combobox, Field
Display Components - Typography, Avatar, Badge, Icon, Empty, Progress
Interactive Components - Button, Tabs, Menu, Popover, Calendar
Feedback Components - Alert, AlertDialog, Toast

布局组件 - Card、ScrollBar、Portal、List
输入组件 - Input、NumericInput、Textarea、Checkbox、Select、Combobox、Field
展示组件 - Typography、Avatar、Badge、Icon、Empty、Progress
交互组件 - Button、Tabs、Menu、Popover、Calendar
反馈组件 - Alert、AlertDialog、Toast

System References

系统参考

Theme Customization - Complete theming guide with color schemes, typography, and responsive design
Patterns & Recipes - Common implementation patterns for forms, modals, navigation, and feedback
Troubleshooting - Solutions for setup, component, type, and platform-specific issues

主题定制 - 包含配色方案、排版和响应式设计的完整主题指南
模式与实践 - 表单、模态框、导航和反馈的常见实现模式
故障排查 - 安装、组件、类型和平台特定问题的解决方案