zkit-ui 1.0.0 → 1.0.1

package/src/ui/Button/index.tsx

@@ -837,41 +837,60 @@ function resolveWebCursorStyle(disabled: boolean): ViewStyle | undefined {
   return { cursor: disabled ? 'not-allowed' : 'pointer' } as ViewStyle;
 }
 
-function ButtonImpl(
-  {
-    variant = 'solid',
-    tone = 'primary',
-    size = 'md',
-    shape = 'rounded',
-    block = false,
-    disabled = false,
-    loading = false,
-    loadingMode = 'inline',
-    pressEffect = 'auto',
-    icon,
-    iconPlacement = 'start',
-    iconOnly = false,
-    color,
-    colors,
-    border,
-    layout,
-    gradient,
-    shadow = 'none',
-    children,
-    style,
-    contentStyle,
-    textStyle,
-    accessibilityLabel,
-    accessibilityState,
-    hitSlop,
-    onPress,
-    onPressIn,
-    onPressOut,
-    testID,
-    ...pressableProps
-  }: ButtonProps,
-  ref: React.ForwardedRef<ButtonRef>
-) {
+function shouldUseStaticButtonPath({
+  disabled,
+  loading,
+  pressEffect,
+}: {
+  disabled?: boolean;
+  loading?: boolean;
+  pressEffect?: ButtonPressEffect;
+}) {
+  return !loading && (pressEffect === 'none' || disabled === true);
+}
+
+function useButtonFrame({
+  variant = 'solid',
+  tone = 'primary',
+  size = 'md',
+  shape = 'rounded',
+  block = false,
+  disabled = false,
+  loading = false,
+  icon,
+  iconPlacement = 'start',
+  iconOnly = false,
+  color,
+  colors,
+  border,
+  layout,
+  gradient,
+  shadow = 'none',
+  children,
+  textStyle,
+  accessibilityLabel,
+}: Pick<
+  ButtonProps,
+  | 'variant'
+  | 'tone'
+  | 'size'
+  | 'shape'
+  | 'block'
+  | 'disabled'
+  | 'loading'
+  | 'icon'
+  | 'iconPlacement'
+  | 'iconOnly'
+  | 'color'
+  | 'colors'
+  | 'border'
+  | 'layout'
+  | 'gradient'
+  | 'shadow'
+  | 'children'
+  | 'textStyle'
+  | 'accessibilityLabel'
+>) {
   const theme = useTheme();
   const scheme = useColorScheme();
   const { width: viewportWidth } = useWindowDimensions();
@@ -892,8 +911,6 @@ function ButtonImpl(
 
   const interactionDisabled = disabled || loading;
   const visualDisabled = disabled;
-  const resolvedLoadingMode = iconOnly ? 'overlay' : loadingMode;
-  const centeredLoading = resolvedLoadingMode !== 'inline';
 
   const visualColors = React.useMemo(
     () =>
@@ -1009,16 +1026,6 @@ function ButtonImpl(
   const hasText = resolvedText != null;
   const hasIcon = icon != null;
   const iconSize = layout?.iconSize ?? metrics.iconSize;
-  const loadingSize = React.useMemo(
-    () =>
-      resolveLoadingSize({
-        iconOnly,
-        layout,
-        metrics,
-        variant,
-      }),
-    [iconOnly, layout, metrics, variant]
-  );
   const contentGap = layout?.gap ?? metrics.gap;
   const iconBaseBoxStyle = React.useMemo(() => resolveIconBoxStyle(hasIcon, iconSize), [hasIcon, iconSize]);
   const iconPlacedBoxStyle = React.useMemo((): ViewStyle => {
@@ -1034,6 +1041,278 @@ function ButtonImpl(
     iconOnly && isPrimitiveTextChild(children) ? String(children) : undefined;
   const resolvedAccessibilityLabel = accessibilityLabel ?? inferredAccessibilityLabel;
 
+  return {
+    accentColor,
+    contentGap,
+    contentSizeStyle,
+    defaultHitSlop,
+    gradientCfg,
+    hasGradientBackground,
+    hasIcon,
+    hasText,
+    iconBaseBoxStyle,
+    iconPlacedBoxStyle,
+    iconSize,
+    interactionDisabled,
+    LinearGradientComponent,
+    metrics,
+    paddingStyle,
+    radiusStyle,
+    resolvedAccessibilityLabel,
+    resolvedText,
+    rootSizeStyle,
+    shadowStyle,
+    visualColors,
+    visualDisabled,
+    webCursorStyle,
+    borderStyle,
+  };
+}
+
+function ButtonStaticImpl(
+  {
+    variant = 'solid',
+    tone = 'primary',
+    size = 'md',
+    shape = 'rounded',
+    block = false,
+    disabled = false,
+    loading = false,
+    loadingMode: _loadingMode = 'inline',
+    pressEffect: _pressEffect = 'auto',
+    icon,
+    iconPlacement = 'start',
+    iconOnly = false,
+    color,
+    colors,
+    border,
+    layout,
+    gradient,
+    shadow = 'none',
+    children,
+    style,
+    contentStyle,
+    textStyle,
+    accessibilityLabel,
+    accessibilityState,
+    hitSlop,
+    onPress,
+    testID,
+    ...pressableProps
+  }: ButtonProps,
+  ref: React.ForwardedRef<ButtonRef>
+) {
+  const frame = useButtonFrame({
+    accessibilityLabel,
+    block,
+    border,
+    children,
+    color,
+    colors,
+    disabled,
+    gradient,
+    icon,
+    iconOnly,
+    iconPlacement,
+    layout,
+    loading,
+    shadow,
+    shape,
+    size,
+    textStyle,
+    tone,
+    variant,
+  });
+  const {
+    borderStyle,
+    contentSizeStyle,
+    defaultHitSlop,
+    gradientCfg,
+    hasIcon,
+    iconBaseBoxStyle,
+    iconPlacedBoxStyle,
+    interactionDisabled,
+    LinearGradientComponent,
+    paddingStyle,
+    radiusStyle,
+    resolvedAccessibilityLabel,
+    resolvedText,
+    rootSizeStyle,
+    shadowStyle,
+    visualColors,
+    visualDisabled,
+    webCursorStyle,
+  } = frame;
+
+  const handlePress = React.useCallback(
+    (event: GestureResponderEvent) => {
+      if (interactionDisabled) return;
+      onPress?.(event);
+    },
+    [interactionDisabled, onPress]
+  );
+
+  return (
+    <Pressable
+      {...pressableProps}
+      ref={ref}
+      accessibilityLabel={resolvedAccessibilityLabel}
+      accessibilityRole="button"
+      accessibilityState={{
+        ...accessibilityState,
+        busy: Boolean(loading || accessibilityState?.busy),
+        disabled: Boolean(interactionDisabled || accessibilityState?.disabled),
+      }}
+      disabled={interactionDisabled}
+      hitSlop={hitSlop ?? defaultHitSlop}
+      onPress={handlePress}
+      style={[
+        styles.root,
+        rootSizeStyle,
+        radiusStyle,
+        shadowStyle,
+        visualDisabled ? styles.disabledRoot : null,
+        webCursorStyle,
+        style,
+      ]}
+      testID={testID}
+    >
+      <View
+        pointerEvents="none"
+        style={[
+          styles.content,
+          contentSizeStyle,
+          paddingStyle,
+          radiusStyle,
+          borderStyle,
+          { backgroundColor: visualColors.backgroundColor },
+          contentStyle,
+        ]}
+      >
+        {LinearGradientComponent && gradientCfg ? (
+          <LinearGradientComponent
+            pointerEvents="none"
+            colors={gradientCfg.colors}
+            start={gradientCfg.start}
+            end={gradientCfg.end}
+            style={[StyleSheet.absoluteFillObject, radiusStyle]}
+          />
+        ) : null}
+
+        {iconOnly ? (
+          (icon ?? resolvedText)
+        ) : (
+          <>
+            {icon && iconPlacement === 'start' ? (
+              <View style={[iconBaseBoxStyle, iconPlacedBoxStyle]}>{icon}</View>
+            ) : null}
+            {resolvedText}
+            {icon && iconPlacement === 'end' ? (
+              <View style={[iconBaseBoxStyle, iconPlacedBoxStyle]}>{icon}</View>
+            ) : null}
+          </>
+        )}
+      </View>
+    </Pressable>
+  );
+}
+
+function ButtonAnimatedImpl(
+  {
+    variant = 'solid',
+    tone = 'primary',
+    size = 'md',
+    shape = 'rounded',
+    block = false,
+    disabled = false,
+    loading = false,
+    loadingMode = 'inline',
+    pressEffect = 'auto',
+    icon,
+    iconPlacement = 'start',
+    iconOnly = false,
+    color,
+    colors,
+    border,
+    layout,
+    gradient,
+    shadow = 'none',
+    children,
+    style,
+    contentStyle,
+    textStyle,
+    accessibilityLabel,
+    accessibilityState,
+    hitSlop,
+    onPress,
+    onPressIn,
+    onPressOut,
+    testID,
+    ...pressableProps
+  }: ButtonProps,
+  ref: React.ForwardedRef<ButtonRef>
+) {
+  const resolvedLoadingMode = iconOnly ? 'overlay' : loadingMode;
+  const centeredLoading = resolvedLoadingMode !== 'inline';
+  const frame = useButtonFrame({
+    accessibilityLabel,
+    block,
+    border,
+    children,
+    color,
+    colors,
+    disabled,
+    gradient,
+    icon,
+    iconOnly,
+    iconPlacement,
+    layout,
+    loading,
+    shadow,
+    shape,
+    size,
+    textStyle,
+    tone,
+    variant,
+  });
+  const {
+    accentColor,
+    borderStyle,
+    contentGap,
+    contentSizeStyle,
+    defaultHitSlop,
+    gradientCfg,
+    hasGradientBackground,
+    hasIcon,
+    hasText,
+    iconBaseBoxStyle,
+    iconPlacedBoxStyle,
+    iconSize,
+    interactionDisabled,
+    LinearGradientComponent,
+    metrics,
+    paddingStyle,
+    radiusStyle,
+    resolvedAccessibilityLabel,
+    resolvedText,
+    rootSizeStyle,
+    shadowStyle,
+    visualColors,
+    visualDisabled,
+    webCursorStyle,
+  } = frame;
+
+  const loadingSize = React.useMemo(
+    () =>
+      resolveLoadingSize({
+        iconOnly,
+        layout,
+        metrics,
+        variant,
+      }),
+    [iconOnly, layout, metrics, variant]
+  );
+
   const pressSv = useSharedValue(0);
   const loadingSv = useSharedValue(loading ? 1 : 0);
   const [spinnerMounted, setSpinnerMounted] = React.useState(loading);
@@ -1075,23 +1354,32 @@ function ButtonImpl(
 
     if (loading) {
       setSpinnerMounted(true);
+      loadingSv.value = withTiming(1, LOADING_TIMING);
+      return () => {
+        if (hideSpinnerTimerRef.current) {
+          clearTimeout(hideSpinnerTimerRef.current);
+          hideSpinnerTimerRef.current = null;
+        }
+      };
     }
 
-    loadingSv.value = withTiming(loading ? 1 : 0, LOADING_TIMING);
-
-    if (!loading) {
-      hideSpinnerTimerRef.current = setTimeout(() => {
-        setSpinnerMounted(false);
-      }, LOADING_TIMING.duration);
+    if (!spinnerMounted) {
+      loadingSv.value = 0;
+      return undefined;
     }
 
+    loadingSv.value = withTiming(0, LOADING_TIMING);
+    hideSpinnerTimerRef.current = setTimeout(() => {
+      setSpinnerMounted(false);
+    }, LOADING_TIMING.duration);
+
     return () => {
       if (hideSpinnerTimerRef.current) {
         clearTimeout(hideSpinnerTimerRef.current);
         hideSpinnerTimerRef.current = null;
       }
     };
-  }, [loading, loadingSv]);
+  }, [loading, loadingSv, spinnerMounted]);
 
   const rootAnimatedStyle = useAnimatedStyle(() => {
     const baseOpacity = visualDisabled ? DISABLED_OPACITY : 1;
@@ -1311,6 +1599,20 @@ function ButtonImpl(
   );
 }
 
+const ButtonStaticWithRef = React.forwardRef<ButtonRef, ButtonProps>(ButtonStaticImpl);
+ButtonStaticWithRef.displayName = 'ButtonStatic';
+
+const ButtonAnimatedWithRef = React.forwardRef<ButtonRef, ButtonProps>(ButtonAnimatedImpl);
+ButtonAnimatedWithRef.displayName = 'ButtonAnimated';
+
+function ButtonImpl(props: ButtonProps, ref: React.ForwardedRef<ButtonRef>) {
+  if (shouldUseStaticButtonPath(props)) {
+    return <ButtonStaticWithRef {...props} ref={ref} />;
+  }
+
+  return <ButtonAnimatedWithRef {...props} ref={ref} />;
+}
+
 const ButtonWithRef = React.forwardRef<ButtonRef, ButtonProps>(ButtonImpl);
 ButtonWithRef.displayName = 'Button';
 
@@ -1342,6 +1644,9 @@ const styles = StyleSheet.create({
     textDecorationLine: 'underline',
   },
   root: {},
+  disabledRoot: {
+    opacity: DISABLED_OPACITY,
+  },
   spinnerBox: {
     alignItems: 'center',
     justifyContent: 'center',

package/src/ui/Checkbox/README.md

@@ -10,6 +10,7 @@ Checkbox 是三端一致的复选框组件，适合协议勾选、多选列表
 - 非受控模式先在 UI 线程推进动画，再同步内部状态
 - `CheckboxGroup` 使用 `value/defaultValue/onChange` 管理选中集合
 - 默认触控热区至少补到 `wp(44)`，小尺寸也保持可点性
+- 自定义 `layout.indicatorSize` 但未传 `layout.indicatorIconSize` 时，默认勾号会按最终指示器尺寸等比缩放并取整
 
 ## 基础用法
 
@@ -102,6 +103,8 @@ export function Demo() {
 />
 ```
 
+只覆盖 `indicatorSize` 时，内置勾号尺寸会随最终指示器尺寸按比例取整；显式传入 `indicatorIconSize` 或 `indicatorRadius` 时仍以调用侧配置为准。`shape="circle"` 且未传 `indicatorRadius` 时，默认圆角会对 `indicatorSize / 2` 取整，减少 17、18 等小尺寸下的半像素圆角毛边。
+
 ## 自定义内容
 
 `children` 支持 render-prop。根节点本身就是可点击区域，子节点通常只读取状态做视觉变化，不需要再绑定一次点击。
@@ -149,7 +152,7 @@ Checkbox 透传 React Native `Pressable` 的常用属性和事件；组件自身
 - `shape?: 'rounded' | 'square' | 'circle'`：指示器形状，默认 `'rounded'`。
 - `color?: string`：主色覆盖，支持主题 token、语义色或颜色字符串。
 - `colors?: CheckboxColors`：结构化颜色覆盖。
-- `layout?: CheckboxLayout`：结构化尺寸覆盖。
+- `layout?: CheckboxLayout`：结构化尺寸覆盖；自定义 `indicatorSize` 且未显式传 `indicatorIconSize` 时，勾号默认随最终尺寸缩放。
 - `duration?: number`：状态切换动画时长，默认 `170`。
 
 ### 内容

package/src/ui/Checkbox/index.tsx

@@ -274,6 +274,7 @@ const SIZE_TOKENS = {
 const DISABLED_OPACITY = 0.48;
 const PRESSED_OPACITY = 0.86;
 const PRESSED_SCALE = 0.965;
+const CUSTOM_INDICATOR_ICON_SIZE_RATIO = 0.625;
 const VALUE_TIMING_DURATION = 170;
 const PRESS_IN_DURATION = 90;
 const PRESS_OUT_DURATION = 140;
@@ -438,9 +439,19 @@ function resolveCheckboxMetrics(
   layout: CheckboxLayout | undefined
 ): CheckboxMetrics {
   const token = SIZE_TOKENS[size] ?? SIZE_TOKENS.md;
-  const indicatorSize = resolvePositiveNumber(layout?.indicatorSize, wp(token.indicatorSize));
+  const tokenIndicatorSize = wp(token.indicatorSize);
+  const tokenIndicatorIconSize = wp(token.indicatorIconSize);
+  const hasCustomIndicatorSize = isPositiveNumber(layout?.indicatorSize);
+  const indicatorSize = resolvePositiveNumber(layout?.indicatorSize, tokenIndicatorSize);
+  const fallbackIconSize = hasCustomIndicatorSize
+    ? Math.max(wp(1), Math.round(indicatorSize * CUSTOM_INDICATOR_ICON_SIZE_RATIO))
+    : tokenIndicatorIconSize;
   const fallbackRadius =
-    shape === 'circle' ? indicatorSize / 2 : shape === 'square' ? 0 : wp(token.indicatorRadius);
+    shape === 'circle'
+      ? Math.round(indicatorSize / 2)
+      : shape === 'square'
+        ? 0
+        : wp(token.indicatorRadius);
 
   return {
     indicatorSize,
@@ -449,7 +460,7 @@ function resolveCheckboxMetrics(
       layout?.indicatorBorderWidth,
       wp(token.indicatorBorderWidth)
     ),
-    indicatorIconSize: resolvePositiveNumber(layout?.indicatorIconSize, wp(token.indicatorIconSize)),
+    indicatorIconSize: resolvePositiveNumber(layout?.indicatorIconSize, fallbackIconSize),
     gap: resolveNonNegativeNumber(layout?.gap, wp(token.gap)),
     minTouchTarget: resolvePositiveNumber(layout?.minTouchTarget, wp(44)),
     focusRingWidth: resolvePositiveNumber(layout?.focusRingWidth, wp(2)),
@@ -457,8 +468,12 @@ function resolveCheckboxMetrics(
   };
 }
 
+function isPositiveNumber(value: number | undefined): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+
 function resolvePositiveNumber(value: number | undefined, fallback: number) {
-  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+  return isPositiveNumber(value) ? value : fallback;
 }
 
 function resolveNonNegativeNumber(value: number | undefined, fallback: number) {

package/src/ui/Radio/README.md

@@ -11,6 +11,7 @@ Radio 是三端一致的单选组件，适合互斥选项、设置项模式选
 - 已选项默认再次点击不取消；筛选类场景需要清空时显式开启 `allowDeselect`
 - `size/tone/variant` 提供语义化外观，`colors/layout` 作为集中 escape hatch
 - 默认触控热区至少补到 `wp(44)`，小尺寸也保持可点性
+- 自定义 `layout.indicatorSize` 但未传 `layout.indicatorDotSize` 时，默认内点会按最终指示器尺寸等比缩放并取整
 
 ## RadioGroup
 
@@ -82,6 +83,8 @@ Radio 默认遵循单选控件直觉：点击已选项不会取消。需要筛
 />
 ```
 
+只覆盖 `indicatorSize` 时，内置圆点尺寸会随最终指示器尺寸按比例取整；显式传入 `indicatorDotSize` 时仍以调用侧配置为准。Radio 外圈默认圆角会对 `indicatorSize / 2` 取整，减少 17、18 等小尺寸下的半像素圆角毛边。
+
 ## 自定义内容
 
 `children` 支持 render-prop。根节点本身就是可点击区域，子节点通常只读取状态做视觉变化，不需要再绑定一次点击。
@@ -148,7 +151,7 @@ Radio 透传 React Native `Pressable` 的常用属性和事件；组件自身固
 - `variant?: 'outline' | 'soft' | 'solid'`：选中态视觉样式，默认 `'outline'`。
 - `color?: string`：主色覆盖，支持主题 token、语义色或颜色字符串。
 - `colors?: RadioColors`：结构化颜色覆盖。
-- `layout?: RadioLayout`：结构化尺寸覆盖。
+- `layout?: RadioLayout`：结构化尺寸覆盖；自定义 `indicatorSize` 且未显式传 `indicatorDotSize` 时，圆点默认随最终尺寸缩放。
 - `duration?: number`：状态切换动画时长，默认 `170`。
 
 ### 内容

package/src/ui/Radio/index.tsx

@@ -72,6 +72,7 @@ export type RadioSlotProps = {
 
 type RadioMetrics = {
   indicatorSize: number;
+  indicatorRadius: number;
   indicatorDotSize: number;
   indicatorBorderWidth: number;
   gap: number;
@@ -233,12 +234,16 @@ const SIZE_TOKENS = {
   },
 } as const satisfies Record<
   RadioSize,
-  Omit<RadioMetrics, 'minTouchTarget' | 'focusRingWidth' | 'focusRingOffset'>
+  Omit<
+    RadioMetrics,
+    'indicatorRadius' | 'minTouchTarget' | 'focusRingWidth' | 'focusRingOffset'
+  >
 >;
 
 const DISABLED_OPACITY = 0.48;
 const PRESSED_OPACITY = 0.86;
 const PRESSED_SCALE = 0.965;
+const CUSTOM_INDICATOR_DOT_SIZE_RATIO = 0.45;
 const VALUE_TIMING_DURATION = 170;
 const PRESS_IN_DURATION = 90;
 const PRESS_OUT_DURATION = 140;
@@ -377,14 +382,18 @@ function resolveVariantColors(
 
 function resolveRadioMetrics(size: RadioSize, layout: RadioLayout | undefined): RadioMetrics {
   const token = SIZE_TOKENS[size] ?? SIZE_TOKENS.md;
-  const indicatorSize = resolvePositiveNumber(layout?.indicatorSize, wp(token.indicatorSize));
+  const tokenIndicatorSize = wp(token.indicatorSize);
+  const tokenIndicatorDotSize = wp(token.indicatorDotSize);
+  const hasCustomIndicatorSize = isPositiveNumber(layout?.indicatorSize);
+  const indicatorSize = resolvePositiveNumber(layout?.indicatorSize, tokenIndicatorSize);
+  const fallbackDotSize = hasCustomIndicatorSize
+    ? Math.max(wp(1), Math.round(indicatorSize * CUSTOM_INDICATOR_DOT_SIZE_RATIO))
+    : tokenIndicatorDotSize;
 
   return {
     indicatorSize,
-    indicatorDotSize: resolvePositiveNumber(
-      layout?.indicatorDotSize,
-      wp(token.indicatorDotSize)
-    ),
+    indicatorRadius: Math.round(indicatorSize / 2),
+    indicatorDotSize: resolvePositiveNumber(layout?.indicatorDotSize, fallbackDotSize),
     indicatorBorderWidth: resolvePositiveNumber(
       layout?.indicatorBorderWidth,
       wp(token.indicatorBorderWidth)
@@ -396,8 +405,12 @@ function resolveRadioMetrics(size: RadioSize, layout: RadioLayout | undefined):
   };
 }
 
+function isPositiveNumber(value: number | undefined): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+
 function resolvePositiveNumber(value: number | undefined, fallback: number) {
-  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+  return isPositiveNumber(value) ? value : fallback;
 }
 
 function resolveNonNegativeNumber(value: number | undefined, fallback: number) {
@@ -798,10 +811,10 @@ function RadioImpl(
     () => ({
       width: metrics.indicatorSize,
       height: metrics.indicatorSize,
-      borderRadius: metrics.indicatorSize / 2,
+      borderRadius: metrics.indicatorRadius,
       borderWidth: metrics.indicatorBorderWidth,
     }),
-    [metrics.indicatorBorderWidth, metrics.indicatorSize]
+    [metrics.indicatorBorderWidth, metrics.indicatorRadius, metrics.indicatorSize]
   );
 
   const indicatorNode = showIndicator ? (
@@ -823,7 +836,7 @@ function RadioImpl(
             bottom: -metrics.focusRingOffset,
             left: -metrics.focusRingOffset,
             right: -metrics.focusRingOffset,
-            borderRadius: metrics.indicatorSize / 2 + metrics.focusRingOffset,
+            borderRadius: metrics.indicatorRadius + metrics.focusRingOffset,
             borderWidth: metrics.focusRingWidth,
             borderColor: resolvedColors.focusRing,
           },

package/src/ui/Text/README.md

@@ -10,6 +10,8 @@
 - 默认使用 `getMaxFontSizeMultiplier()` 限制字体缩放上限，单次可用 `maxFontSizeMultiplier` 覆盖。
 - Android 默认关闭 `includeFontPadding`，用明确 lineHeight 保证 iOS / Android / Web 视觉高度更一致。
 - `color` 支持主题 token、语义色 token 和原生可解析颜色；无效颜色会回落到 `tone`。
+- `style.fontSize` 作为最终 escape hatch 覆盖字号时，如果没有显式 `lineHeight`，组件不会继续注入默认行高，会交给原生 Text 按字体度量排版。
+- 嵌套在 zkit `Text` 内部的 `Text`，未显式传入 `variant / size / lineHeight / style.fontSize / style.lineHeight` 时会继承父级排版。
 - 屏幕宽度变化时会重新计算排版尺寸，横竖屏和分屏场景不会卡在初始化尺寸。
 
 ## 基础用法
@@ -22,7 +24,7 @@ export function Demo() {
 }
 ```
 
-默认等价于：
+单独使用时默认等价于：
 
 - `variant="body"`
 - `tone="default"`
@@ -52,7 +54,7 @@ export function Demo() {
 }
 ```
 
-`variant` 只决定默认 `size / weight / fontFamily`，显式传入 `size`、`weight` 或 `style` 时会覆盖对应值。
+`variant` 只决定默认 `size / weight / fontFamily`，显式传入 `size`、`weight` 或 `style` 时会覆盖对应值。嵌套 `Text` 未显式声明排版时不会重新套用默认 `body`，以保持内联链接、强调文案和协议文字的字号稳定。
 
 ## 尺寸
 
@@ -88,6 +90,7 @@ export function Demo() {
 | `4xl` | `wp(36)` | `wp(44)` |
 
 传入数字 `size` 或 `lineHeight` 时，数字代表未缩放的设计像素，组件内部会统一转换。
+通过 `style.fontSize` 直接覆盖字号时，调用侧应传入已经计算好的原生字号；如果没有同时传入 `lineHeight` 或 `style.lineHeight`，组件会移除内置 token 行高，避免字号和行高不匹配。
 
 ## 颜色