@djangocfg/ui-core 2.1.583 → 2.1.585

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.583",
+  "version": "2.1.585",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -130,8 +130,8 @@
     "check:contrast": "node scripts/check-preset-contrast.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.583",
-    "@djangocfg/i18n": "^2.1.583",
+    "@djangocfg/api": "^2.1.585",
+    "@djangocfg/i18n": "^2.1.585",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -207,10 +207,10 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.583",
-    "@djangocfg/eslint-config": "^2.1.583",
-    "@djangocfg/i18n": "^2.1.583",
-    "@djangocfg/typescript-config": "^2.1.583",
+    "@djangocfg/api": "^2.1.585",
+    "@djangocfg/eslint-config": "^2.1.585",
+    "@djangocfg/i18n": "^2.1.585",
+    "@djangocfg/typescript-config": "^2.1.585",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",

package/src/components/index.ts

@@ -1,5 +1,11 @@
 "use client";
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Primitives
+// ─────────────────────────────────────────────────────────────────────────────
+export { TouchSafeInput, TouchSafeTextarea, TouchSafeSelect } from './primitives/TouchSafeInput';
+export type { TouchSafeInputProps, TouchSafeTextareaProps, TouchSafeSelectProps } from './primitives/TouchSafeInput';
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Forms
 // ─────────────────────────────────────────────────────────────────────────────

package/src/components/primitives/TouchSafeInput.tsx

@@ -0,0 +1,160 @@
+import { forwardRef, type ComponentPropsWithoutRef, type ElementRef } from 'react';
+import { touchSafeStyle } from '../../utils/touch-safe';
+
+/**
+ * Touch-safe input wrapper that automatically prevents iOS WebKit auto-zoom.
+ *
+ * Drop-in replacement for <input> with automatic iOS protection.
+ * No device detection needed, no hooks, no manual styling.
+ *
+ * **How it works**:
+ * - Uses CSS custom property `--touch-safe-font-size`
+ * - iOS: Automatically gets max(16px, 1em) via @supports
+ * - Android/Desktop: Uses provided fontSize or 1rem default
+ *
+ * **WCAG Compliant**: No viewport restrictions, text zoom works.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { TouchSafeInput } from '@djangocfg/ui-core/components';
+ *
+ * <TouchSafeInput type="email" placeholder="Email" />
+ * // iOS: font-size max(16px, 1em) → no zoom
+ * // Android/Desktop: font-size 1rem → design's default
+ * ```
+ *
+ * @example Custom design font-size
+ * ```tsx
+ * <TouchSafeInput
+ *   type="search"
+ *   designFontSize="0.875rem"  // 14px on Android/Desktop
+ * />
+ * // iOS: max(16px, 1em)
+ * // Android/Desktop: 0.875rem (14px)
+ * ```
+ *
+ * @example With existing styles
+ * ```tsx
+ * <TouchSafeInput
+ *   style={{ padding: '8px', border: '1px solid gray' }}
+ *   designFontSize="14px"
+ * />
+ * // fontSize automatically added, other styles preserved
+ * ```
+ *
+ * @see {@link ../../utils/touch-safe.ts} Utility functions
+ * @see {@link ../../hooks/device/useTouchSafeStyle.ts} Hook alternative
+ */
+export interface TouchSafeInputProps extends ComponentPropsWithoutRef<'input'> {
+  /**
+   * Design's intended font-size for Android/Desktop.
+   * iOS will use max(16px, 1em) regardless.
+   *
+   * @default '1rem'
+   */
+  designFontSize?: string;
+}
+
+export const TouchSafeInput = forwardRef<
+  ElementRef<'input'>,
+  TouchSafeInputProps
+>(({ designFontSize = '1rem', style, ...props }, ref) => {
+  return (
+    <input
+      ref={ref}
+      {...props}
+      style={{
+        ...style,
+        ...touchSafeStyle(designFontSize),
+      }}
+    />
+  );
+});
+
+TouchSafeInput.displayName = 'TouchSafeInput';
+
+/**
+ * Touch-safe textarea wrapper that automatically prevents iOS WebKit auto-zoom.
+ *
+ * Drop-in replacement for <textarea> with automatic iOS protection.
+ *
+ * @example
+ * ```tsx
+ * import { TouchSafeTextarea } from '@djangocfg/ui-core/components';
+ *
+ * <TouchSafeTextarea
+ *   placeholder="Type a message..."
+ *   designFontSize="14px"
+ * />
+ * ```
+ */
+export interface TouchSafeTextareaProps extends ComponentPropsWithoutRef<'textarea'> {
+  /**
+   * Design's intended font-size for Android/Desktop.
+   * iOS will use max(16px, 1em) regardless.
+   *
+   * @default '1rem'
+   */
+  designFontSize?: string;
+}
+
+export const TouchSafeTextarea = forwardRef<
+  ElementRef<'textarea'>,
+  TouchSafeTextareaProps
+>(({ designFontSize = '1rem', style, ...props }, ref) => {
+  return (
+    <textarea
+      ref={ref}
+      {...props}
+      style={{
+        ...style,
+        ...touchSafeStyle(designFontSize),
+      }}
+    />
+  );
+});
+
+TouchSafeTextarea.displayName = 'TouchSafeTextarea';
+
+/**
+ * Touch-safe select wrapper that automatically prevents iOS WebKit auto-zoom.
+ *
+ * Drop-in replacement for <select> with automatic iOS protection.
+ *
+ * @example
+ * ```tsx
+ * import { TouchSafeSelect } from '@djangocfg/ui-core/components';
+ *
+ * <TouchSafeSelect designFontSize="14px">
+ *   <option value="1">Option 1</option>
+ *   <option value="2">Option 2</option>
+ * </TouchSafeSelect>
+ * ```
+ */
+export interface TouchSafeSelectProps extends ComponentPropsWithoutRef<'select'> {
+  /**
+   * Design's intended font-size for Android/Desktop.
+   * iOS will use max(16px, 1em) regardless.
+   *
+   * @default '1rem'
+   */
+  designFontSize?: string;
+}
+
+export const TouchSafeSelect = forwardRef<
+  ElementRef<'select'>,
+  TouchSafeSelectProps
+>(({ designFontSize = '1rem', style, ...props }, ref) => {
+  return (
+    <select
+      ref={ref}
+      {...props}
+      style={{
+        ...style,
+        ...touchSafeStyle(designFontSize),
+      }}
+    />
+  );
+});
+
+TouchSafeSelect.displayName = 'TouchSafeSelect';

package/src/components/specialized/token-icon/index.tsx

@@ -3,6 +3,7 @@
 import * as React from 'react';
 
 import { cn } from '../../../lib/utils';
+import { touchSafeFontSize } from '../../../utils/touch-safe';
 
 export interface TokenIconProps extends React.HTMLAttributes<HTMLDivElement> {
   symbol: string
@@ -149,6 +150,10 @@ export function TokenIcon({
   const fallbackFontSize = Math.max(8, size * 0.4)
   const truncatedSymbol = symbol?.slice(0, 3) || '?'
 
+  // Touch-safe font size for iOS auto-zoom prevention
+  // iOS: max(16px, fallbackFontSize), Android/Desktop: fallbackFontSize
+  const touchSafeFallbackFontSize = touchSafeFontSize(`${fallbackFontSize}px`)
+
   return (
     <div
       className={cn("inline-flex items-center justify-center flex-shrink-0", className)}
@@ -164,7 +169,7 @@ export function TokenIcon({
         // Fallback: show symbol as text
         <span
           className="text-muted-foreground font-medium uppercase"
-          style={{ fontSize: fallbackFontSize }}
+          style={{ fontSize: touchSafeFallbackFontSize }}
         >
           {truncatedSymbol}
         </span>

package/src/hooks/device/index.ts

@@ -5,3 +5,5 @@ export type { BrowserInfo } from './useBrowserDetect';
 export { useDeviceDetect } from './useDeviceDetect';
 export type { DeviceDetectResult } from './useDeviceDetect';
 export { useShortcutModLabel } from './useShortcutModLabel';
+export { useTouchSafeStyle } from './useTouchSafeStyle';
+export type { TouchSafeStyleOptions } from './useTouchSafeStyle';

package/src/hooks/device/useTouchSafeStyle.md

@@ -0,0 +1,341 @@
+# useTouchSafeStyle
+
+**iOS WebKit auto-zoom prevention hook**
+
+Returns touch-safe font-size for input/textarea elements to prevent iOS Safari/Chrome from zooming viewport on focus.
+
+---
+
+## Problem
+
+iOS WebKit (Safari, Chrome, Edge) automatically zooms the viewport when an `<input>` or `<textarea>` with `font-size < 16px` receives focus. This causes:
+
+- **UI "flying away"** — the entire page zooms in, scrolling content out of view
+- **Critical UX failure** — especially in chat/conversation interfaces where context is essential
+- **Disorientation** — users must manually zoom out to regain context
+
+**Root Cause**: iOS design decision to help users read small text, but problematic for modern responsive designs.
+
+---
+
+## Solution
+
+Use `max(16px, 1em)` to maintain relative sizing while preventing zoom:
+
+- **16px**: iOS zoom threshold (anything ≥16px prevents auto-zoom)
+- **1em**: Maintains relative sizing for accessibility (respects user's base font-size preference)
+- **max()**: Takes the larger value, ensuring both goals are met
+
+**Default Behavior**: iOS-only targeting. Android and desktop remain unaffected.
+
+---
+
+## API
+
+```typescript
+function useTouchSafeStyle(options?: TouchSafeStyleOptions): string | undefined
+```
+
+### Options
+
+```typescript
+interface TouchSafeStyleOptions {
+  /** Target iOS specifically (default: true) */
+  ios?: boolean;
+  
+  /** Target all mobile devices (default: false) */
+  mobile?: boolean;
+  
+  /** Minimum font size to prevent zoom (default: '16px') */
+  minSize?: string;
+}
+```
+
+### Returns
+
+- **iOS** (when `ios: true`, default): `"max(16px, 1em)"`
+- **Android** (when `ios: true`): `undefined` (keeps optimal font-size, no zoom issue)
+- **Desktop**: `undefined` (no mobile zoom behavior)
+- **All mobile** (when `mobile: true`): `"max(16px, 1em)"` for iOS + Android
+
+---
+
+## Usage
+
+### Basic (iOS-only, recommended)
+
+```tsx
+import { useTouchSafeStyle } from '@djangocfg/ui-core/hooks/device';
+
+function ChatInput() {
+  const fontSize = useTouchSafeStyle();
+  
+  return (
+    <textarea
+      style={{ fontSize }}
+      placeholder="Type a message..."
+    />
+  );
+}
+```
+
+**Result**:
+- **iOS**: `font-size: max(16px, 1em)` — no zoom ✅
+- **Android**: no inline style — keeps design's 14px ✅
+- **Desktop**: no inline style — normal sizing ✅
+
+### All Mobile Devices
+
+```tsx
+const fontSize = useTouchSafeStyle({ mobile: true, ios: false });
+
+// iOS + Android both get 16px minimum
+// Useful when: consistency across mobile platforms > optimal Android UX
+```
+
+### Custom Minimum Size
+
+```tsx
+const fontSize = useTouchSafeStyle({ minSize: '18px' });
+
+// Ensures font-size ≥18px on iOS
+// Useful for: accessibility requirements, larger touch targets
+```
+
+### Conditional Fallback
+
+```tsx
+function SearchInput() {
+  const touchSafeFontSize = useTouchSafeStyle();
+  
+  return (
+    <input
+      type="search"
+      style={{
+        fontSize: touchSafeFontSize || '14px', // Desktop gets 14px
+      }}
+    />
+  );
+}
+```
+
+### Form with Multiple Inputs
+
+```tsx
+function LoginForm() {
+  const fontSize = useTouchSafeStyle();
+  
+  return (
+    <form>
+      <input type="email" style={{ fontSize }} />
+      <input type="password" style={{ fontSize }} />
+      <button type="submit">Sign In</button>
+    </form>
+  );
+}
+```
+
+---
+
+## CSS Alternative
+
+For inputs that don't need programmatic control, use CSS utilities:
+
+```tsx
+import '@djangocfg/ui-core/styles';
+
+// Option 1: Utility class (opt-in)
+<div className="touch-safe-input">
+  <input type="text" />
+  <textarea />
+</div>
+
+// Option 2: Automatic via @supports (iOS detection at build time)
+// Already applied globally — inputs get max(16px, 1em) on iOS
+// No class needed, works without JS
+```
+
+**When to use CSS vs Hook**:
+- **CSS**: Static inputs, no conditional logic, works without JS
+- **Hook**: Dynamic styling, iOS-only precision, React-controlled components
+
+---
+
+## Why iOS-Only by Default?
+
+**Android doesn't have auto-zoom behavior** — enforcing 16px there is unnecessary:
+
+- ✅ **Better UX**: Android keeps design's optimal font-size (e.g., 14px for compact UI)
+- ✅ **Precise targeting**: Only fixes the platform with the problem
+- ✅ **Design flexibility**: Developers can choose smaller fonts on Android
+
+**When to use `mobile: true`**:
+- Consistent font-size across all mobile platforms is a requirement
+- Simplicity over optimization
+- Accessibility guidelines mandate 16px minimum everywhere
+
+---
+
+## WCAG Compliance
+
+✅ **WCAG 2.1 Level AA Compliant**
+
+- **SC 1.4.4 Resize Text**: Text can be resized up to 200% without loss of content or functionality
+  - ✅ No viewport restrictions (no `user-scalable=no`)
+  - ✅ `max(16px, 1em)` respects user's base font-size settings
+  - ✅ Browser's text zoom still works
+
+- **SC 1.4.10 Reflow**: Content reflows at 400% zoom without horizontal scrolling
+  - ✅ Relative `em` units maintain reflow behavior
+  - ✅ No fixed pixel-only sizing
+
+**Rejected Alternative**: `viewport meta` with `user-scalable=no` ❌
+```html
+<!-- ❌ WCAG violation — prevents text zoom -->
+<meta name="viewport" content="user-scalable=no" />
+```
+
+---
+
+## Examples
+
+### Chat Composer (Critical Context)
+
+```tsx
+function ChatComposer() {
+  const fontSize = useTouchSafeStyle(); // iOS-only
+  
+  return (
+    <textarea
+      style={{ fontSize }}
+      placeholder="Type your message..."
+      aria-label="Message input"
+    />
+  );
+}
+```
+
+**Rationale**: Chat conversations are context-critical. iOS zoom breaks UX entirely. Android keeps optimal 14px.
+
+### Search Box (Optional Enhancement)
+
+```tsx
+function SearchBar() {
+  const fontSize = useTouchSafeStyle();
+  
+  return (
+    <input
+      type="search"
+      style={{ fontSize: fontSize || '15px' }} // Desktop: 15px
+    />
+  );
+}
+```
+
+**Rationale**: Search is less context-critical, but preventing zoom improves UX. Desktop gets design's preferred size.
+
+### Login Form (Security-Critical)
+
+```tsx
+function PasswordField() {
+  const fontSize = useTouchSafeStyle({ mobile: true }); // All mobile
+  
+  return (
+    <input
+      type="password"
+      style={{ fontSize }}
+      autoComplete="current-password"
+    />
+  );
+}
+```
+
+**Rationale**: Password fields benefit from larger text on all mobile devices for security/visibility.
+
+---
+
+## Implementation Details
+
+### How It Works
+
+```typescript
+export function useTouchSafeStyle(options = {}) {
+  const { isIOS, isMobile } = useDeviceDetect();
+  const minSize = options.minSize || '16px';
+  
+  // All mobile (iOS + Android)
+  if (options.mobile && isMobile) {
+    return `max(${minSize}, 1em)`;
+  }
+  
+  // iOS-only (default)
+  if (options.ios !== false && isIOS) {
+    return `max(${minSize}, 1em)`;
+  }
+  
+  // Desktop or non-targeted mobile
+  return undefined;
+}
+```
+
+### Detection Method
+
+Uses `useDeviceDetect()` hook (from `react-device-detect`):
+- **iOS**: Detects iOS Safari, Chrome, Edge, Firefox
+- **Android**: Detects Android browsers
+- **Desktop**: Excludes non-mobile devices
+- **SSR-safe**: Returns default values server-side, updates client-side
+
+### Performance
+
+- **Zero runtime cost on desktop** — returns `undefined`, no style applied
+- **Minimal on mobile** — one device detect call (cached), simple string return
+- **No layout shift** — applied on mount, before first paint
+
+---
+
+## Related
+
+- **CSS Utilities**: `@djangocfg/ui-core/styles/utilities/touch-safe.css`
+- **Research**: `@researches/2026-10-25__ios-webkit-auto-zoom/`
+- **Widget Implementation**: `@djangocfg/widget-chat` (auto-applied)
+- **Device Detection**: `useDeviceDetect()` hook
+
+---
+
+## References
+
+- [Apple: Configuring the Viewport](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/AdjustingtheTextSize/AdjustingtheTextSize.html)
+- [MDN: viewport meta tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag)
+- [WCAG 2.1: Success Criterion 1.4.4](https://www.w3.org/WAI/WCAG21/Understanding/resize-text.html)
+- [WCAG 2.1: Success Criterion 1.4.10](https://www.w3.org/WAI/WCAG21/Understanding/reflow.html)
+
+---
+
+## Migration from Viewport Meta
+
+**Before** (❌ WCAG violation):
+```tsx
+// layout.tsx
+export const viewport = {
+  maximumScale: 1,
+  userScalable: false, // ❌ Prevents text zoom
+};
+```
+
+**After** (✅ WCAG compliant):
+```tsx
+// Remove viewport restrictions entirely
+// Use useTouchSafeStyle() in components instead
+
+function MyInput() {
+  const fontSize = useTouchSafeStyle();
+  return <input style={{ fontSize }} />;
+}
+```
+
+**Benefits**:
+- ✅ WCAG 2.1 AA compliant
+- ✅ Text zoom works
+- ✅ No global viewport restrictions
+- ✅ iOS-only targeting (better Android UX)

package/src/hooks/device/useTouchSafeStyle.ts

@@ -0,0 +1,112 @@
+'use client';
+
+import { useDeviceDetect } from './useDeviceDetect';
+
+export interface TouchSafeStyleOptions {
+  /**
+   * Target iOS specifically (default: true)
+   *
+   * When enabled, returns font-size only for iOS devices.
+   * Android and other platforms return undefined.
+   */
+  ios?: boolean;
+
+  /**
+   * Target all mobile devices (default: false)
+   *
+   * When enabled, returns font-size for all mobile devices,
+   * not just iOS. Overrides `ios` option.
+   */
+  mobile?: boolean;
+
+  /**
+   * Minimum font size to prevent zoom (default: '16px')
+   *
+   * iOS WebKit zooms when font-size < 16px, but you can set
+   * a higher threshold if needed (e.g., '18px').
+   */
+  minSize?: string;
+}
+
+/**
+ * Returns touch-safe font-size style for iOS WebKit auto-zoom prevention.
+ *
+ * **Problem**: iOS Safari/Chrome zooms viewport when font-size < 16px on input focus,
+ * causing UI elements to "fly away" (especially critical in chat/conversation interfaces).
+ *
+ * **Solution**: Use max(16px, 1em) to maintain relative sizing while preventing zoom.
+ *
+ * **WCAG Compliance**: ✅ WCAG 2.1 AA compliant (SC 1.4.4, 1.4.10)
+ * - Text zoom still works (no viewport user-scalable=no)
+ * - No reflow issues
+ * - Maintains 200% text zoom capability
+ *
+ * **Default Behavior**: iOS-only targeting (Android keeps optimal font-size)
+ *
+ * @param options - Configuration options
+ * @returns Font-size CSS value string or undefined if not applicable
+ *
+ * @example
+ * ```tsx
+ * // iOS-only (default) — Android keeps 14px, iOS gets 16px
+ * function ChatInput() {
+ *   const fontSize = useTouchSafeStyle();
+ *   return <textarea style={{ fontSize }} placeholder="Type a message..." />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // All mobile devices
+ * const fontSize = useTouchSafeStyle({ mobile: true, ios: false });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom minimum size
+ * const fontSize = useTouchSafeStyle({ minSize: '18px' });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Conditional application
+ * function SearchInput() {
+ *   const fontSize = useTouchSafeStyle();
+ *
+ *   return (
+ *     <input
+ *       type="search"
+ *       style={{
+ *         fontSize: fontSize || '14px', // Fallback for desktop
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/AdjustingtheTextSize/AdjustingtheTextSize.html}
+ * @see {@link @researches/2026-10-25__ios-webkit-auto-zoom} Research documentation
+ * @see {@link ../../styles/css/utilities/touch-safe.css} CSS utilities
+ */
+export function useTouchSafeStyle(options: TouchSafeStyleOptions = {}): string | undefined {
+  const { isIOS, isMobile } = useDeviceDetect();
+
+  const minSize = options.minSize || '16px';
+
+  // Default: iOS-only targeting
+  const targetIOS = options.ios !== false;
+  const targetMobile = options.mobile === true;
+
+  // Mobile override (all mobile devices)
+  if (targetMobile && isMobile) {
+    return `max(${minSize}, 1em)`;
+  }
+
+  // iOS-specific targeting (default)
+  if (targetIOS && isIOS) {
+    return `max(${minSize}, 1em)`;
+  }
+
+  // Desktop or non-targeted mobile (Android when ios: true)
+  return undefined;
+}

package/src/styles/css/utilities/touch-safe.css

@@ -0,0 +1,166 @@
+/**
+ * Touch-Safe Input Utilities
+ *
+ * Prevents iOS WebKit auto-zoom on input/textarea focus by enforcing 16px minimum font-size.
+ *
+ * **Problem**: iOS Safari/Chrome zooms viewport when font-size < 16px on focus,
+ * causing UI elements to "fly away" (especially critical in chat/conversation interfaces).
+ *
+ * **Solution**: Use max(16px, 1em) to maintain relative sizing while preventing zoom.
+ *
+ * **Universal Application**: CSS custom property `--touch-safe-font-size` is set on :root
+ * for iOS devices. Components can reference this variable to get automatic iOS fix without
+ * explicit hook calls.
+ *
+ * **WCAG Compliance**: ✅ WCAG 2.1 AA compliant (SC 1.4.4, 1.4.10)
+ * - Text zoom still works (no viewport user-scalable=no)
+ * - No reflow issues
+ * - Maintains 200% text zoom capability
+ *
+ * @see {@link ../../hooks/input/useTouchSafeStyle.ts} React hook for programmatic control
+ * @see {@link @researches/2026-10-25__ios-webkit-auto-zoom} Research documentation
+ */
+
+/* ============================================================================
+   CSS Custom Property (Universal iOS Fix)
+   ========================================================================= */
+
+/**
+ * Global CSS variable for touch-safe font sizing.
+ * 
+ * Set on :root for iOS devices only via @supports detection.
+ * Components can reference var(--touch-safe-font-size, fallback) to get
+ * automatic iOS protection without explicit hook usage.
+ *
+ * iOS: 16px minimum (prevents auto-zoom)
+ * Android/Desktop: undefined (use component's design font-size)
+ *
+ * @example Component usage:
+ * .my-input {
+ *   font-size: var(--touch-safe-font-size, 0.875rem);
+ * }
+ * // iOS: max(16px, 1em)
+ * // Android/Desktop: 0.875rem (14px)
+ */
+:root {
+  --touch-safe-font-size: initial; /* Desktop/Android default */
+}
+
+@supports (-webkit-touch-callout: none) {
+  :root {
+    --touch-safe-font-size: max(16px, 1em);
+  }
+}
+
+/* ============================================================================
+   Utility Class (Opt-In)
+   ========================================================================= */
+
+/**
+ * Apply to any container with inputs/textareas that need touch-safe sizing.
+ *
+ * @example
+ * <form className="touch-safe-input">
+ *   <input type="text" />
+ *   <textarea />
+ * </form>
+ */
+.touch-safe-input input,
+.touch-safe-input textarea,
+.touch-safe-input select {
+  font-size: max(16px, 1em);
+}
+
+/* ============================================================================
+   iOS-Specific Auto-Fix (@supports detection)
+   ========================================================================= */
+
+/**
+ * Targets iOS WebKit devices via CSS feature detection.
+ * More reliable than user-agent sniffing, works at build time.
+ *
+ * Note: Also matches desktop Safari on macOS, but 16px is acceptable there
+ * (no zoom behavior). For precise iOS-only targeting, use useTouchSafeStyle hook.
+ */
+@supports (-webkit-touch-callout: none) {
+  input[type="text"],
+  input[type="email"],
+  input[type="search"],
+  input[type="tel"],
+  input[type="url"],
+  input[type="password"],
+  input[type="number"],
+  textarea,
+  select {
+    font-size: max(16px, 1em);
+  }
+
+  /* Prevent iOS text size adjustment during orientation changes */
+  html {
+    -webkit-text-size-adjust: 100%;
+    text-size-adjust: 100%;
+  }
+}
+
+/* ============================================================================
+   Mobile Baseline (Opt-In via class)
+   ========================================================================= */
+
+/**
+ * Apply to containers for mobile-wide touch-safe inputs (iOS + Android).
+ *
+ * Note: Android doesn't have the same zoom behavior, so this is only needed
+ * if you want consistent 16px across all mobile devices. For iOS-only,
+ * prefer @supports above or useTouchSafeStyle({ ios: true }) hook.
+ *
+ * @example
+ * <div className="touch-safe-mobile">
+ *   <input type="text" />
+ * </div>
+ */
+@media (max-width: 768px) {
+  .touch-safe-mobile input,
+  .touch-safe-mobile textarea,
+  .touch-safe-mobile select {
+    font-size: max(16px, 1em);
+  }
+}
+
+/* ============================================================================
+   Touch Target Size (44px minimum for WCAG)
+   ========================================================================= */
+
+/**
+ * Ensures minimum 44×44px touch targets for mobile accessibility.
+ *
+ * WCAG 2.1 Success Criterion 2.5.5 (Level AAA): Target Size
+ * iOS Human Interface Guidelines: 44pt minimum
+ *
+ * @example
+ * <button className="touch-target">Click Me</button>
+ */
+.touch-target {
+  min-height: 44px;
+  min-width: 44px;
+}
+
+@media (max-width: 768px) {
+  /* Enforce on mobile for buttons, links with onClick, form controls */
+  button,
+  [role="button"],
+  a[onClick],
+  input[type="submit"],
+  input[type="button"],
+  input[type="reset"],
+  select {
+    min-height: 44px;
+    min-width: 44px;
+  }
+
+  /* Special case: Icon-only buttons */
+  button[aria-label]:not(:has(*)),
+  [role="button"][aria-label]:not(:has(*)) {
+    min-height: 44px;
+    min-width: 44px;
+  }
+}

package/src/styles/css/utilities.css

@@ -17,3 +17,4 @@
 @import './utilities/animations.css';
 @import './utilities/glass.css';
 @import './utilities/marquee.css';
+@import './utilities/touch-safe.css';

package/src/utils/index.ts

@@ -1 +1,8 @@
 export { emitRuntimeError, RUNTIME_ERROR_EVENT } from './runtime-errors';
+export {
+  touchSafeFontSize,
+  touchSafeStyle,
+  TOUCH_SAFE_INPUT_CLASS,
+  TOUCH_SAFE_MOBILE_CLASS,
+  TOUCH_TARGET_CLASS,
+} from './touch-safe';

package/src/utils/touch-safe.ts

@@ -0,0 +1,116 @@
+/**
+ * Touch-safe font-size utilities for universal iOS auto-zoom prevention.
+ *
+ * Provides CSS and JavaScript helpers that automatically protect against
+ * iOS WebKit viewport zoom on input focus, without requiring explicit
+ * device detection in every component.
+ *
+ * @see {@link ../styles/css/utilities/touch-safe.css} CSS implementation
+ * @see {@link ../hooks/device/useTouchSafeStyle.ts} React hook alternative
+ * @see {@link @researches/2026-10-25__ios-webkit-auto-zoom} Research
+ */
+
+/**
+ * Returns touch-safe font-size value that works universally.
+ *
+ * Uses CSS custom property `--touch-safe-font-size` which is automatically
+ * set to `max(16px, 1em)` on iOS via @supports detection.
+ *
+ * **Automatic behavior**:
+ * - iOS: `max(16px, 1em)` (prevents auto-zoom)
+ * - Android/Desktop: fallback value (design's intended size)
+ *
+ * @param fallback - Fallback font-size for Android/Desktop (default: '1rem')
+ * @returns CSS font-size value string
+ *
+ * @example Inline style
+ * ```tsx
+ * import { touchSafeFontSize } from '@djangocfg/ui-core/utils';
+ *
+ * <input style={{ fontSize: touchSafeFontSize('0.875rem') }} />
+ * // iOS: max(16px, 1em)
+ * // Android/Desktop: 0.875rem (14px)
+ * ```
+ *
+ * @example CSS-in-JS
+ * ```tsx
+ * const inputStyles = {
+ *   fontSize: touchSafeFontSize('14px'),
+ * };
+ * ```
+ *
+ * @example Tailwind arbitrary value
+ * ```tsx
+ * <input className={`text-[${touchSafeFontSize('14px')}]`} />
+ * ```
+ */
+export function touchSafeFontSize(fallback: string = '1rem'): string {
+  return `var(--touch-safe-font-size, ${fallback})`;
+}
+
+/**
+ * Returns touch-safe style object for inline styles.
+ *
+ * Convenience wrapper around touchSafeFontSize() that returns
+ * a complete style object ready for React inline styles.
+ *
+ * @param fallback - Fallback font-size for Android/Desktop
+ * @returns Style object with fontSize property
+ *
+ * @example
+ * ```tsx
+ * import { touchSafeStyle } from '@djangocfg/ui-core/utils';
+ *
+ * <textarea style={touchSafeStyle('14px')} />
+ * // iOS: { fontSize: 'max(16px, 1em)' }
+ * // Android/Desktop: { fontSize: '14px' }
+ * ```
+ *
+ * @example Merge with existing styles
+ * ```tsx
+ * <input
+ *   style={{
+ *     ...myStyles,
+ *     ...touchSafeStyle('0.875rem'),
+ *   }}
+ * />
+ * ```
+ */
+export function touchSafeStyle(fallback: string = '1rem'): { fontSize: string } {
+  return {
+    fontSize: touchSafeFontSize(fallback),
+  };
+}
+
+/**
+ * CSS class name for touch-safe inputs (opt-in).
+ *
+ * Apply to a container to make all child inputs/textareas touch-safe
+ * on mobile devices.
+ *
+ * @example
+ * import { TOUCH_SAFE_INPUT_CLASS } from '@djangocfg/ui-core/utils';
+ * // className={TOUCH_SAFE_INPUT_CLASS}
+ */
+export const TOUCH_SAFE_INPUT_CLASS = 'touch-safe-input';
+
+/**
+ * CSS class name for mobile touch-safe inputs (iOS + Android).
+ *
+ * Apply when you want consistent 16px minimum across all mobile
+ * platforms, not just iOS.
+ *
+ * @example
+ * import { TOUCH_SAFE_MOBILE_CLASS } from '@djangocfg/ui-core/utils';
+ * // className={TOUCH_SAFE_MOBILE_CLASS}
+ */
+export const TOUCH_SAFE_MOBILE_CLASS = 'touch-safe-mobile';
+
+/**
+ * CSS class name for minimum 44px touch targets (WCAG AAA).
+ *
+ * @example
+ * import { TOUCH_TARGET_CLASS } from '@djangocfg/ui-core/utils';
+ * // className={TOUCH_TARGET_CLASS}
+ */
+export const TOUCH_TARGET_CLASS = 'touch-target';