@newtonedev/components 0.1.2 → 0.1.3

package/src/_COMPONENT_TEMPLATE/ComponentName.tsx

@@ -0,0 +1,106 @@
+/**
+ * Component Template — Copy this directory when creating a new component.
+ *
+ * CROSS-PLATFORM RULES (enforced for all @newtonedev/components):
+ *
+ * 1. PRIMITIVES — Import ONLY from 'react-native':
+ *    View, Text, Pressable, ScrollView, TextInput, PanResponder, Animated, StyleSheet
+ *    NEVER use HTML elements (div, span, input, select, button, etc.)
+ *
+ * 2. STYLES — Always use StyleSheet.create() via a dedicated .styles.ts file.
+ *    Never use plain JS objects or React.CSSProperties.
+ *
+ * 3. COLORS — Use useTokens() for all colors. Never hardcode hex values.
+ *    Token palette: background, backgroundElevated, backgroundSunken,
+ *    textPrimary, textSecondary, interactive, interactiveHover, interactiveActive, border
+ *
+ * 4. ACCESSIBILITY — Use accessibilityRole and accessibilityState (not aria-* attributes).
+ *    react-native-web maps these to ARIA on the DOM automatically.
+ *    Reference: Toggle.tsx (accessibilityRole="switch", accessibilityState={{ checked }})
+ *
+ * 5. SHADOWS — Use RN shadow properties:
+ *    shadowColor, shadowOffset, shadowOpacity, shadowRadius, elevation
+ *    NEVER use boxShadow as a CSS string. react-native-web maps RN shadows automatically.
+ *    Reference: Frame.styles.ts, Popover.styles.ts
+ *
+ * 6. WEB-ONLY DOM — Guard with: if (typeof document === 'undefined') return;
+ *    This covers both native (no document) and SSR (no document during render).
+ *    Reference: GoogleFontLoader.tsx, Popover.tsx
+ *
+ * 7. WEB-ONLY EVENTS — Spread via typed-any pattern with comment:
+ *    const webProps = { onKeyDown: handler } as any; // web-only
+ *    <Pressable {...webProps} />
+ *    These are silently ignored on native. Reference: Select.tsx, Popover.tsx
+ *
+ * 8. WEB-ONLY CSS — Properties like userSelect, fontVariationSettings, cursor
+ *    are silently ignored on native. Mark with inline // web-only comment.
+ *    Cast via `as TextStyle` or `as any` to satisfy TypeScript.
+ *
+ * 9. TYPES — All props must be readonly. Define in ComponentName.types.ts.
+ *
+ * 10. MEMOIZATION — Wrap style computation in useMemo keyed on tokens + props.
+ *
+ * 11. JSDOC — Every interface and prop must have JSDoc with @example blocks.
+ *     Complex props (unions, objects) must explain all accepted forms inline.
+ *     Developers must be able to use components via autocomplete alone,
+ *     without consulting external documentation. See ComponentName.types.ts.
+ *
+ * 12. INLINE COMMENTS — Every logical block in .tsx and .styles.ts files must
+ *     have a plain-language comment explaining what it does and why. Write for
+ *     someone who has never seen React or React Native before. No jargon,
+ *     no assumed knowledge. A reader should be able to understand the entire
+ *     file top-to-bottom without external documentation.
+ *     Reference: Frame.tsx, Text.tsx, Frame.styles.ts, Frame.utils.ts
+ *
+ * 13. STANDARD PROPS — Every component must accept testID, nativeID, and ref.
+ *     testID maps to data-testid on web (used by testing libraries).
+ *     nativeID maps to id on web (used for DOM anchors).
+ *     ref is a regular React 19 prop (no forwardRef needed).
+ *     Reference: Frame.tsx, Text.tsx, Icon.tsx, Wrapper.tsx
+ *
+ * 14. ACCESSIBILITY — Interactive components must accept accessibilityLabel
+ *     and accessibilityHint. Use accessibilityState={{ disabled }} on Pressable.
+ *     Decorative elements use importantForAccessibility="no-hide-descendants".
+ *     Layout-only containers use accessibilityRole="none".
+ *     Reference: Frame.tsx (interactive), Icon.tsx (decorative), Wrapper.tsx (layout)
+ */
+
+import React, { useMemo } from 'react';
+import { View } from 'react-native';
+import type { ComponentNameProps } from './ComponentName.types';
+import { getComponentNameStyles } from './ComponentName.styles';
+import { useTokens } from '../tokens/useTokens';
+
+export function ComponentName({
+  style,
+  // Standard props — every component must accept these
+  testID,
+  nativeID,
+  ref,
+}: ComponentNameProps) {
+  // Get the current theme's design tokens (colors, fonts, spacing).
+  // The "1" is the default elevation level for token lookups.
+  const tokens = useTokens(1);
+
+  // Build the component's styles from the theme tokens.
+  // Wrapped in useMemo so it only recalculates when the tokens change,
+  // instead of recalculating on every render (which would be wasteful).
+  const styles = useMemo(
+    () => getComponentNameStyles(tokens),
+    [tokens]
+  );
+
+  // Render the component. User's custom styles are merged last
+  // so they can override the theme defaults.
+  return (
+    <View
+      ref={ref}
+      testID={testID}
+      nativeID={nativeID}
+      style={[styles.container, style]}
+      accessibilityRole="none"
+    >
+      {/* Component content */}
+    </View>
+  );
+}

package/src/_COMPONENT_TEMPLATE/ComponentName.types.ts

@@ -0,0 +1,86 @@
+import type { View, ViewStyle } from 'react-native';
+import type { ElevationLevel } from '../theme/types';
+
+/**
+ * Props for ComponentName — [one-line description of what this component does].
+ *
+ * [Brief explanation of when to use this component and what it provides.]
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <ComponentName>Content</ComponentName>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With common prop combinations
+ * <ComponentName disabled elevation={2}>
+ *   Advanced usage
+ * </ComponentName>
+ * ```
+ */
+export interface ComponentNameProps {
+  /**
+   * [Describe what children this component expects.]
+   *
+   * @example
+   * ```tsx
+   * <ComponentName>Text or elements</ComponentName>
+   * ```
+   */
+  readonly children?: React.ReactNode;
+
+  /** Additional styles applied to the container. */
+  readonly style?: ViewStyle;
+
+  /** Elevation level for token computation. @default 1 */
+  readonly elevation?: ElevationLevel;
+
+  /** Whether the component is disabled. @default false */
+  readonly disabled?: boolean;
+
+  // ── Standard Props (required for all components) ──
+
+  /** Test identifier — maps to `data-testid` on web. Used by testing libraries. */
+  readonly testID?: string;
+
+  /** DOM id — maps to `id` attribute on web. Used for anchors and scroll targets. */
+  readonly nativeID?: string;
+
+  /** Ref to the underlying View element. */
+  readonly ref?: React.Ref<View>;
+}
+
+/*
+ * ═══════════════════════════════════════════════════════════════
+ * JSDOC CONVENTION (enforced for all @newtonedev/components):
+ *
+ * Every .types.ts file MUST follow these rules to support IDE
+ * auto-fill so developers never need external documentation:
+ *
+ * 1. INTERFACE-LEVEL JSDOC — Every exported interface must have:
+ *    - One-line description of what the component does
+ *    - Brief explanation of when/why to use it
+ *    - At least 2 @example blocks showing common usage patterns
+ *
+ * 2. PROP-LEVEL JSDOC — Every prop must have:
+ *    - Description of what it controls
+ *    - @default tag if the prop has a default value
+ *    - @example block for complex props (unions, objects, callbacks)
+ *
+ * 3. COMPLEX TYPES — Union types and object props must explain
+ *    all accepted forms inline:
+ *    - PaddingProp: uniform ('md'), axis ({x, y}), per-side ({top, ...})
+ *    - SizingMode: 'hug', 'fill', or number
+ *    - Callbacks: show the expected signature and return value
+ *
+ * 4. TYPE ALIASES — Exported type aliases (e.g., TextSize, Direction)
+ *    must have a JSDoc comment explaining what they map to.
+ *
+ * 5. EXTERNAL REFERENCES — When a prop references external concepts
+ *    (e.g., icon names, font families), include a @see link.
+ *
+ * Reference: Frame.types.ts, Icon.types.ts, Text.types.ts, Wrapper.types.ts
+ * ═══════════════════════════════════════════════════════════════
+ */

package/src/_COMPONENT_TEMPLATE/index.ts

@@ -0,0 +1,2 @@
+export { ComponentName } from './ComponentName';
+export type { ComponentNameProps } from './ComponentName.types';

package/src/fonts/GoogleFontLoader.tsx

@@ -22,6 +22,8 @@ export function GoogleFontLoader({ fonts }: GoogleFontLoaderProps) {
   const linkRef = useRef<HTMLLinkElement | null>(null);
 
   useEffect(() => {
+    // Web-only: on native, fonts are linked at build time (no DOM to inject <link> tags).
+    // Also guards against SSR where document is undefined.
     if (typeof document === 'undefined') return;
 
     const url = buildGoogleFontsUrl(fonts);

package/src/fonts/IconFontLoader.tsx

@@ -15,6 +15,8 @@ export function IconFontLoader({ icons }: IconFontLoaderProps) {
   const linkRef = useRef<HTMLLinkElement | null>(null);
 
   useEffect(() => {
+    // Web-only: on native, fonts are linked at build time (no DOM to inject <link> tags).
+    // Also guards against SSR where document is undefined.
     if (typeof document === 'undefined') return;
 
     const variantName = icons.variant.charAt(0).toUpperCase() + icons.variant.slice(1);

package/src/index.ts

@@ -27,7 +27,10 @@ export type { ButtonProps, ButtonVariant, ButtonSize, ButtonIconPosition } from
 export { Card } from './Card/Card';
 export type { CardProps } from './Card/Card.types';
 
-export { Frame } from './Frame/Frame';
+export { useFocusVisible } from './primitives/useFocusVisible';
+export type { FocusVisibleResult } from './primitives/useFocusVisible';
+
+export { Frame } from './primitives/Frame/Frame';
 export type {
   FrameProps,
   SpacingToken,
@@ -46,8 +49,8 @@ export type {
   Direction,
   Alignment,
   Justification,
-} from './Frame/Frame.types';
-export type { ResolvedCorners } from './Frame/Frame.utils';
+} from './primitives/Frame/Frame.types';
+export type { ResolvedCorners } from './primitives/Frame/Frame.utils';
 
 export { TextInput } from './TextInput/TextInput';
 export type { TextInputProps } from './TextInput/TextInput.types';
@@ -72,8 +75,22 @@ export type { HueSliderProps } from './HueSlider/HueSlider.types';
 export { ColorScaleSlider } from './ColorScaleSlider/ColorScaleSlider';
 export type { ColorScaleSliderProps } from './ColorScaleSlider/ColorScaleSlider.types';
 
-export { Icon } from './Icon/Icon';
-export type { IconProps } from './Icon/Icon';
+export { Icon } from './primitives/Icon/Icon';
+export type { IconProps } from './primitives/Icon/Icon.types';
+
+export { Wrapper } from './primitives/Wrapper/Wrapper';
+export type { WrapperProps } from './primitives/Wrapper/Wrapper.types';
+
+export { Text } from './primitives/Text/Text';
+export type {
+  TextProps,
+  TextSize,
+  TextWeight,
+  TextColor,
+  TextFont,
+  TextLineHeight,
+  TextAlign,
+} from './primitives/Text/Text.types';
 
 export { AppShell } from './AppShell/AppShell';
 export type { AppShellProps } from './AppShell/AppShell.types';

package/src/{Frame → primitives/Frame}/Frame.styles.ts

@@ -1,8 +1,8 @@
 import type { ViewStyle } from 'react-native';
 import { StyleSheet } from 'react-native';
 import { srgbToHex } from 'newtone';
-import type { ResolvedTokens } from '../tokens/types';
-import type { FrameElevation } from '../theme/types';
+import type { ResolvedTokens } from '../../tokens/types';
+import type { FrameElevation } from '../../theme/types';
 import type {
   PaddingProp,
   GapProp,
@@ -75,6 +75,15 @@ export interface FrameStyles {
 
 // ── Builder ──────────────────────────────────────────────────────
 
+/**
+ * Build all visual styles for a Frame.
+ *
+ * Takes the Frame's props + design tokens and produces:
+ * - container: the main style (background, layout, spacing, border, shadow, etc.)
+ * - pressed: style override applied when the user is pressing/clicking
+ * - gridWebStyle: CSS Grid properties (only works on web, null otherwise)
+ * - insetBoxShadow: inner shadow CSS string for sunken frames (web-only)
+ */
 export function getFrameStyles(input: FrameStyleInput): FrameStyles {
   const {
     tokens,
@@ -100,30 +109,40 @@ export function getFrameStyles(input: FrameStyleInput): FrameStyles {
     disabled = false,
   } = input;
 
+  // We build styles as a plain object first, then validate it through
+  // StyleSheet.create() at the end. Using Record<string, unknown> lets us
+  // set properties conditionally without TypeScript complaining.
   const container: Record<string, unknown> = {};
 
   // ── Background & foreground ──
+  // Set the surface color and default text color from the current theme.
   container.backgroundColor = srgbToHex(tokens.background.srgb);
   container.color = srgbToHex(tokens.textPrimary.srgb);
 
   // ── Layout mode ──
   if (layout === 'flex') {
+    // Standard flex layout: children arranged in a row or column.
     container.display = 'flex';
     container.flexDirection = resolveFlexDirection(direction, reverse);
     if (wrap) container.flexWrap = 'wrap';
   }
-  // Grid: set flex as RN fallback; actual grid applied via gridWebStyle
   if (layout === 'grid') {
+    // Grid layout: uses CSS Grid on web, but React Native doesn't support grid.
+    // So we set flex as a fallback (wrapping row) for native platforms.
+    // The actual CSS Grid styles are applied separately via gridWebStyle below.
     container.display = 'flex';
     container.flexDirection = 'row';
     container.flexWrap = 'wrap';
   }
 
   // ── Alignment ──
+  // Cross-axis: how children are positioned perpendicular to the main direction.
   if (align) container.alignItems = resolveAlignment(align);
+  // Main-axis: how children are distributed along the main direction.
   if (justify) container.justifyContent = resolveJustification(justify);
 
   // ── Padding ──
+  // Convert spacing tokens (like 'md') or pixel values into actual padding.
   if (padding !== undefined) {
     const p = resolvePadding(padding, tokens);
     container.paddingTop = p.top;
@@ -133,6 +152,7 @@ export function getFrameStyles(input: FrameStyleInput): FrameStyles {
   }
 
   // ── Gap ──
+  // Space between children (row gap for vertical stacks, column gap for horizontal).
   if (gap !== undefined) {
     const g = resolveGap(gap, tokens);
     container.rowGap = g.rowGap;
@@ -140,16 +160,19 @@ export function getFrameStyles(input: FrameStyleInput): FrameStyles {
   }
 
   // ── Sizing ──
+  // Apply width/height settings: 'hug' (shrink), 'fill' (expand), or fixed pixels.
   const sizing = resolveSizing(width, height);
   Object.assign(container, sizing);
 
   // ── Constraints ──
+  // Set min/max boundaries for width and height.
   if (minWidth !== undefined) container.minWidth = minWidth;
   if (maxWidth !== undefined) container.maxWidth = maxWidth;
   if (minHeight !== undefined) container.minHeight = minHeight;
   if (maxHeight !== undefined) container.maxHeight = maxHeight;
 
   // ── Radius ──
+  // Round the corners of the Frame (e.g. for cards, buttons, pills).
   if (radius !== undefined) {
     const corners = resolveRadiusCorners(radius, tokens);
     container.borderTopLeftRadius = corners.topLeft;
@@ -157,54 +180,68 @@ export function getFrameStyles(input: FrameStyleInput): FrameStyles {
     container.borderBottomLeftRadius = corners.bottomLeft;
     container.borderBottomRightRadius = corners.bottomRight;
 
-    // Auto-clip when any corner has radius
+    // Clip overflowing content when corners are rounded,
+    // otherwise children would visually leak outside the rounded edges.
     if (hasPositiveRadius(corners)) {
       container.overflow = 'hidden';
     }
   }
 
   // ── Border ──
+  // Add a thin border using the theme's border color.
   if (bordered) {
     container.borderWidth = 1;
     container.borderColor = srgbToHex(tokens.border.srgb);
   }
 
   // ── Outer shadow (elevation 2) ──
+  // Add a subtle drop shadow to make the Frame look raised above the surface.
+  // These are React Native shadow properties — react-native-web converts them
+  // to CSS box-shadow automatically.
   if (frameElevation === 2) {
     container.shadowColor = '#000';
     container.shadowOffset = { width: 0, height: 2 };
     container.shadowOpacity = 0.12;
     container.shadowRadius = 6;
-    // Android elevation prop (react-native-web maps to box-shadow)
-    container.elevation = 4;
+    container.elevation = 4; // Android-specific shadow depth
   }
 
   // ── Disabled ──
+  // Make the Frame look faded when disabled.
   if (disabled) {
     container.opacity = 0.5;
   }
 
-  // ── Pressed state (background shift to sunken) ──
+  // ── Pressed state ──
+  // When the user is pressing an interactive Frame, shift the background
+  // to a darker "sunken" shade to give visual feedback.
   const pressed = StyleSheet.create({
     s: { backgroundColor: srgbToHex(tokens.backgroundSunken.srgb) },
   }).s;
 
-  // ── Grid web style ──
+  // ── Grid web style (web-only) ──
+  // CSS Grid only works in web browsers. On native platforms this stays null,
+  // and the flex fallback (set above) handles the layout instead.
   let gridWebStyle: React.CSSProperties | null = null;
   if (layout === 'grid') {
     gridWebStyle = {
       display: 'grid' as const,
+      // Divide into equal-width columns (e.g. 3 columns → "repeat(3, 1fr)").
       gridTemplateColumns: columns ? `repeat(${columns}, 1fr)` : undefined,
       gridTemplateRows: rows ? `repeat(${rows}, 1fr)` : undefined,
     };
   }
 
-  // ── Inset shadow (elevation -2) ──
+  // ── Inset shadow (elevation -2, web-only) ──
+  // Creates an inner shadow effect to make the Frame look sunken/recessed.
+  // Only used for the deepest sunken level (-2).
   const insetBoxShadow = frameElevation === -2
     ? 'inset 0 2px 4px rgba(0,0,0,0.12)'
     : null;
 
   return {
+    // Validate and optimize the container styles through StyleSheet.create(),
+    // then extract the single style object with `.c`.
     container: StyleSheet.create({ c: container as ViewStyle }).c,
     pressed,
     gridWebStyle,

package/src/{Frame → primitives/Frame}/Frame.tsx

@@ -2,16 +2,20 @@ import React, { useMemo } from 'react';
 import { View, Pressable, Text } from 'react-native';
 import type { ViewStyle, TextStyle } from 'react-native';
 import type { FrameProps } from './Frame.types';
-import type { ElevationLevel, FrameElevation } from '../theme/types';
+import type { ElevationLevel, FrameElevation } from '../../theme/types';
 import { srgbToHex } from 'newtone';
-import { FrameContext, useFrameContext } from '../theme/FrameContext';
-import { useNewtoneTheme } from '../theme/NewtoneProvider';
-import { computeTokens } from '../tokens/computeTokens';
+import { FrameContext, useFrameContext } from '../../theme/FrameContext';
+import { useNewtoneTheme } from '../../theme/NewtoneProvider';
+import { computeTokens } from '../../tokens/computeTokens';
 import { getFrameStyles } from './Frame.styles';
+import { useFocusVisible } from '../useFocusVisible';
 
 /**
- * Wrap raw string/number children in <Text> to prevent
- * react-native-web "Unexpected text node" console errors.
+ * Wrap raw string/number children in <Text> so they display correctly.
+ *
+ * In React Native, raw text like <View>"hello"</View> will crash on native
+ * and show console warnings on web. All text must be inside a <Text> element.
+ * This helper scans children and auto-wraps any bare strings or numbers.
  */
 function wrapTextChildren(
   children: React.ReactNode,
@@ -118,24 +122,39 @@ export function Frame({
   onPress,
   href,
   disabled = false,
+  // Accessibility
+  accessibilityLabel,
+  accessibilityHint,
+  // Testing & platform
+  testID,
+  nativeID,
+  ref,
   // Style override
   style,
 }: FrameProps) {
+  // Read the global theme configuration, current color mode (light/dark),
+  // and the default theme name from the nearest NewtoneProvider.
   const { config, mode, theme: providerTheme } = useNewtoneTheme();
+  // Read the theme/elevation from the nearest parent Frame (if nested).
   const parentFrameCtx = useFrameContext();
 
-  // Resolve theme: prop > parent Frame > NewtoneProvider
+  // Decide which theme to use. Priority: this Frame's prop > parent Frame > NewtoneProvider.
   const resolvedTheme = theme ?? parentFrameCtx?.theme ?? providerTheme;
 
-  // Resolve frame elevation (user-facing, for shadow/style decisions)
+  // The user-facing elevation (-2 to 2) controls visual depth (shadows, background).
   const resolvedFrameElevation: FrameElevation = elevation ?? 0;
 
-  // Map to internal elevation level for token computation
+  // Convert user-facing elevation to internal level (0-2) for token computation.
+  // When no elevation is set, inherit from parent Frame or default to 1.
   const resolvedElevation: ElevationLevel = elevation !== undefined
     ? toElevationLevel(elevation)
     : parentFrameCtx?.elevation ?? 1;
 
-  // Compute tokens directly (not useTokens) to avoid reading our own FrameContext
+  // Generate the design tokens (colors, spacing, fonts) for this Frame.
+  // Frame computes its own tokens instead of using useTokens() because
+  // useTokens() reads from FrameContext — but this Frame IS the provider,
+  // so it needs to compute fresh tokens from the resolved theme/elevation.
+  // Wrapped in useMemo so it only recalculates when the theme/mode/elevation changes.
   const tokens = useMemo(() => {
     const themeMapping = config.themes[resolvedTheme];
     return computeTokens(
@@ -151,6 +170,8 @@ export function Frame({
     );
   }, [config, mode, resolvedTheme, resolvedElevation]);
 
+  // Calculate all visual styles (background, layout, border, shadow, etc.).
+  // Only recalculates when one of the style-related props changes.
   const styles = useMemo(
     () => getFrameStyles({
       tokens,
@@ -184,13 +205,16 @@ export function Frame({
     ],
   );
 
-  // Memoize context value
+  // This is the value that child components will inherit via FrameContext.
+  // Any nested Frame, Text, Icon, etc. will read this theme and elevation.
   const contextValue = useMemo(
     () => ({ theme: resolvedTheme, elevation: resolvedElevation }),
     [resolvedTheme, resolvedElevation],
   );
 
-  // Build the style array with web-specific overrides
+  // Some styles only work on web browsers (CSS grid, inset shadows).
+  // We collect them separately and cast them to ViewStyle so React Native
+  // doesn't complain about unknown properties (they're silently ignored on native).
   const webOverrides: ViewStyle[] = [];
   if (styles.gridWebStyle) {
     webOverrides.push(styles.gridWebStyle as unknown as ViewStyle);
@@ -199,11 +223,34 @@ export function Frame({
     webOverrides.push({ boxShadow: styles.insetBoxShadow } as unknown as ViewStyle);
   }
 
+  // Normalize user's custom styles into an array for merging.
   const userStyles = Array.isArray(style) ? style : style ? [style] : [];
 
+  // If the Frame has onPress or href, it needs to respond to taps/clicks.
+  // In that case we render a Pressable (tappable); otherwise a plain View.
   const isInteractive = onPress !== undefined || href !== undefined;
 
-  // Wrap raw string/number children in <Text> for RN compatibility
+  // Detect keyboard-only focus (Tab, arrows) vs mouse/touch focus.
+  // Only shows a visible focus ring when the user navigated via keyboard,
+  // matching the browser's native :focus-visible behavior.
+  const { isFocusVisible, focusProps } = useFocusVisible();
+
+  // Focus ring style: 2px solid outline in the theme's interactive color,
+  // offset by 2px so it doesn't overlap the Frame's border.
+  // Uses CSS outline properties — silently ignored on native platforms.
+  const focusRingStyle = isFocusVisible && !disabled ? {
+    outlineWidth: 2,
+    outlineStyle: 'solid',
+    outlineColor: srgbToHex(tokens.interactive.srgb),
+    outlineOffset: 2,
+  } as unknown as ViewStyle : undefined; // web-only
+
+  // Spread focus event handlers onto the Pressable. These are web-only
+  // handlers supported by react-native-web — silently ignored on native.
+  const webFocusProps = isInteractive ? focusProps as any : {}; // web-only
+
+  // Default text style for any raw strings/numbers passed as children.
+  // Uses the theme's primary text color, default font, and base size.
   const textStyle = useMemo<TextStyle>(
     () => ({
       color: srgbToHex(tokens.textPrimary.srgb),
@@ -213,19 +260,38 @@ export function Frame({
     }),
     [tokens],
   );
-  const wrappedChildren = wrapTextChildren(children, textStyle);
+  // Auto-wrap bare text ("hello") in <Text> elements (required by React Native).
+  // Wrapped in useMemo so it only re-scans children when they or the text style changes.
+  const wrappedChildren = useMemo(
+    () => wrapTextChildren(children, textStyle),
+    [children, textStyle],
+  );
 
+  // FrameContext.Provider shares this Frame's theme and elevation with all
+  // descendants, so nested components automatically pick up the right colors.
   return (
     <FrameContext.Provider value={contextValue}>
       {isInteractive ? (
+        // Pressable handles taps. When href is set, react-native-web renders
+        // it as an <a> tag so it works like a regular link on the web.
         <Pressable
+          ref={ref}
+          testID={testID}
+          nativeID={nativeID}
+          accessibilityLabel={accessibilityLabel}
+          accessibilityHint={accessibilityHint}
+          // Tell screen readers this is disabled so assistive technology can announce it.
+          accessibilityState={disabled ? { disabled: true } : undefined}
           onPress={onPress}
           disabled={disabled}
-          // react-native-web renders Pressable with href as <a>
           {...(href ? { href, accessibilityRole: 'link' as const } : { accessibilityRole: 'button' as const })}
+          {...webFocusProps}
+          // The style callback receives { pressed: true/false } so we can
+          // change the background when the user is actively pressing.
           style={({ pressed }) => [
             styles.container,
             pressed && !disabled && styles.pressed,
+            focusRingStyle,
             ...webOverrides,
             ...userStyles,
           ]}
@@ -233,7 +299,15 @@ export function Frame({
           {wrappedChildren}
         </Pressable>
       ) : (
-        <View style={[styles.container, ...webOverrides, ...userStyles]}>
+        // Non-interactive Frame: just a plain View with no tap handling.
+        <View
+          ref={ref}
+          testID={testID}
+          nativeID={nativeID}
+          accessibilityLabel={accessibilityLabel}
+          accessibilityHint={accessibilityHint}
+          style={[styles.container, ...webOverrides, ...userStyles]}
+        >
           {wrappedChildren}
         </View>
       )}