kasy-cli 1.21.8 → 1.22.0

package/templates/firebase/lib/core/theme/radius.dart

@@ -1,21 +1,32 @@
 import 'package:flutter/material.dart';
 
-/// Kasy Design System — Border Radius Tokens
+/// Kasy Design System — Border Radius Tokens (HeroUI / Tailwind scale)
 ///
-/// Single source of truth for all border radius values in the app.
-/// Usage: KasyRadius.md → 8.0
-///        BorderRadius.circular(KasyRadius.md)
+/// Radius is a system-level variable based on Tailwind's base radius values.
+/// The full HeroUI scale is exposed as `rounded*` tokens; the existing semantic
+/// names (xs/sm/md/lg/xl/full) are kept for backward compatibility and already
+/// land on points of this scale:
+///   xs (4) = roundedSm · sm (8) = roundedLg · md (12) = roundedXl
+///   lg (16) = rounded2xl · xl (24) = rounded3xl
 ///
-/// Scale reference:
-/// xs   →  4
-/// sm   →  8
-/// md   → 12
-/// lg   → 16
-/// xl   → 24
-/// full → 999 (pill shape / fully rounded)
+/// Usage: KasyRadius.md → 12.0 · BorderRadius.circular(KasyRadius.md)
 class KasyRadius {
   KasyRadius._();
 
+  // --- HeroUI / Tailwind scale (canonical) ---
+  static const double roundedNone = 0;
+  static const double roundedXs = 2;
+  static const double roundedSm = 4;
+  static const double roundedMd = 6;
+  static const double roundedLg = 8;
+  static const double roundedXl = 12;
+  static const double rounded2xl = 16;
+  static const double rounded2_5xl = 20;
+  static const double rounded3xl = 24;
+  static const double rounded4xl = 32;
+  static const double roundedFull = 9999;
+
+  // --- Semantic names (backward compatible — map onto the scale above) ---
   static const double xs = 4;
   static const double sm = 8;
   static const double md = 12;

package/templates/firebase/lib/core/theme/shadows.dart

@@ -61,4 +61,70 @@ class KasyShadows {
       blurRadius: base.blurRadius - 0.3,
     );
   }
+
+  // -------------------------------------------------------------------------
+  // HeroUI Effect Styles — exact Figma specs (drop-shadow layers).
+  //
+  // The Figma effects also include inner-shadow and background-blur layers.
+  // Flutter has no native inner shadow and blur needs a [BackdropFilter], so
+  // these lists model the drop-shadow stack — the part expressible as
+  // [BoxShadow]. Blur radii and the inner-shadow tint are exposed separately.
+  // -------------------------------------------------------------------------
+
+  /// Surface elevation (cards, panels, modals).
+  static const List<BoxShadow> surface = [
+    BoxShadow(color: Color(0x0F000000), blurRadius: 1),
+    BoxShadow(color: Color(0x0F000000), offset: Offset(0, 1), blurRadius: 2),
+    BoxShadow(color: Color(0x0A000000), offset: Offset(0, 2), blurRadius: 4),
+  ];
+
+  /// Form field resting elevation (same drop stack as [surface]).
+  static const List<BoxShadow> field = surface;
+
+  /// Switch thumb.
+  static const List<BoxShadow> switchControl = [
+    BoxShadow(color: Color(0x05000000), blurRadius: 5),
+    BoxShadow(color: Color(0x0F000000), offset: Offset(0, 2), blurRadius: 10),
+    BoxShadow(color: Color(0x4D000000), blurRadius: 1),
+  ];
+
+  /// Segmented control / tab selected thumb.
+  static const List<BoxShadow> tab = [
+    BoxShadow(color: Color(0x0F000000), offset: Offset(0, 2), blurRadius: 8),
+  ];
+
+  /// Floating overlays (menus, popovers, dropdowns).
+  static const List<BoxShadow> overlay = [
+    BoxShadow(color: Color(0x14000000), offset: Offset(0, 14), blurRadius: 28),
+    BoxShadow(color: Color(0x08000000), offset: Offset(0, -6), blurRadius: 12),
+    BoxShadow(color: Color(0x0F000000), offset: Offset(0, 2), blurRadius: 8),
+  ];
+
+  /// Inner-shadow tint used on insets (apply via custom painter / overlay).
+  static const Color inner = Color(0x4D000000);
+
+  /// Background-blur radius for translucent surfaces (Figma `blur`), logical px.
+  static const double blurRadius = 64;
+
+  /// Background-blur radius for backdrops (Figma `blur-backdrop`), logical px.
+  static const double backdropBlurRadius = 12;
+
+  /// Focus ring thickness (HeroUI `ring-focus-width`).
+  static const double ringFocusWidth = 4;
+
+  /// Gap between the element and its focus ring (HeroUI `ring-offset-width`).
+  static const double ringOffsetWidth = 2;
+
+  /// HeroUI focus ring as box-shadows: an accent ring with a background-colored
+  /// offset gap. Pass `ring` = accent and `gap` = the surrounding background.
+  static List<BoxShadow> focusRing({required Color ring, required Color gap}) =>
+      [
+        BoxShadow(color: ring, spreadRadius: ringFocusWidth),
+        BoxShadow(color: gap, spreadRadius: ringOffsetWidth),
+      ];
+
+  /// Focus ring for form fields: accent ring with no offset gap.
+  static List<BoxShadow> focusRingField({required Color ring}) => [
+        BoxShadow(color: ring, spreadRadius: ringOffsetWidth),
+      ];
 }

package/templates/firebase/lib/core/theme/texts.dart

@@ -1,32 +1,68 @@
 import 'package:flutter/material.dart';
 import 'package:google_fonts/google_fonts.dart';
 
-/// Kasy Design System — Typography Tokens
+/// Kasy Design System — Typography Tokens (HeroUI type scale)
 ///
-/// Single source of truth for all text styles in the app.
-/// To change the font family or any style globally, change it here.
+/// Single source of truth for all text styles in the app. Mirrors the HeroUI
+/// typography, which is based on Tailwind's default scale: Inter, neutral
+/// tracking (letter-spacing 0), predictable sizes and line-heights.
 ///
-/// Usage via context extension:
-///   context.textTheme.bodyMedium
-///   context.textTheme.titleLarge
+/// HeroUI roles (heading1…buttonSm) are exposed as static getters and are the
+/// canonical styles. The Material slots (displayLarge…labelSmall) map onto
+/// those roles so existing `context.textTheme.*` call sites keep working.
 ///
-/// Font family is defined once in [KasyTextTheme._fontFamily].
-/// Change it here → all text in the app updates automatically.
+/// Usage:
+///   context.textTheme.bodyMedium       → Body sm (Material slot)
+///   KasyTextTheme.heading1             → HeroUI Heading 1
 class KasyTextTheme extends ThemeExtension<KasyTextTheme> {
   // -----------------------------------------------------------------------
-  // Font family — change here to update the entire app
+  // Font family — Inter. Change here to update the entire app.
   // -----------------------------------------------------------------------
-  static TextStyle get _base => GoogleFonts.plusJakartaSans();
+  static TextStyle _inter(
+    FontWeight weight,
+    double size,
+    double lineHeight, {
+    TextDecoration? decoration,
+  }) =>
+      GoogleFonts.inter(
+        fontSize: size,
+        fontWeight: weight,
+        height: lineHeight / size,
+        letterSpacing: 0,
+        decoration: decoration,
+      );
 
   // -----------------------------------------------------------------------
-  // Display — for large, prominent text (hero sections, splash screens)
+  // HeroUI roles — canonical styles (color applied per-theme downstream)
+  // -----------------------------------------------------------------------
+  static TextStyle get heading1 => _inter(FontWeight.w800, 36, 40);
+  static TextStyle get heading2 => _inter(FontWeight.w700, 24, 32);
+  static TextStyle get heading3 => _inter(FontWeight.w600, 20, 28);
+  static TextStyle get heading4 => _inter(FontWeight.w600, 16, 24);
+  static TextStyle get bodyBase => _inter(FontWeight.w400, 16, 24);
+  static TextStyle get bodyBaseMedium => _inter(FontWeight.w500, 16, 24);
+  static TextStyle get bodySm => _inter(FontWeight.w400, 14, 20);
+  static TextStyle get bodySmMedium => _inter(FontWeight.w500, 14, 20);
+  static TextStyle get bodyXs => _inter(FontWeight.w400, 12, 16);
+  static TextStyle get bodyXsMedium => _inter(FontWeight.w500, 12, 16);
+  static TextStyle get linkBase =>
+      _inter(FontWeight.w500, 16, 24, decoration: TextDecoration.underline);
+  static TextStyle get linkSm =>
+      _inter(FontWeight.w500, 14, 20, decoration: TextDecoration.underline);
+  static TextStyle get textFieldBase => _inter(FontWeight.w400, 16, 24);
+  static TextStyle get textFieldSm => _inter(FontWeight.w400, 14, 20);
+  static TextStyle get buttonBase => _inter(FontWeight.w500, 16, 24);
+  static TextStyle get buttonSm => _inter(FontWeight.w500, 14, 20);
+
+  // -----------------------------------------------------------------------
+  // Display — large hero text (extends the HeroUI scale upward in Inter)
   // -----------------------------------------------------------------------
   final TextStyle displayLarge;
   final TextStyle displayMedium;
   final TextStyle displaySmall;
 
   // -----------------------------------------------------------------------
-  // Headline — section headings
+  // Headline — section headings (Heading 1–3)
   // -----------------------------------------------------------------------
   final TextStyle headlineLarge;
   final TextStyle headlineMedium;
@@ -76,36 +112,34 @@ class KasyTextTheme extends ThemeExtension<KasyTextTheme> {
   });
 
   factory KasyTextTheme.build() {
-    final base = _base;
-
     return KasyTextTheme(
-      // Display
-      displayLarge: base.copyWith(fontSize: 57, fontWeight: FontWeight.w300, letterSpacing: -0.25),
-      displayMedium: base.copyWith(fontSize: 45, fontWeight: FontWeight.w300),
-      displaySmall: base.copyWith(fontSize: 36, fontWeight: FontWeight.w400),
-
-      // Headline
-      headlineLarge: base.copyWith(fontSize: 32, fontWeight: FontWeight.w600),
-      headlineMedium: base.copyWith(fontSize: 26, fontWeight: FontWeight.w600),
-      headlineSmall: base.copyWith(fontSize: 22, fontWeight: FontWeight.w500),
-
-      // Title
-      titleLarge: base.copyWith(fontSize: 20, fontWeight: FontWeight.w500),
-      titleMedium: base.copyWith(fontSize: 15, fontWeight: FontWeight.w600, letterSpacing: 0.1),
-      titleSmall: base.copyWith(fontSize: 14, fontWeight: FontWeight.w500, letterSpacing: 0.1),
-
-      // Body
-      bodyLarge: base.copyWith(fontSize: 16, fontWeight: FontWeight.w400, letterSpacing: 0.15),
-      bodyMedium: base.copyWith(fontSize: 14, fontWeight: FontWeight.w400, letterSpacing: 0.1),
-      bodySmall: base.copyWith(fontSize: 12, fontWeight: FontWeight.w400, letterSpacing: 0.2),
-
-      // Label
-      labelLarge: base.copyWith(fontSize: 14, fontWeight: FontWeight.w600, letterSpacing: 0.05),
-      labelMedium: base.copyWith(fontSize: 12, fontWeight: FontWeight.w500, letterSpacing: 0.4),
-      labelSmall: base.copyWith(fontSize: 11, fontWeight: FontWeight.w500, letterSpacing: 0.4),
-
-      // Legacy primary
-      primary: base.copyWith(fontSize: 16, fontWeight: FontWeight.w400),
+      // Display — hero text in Inter, neutral tracking.
+      displayLarge: _inter(FontWeight.w800, 57, 64),
+      displayMedium: _inter(FontWeight.w800, 45, 52),
+      displaySmall: heading1, // 36/40
+
+      // Headline → HeroUI Heading 1–3.
+      headlineLarge: heading1,
+      headlineMedium: heading2,
+      headlineSmall: heading3,
+
+      // Title → HeroUI Heading 3 / Heading 4 / Body sm medium.
+      titleLarge: heading3,
+      titleMedium: heading4,
+      titleSmall: bodySmMedium,
+
+      // Body → HeroUI Body base / Body sm / Body xs.
+      bodyLarge: bodyBase,
+      bodyMedium: bodySm,
+      bodySmall: bodyXs,
+
+      // Label → HeroUI Button sm / Body xs medium.
+      labelLarge: buttonSm,
+      labelMedium: bodyXsMedium,
+      labelSmall: bodyXsMedium,
+
+      // Legacy primary.
+      primary: bodyBase,
     );
   }
 

package/templates/firebase/lib/core/theme/universal_theme.dart

@@ -64,15 +64,20 @@ class UniversalThemeFactory extends KasyThemeDataFactory {
           textTheme: defaultTextStyle,
         ),
         appBarTheme: AppBarTheme(
-          backgroundColor: colors.background.computeLuminance() < 0.5
-              ? const Color(0xFF161618)
-              : const Color(0xFFF7F7F7),
-          foregroundColor: colors.onSurface,
+          backgroundColor: colors.surface,
+          foregroundColor: colors.foreground,
           elevation: colors.background.computeLuminance() < 0.5 ? 0 : 1.4,
           shadowColor: colors.background.computeLuminance() < 0.5
               ? Colors.transparent
               : Colors.black.withValues(alpha: 0.05),
         ),
+        // Modal bottom sheets span the full available width on every breakpoint.
+        // Material 3 otherwise caps them at 640 logical px, so on web/desktop the
+        // sheet floats at tablet width with empty gutters on each side. An empty
+        // BoxConstraints() removes that cap; phones are unaffected (already < 640).
+        bottomSheetTheme: const BottomSheetThemeData(
+          constraints: BoxConstraints(),
+        ),
       ),
     );
   }

package/templates/firebase/lib/core/web_device_preview/web_device_preview.dart

@@ -203,10 +203,11 @@ class _WebDevicePreviewState extends State<WebDevicePreview>
   Future<void> _bootstrap() async {
     final prefs = await SharedPreferences.getInstance();
 
-    // Default ON for the first run: most devs hitting `kasy run --web` want to
-    // preview their mobile app inside a device frame. Closing the chrome
-    // persists the choice, so subsequent launches respect what the user left.
-    final savedEnabled = prefs.getBool(webDevicePreviewEnabledPrefKey) ?? true;
+    // Default OFF: the web app renders at its real desktop proportions instead
+    // of inside a simulated device frame (which distorts scale/proportion).
+    // Devs who want to preview the mobile app in a device frame toggle it on
+    // (shortcut), and that choice persists for subsequent launches.
+    final savedEnabled = prefs.getBool(webDevicePreviewEnabledPrefKey) ?? false;
     final savedPlatform = prefs.getInt(_platformPrefKey);
     final savedIosIndex = prefs.getInt(_iosIndexPrefKey);
     final savedAndroidIndex = prefs.getInt(_androidIndexPrefKey);

package/templates/firebase/lib/core/web_viewport_scale.dart

@@ -0,0 +1,52 @@
+import 'package:flutter/foundation.dart' show kIsWeb;
+import 'package:flutter/widgets.dart';
+
+/// Global render scale applied to the app on web.
+///
+/// Flutter web tends to render ~10% larger than equivalent HTML apps at the
+/// browser's 100% zoom, so the whole UI feels oversized on desktop. `0.9` brings
+/// it to the proportion the design targets (i.e. what 90% zoom looked like)
+/// without the user having to touch the browser zoom.
+const double kWebViewportScale = 0.9;
+
+/// Renders [child] uniformly scaled by [scale] on web (no-op elsewhere).
+///
+/// This is a *true* viewport scale, not a visual-only [Transform]: it enlarges
+/// the logical [MediaQuery] size by `1/scale` and fits it back into the real
+/// viewport with a [FittedBox], so layout, scrolling and hit-testing all stay
+/// correct — exactly as if the browser were zoomed out, but baked into the app.
+class WebViewportScale extends StatelessWidget {
+  final Widget child;
+  final double scale;
+
+  const WebViewportScale({
+    super.key,
+    required this.child,
+    this.scale = kWebViewportScale,
+  });
+
+  /// Wraps [child] on web; returns it untouched on every other platform.
+  static Widget wrap(Widget child) =>
+      kIsWeb ? WebViewportScale(child: child) : child;
+
+  @override
+  Widget build(BuildContext context) {
+    if (!kIsWeb || scale == 1.0) return child;
+    final MediaQueryData mq = MediaQuery.of(context);
+    final Size logicalSize = Size(
+      mq.size.width / scale,
+      mq.size.height / scale,
+    );
+    return MediaQuery(
+      data: mq.copyWith(size: logicalSize),
+      child: FittedBox(
+        fit: BoxFit.fill,
+        child: SizedBox(
+          width: logicalSize.width,
+          height: logicalSize.height,
+          child: child,
+        ),
+      ),
+    );
+  }
+}

package/templates/firebase/lib/core/widgets/kasy_brand_badge.dart

@@ -0,0 +1,118 @@
+import 'package:flutter/material.dart';
+import 'package:kasy_kit/core/theme/theme.dart';
+
+/// Premium brand mark: a brand‑gradient rounded squircle holding an icon (or any
+/// child), optionally floating on a soft radial brand glow.
+///
+/// This is the kit's single "hero badge" primitive. Auth screens and permission
+/// prompts all build their top mark from it, so rebranding is a one‑file change:
+/// swap the [icon] (or pass a logo as [child]), or retint via [gradient] /
+/// [foregroundColor]. Colors default to the active theme's brand color, so it
+/// adapts to light/dark automatically.
+class KasyBrandBadge extends StatelessWidget {
+  const KasyBrandBadge({
+    super.key,
+    this.icon,
+    this.child,
+    this.size = 64,
+    this.glyphSize = 30,
+    this.glow = true,
+    this.gradient,
+    this.foregroundColor,
+  }) : assert(
+         icon != null || child != null,
+         'KasyBrandBadge needs an icon or a child',
+       );
+
+  /// Icon drawn inside the badge. Ignored when [child] is provided.
+  final IconData? icon;
+
+  /// Custom content (e.g. an `Image` logo). Overrides [icon] when set.
+  final Widget? child;
+
+  /// Badge edge length.
+  final double size;
+
+  /// Icon size inside the badge.
+  final double glyphSize;
+
+  /// Soft radial brand glow behind the badge.
+  final bool glow;
+
+  /// Overrides the default subtle brand gradient fill.
+  final Gradient? gradient;
+
+  /// Icon color. Defaults to [KasyColors.onPrimary].
+  final Color? foregroundColor;
+
+  @override
+  Widget build(BuildContext context) {
+    final KasyColors colors = context.colors;
+
+    final Widget badge = Container(
+      width: size,
+      height: size,
+      alignment: Alignment.center,
+      decoration: BoxDecoration(
+        gradient:
+            gradient ??
+            LinearGradient(
+              begin: Alignment.topLeft,
+              end: Alignment.bottomRight,
+              colors: [
+                colors.primary,
+                Color.lerp(colors.primary, Colors.black, 0.18)!,
+              ],
+            ),
+        borderRadius: BorderRadius.circular(size * 0.3),
+        boxShadow: [
+          BoxShadow(
+            color: colors.primary.withValues(
+              alpha: context.isDark ? 0.34 : 0.26,
+            ),
+            blurRadius: 22,
+            spreadRadius: -6,
+            offset: const Offset(0, 10),
+          ),
+        ],
+      ),
+      child:
+          child ??
+          Icon(
+            icon,
+            color: foregroundColor ?? colors.onPrimary,
+            size: glyphSize,
+          ),
+    );
+
+    if (!glow) return badge;
+
+    final double glowSize = size * 2.2;
+    return SizedBox(
+      width: glowSize,
+      height: glowSize,
+      child: Stack(
+        alignment: Alignment.center,
+        clipBehavior: Clip.none,
+        children: [
+          IgnorePointer(
+            child: Container(
+              decoration: BoxDecoration(
+                shape: BoxShape.circle,
+                gradient: RadialGradient(
+                  colors: [
+                    colors.primary.withValues(
+                      alpha: context.isDark ? 0.20 : 0.14,
+                    ),
+                    colors.primary.withValues(alpha: 0),
+                  ],
+                ),
+              ),
+            ),
+          ),
+          badge,
+        ],
+      ),
+    );
+  }
+}

package/templates/firebase/lib/core/widgets/kasy_brand_logo.dart

@@ -0,0 +1,40 @@
+import 'package:flutter/material.dart';
+import 'package:kasy_kit/core/theme/theme.dart';
+
+/// The app's brand logo — the SAME artwork shown on the native splash screen,
+/// so the launch → app handoff feels seamless.
+///
+/// It auto‑swaps between the light and dark splash logos based on the active
+/// theme. To rebrand, replace the two PNGs (or point [lightAsset] / [darkAsset]
+/// at your own) — keep them in sync with `flutter_native_splash` in
+/// `pubspec.yaml` so the splash and the in‑app logo always match.
+class KasyBrandLogo extends StatelessWidget {
+  const KasyBrandLogo({
+    super.key,
+    this.height = 48,
+    this.lightAsset = 'assets/images/splash_logo_light.png',
+    this.darkAsset = 'assets/images/splash_logo_dark.png',
+    this.semanticLabel,
+  });
+
+  /// Rendered logo height. Width follows the artwork's aspect ratio.
+  final double height;
+
+  /// Logo used in light mode (matches the splash `image`).
+  final String lightAsset;
+
+  /// Logo used in dark mode (matches the splash `image_dark`).
+  final String darkAsset;
+
+  final String? semanticLabel;
+
+  @override
+  Widget build(BuildContext context) {
+    return Image.asset(
+      context.isDark ? darkAsset : lightAsset,
+      height: height,
+      fit: BoxFit.contain,
+      semanticLabel: semanticLabel,
+    );
+  }
+}

package/templates/firebase/lib/core/widgets/kasy_focus_ring.dart

@@ -0,0 +1,125 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:kasy_kit/core/theme/theme.dart';
+
+/// The kit's single keyboard focus indicator: a thin primary-coloured ring shown
+/// ONLY during keyboard navigation (never on pointer/touch focus), lifted off the
+/// control by a hair-line gap so it reads as a crisp outline, not a glow.
+///
+/// Visibility follows [FocusManager]'s highlight mode via
+/// [FocusableActionDetector.onShowFocusHighlight], so clicking/tapping a control
+/// (or it merely receiving pointer focus) never paints the ring.
+///
+/// Two ways to use it:
+/// - Controls without their own keyboard activation: pass [onActivate]
+///   (Enter/Space) and let this widget own focus.
+/// - Controls that already activate from their own focusable (e.g. an
+///   [InkWell]): set that focusable's `canRequestFocus: false` and wrap it here
+///   with [onActivate] so focus + ring live in one place.
+class KasyFocusRing extends StatefulWidget {
+  final Widget child;
+  final BorderRadius borderRadius;
+
+  /// Invoked on Enter/Space while focused. When null the ring still appears but
+  /// no keyboard activation is wired (use when a child handles its own keys).
+  final VoidCallback? onActivate;
+
+  /// When false the ring never takes focus or paints (disabled controls).
+  final bool enabled;
+
+  const KasyFocusRing({
+    super.key,
+    required this.child,
+    required this.borderRadius,
+    this.onActivate,
+    this.enabled = true,
+  });
+
+  @override
+  State<KasyFocusRing> createState() => _KasyFocusRingState();
+}
+
+class _KasyFocusRingState extends State<KasyFocusRing> {
+  bool _showFocusRing = false;
+
+  static const Map<ShortcutActivator, Intent> _activateShortcuts =
+      <ShortcutActivator, Intent>{
+    SingleActivator(LogicalKeyboardKey.enter): ActivateIntent(),
+    SingleActivator(LogicalKeyboardKey.numpadEnter): ActivateIntent(),
+    SingleActivator(LogicalKeyboardKey.space): ActivateIntent(),
+  };
+
+  @override
+  Widget build(BuildContext context) {
+    if (!widget.enabled) return widget.child;
+
+    final Color ringColor = context.colors.primary;
+    // A hair-line gap in the canvas colour lifts the ring just off the control
+    // so it reads as a crisp outline (same focus language as KasyTextField) and
+    // stays visible even on primary-coloured buttons (e.g. the chat send orb).
+    final Color gapColor = context.colors.background;
+    final VoidCallback? onActivate = widget.onActivate;
+
+    return FocusableActionDetector(
+      shortcuts: onActivate != null
+          ? _activateShortcuts
+          : const <ShortcutActivator, Intent>{},
+      actions: <Type, Action<Intent>>{
+        if (onActivate != null)
+          ActivateIntent: CallbackAction<ActivateIntent>(
+            onInvoke: (_) {
+              onActivate();
+              return null;
+            },
+          ),
+      },
+      onShowFocusHighlight: (show) {
+        if (mounted && show != _showFocusRing) {
+          setState(() => _showFocusRing = show);
+        }
+      },
+      // Two concentric layers instead of one box with two shadows: a [BoxShadow]
+      // inflates its box by [spreadRadius] but keeps the box's corner radius, so
+      // on a circular control the inflated ring squares off at the corners and
+      // reads as a rounded rectangle. Giving each layer its own radius — matched
+      // to its inflated edge — keeps the ring a true contour of any shape.
+      // Outer: thin solid primary ring (~1.5px). Inner: a 1.5px gap so the ring
+      // floats just off the control instead of hugging it.
+      child: AnimatedContainer(
+        duration: const Duration(milliseconds: 120),
+        decoration: _showFocusRing
+            ? BoxDecoration(
+                borderRadius: _inflate(widget.borderRadius, 3),
+                boxShadow: <BoxShadow>[
+                  BoxShadow(color: ringColor, spreadRadius: 3),
+                ],
+              )
+            : const BoxDecoration(),
+        child: AnimatedContainer(
+          duration: const Duration(milliseconds: 120),
+          decoration: _showFocusRing
+              ? BoxDecoration(
+                  borderRadius: _inflate(widget.borderRadius, 1.5),
+                  boxShadow: <BoxShadow>[
+                    BoxShadow(color: gapColor, spreadRadius: 1.5),
+                  ],
+                )
+              : const BoxDecoration(),
+          child: widget.child,
+        ),
+      ),
+    );
+  }
+
+  /// Grows every corner of [radius] by [delta] so a layer inflated by the same
+  /// amount stays a perfect contour (a circle stays a circle, not a squircle).
+  BorderRadius _inflate(BorderRadius radius, double delta) {
+    final Radius bump = Radius.circular(delta);
+    return BorderRadius.only(
+      topLeft: radius.topLeft + bump,
+      topRight: radius.topRight + bump,
+      bottomLeft: radius.bottomLeft + bump,
+      bottomRight: radius.bottomRight + bump,
+    );
+  }
+}