@factorialco/f0-react-native 0.28.1 → 0.29.0

package/src/components/primitives/F0Text/AnimatedF0Text/AnimatedF0Text.types.ts

@@ -58,4 +58,19 @@ export interface AnimatedF0TextProps extends Omit<
    * Children content
    */
   children?: React.ReactNode
+
+  /**
+   * Tailwind classes for layout and positioning.
+   *
+   * Allowed: margin, padding, flex, position, width, height, opacity, z-index, etc.
+   * Ignored: font-size, font-weight, line-height, letter-spacing, color, text-align,
+   * text-decoration, text-transform — these are controlled by semantic props and
+   * always take precedence via twMerge.
+   *
+   * @example
+   * className="mt-4 flex-1"
+   * className="mb-2 self-center"
+   * className="absolute top-0 left-0"
+   */
+  className?: string
 }

package/src/components/primitives/F0Text/AnimatedF0Text/__tests__/AnimatedF0Text.spec.tsx

@@ -128,4 +128,224 @@ describe("AnimatedF0Text", () => {
       expect(element.props.testID).toBe("test-animated-text")
     })
   })
+
+  describe("className — layout classes pass through", () => {
+    it("applies margin classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="mx-3 mt-4 mb-2">Margin text</AnimatedF0Text>
+      )
+      const element = getByText("Margin text")
+      expect(element.props.className).toContain("mt-4")
+      expect(element.props.className).toContain("mb-2")
+      expect(element.props.className).toContain("mx-3")
+    })
+
+    it("applies padding classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="p-4 px-2 py-1">Padded text</AnimatedF0Text>
+      )
+      const element = getByText("Padded text")
+      expect(element.props.className).toContain("p-4")
+      expect(element.props.className).toContain("px-2")
+      expect(element.props.className).toContain("py-1")
+    })
+
+    it("applies flex classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="flex-1 flex-shrink-0">
+          Flex text
+        </AnimatedF0Text>
+      )
+      const element = getByText("Flex text")
+      expect(element.props.className).toContain("flex-1")
+      expect(element.props.className).toContain("flex-shrink-0")
+    })
+
+    it("applies position classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="absolute top-0 left-0">
+          Positioned text
+        </AnimatedF0Text>
+      )
+      const element = getByText("Positioned text")
+      expect(element.props.className).toContain("absolute")
+      expect(element.props.className).toContain("top-0")
+      expect(element.props.className).toContain("left-0")
+    })
+
+    it("applies opacity classes", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="opacity-50">Faded text</AnimatedF0Text>
+      )
+      const element = getByText("Faded text")
+      expect(element.props.className).toContain("opacity-50")
+    })
+
+    it("preserves layout classes with all variant combinations", () => {
+      const { getByText } = render(
+        <AnimatedF0Text
+          variant="heading-lg"
+          color="critical"
+          align="center"
+          decoration="underline"
+          transform="uppercase"
+          className="mt-4 flex-1 self-end"
+        >
+          Full combo
+        </AnimatedF0Text>
+      )
+      const element = getByText("Full combo")
+      expect(element.props.className).toContain("mt-4")
+      expect(element.props.className).toContain("flex-1")
+      expect(element.props.className).toContain("self-end")
+      expect(element.props.className).toContain("text-[24px]")
+      expect(element.props.className).toContain("font-semibold")
+      expect(element.props.className).toContain("text-f0-foreground-critical")
+      expect(element.props.className).toContain("text-center")
+      expect(element.props.className).toContain("underline")
+      expect(element.props.className).toContain("uppercase")
+    })
+  })
+
+  describe("className — typography overrides are rejected", () => {
+    it("rejects font-size override", () => {
+      const { getByText } = render(
+        <AnimatedF0Text variant="body-sm-default" className="text-xs">
+          Size override attempt
+        </AnimatedF0Text>
+      )
+      const element = getByText("Size override attempt")
+      expect(element.props.className).toContain("text-[14px]")
+      expect(element.props.className).not.toContain("text-xs")
+    })
+
+    it("rejects font-weight override", () => {
+      const { getByText } = render(
+        <AnimatedF0Text variant="body-sm-default" className="font-bold">
+          Weight override attempt
+        </AnimatedF0Text>
+      )
+      const element = getByText("Weight override attempt")
+      expect(element.props.className).toContain("font-normal")
+      expect(element.props.className).not.toContain("font-bold")
+    })
+
+    it("rejects line-height override", () => {
+      const { getByText } = render(
+        <AnimatedF0Text variant="body-sm-default" className="leading-10">
+          Leading override attempt
+        </AnimatedF0Text>
+      )
+      const element = getByText("Leading override attempt")
+      expect(element.props.className).toContain("leading-[20px]")
+      expect(element.props.className).not.toContain("leading-10")
+    })
+
+    it("rejects text-color override", () => {
+      const { getByText } = render(
+        <AnimatedF0Text color="default" className="text-red-500">
+          Color override attempt
+        </AnimatedF0Text>
+      )
+      const element = getByText("Color override attempt")
+      expect(element.props.className).toContain("text-f0-foreground")
+      expect(element.props.className).not.toContain("text-red-500")
+    })
+
+    it("rejects multiple typography overrides simultaneously", () => {
+      const { getByText } = render(
+        <AnimatedF0Text
+          variant="body-sm-default"
+          color="default"
+          className="text-xl leading-loose font-bold tracking-wider text-blue-500"
+        >
+          Multi override attempt
+        </AnimatedF0Text>
+      )
+      const element = getByText("Multi override attempt")
+      expect(element.props.className).toContain("text-[14px]")
+      expect(element.props.className).toContain("font-normal")
+      expect(element.props.className).toContain("leading-[20px]")
+      expect(element.props.className).toContain("text-f0-foreground")
+      expect(element.props.className).not.toContain("text-xl")
+      expect(element.props.className).not.toContain("font-bold")
+      expect(element.props.className).not.toContain("leading-loose")
+      expect(element.props.className).not.toContain("text-blue-500")
+      expect(element.props.className).not.toContain("tracking-wider")
+    })
+  })
+
+  describe("className — mixed layout + typography attempts", () => {
+    it("keeps layout classes, rejects typography overrides", () => {
+      const { getByText } = render(
+        <AnimatedF0Text
+          variant="heading-md"
+          className="mt-4 flex-1 p-2 text-xl font-bold text-red-500"
+        >
+          Mixed attempt
+        </AnimatedF0Text>
+      )
+      const element = getByText("Mixed attempt")
+      expect(element.props.className).toContain("mt-4")
+      expect(element.props.className).toContain("p-2")
+      expect(element.props.className).toContain("flex-1")
+      expect(element.props.className).toContain("text-[20px]")
+      expect(element.props.className).toContain("font-semibold")
+      expect(element.props.className).toContain("text-f0-foreground")
+      expect(element.props.className).not.toContain("font-bold")
+      expect(element.props.className).not.toContain("text-red-500")
+      expect(element.props.className).not.toContain("text-xl")
+    })
+
+    it("works with both className and style simultaneously", () => {
+      const animatedStyle = { opacity: 0.5 }
+      const { getByText } = render(
+        <AnimatedF0Text
+          variant="heading-sm"
+          className="mb-2 flex-1"
+          style={animatedStyle}
+        >
+          className + style
+        </AnimatedF0Text>
+      )
+      const element = getByText("className + style")
+      expect(element.props.className).toContain("mb-2")
+      expect(element.props.className).toContain("flex-1")
+      expect(element.props.className).toContain("text-[16px]")
+      expect(element.props.className).toContain("font-semibold")
+      expect(element.props.style).toEqual(animatedStyle)
+    })
+  })
+
+  describe("className — edge cases", () => {
+    it("works correctly when className is undefined", () => {
+      const { getByText } = render(
+        <AnimatedF0Text>No className</AnimatedF0Text>
+      )
+      const element = getByText("No className")
+      expect(element.props.className).toContain("text-[14px]")
+      expect(element.props.className).toContain("font-normal")
+      expect(element.props.className).toContain("text-f0-foreground")
+    })
+
+    it("works correctly when className is empty string", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="">Empty className</AnimatedF0Text>
+      )
+      const element = getByText("Empty className")
+      expect(element.props.className).toContain("text-[14px]")
+      expect(element.props.className).toContain("font-normal")
+    })
+
+    it("handles className with extra whitespace", () => {
+      const { getByText } = render(
+        <AnimatedF0Text className="  mt-4   mb-2  ">
+          Whitespace className
+        </AnimatedF0Text>
+      )
+      const element = getByText("Whitespace className")
+      expect(element.props.className).toContain("mt-4")
+      expect(element.props.className).toContain("mb-2")
+    })
+  })
 })

package/src/components/primitives/F0Text/AnimatedF0Text/__tests__/__snapshots__/AnimatedF0Text.spec.tsx.snap

@@ -2,7 +2,7 @@
 
 exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-md-default 1`] = `
 <Text
-  className="text-[16px] leading-[24px] font-normal text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[16px] leading-[24px] font-normal text-f0-foreground text-left"
 >
   body-md-default
    text
@@ -11,7 +11,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-md-medium 1`] = `
 <Text
-  className="text-[16px] leading-[24px] font-medium text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[16px] leading-[24px] font-medium text-f0-foreground text-left"
 >
   body-md-medium
    text
@@ -20,7 +20,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-md-semibold 1`] = `
 <Text
-  className="text-[16px] leading-[24px] font-semibold text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[16px] leading-[24px] font-semibold text-f0-foreground text-left"
 >
   body-md-semibold
    text
@@ -29,7 +29,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-sm-default 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
 >
   body-sm-default
    text
@@ -38,7 +38,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-sm-medium 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-medium text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-medium text-f0-foreground text-left"
 >
   body-sm-medium
    text
@@ -47,7 +47,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-sm-semibold 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-semibold text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-semibold text-f0-foreground text-left"
 >
   body-sm-semibold
    text
@@ -56,7 +56,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-xs-medium 1`] = `
 <Text
-  className="text-[12px] leading-[16px] font-medium text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[12px] leading-[16px] font-medium text-f0-foreground text-left"
 >
   body-xs-medium
    text
@@ -65,7 +65,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-body-
 
 exports[`AnimatedF0Text Snapshots renders all typography variants: variant-heading-lg 1`] = `
 <Text
-  className="text-[24px] leading-[32px] tracking-[-0.2px] font-semibold text-f0-foreground text-left"
+  className="no-underline normal-case text-[24px] leading-[32px] tracking-[-0.2px] font-semibold text-f0-foreground text-left"
 >
   heading-lg
    text
@@ -74,7 +74,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-headi
 
 exports[`AnimatedF0Text Snapshots renders all typography variants: variant-heading-md 1`] = `
 <Text
-  className="text-[20px] leading-[28px] tracking-[-0.2px] font-semibold text-f0-foreground text-left"
+  className="no-underline normal-case text-[20px] leading-[28px] tracking-[-0.2px] font-semibold text-f0-foreground text-left"
 >
   heading-md
    text
@@ -83,7 +83,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-headi
 
 exports[`AnimatedF0Text Snapshots renders all typography variants: variant-heading-sm 1`] = `
 <Text
-  className="text-[16px] leading-[24px] font-semibold text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[16px] leading-[24px] font-semibold text-f0-foreground text-left"
 >
   heading-sm
    text
@@ -92,7 +92,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-headi
 
 exports[`AnimatedF0Text Snapshots renders all typography variants: variant-heading-xl 1`] = `
 <Text
-  className="text-[36px] leading-[40px] tracking-[-0.2px] font-semibold text-f0-foreground text-left"
+  className="no-underline normal-case text-[36px] leading-[40px] tracking-[-0.2px] font-semibold text-f0-foreground text-left"
 >
   heading-xl
    text
@@ -101,7 +101,7 @@ exports[`AnimatedF0Text Snapshots renders all typography variants: variant-headi
 
 exports[`AnimatedF0Text Snapshots renders with color variants: color-accent 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-normal text-f0-foreground-accent text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-normal text-f0-foreground-accent text-left"
 >
   accent
    text
@@ -110,7 +110,7 @@ exports[`AnimatedF0Text Snapshots renders with color variants: color-accent 1`]
 
 exports[`AnimatedF0Text Snapshots renders with color variants: color-critical 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-normal text-f0-foreground-critical text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-normal text-f0-foreground-critical text-left"
 >
   critical
    text
@@ -119,7 +119,7 @@ exports[`AnimatedF0Text Snapshots renders with color variants: color-critical 1`
 
 exports[`AnimatedF0Text Snapshots renders with color variants: color-default 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
 >
   default
    text
@@ -128,7 +128,7 @@ exports[`AnimatedF0Text Snapshots renders with color variants: color-default 1`]
 
 exports[`AnimatedF0Text Snapshots renders with color variants: color-secondary 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-normal text-f0-foreground-secondary text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-normal text-f0-foreground-secondary text-left"
 >
   secondary
    text
@@ -137,7 +137,7 @@ exports[`AnimatedF0Text Snapshots renders with color variants: color-secondary 1
 
 exports[`AnimatedF0Text Snapshots renders with default variant (body-sm-default) 1`] = `
 <Text
-  className="text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
+  className="no-underline normal-case tracking-normal text-[14px] leading-[20px] font-normal text-f0-foreground text-left"
 >
   Default text
 </Text>

package/src/components/primitives/F0Text/F0Text/F0Text.md

@@ -40,18 +40,19 @@ import { F0Text } from "@factorialco/f0-react-native"
 
 ### Props
 
-| Prop            | Type                | Default             | Description                                             |
-| --------------- | ------------------- | ------------------- | ------------------------------------------------------- |
-| `variant`       | `TypographyVariant` | `'body-sm-default'` | Typography variant with weight included                 |
-| `color`         | `TextColor`         | `'default'`         | Text color from F0 semantic color system                |
-| `align`         | `TextAlign`         | `'left'`            | Text alignment (left, center, right, justify)           |
-| `decoration`    | `TextDecoration`    | `'none'`            | Text decoration (none, underline, line-through)         |
-| `transform`     | `TextTransform`     | `'none'`            | Text transform (none, uppercase, lowercase, capitalize) |
-| `numberOfLines` | `number`            | `undefined`         | Max lines before truncation with ellipsis               |
+| Prop            | Type                | Default             | Description                                              |
+| --------------- | ------------------- | ------------------- | -------------------------------------------------------- |
+| `variant`       | `TypographyVariant` | `'body-sm-default'` | Typography variant with weight included                  |
+| `color`         | `TextColor`         | `'default'`         | Text color from F0 semantic color system                 |
+| `align`         | `TextAlign`         | `'left'`            | Text alignment (left, center, right, justify)            |
+| `decoration`    | `TextDecoration`    | `'none'`            | Text decoration (none, underline, line-through)          |
+| `transform`     | `TextTransform`     | `'none'`            | Text transform (none, uppercase, lowercase, capitalize)  |
+| `numberOfLines` | `number`            | `undefined`         | Max lines before truncation with ellipsis                |
+| `className`     | `string`            | `undefined`         | Layout/positioning classes (margin, padding, flex, etc.) |
 
-All React Native `TextProps` are also supported (onPress, testID, etc.).
+All React Native `TextProps` are also supported (onPress, testID, etc.), **except `style`** which is omitted from the type and filtered at runtime.
 
-**Note**: `className` and `style` props are **not available**. Use semantic props for typography. For spacing/layout, wrap F0Text in a View. Both props are filtered at runtime to prevent override via spread.
+Typography is controlled exclusively by semantic props (variant, color, align, etc.) and always takes precedence — any typography classes passed via `className` are automatically overridden by the semantic props via `twMerge`.
 
 ### Typography Variants
 
@@ -180,26 +181,33 @@ All variants use **Inter** font family with the weight included in the variant n
 
 ### Spacing & Layout
 
-F0Text doesn't accept `className` to prevent typography override. Use a View wrapper for spacing:
+F0Text accepts `className` for layout and positioning. Typography classes in `className` are safely overridden by semantic props via `twMerge`:
 
 <!-- prettier-ignore -->
 ```tsx
 <>
-  {/* Spacing with View wrapper */}
-  <View className="mt-4 mb-2">
-    <F0Text variant="body-sm-default">Text with margin</F0Text>
-  </View>
+  {/* Spacing directly on the text */}
+  <F0Text variant="body-sm-default" className="mt-4 mb-2">
+    Text with margin
+  </F0Text>
 
-  {/* Layout with View wrapper */}
-  <View className="flex-1">
-    <F0Text variant="body-sm-default">Flexible text</F0Text>
-  </View>
+  {/* Layout directly on the text */}
+  <F0Text variant="body-sm-default" className="flex-1">
+    Flexible text
+  </F0Text>
 
   {/* Icon + Text pattern */}
   <View className="flex-row items-center gap-2">
     <F0Icon icon={Check} size="sm" />
-    <F0Text variant="body-sm-default">Success message</F0Text>
+    <F0Text variant="body-sm-default" className="flex-1">
+      Success message
+    </F0Text>
   </View>
+
+  {/* Typography override attempts are safely ignored */}
+  <F0Text variant="body-sm-default" className="mt-4 font-bold text-red-500">
+    font-bold and text-red-500 are ignored; mt-4 is applied
+  </F0Text>
 </>
 ```
 
@@ -236,18 +244,16 @@ F0Text doesn't accept `className` to prevent typography override. Use a View wra
 <!-- prettier-ignore -->
 ```tsx
 <View className="rounded-lg bg-f0-background-secondary p-4">
-  <View className="mb-2">
-    <F0Text variant="heading-sm">Card Title</F0Text>
-  </View>
+  <F0Text variant="heading-sm" className="mb-2">
+    Card Title
+  </F0Text>
   <F0Text variant="body-sm-default" color="secondary" numberOfLines={2}>
     This is a description that will be truncated after two lines if it's too
     long to fit in the available space.
   </F0Text>
-  <View className="mt-2">
-    <F0Text variant="body-xs-medium" color="tertiary">
-      Last updated 2 hours ago
-    </F0Text>
-  </View>
+  <F0Text variant="body-xs-medium" color="tertiary" className="mt-2">
+    Last updated 2 hours ago
+  </F0Text>
 </View>
 ```
 
@@ -347,11 +353,16 @@ to these variables.
 
 <!-- prettier-ignore -->
 ```tsx
-// ✅ Good: Use appropriate variant
+// ✅ Good: Use semantic props for typography
 <F0Text variant="body-md-semibold">Bold text</F0Text>
 
-// ❌ Bad: Don't try to override with className (not supported)
-// <F0Text className="font-bold">Text</F0Text>
+// ✅ Good: Use className for layout
+<F0Text variant="body-md-semibold" className="mt-4 flex-1">Bold text</F0Text>
+
+// ❌ Bad: Don't use className for typography (it will be overridden)
+<F0Text variant="body-sm-default" className="font-bold text-red-500">
+  font-bold and text-red-500 are silently ignored
+</F0Text>
 ```
 
 <!-- prettier-ignore -->

package/src/components/primitives/F0Text/F0Text/F0Text.styles.ts

@@ -7,7 +7,7 @@ import { tv, type VariantProps } from "tailwind-variants"
  * via --font-* CSS variables defined in @theme.
  */
 export const textVariants = tv({
-  base: "",
+  base: "no-underline normal-case tracking-normal",
   variants: {
     variant: {
       // Heading variants

package/src/components/primitives/F0Text/F0Text/F0Text.tsx

@@ -1,7 +1,7 @@
 import React from "react"
 import { Text as RNText } from "react-native"
 
-import { omitProps } from "../../../../lib/utils"
+import { cn, omitProps } from "../../../../lib/utils"
 
 import { textVariants } from "./F0Text.styles"
 import { F0_TEXT_BANNED_PROPS, type F0TextProps } from "./F0Text.types"
@@ -9,10 +9,13 @@ import { F0_TEXT_BANNED_PROPS, type F0TextProps } from "./F0Text.types"
 /**
  * F0Text - Primitive Text component with semantic typography variants
  *
+ * Typography is controlled by semantic props and always takes precedence.
+ * `className` is accepted for layout/positioning (margin, padding, flex, etc.).
+ *
  * @example
  * <F0Text variant="heading-lg">Large Heading</F0Text>
  * <F0Text variant="body-sm-default" color="secondary">Secondary text</F0Text>
- * <F0Text variant="body-md-medium" numberOfLines={2}>Truncated text...</F0Text>
+ * <F0Text variant="body-sm-default" className="mt-4 flex-1">Positioned text</F0Text>
  */
 const F0TextComponent = React.forwardRef<RNText, F0TextProps>(
   (
@@ -22,6 +25,7 @@ const F0TextComponent = React.forwardRef<RNText, F0TextProps>(
       align = "left",
       decoration = "none",
       transform = "none",
+      className,
       children,
       numberOfLines,
       ...rest
@@ -30,14 +34,17 @@ const F0TextComponent = React.forwardRef<RNText, F0TextProps>(
   ) => {
     const textClassName = React.useMemo(
       () =>
-        textVariants({
-          variant,
-          color,
-          align,
-          decoration,
-          transform,
-        }),
-      [variant, color, align, decoration, transform]
+        cn(
+          className,
+          textVariants({
+            variant,
+            color,
+            align,
+            decoration,
+            transform,
+          })
+        ),
+      [variant, color, align, decoration, transform, className]
     )
 
     return (

package/src/components/primitives/F0Text/F0Text/F0Text.types.ts

@@ -1,11 +1,11 @@
 import type { TextProps as RNTextProps } from "react-native"
 
 /**
- * Props that must not be passed through to the underlying RN Text
- * (`style` and `className` are handled by F0 instead).
- * Used with omitProps for runtime safety.
+ * Props that must not be passed through to the underlying RN Text.
+ * `style` is blocked to enforce the semantic API; `className` is allowed
+ * for layout/positioning and merged with typography classes via twMerge.
  */
-export const F0_TEXT_BANNED_PROPS = ["style", "className"] as const
+export const F0_TEXT_BANNED_PROPS = ["style"] as const
 
 /**
  * Typography variant types based on semantic design tokens
@@ -73,10 +73,14 @@ export const TEXT_TRANSFORMS = [
 export type TextTransform = (typeof TEXT_TRANSFORMS)[number]
 
 /**
- * Internal props for the F0Text component.
- * @private
+ * Props for the F0Text component.
+ *
+ * `className` is available for layout/positioning (margin, padding, flex, etc.).
+ * Typography is controlled exclusively by semantic props (variant, color, align, etc.)
+ * and always takes precedence — any typography classes in `className` are overridden.
+ * `style` is NOT available (omitted from RNTextProps and filtered at runtime).
  */
-interface F0TextPropsInternal extends Omit<RNTextProps, "style"> {
+export interface F0TextProps extends Omit<RNTextProps, "style"> {
   /**
    * Semantic typography variant
    * @default "body-sm-default"
@@ -118,17 +122,17 @@ interface F0TextPropsInternal extends Omit<RNTextProps, "style"> {
   children?: React.ReactNode
 
   /**
-   * Excluded from public API via Omit<F0TextPropsInternal, "className">.
-   * @private
+   * Tailwind classes for layout and positioning.
+   *
+   * Allowed: margin, padding, flex, position, width, height, opacity, z-index, etc.
+   * Ignored: font-size, font-weight, line-height, letter-spacing, color, text-align,
+   * text-decoration, text-transform — these are controlled by semantic props and
+   * always take precedence via twMerge.
+   *
+   * @example
+   * className="mt-4 flex-1"
+   * className="mb-2 self-center"
+   * className="absolute top-0 left-0"
    */
   className?: string
 }
-
-/**
- * Public props for the F0Text component
- *
- * Note: `className` and `style` props are NOT available.
- * Use semantic props (variant, color, align, etc.) for typography.
- * For spacing/layout, wrap F0Text in a View with className.
- */
-export type F0TextProps = Omit<F0TextPropsInternal, "className">