kasy-cli 1.25.0 → 1.26.0

package/lib/commands/new.js

@@ -195,6 +195,56 @@ async function confirmIdentities(backend, gcloudAccount, tr, cancel) {
   }
 }
 
+/**
+ * Try to get gcloud ready (installed + logged in) without making the user leave
+ * the flow. Mirrors the machine-prep we do for Node/Flutter/Firebase: offer to
+ * auto-install gcloud (winget on Windows, brew on macOS), make it visible to
+ * this process, then run the interactive Google login (their own account — that
+ * part can't be automated). On any failure it returns the latest check so the
+ * caller keeps its existing fallback (cancel in Quick mode, or ask for a project
+ * id elsewhere). Never throws.
+ */
+async function ensureGcloudReady(tr) {
+  const { spawnSync } = require('node:child_process');
+  const { augmentedEnv } = require('../utils/env-tools');
+
+  let check = await checkGcloudAuth();
+  if (check.ok) return check;
+
+  // 1) Not installed → offer to install it for them.
+  if (check.missing === 'gcloud') {
+    const guide = getGcloudInstallInstructions();
+    if (guide.install) {
+      const doInstall = await ui.confirm({
+        message: tr('new.firebase.create.gcloudInstallConfirm'),
+        initialValue: true,
+      });
+      if (doInstall) {
+        const spinner = ui.timedSpinner();
+        spinner.start(tr('new.firebase.create.gcloudInstalling'));
+        spawnSync(guide.install, { stdio: 'pipe', shell: true });
+        spinner.stop(tr('new.firebase.create.gcloudInstalling'));
+        // checkGcloudAuth / the later billing+project calls run with the plain
+        // process PATH, which doesn't see a tool winget just dropped on the
+        // machine PATH. Inject the known gcloud dir so the rest of the flow works.
+        const env = augmentedEnv();
+        if (env.PATH) process.env.PATH = env.PATH;
+        if (process.platform === 'win32' && env.Path) process.env.Path = env.Path;
+        check = await checkGcloudAuth();
+      }
+    }
+  }
+
+  // 2) Installed but not logged in → run the interactive login (their account).
+  if (!check.ok && check.missing === 'auth') {
+    ui.log.info(tr('new.firebase.create.gcloudAuthOpening'));
+    spawnSync('gcloud auth login', { stdio: 'inherit', shell: true });
+    check = await checkGcloudAuth();
+  }
+
+  return check;
+}
+
 function printPrerequisites(tr, backend, firebaseSetupMode = 'existing', checkResults = []) {
   const gcloudOk = checkResults.every(
     (r) => !r.name?.includes('gcloud') || r.ok
@@ -644,7 +694,7 @@ async function runNew(directory, { language: langHint = null, backend: backendHi
   // ── gcloud is required for Quick mode (creates GCP project + enables Auth via API) ─
   // Failing here, before the project is generated, is much friendlier than dying mid-flow.
   if (isQuick) {
-    const gcloudCheck = await checkGcloudAuth();
+    const gcloudCheck = await ensureGcloudReady(tr);
     if (!gcloudCheck.ok) {
       ui.log.error(tr('new.firebase.create.gcloudRequired'));
       if (gcloudCheck.missing === 'gcloud') {
@@ -815,7 +865,7 @@ async function runNew(directory, { language: langHint = null, backend: backendHi
         onCancel: cancel,
       });
     }
-    const gcloudCheck = await checkGcloudAuth();
+    const gcloudCheck = await ensureGcloudReady(tr);
     if (!gcloudCheck.ok) {
       ui.log.error(tr('new.firebase.create.gcloudRequired'));
       if (gcloudCheck.missing === 'gcloud') {
@@ -1019,7 +1069,7 @@ async function runNew(directory, { language: langHint = null, backend: backendHi
 
   // ── Firebase: create from scratch for Supabase/API (push notifications only) ─
   if ((backend === 'supabase' || backend === 'api') && firebaseSetupMode === 'create') {
-    const gcloudCheck = await checkGcloudAuth();
+    const gcloudCheck = await ensureGcloudReady(tr);
     if (!gcloudCheck.ok) {
       ui.log.error(tr('new.firebase.create.gcloudRequired'));
       if (gcloudCheck.missing === 'gcloud') {

package/lib/utils/i18n/messages-en.js

@@ -238,6 +238,9 @@ module.exports = {
     'new.firebase.create.installAfter': 'Then log in',
     'new.firebase.create.installUrl': 'Or download from',
     'new.firebase.create.authCommand': 'Run: gcloud auth login',
+    'new.firebase.create.gcloudInstallConfirm': 'Install the Google Cloud CLI (gcloud) automatically now?',
+    'new.firebase.create.gcloudInstalling': 'Installing the Google Cloud CLI…',
+    'new.firebase.create.gcloudAuthOpening': 'Opening the Google sign-in in your browser — log in with your account…',
     'new.firebase.create.fallbackHint': 'For now, enter an existing Firebase Project ID to continue (or install gcloud and run again):',
     'new.firebase.q.billingAccount': 'Which billing account to link to the project?',
     'new.firebase.q.billingAccount.hint': 'Choose the account with available quota (up to 3 projects per account)',

package/lib/utils/i18n/messages-es.js

@@ -238,6 +238,9 @@ module.exports = {
     'new.firebase.create.installAfter': 'Luego inicia sesión',
     'new.firebase.create.installUrl': 'O descarga en',
     'new.firebase.create.authCommand': 'Ejecuta: gcloud auth login',
+    'new.firebase.create.gcloudInstallConfirm': '¿Instalar el Google Cloud CLI (gcloud) automáticamente ahora?',
+    'new.firebase.create.gcloudInstalling': 'Instalando el Google Cloud CLI…',
+    'new.firebase.create.gcloudAuthOpening': 'Abriendo el inicio de sesión de Google en el navegador — entra con tu cuenta…',
     'new.firebase.create.fallbackHint': 'Por ahora, ingresa un Firebase Project ID existente para continuar (o instala gcloud y ejecuta de nuevo):',
     'new.firebase.q.billingAccount': '¿Qué cuenta de facturación vincular al proyecto?',
     'new.firebase.q.billingAccount.hint': 'Elige la cuenta con cuota disponible (hasta 3 proyectos por cuenta)',

package/lib/utils/i18n/messages-pt.js

@@ -238,6 +238,9 @@ module.exports = {
     'new.firebase.create.installAfter': 'Depois faca login',
     'new.firebase.create.installUrl': 'Ou baixe em',
     'new.firebase.create.authCommand': 'Execute: gcloud auth login',
+    'new.firebase.create.gcloudInstallConfirm': 'Instalar o Google Cloud CLI (gcloud) automaticamente agora?',
+    'new.firebase.create.gcloudInstalling': 'Instalando o Google Cloud CLI…',
+    'new.firebase.create.gcloudAuthOpening': 'Abrindo o login do Google no navegador — entre com a sua conta…',
     'new.firebase.create.fallbackHint': 'Por enquanto, informe um Firebase Project ID existente para continuar (ou instale o gcloud e execute novamente):',
     'new.firebase.q.billingAccount': 'Qual conta de faturamento vincular ao projeto?',
     'new.firebase.q.billingAccount.hint': 'Escolha a conta com cota disponível (até 3 projetos por conta)',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kasy-cli",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "CLI for scaffolding production-ready Flutter SaaS apps with Firebase, Supabase, or API REST backends.",
   "bin": {
     "kasy": "./bin/kasy.js"

package/templates/firebase/lib/components/kasy_app_bar.dart

@@ -29,6 +29,7 @@ import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart' show SystemUiOverlayStyle;
 import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/core/widgets/kasy_focus_ring.dart';
 import 'package:kasy_kit/core/widgets/responsive_layout.dart';
 
 /// Inner toolbar band height (orbit hit targets, title baseline).
@@ -468,12 +469,17 @@ class KasyAppBarChromeTap extends StatelessWidget {
       button: true,
       enabled: true,
       label: label,
-      child: GestureDetector(
-        behavior: HitTestBehavior.opaque,
-        onTap: onPressed,
-        child: ConstrainedBox(
-          constraints: const BoxConstraints(minWidth: 44, minHeight: 44),
-          child: Center(child: child),
+      child: KasyFocusRing(
+        onActivate: onPressed,
+        // Circular icon button, so a large radius keeps the focus ring round.
+        borderRadius: BorderRadius.circular(999),
+        child: GestureDetector(
+          behavior: HitTestBehavior.opaque,
+          onTap: onPressed,
+          child: ConstrainedBox(
+            constraints: const BoxConstraints(minWidth: 44, minHeight: 44),
+            child: Center(child: child),
+          ),
         ),
       ),
     );

package/templates/firebase/lib/components/kasy_avatar.dart

@@ -4,6 +4,7 @@ import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:flutter/material.dart';
 import 'package:kasy_kit/components/kasy_avatar_presets.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/core/widgets/kasy_focus_ring.dart';
 
 /// Logical sizes for [KasyAvatar] (diameter in logical pixels).
 enum KasyAvatarSize {
@@ -609,16 +610,22 @@ class _KasyAvatarPressableState extends State<_KasyAvatarPressable>
     final Widget inner = Semantics(
       button: true,
       label: widget.semanticLabel,
-      child: GestureDetector(
-        behavior: HitTestBehavior.opaque,
-        onTap: _tap,
-        child: ConstrainedBox(
-          constraints: BoxConstraints(
-            minWidth: widget.minSide,
-            minHeight: widget.minSide,
-          ),
-          child: Center(
-            child: Transform.scale(scale: _s, child: widget.child),
+      child: KasyFocusRing(
+        onActivate: _tap,
+        // The avatar is circular, so a large radius keeps the focus ring
+        // hugging the circle (radius >= half the diameter).
+        borderRadius: BorderRadius.circular(widget.minSide),
+        child: GestureDetector(
+          behavior: HitTestBehavior.opaque,
+          onTap: _tap,
+          child: ConstrainedBox(
+            constraints: BoxConstraints(
+              minWidth: widget.minSide,
+              minHeight: widget.minSide,
+            ),
+            child: Center(
+              child: Transform.scale(scale: _s, child: widget.child),
+            ),
           ),
         ),
       ),

package/templates/firebase/lib/components/kasy_checkbox.dart

@@ -1,5 +1,6 @@
 import 'package:flutter/material.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/core/widgets/kasy_focus_ring.dart';
 
 /// Shape of the checkbox box.
 enum KasyCheckboxShape {
@@ -169,21 +170,29 @@ class _KasyCheckboxState extends State<KasyCheckbox>
     final bool hasLabel =
         widget.label != null || widget.description != null;
 
-    return GestureDetector(
-      onTap: widget._isDisabled ? null : () => widget.onChanged!(!widget.value),
-      behavior: HitTestBehavior.opaque,
-      child: hasLabel
-          ? Row(
-              children: [
-                box,
-                const SizedBox(width: KasySpacing.smd),
-                Expanded(child: _LabelColumn(widget: widget)),
-              ],
-            )
-          : Padding(
-              padding: const EdgeInsets.all(11),
-              child: box,
-            ),
+    final VoidCallback? onTap =
+        widget._isDisabled ? null : () => widget.onChanged!(!widget.value);
+
+    return KasyFocusRing(
+      enabled: onTap != null,
+      onActivate: onTap,
+      borderRadius: BorderRadius.circular(KasyRadius.sm),
+      child: GestureDetector(
+        onTap: onTap,
+        behavior: HitTestBehavior.opaque,
+        child: hasLabel
+            ? Row(
+                children: [
+                  box,
+                  const SizedBox(width: KasySpacing.smd),
+                  Expanded(child: _LabelColumn(widget: widget)),
+                ],
+              )
+            : Padding(
+                padding: const EdgeInsets.all(11),
+                child: box,
+              ),
+      ),
     );
   }
 }

package/templates/firebase/lib/components/kasy_date_picker.dart

@@ -3,6 +3,7 @@ import 'package:kasy_kit/components/kasy_bottom_sheet.dart';
 import 'package:kasy_kit/components/kasy_dialog.dart';
 import 'package:kasy_kit/components/kasy_text_field.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/core/widgets/kasy_focus_ring.dart';
 import 'package:kasy_kit/core/widgets/kasy_hover.dart';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1038,26 +1039,32 @@ class _KasyDatePickerState extends State<KasyDatePicker>
             cursor: widget.enabled
                 ? SystemMouseCursors.click
                 : SystemMouseCursors.basic,
-            child: GestureDetector(
-              behavior: HitTestBehavior.opaque,
-              onTap: _toggleCalendar,
-              child: IgnorePointer(
-                child: KasyTextField(
-                  key: _fieldKey,
-                  controller: _displayController,
-                  focusNode: _fieldFocusNode,
-                  readOnly: true,
-                  enabled: widget.enabled,
-                  hint: _resolvedPlaceholder,
-                  isInvalid: hasInvalidState,
-                  variant: widget.variant,
-                  focusBorder: widget.focusBorder,
-                  // No caret, no selection handles, no "blue text" when the
-                  // trigger is focused while the calendar is open — keeps the
-                  // field reading as a button, not an editable input.
-                  enableInteractiveSelection: false,
-                  suffix:
-                      widget.showSuffix ? const Icon(KasyIcons.calendar) : null,
+            child: KasyFocusRing(
+              onActivate: _toggleCalendar,
+              // Match the text field corner radius so the ring hugs the trigger.
+              borderRadius: BorderRadius.circular(KasyRadius.md),
+              child: GestureDetector(
+                behavior: HitTestBehavior.opaque,
+                onTap: _toggleCalendar,
+                child: IgnorePointer(
+                  child: KasyTextField(
+                    key: _fieldKey,
+                    controller: _displayController,
+                    focusNode: _fieldFocusNode,
+                    readOnly: true,
+                    enabled: widget.enabled,
+                    hint: _resolvedPlaceholder,
+                    isInvalid: hasInvalidState,
+                    variant: widget.variant,
+                    focusBorder: widget.focusBorder,
+                    // No caret, no selection handles, no "blue text" when the
+                    // trigger is focused while the calendar is open — keeps the
+                    // field reading as a button, not an editable input.
+                    enableInteractiveSelection: false,
+                    suffix: widget.showSuffix
+                        ? const Icon(KasyIcons.calendar)
+                        : null,
+                  ),
                 ),
               ),
             ),

package/templates/firebase/lib/components/kasy_otp_verification_bottom_sheet.dart

@@ -4,6 +4,7 @@ import 'package:kasy_kit/components/kasy_button.dart';
 import 'package:kasy_kit/components/kasy_text_field_otp.dart';
 import 'package:kasy_kit/core/haptics/kasy_haptics.dart';
 import 'package:kasy_kit/core/theme/theme.dart';
+import 'package:kasy_kit/core/widgets/kasy_focus_ring.dart';
 
 /// Built-in layouts for [showKasyOtpVerificationBottomSheet].
 enum KasyOtpVerificationSheetPreset {
@@ -209,21 +210,25 @@ class _SheetResendCodeLinkState extends State<_SheetResendCodeLink> {
 
   @override
   Widget build(BuildContext context) {
-    return GestureDetector(
-      onTap: _handleTap,
-      onTapCancel: () => setState(() => _pressed = false),
-      child: AnimatedScale(
-        scale: _pressed ? 0.93 : 1.0,
-        duration: const Duration(milliseconds: 120),
-        curve: Curves.easeOutCubic,
-        child: AnimatedOpacity(
-          opacity: _pressed ? 0.55 : 1.0,
+    return KasyFocusRing(
+      onActivate: _handleTap,
+      borderRadius: BorderRadius.circular(KasyRadius.sm),
+      child: GestureDetector(
+        onTap: _handleTap,
+        onTapCancel: () => setState(() => _pressed = false),
+        child: AnimatedScale(
+          scale: _pressed ? 0.93 : 1.0,
           duration: const Duration(milliseconds: 120),
-          child: Text(
-            'Resend code',
-            style: context.textTheme.bodyMedium?.copyWith(
-              color: context.colors.onBackground,
-              fontWeight: FontWeight.w700,
+          curve: Curves.easeOutCubic,
+          child: AnimatedOpacity(
+            opacity: _pressed ? 0.55 : 1.0,
+            duration: const Duration(milliseconds: 120),
+            child: Text(
+              'Resend code',
+              style: context.textTheme.bodyMedium?.copyWith(
+                color: context.colors.onBackground,
+                fontWeight: FontWeight.w700,
+              ),
             ),
           ),
         ),

package/templates/firebase/lib/components/kasy_tabs.dart

@@ -507,35 +507,40 @@ class _PrimaryTabState extends State<_PrimaryTab> {
       ),
     );
 
-    final Widget gesture = GestureDetector(
-      onTap: widget.onTap,
-      behavior: HitTestBehavior.opaque,
-      child: Padding(
-        padding: verticalLayout
-            // Fill+icon: 12px all sides — per Figma spec.
-            ? const EdgeInsets.all(12)
-            // Default: 6px vertical, 12px horizontal — per Figma spec.
-            : const EdgeInsets.symmetric(vertical: 6, horizontal: 12),
-        child: verticalLayout
-            ? Column(
-                mainAxisSize: MainAxisSize.min,
-                mainAxisAlignment: MainAxisAlignment.center,
-                children: [
-                  iconWidget,
-                  const SizedBox(height: 6),
-                  labelWidget,
-                ],
-              )
-            : Row(
-                mainAxisSize: MainAxisSize.min,
-                mainAxisAlignment: MainAxisAlignment.center,
-                children: [
-                  if (item.icon != null) iconWidget,
-                  if (item.icon != null && hasLabel)
-                    const SizedBox(width: 6),
-                  if (hasLabel) labelWidget,
-                ],
-              ),
+    final Widget gesture = KasyFocusRing(
+      enabled: widget.onTap != null,
+      onActivate: widget.onTap,
+      borderRadius: BorderRadius.circular(KasyRadius.sm),
+      child: GestureDetector(
+        onTap: widget.onTap,
+        behavior: HitTestBehavior.opaque,
+        child: Padding(
+          padding: verticalLayout
+              // Fill+icon: 12px all sides — per Figma spec.
+              ? const EdgeInsets.all(12)
+              // Default: 6px vertical, 12px horizontal — per Figma spec.
+              : const EdgeInsets.symmetric(vertical: 6, horizontal: 12),
+          child: verticalLayout
+              ? Column(
+                  mainAxisSize: MainAxisSize.min,
+                  mainAxisAlignment: MainAxisAlignment.center,
+                  children: [
+                    iconWidget,
+                    const SizedBox(height: 6),
+                    labelWidget,
+                  ],
+                )
+              : Row(
+                  mainAxisSize: MainAxisSize.min,
+                  mainAxisAlignment: MainAxisAlignment.center,
+                  children: [
+                    if (item.icon != null) iconWidget,
+                    if (item.icon != null && hasLabel)
+                      const SizedBox(width: 6),
+                    if (hasLabel) labelWidget,
+                  ],
+                ),
+        ),
       ),
     );
 
@@ -598,45 +603,50 @@ class _SecondaryTabState extends State<_SecondaryTab> {
     // selected color so it reads as interactive (mobile keeps the flat look).
     final Color fg = (selected || _hovered) ? c.onSurface : c.muted;
 
-    final Widget gesture = GestureDetector(
-      onTap: widget.onTap,
-      behavior: HitTestBehavior.opaque,
-      child: Padding(
-        // top:4 bottom:6 horizontal:12 — per Figma spec.
-        // Extra bottom padding visually balances the 2px underline indicator.
-        padding: const EdgeInsets.only(
-          top: 4,
-          bottom: 6,
-          left: 12,
-          right: 12,
-        ),
-        child: Row(
-          mainAxisSize: MainAxisSize.min,
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: [
-            if (item.icon != null) ...[
-              Opacity(
-                opacity: disabled ? 0.4 : 1.0,
-                child: Icon(
-                  item.icon,
-                  size: 16,
-                  color: fg,
-                ),
-              ),
-              if (hasLabel) const SizedBox(width: 6),
-            ],
-            if (hasLabel)
-              Opacity(
-                opacity: disabled ? 0.4 : 1.0,
-                child: Text(
-                  item.label,
-                  // Use labelLarge as defined in the Kasy theme (14px/w600).
-                  style: context.textTheme.labelLarge?.copyWith(
+    final Widget gesture = KasyFocusRing(
+      enabled: widget.onTap != null,
+      onActivate: widget.onTap,
+      borderRadius: BorderRadius.circular(KasyRadius.sm),
+      child: GestureDetector(
+        onTap: widget.onTap,
+        behavior: HitTestBehavior.opaque,
+        child: Padding(
+          // top:4 bottom:6 horizontal:12 — per Figma spec.
+          // Extra bottom padding visually balances the 2px underline indicator.
+          padding: const EdgeInsets.only(
+            top: 4,
+            bottom: 6,
+            left: 12,
+            right: 12,
+          ),
+          child: Row(
+            mainAxisSize: MainAxisSize.min,
+            mainAxisAlignment: MainAxisAlignment.center,
+            children: [
+              if (item.icon != null) ...[
+                Opacity(
+                  opacity: disabled ? 0.4 : 1.0,
+                  child: Icon(
+                    item.icon,
+                    size: 16,
                     color: fg,
                   ),
                 ),
-              ),
-          ],
+                if (hasLabel) const SizedBox(width: 6),
+              ],
+              if (hasLabel)
+                Opacity(
+                  opacity: disabled ? 0.4 : 1.0,
+                  child: Text(
+                    item.label,
+                    // Use labelLarge as defined in the Kasy theme (14px/w600).
+                    style: context.textTheme.labelLarge?.copyWith(
+                      color: fg,
+                    ),
+                  ),
+                ),
+            ],
+          ),
         ),
       ),
     );

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

@@ -6,6 +6,7 @@ import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:kasy_kit/components/kasy_sidebar.dart';
 import 'package:kasy_kit/core/bottom_menu/bottom_router.dart';
 import 'package:kasy_kit/core/bottom_menu/kasy_bottom_bar_factory.dart';
+import 'package:kasy_kit/core/bottom_menu/web_content_wrapper.dart';
 import 'package:kasy_kit/core/data/models/user.dart';
 import 'package:kasy_kit/core/states/logout_action.dart';
 import 'package:kasy_kit/core/states/user_state_notifier.dart';
@@ -220,17 +221,116 @@ class _FocusableSidebarState extends State<_FocusableSidebar> {
     super.dispose();
   }
 
+  // "Skip to content" moves the primary focus into the routed content, so the
+  // next Tab steps to the first real control there instead of the sidebar.
+  void _skipToContent() => kasyContentFocusTarget?.requestFocus();
+
   @override
   Widget build(BuildContext context) {
+    // Ordered so the first Tab reveals the "skip to content" link (order 0),
+    // then the sidebar (order 1). The header (2) and content (3) come after,
+    // ordered by the scaffold's OrderedTraversalPolicy. The invisible anchor
+    // holds the initial focus so that very first Tab lands on the skip link.
     return FocusTraversalGroup(
-      // The anchor is a zero-size sibling so it never affects the sidebar's
-      // layout; it exists only to hold the initial keyboard focus (see above).
+      policy: OrderedTraversalPolicy(),
       child: Stack(
+        clipBehavior: Clip.none,
         children: [
-          widget.child,
+          FocusTraversalOrder(
+            order: const NumericFocusOrder(1),
+            child: FocusTraversalGroup(child: widget.child),
+          ),
+          // Zero-size sibling; only holds the initial keyboard focus.
           Focus(focusNode: _anchor, child: const SizedBox.shrink()),
+          Positioned(
+            top: KasySpacing.sm,
+            left: KasySpacing.sm,
+            child: FocusTraversalOrder(
+              order: const NumericFocusOrder(0),
+              child: _SkipToContentLink(onSkip: _skipToContent),
+            ),
+          ),
         ],
       ),
     );
   }
 }
+
+/// The "skip to content" link (WCAG 2.4.1 "Bypass Blocks"). It is the first Tab
+/// stop on every screen: pressing Tab once reveals it above the sidebar, Enter
+/// jumps focus into the content, and pressing Tab again moves on to the sidebar.
+/// It only paints while focused via the keyboard, so pointer/touch users never
+/// see it. Mirrors the pattern used by Stripe, GitHub, etc.
+class _SkipToContentLink extends StatefulWidget {
+  final VoidCallback onSkip;
+
+  const _SkipToContentLink({required this.onSkip});
+
+  @override
+  State<_SkipToContentLink> createState() => _SkipToContentLinkState();
+}
+
+class _SkipToContentLinkState extends State<_SkipToContentLink> {
+  bool _show = false;
+
+  static const Map<ShortcutActivator, Intent> _shortcuts =
+      <ShortcutActivator, Intent>{
+    SingleActivator(LogicalKeyboardKey.enter): ActivateIntent(),
+    SingleActivator(LogicalKeyboardKey.numpadEnter): ActivateIntent(),
+    SingleActivator(LogicalKeyboardKey.space): ActivateIntent(),
+  };
+
+  @override
+  Widget build(BuildContext context) {
+    final KasyColors c = context.colors;
+    return FocusableActionDetector(
+      shortcuts: _shortcuts,
+      actions: <Type, Action<Intent>>{
+        ActivateIntent: CallbackAction<ActivateIntent>(
+          onInvoke: (_) {
+            widget.onSkip();
+            return null;
+          },
+        ),
+      },
+      onShowFocusHighlight: (bool show) {
+        if (mounted && show != _show) setState(() => _show = show);
+      },
+      child: IgnorePointer(
+        ignoring: !_show,
+        child: AnimatedOpacity(
+          opacity: _show ? 1 : 0,
+          duration: const Duration(milliseconds: 120),
+          child: GestureDetector(
+            onTap: widget.onSkip,
+            child: Container(
+              padding: const EdgeInsets.symmetric(
+                horizontal: KasySpacing.md,
+                vertical: KasySpacing.sm,
+              ),
+              decoration: BoxDecoration(
+                color: c.surface,
+                borderRadius: BorderRadius.circular(KasyRadius.md),
+                border: Border.all(color: c.primary, width: 1.5),
+                boxShadow: <BoxShadow>[
+                  BoxShadow(
+                    color: c.onSurface.withValues(alpha: 0.18),
+                    blurRadius: 16,
+                    offset: const Offset(0, 4),
+                  ),
+                ],
+              ),
+              child: Text(
+                context.t.navigation.skip_to_content,
+                style: context.textTheme.bodyMedium?.copyWith(
+                  color: c.onSurface,
+                  fontWeight: FontWeight.w600,
+                ),
+              ),
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}