fix(ring): paint rings as outlines, and on WButton at all

CHANGELOG.md

@@ -14,6 +14,8 @@ This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.
 
 ### Fixed
 
+- **A `ring-*` is an outline, so a focused element with no background is no longer a solid block.** Wind drew the ring as a spread `BoxShadow`. A browser clips a box-shadow to the outside of its element, so Tailwind's ring reads as an outline; Flutter does not clip it, and an element with no background filled with the ring colour. A host app's rail drew every keyboard-focused icon button as a solid blue block with the glyph lost inside it. `WDiv` now paints `WindStyle.ringOutline`, a stroke over the box on its own corner radius: outside the edge, inside it for `ring-inset` (which never showed over a background before), and moved out by `ring-offset-*` with the gap left unpainted (the offset used to be covered by the ring itself). The ring no longer joins the box shadows. A focused `WInput` paints the same outline instead of its ring shadow (it still promotes the ring to its border), so a transparent field no longer fills with the ring colour. The docs' `ring-offset-white` example is gone: Wind has no ring-offset colour and the class did nothing. (`lib/src/parser/wind_style.dart`, `lib/src/widgets/w_div.dart`, `lib/src/widgets/w_input.dart`, `test/pixel/ring_outline_pixel_test.dart`, `test/widgets/w_input_test.dart`, `test/pixel/radius_ring_border_pixel_test.dart`, `doc/borders/ring.md`)
+- **`WButton` paints its `ring-*` and `shadow-*`.** It built its box from the parsed decoration alone, so both parsed and painted nothing: a host app's dialog buttons showed no focus while Tab moved between them. It now folds `boxShadow` into the decoration and paints `ringOutline` over the box. (`lib/src/widgets/w_button.dart`, `test/widgets/w_button_test.dart`)
 - **A `WPopover` opens from the keyboard and shows where focus is.** Its trigger took focus on Tab and then answered nothing: Enter and Space did not open it, Escape did not close it, and no `focus:` class on the trigger could light, so a host app's notification bell was a Tab stop a keyboard user could neither see nor use. The trigger now answers `ActivateIntent` (Enter, Space, the Android TV D-pad centre), as `WAnchor` does, only where a tap would toggle; Escape closes an open popover from the trigger or from inside the panel, returns focus to the trigger and consumes the key, so a popover in a dialog closes alone; and the popover publishes its trigger's hover, focus and disabled state through `WindAnchorStateProvider`, so a plain `WDiv` trigger answers `focus:` and its own styling wrapper stops being a second Tab stop. Escape is a key handler on the focus tree, above the portal. In a host app's web walk it first went deaf: the browser drops the trigger's focus as the panel mounts, so after a keyboard open Escape reached nothing and the next Tab started over from the top of the page. The first focus change after a keyboard open, when it lands on a scope rather than a control, now hands focus back to the trigger, once. A `HardwareKeyboard` handler was rejected for Escape: returning true from one does not stop the key reaching the focus tree, so a popover open in a dialog closed together with the dialog. The trigger and the panel are one `FocusTraversalGroup` in widget order, so Tab goes from the trigger into the panel: reading order had ranked a control beside the trigger before the panel below it, and a panel flipped above its trigger before the trigger itself, so the walk measured a phone shell that never reached the panel and a rail bell whose panel was reachable only with Shift+Tab. A `DismissIntent` action was rejected because `ShortcutManager` asks only the nearest action for an intent, so a disabled one would have swallowed Escape on a closed popover and a dialog holding it would have stopped closing. A disabled popover is no longer a Tab stop. (`lib/src/widgets/w_popover.dart`, `test/widgets/w_popover/keyboard_test.dart`, `doc/widgets/w-popover.md`, `skills/wind-ui/SKILL.md`)
 - **Arbitrary `tracking-[...]` honours its unit and its sign.** `tracking-[0.1em]` stripped the unit and set 0.1 logical pixels, and a negative value such as `tracking-[-0.02em]` did not match the pattern at all, so it was dropped. An `em` value is now em, a `px` value or a bare number is logical pixels (as in `leading-[24]` and `text-[20]`), and both take a negative sign. (`lib/src/parser/parsers/text_parser.dart`, `test/parser/parsers/text_parser_test.dart`, `doc/typography/letter-spacing.md`)
 

doc/borders/ring.md

@@ -1,6 +1,6 @@
 # Ring Width, Color, and Offset
 
-Utilities for creating outline rings with box-shadows. These are useful for focus states or highlighting elements without affecting layout.
+Utilities for drawing an outline ring around an element. These are useful for focus states or highlighting elements without affecting layout.
 
 - [Basic Usage](#basic-usage)
 - [Quick Reference](#quick-reference)
@@ -26,10 +26,10 @@ WDiv(className: 'ring-2 ring-offset-2')
 
 ## Basic Usage
 
-Use `ring-{width}` utilities to apply a solid box-shadow to an element. By default, this adds a 3px blue ring.
+Use `ring-{width}` utilities to draw a solid outline around an element. By default, this adds a 3px blue ring.
 
 > [!NOTE]
-> Rings in Wind are implemented using `BoxShadow` with a spread radius and zero blur. They do not take up space in the layout, unlike borders.
+> Tailwind draws a ring as a box-shadow, which a browser clips to the outside of the element. Wind paints the same thing as an outline stroke over the element's box, on its corner radius, so an element with no background stays empty inside its ring. A ring does not take up space in the layout, unlike a border.
 
 ```dart
 WDiv(
@@ -49,7 +49,7 @@ WDiv(
 | `ring-4` | 4px | 4px ring width |
 | `ring-8` | 8px | 8px ring width |
 | `ring-inset` | - | Forces ring to be on the inside |
-| `ring-offset-{width}` | - | Simulates an offset by adding a transparent gap |
+| `ring-offset-{width}` | - | Moves the ring out, leaving an unpainted gap |
 
 ## Variants
 
@@ -66,11 +66,11 @@ WDiv(className: 'ring-2 ring-red-500/50') // 50% opacity
 
 ### Ring Offset
 
-Use `ring-offset-{width}` to simulate space between the element and the ring. This is helpful for focus states on colored backgrounds.
+Use `ring-offset-{width}` to leave space between the element and the ring. The gap is not painted, so whatever is behind the element shows through it; Wind has no `ring-offset-{color}`.
 
 ```dart
 // Creates a 2px gap between the element and the ring
-WDiv(className: 'ring-2 ring-offset-2 ring-offset-white')
+WDiv(className: 'ring-2 ring-offset-2')
 ```
 
 | Class | Value | Description |

example/lib/pages/effects/ring_colors.dart

@@ -55,7 +55,6 @@ class RingColorsExamplePage extends StatelessWidget {
               bg-white dark:bg-slate-800
               border border-gray-300 dark:border-gray-600
               focus:ring-2 focus:ring-amber-500 focus:ring-offset-2
-              focus:ring-offset-white dark:focus:ring-offset-slate-900
             ''',
           ),
         ),

example/lib/pages/images/image_basic.dart

@@ -53,7 +53,6 @@ class ImageBasicExamplePage extends StatelessWidget {
                 className: '''
                   w-20 h-20 rounded-full object-cover
                   ring-4 ring-emerald-500 ring-offset-2
-                  ring-offset-white dark:ring-offset-slate-900
                 ''',
               ),
             ],

lib/src/parser/wind_style.dart

@@ -686,6 +686,42 @@ class WindStyle {
     return null;
   }
 
+  /// The `ring-*` outline as a decoration to paint in the FOREGROUND of the
+  /// element's box, or null when it carries no ring (or `ring-0`).
+  ///
+  /// Tailwind's ring is a box-shadow, and a browser clips a box-shadow to the
+  /// outside of its element, so what a reader sees is an outline. A Flutter
+  /// [BoxShadow] is not clipped, which filled every element without a
+  /// background with the ring colour, so widgets paint this instead: a stroke
+  /// [ringWidth] wide outside the box, or inside it for `ring-inset`, on the
+  /// box's own corner radius. A `ring-offset-*` moves the stroke that far out
+  /// and leaves the gap unpainted, since Wind has no `ring-offset-color`.
+  ///
+  /// `strokeAlign` 1 puts the stroke wholly outside the edge; each further
+  /// `2 / width` moves it one logical pixel out, which is how the offset is
+  /// expressed without a second box.
+  BoxDecoration? get ringOutline {
+    final double width = ringWidth ?? 0;
+    final Color? color = ringColor;
+    if (width <= 0 || color == null || (ringShadow?.isEmpty ?? true)) {
+      return null;
+    }
+
+    final double offset = ringOffset ?? 0;
+    final double strokeAlign = (ringInset ?? false)
+        ? BorderSide.strokeAlignInside
+        : BorderSide.strokeAlignOutside + 2 * offset / width;
+
+    return BoxDecoration(
+      borderRadius: decoration?.borderRadius,
+      border: Border.all(
+        color: color,
+        width: width,
+        strokeAlign: strokeAlign,
+      ),
+    );
+  }
+
   /// Whether an em [letterSpacing] has no [fontSize] of its own to resolve
   /// against, so [toTextStyle] needs the font size the text inherits.
   ///

lib/src/widgets/w_button.dart

@@ -184,6 +184,15 @@ class WButton extends StatelessWidget {
             containerAlignment = styles.alignment;
           }
 
+          // The box shadow travels beside the decoration in WindStyle, so it
+          // is folded in here; building from the decoration alone dropped
+          // every `shadow-*` on a button.
+          final List<BoxShadow>? shadows = styles.boxShadow;
+          final BoxDecoration? decoration = shadows == null || shadows.isEmpty
+              ? styles.decoration
+              : (styles.decoration ?? const BoxDecoration())
+                  .copyWith(boxShadow: shadows);
+
           // Wrap in styled container
           WindPerfCounters.recordWrapperEmission('Container');
           WindPerfCounters.recordWrapperEmission('DefaultTextStyle');
@@ -193,7 +202,7 @@ class WButton extends StatelessWidget {
                 styles.heightFactor != null ? double.infinity : styles.height,
             constraints: styles.constraints,
             padding: styles.padding,
-            decoration: styles.decoration,
+            decoration: decoration,
             alignment: containerAlignment,
             child: DefaultTextStyle.merge(
               style: styles.toTextStyle(
@@ -205,6 +214,19 @@ class WButton extends StatelessWidget {
             ),
           );
 
+          // The ring, an outline around the box (`WindStyle.ringOutline`).
+          // A button is the control most often focused from the keyboard, and
+          // its `focus:ring-*` painted nothing until this.
+          final BoxDecoration? ring = styles.ringOutline;
+          if (ring != null) {
+            WindPerfCounters.recordWrapperEmission('DecoratedBox');
+            styledButton = DecoratedBox(
+              position: DecorationPosition.foreground,
+              decoration: ring,
+              child: styledButton,
+            );
+          }
+
           // Wrap with AbsorbPointer when not interactive
           if (!isInteractive) {
             WindPerfCounters.recordWrapperEmission('AbsorbPointer');

lib/src/widgets/w_div.dart

@@ -1591,11 +1591,11 @@ class WDiv extends StatelessWidget {
       // Merge decoration with shadows (boxShadow + ringShadow)
       BoxDecoration? finalDecoration = styles.decoration;
 
-      // Combine box shadows and ring shadows
-      List<BoxShadow>? combinedShadows;
-      if (styles.boxShadow != null || styles.ringShadow != null) {
-        combinedShadows = [...?styles.boxShadow, ...?styles.ringShadow];
-      }
+      // Box shadows only. The ring is an outline painted around the box below
+      // (`WindStyle.ringOutline`), never a shadow: a Flutter `BoxShadow` is not clipped
+      // to the outside of its box as a browser's box-shadow is, so a ring
+      // shadow filled any element without a background with the ring colour.
+      final List<BoxShadow>? combinedShadows = styles.boxShadow;
 
       if (combinedShadows != null && combinedShadows.isNotEmpty) {
         if (finalDecoration == null) {
@@ -1736,6 +1736,17 @@ class WDiv extends StatelessWidget {
           logger: logger,
         );
       }
+
+      final BoxDecoration? ring = styles.ringOutline;
+      if (ring != null) {
+        logger.wrapWith("DecoratedBox (Ring)", "${styles.ringWidth}px");
+        WindPerfCounters.recordWrapperEmission('DecoratedBox');
+        widgetToBuild = DecoratedBox(
+          position: DecorationPosition.foreground,
+          decoration: ring,
+          child: widgetToBuild,
+        );
+      }
     }
 
     // 1c. EXPLICIT SIZING (w-*, h-* when not handled by overflow)

lib/src/widgets/w_input.dart

@@ -883,10 +883,20 @@ class _WInputState extends State<WInput>
     // Wrap in the decorated box (className → BoxDecoration, same path WDiv
     // uses), recomputing on focus so the ring/border reacts to `_isFocused`.
     WindPerfCounters.recordWrapperEmission('DecoratedBox');
-    Widget result = DecoratedBox(
-      decoration: _buildDecoration(styles),
-      child: field,
-    );
+    final BoxDecoration decoration = _buildDecoration(styles);
+    Widget result = DecoratedBox(decoration: decoration, child: field);
+
+    // The ring outline while focused, on the field's own corner radius,
+    // which falls back to the field's default when className sets none.
+    final BoxDecoration? ring = _isFocused ? styles.ringOutline : null;
+    if (ring != null) {
+      WindPerfCounters.recordWrapperEmission('DecoratedBox');
+      result = DecoratedBox(
+        position: DecorationPosition.foreground,
+        decoration: ring.copyWith(borderRadius: decoration.borderRadius),
+        child: result,
+      );
+    }
 
     // Native selection gesture layer wraps the WHOLE decorated box (padding +
     // prefix/suffix Row + DecoratedBox). The builder hit-tests against the
@@ -1018,13 +1028,14 @@ class _WInputState extends State<WInput>
       );
     }
 
-    // Focus ring: promote ring color/width to the border and paint the ring
-    // shadow, matching the previous focus-on border behavior.
-    List<BoxShadow>? boxShadow = styles.boxShadow;
+    // Focus ring: promote ring color/width to the border, matching the
+    // previous focus-on border behavior. The ring outside it is
+    // `WindStyle.ringOutline`, painted over this box in `build`, never a
+    // shadow under it: a shadow filled a transparent field with the ring
+    // colour.
     if (_isFocused &&
         styles.ringShadow != null &&
         styles.ringShadow!.isNotEmpty) {
-      boxShadow = styles.ringShadow;
       final Color ringColor = styles.ringColor ?? _defaultBorderColor;
       final double ringWidth = styles.ringWidth ?? _defaultBorderWidth;
       border = Border.all(color: ringColor, width: ringWidth);
@@ -1034,7 +1045,7 @@ class _WInputState extends State<WInput>
       color: fillColor,
       border: border,
       borderRadius: borderRadius,
-      boxShadow: boxShadow,
+      boxShadow: styles.boxShadow,
       gradient: parsed?.gradient,
       image: parsed?.image,
     );

skills/wind-ui/SKILL.md

@@ -2,7 +2,7 @@
 name: wind-ui
 description: "fluttersdk_wind 1.8: utility-first Flutter styling with Tailwind-syntax className strings. 27 W-prefix widgets (WDiv, WText, WButton, WInput, WSelect, WDatePicker, WPopover, WCard, WTabs, plus five WForm* wrappers) parse className into a cached immutable WindStyle; WindRecipe and WindSlotRecipe compose variant classNames. Prefixes stack freely (dark: / hover: / focus: / md: / ios: / selected: / disabled: / custom), the last class in a family wins, an unrecognized token drops with a one-time kDebugMode hint, and every color token carries a dark: peer in the same className. TRIGGER when: writing or editing UI in a Flutter app that depends on fluttersdk_wind; any className string; any W-prefix widget; any WindTheme or WindThemeData reference; the user mentions Tailwind for Flutter, utility-first, className, or wind-ui. DO NOT TRIGGER when: backend, API, or state-management work that never touches a widget tree; a Flutter project without fluttersdk_wind in pubspec.yaml; Material-only widgets (Scaffold, AppBar, Dialog) with no Wind content inside."
 when_to_use: "Any task that produces, modifies, or audits Wind-styled UI: composing a className, picking the right W-widget, wiring a Form field, customizing WindThemeData, pairing dark-mode classes, debugging a layout or a RenderFlex overflow, building a popover, rendering a JSON tree via WDynamic, or composing a WindRecipe. Load it before the first line of new UI, and equally when auditing UI that already exists."
-version: 2.24.0
+version: 2.25.0
 ---
 
 <!-- fluttersdk_wind 1.8.x | Skill v2.23.0 (2026-10-13) -->
@@ -177,7 +177,7 @@ Inline this catalog as your default reach-for set. For the full per-parser regex
 
 **Typography** (order of resolution inside `text-*`): color → align → size → weight → style. `text-xs` `text-sm` `text-base` `text-lg` `text-xl` `text-2xl` through `text-6xl` (60 px). `text-7xl` / `text-8xl` / `text-9xl` are no-ops; do not write them. `font-thin` through `font-black`. `text-left` `text-center` `text-right` `text-justify` `text-start` `text-end` (RTL-aware). `truncate` (= `text-ellipsis` + `maxLines: 1` + `softWrap: false`). `line-clamp-N`. `whitespace-nowrap` / `text-nowrap`. `uppercase` `lowercase` `capitalize` `normal-case` (`capitalize` raises the first letter of every word and leaves the rest as typed, so `the HTTP client` is `The HTTP Client` and `well-known` is `Well-Known`, while a digit, an underscore, an apostrophe or a combining mark continues the word, so `3rd party`, `l'orange` and decomposed NFD text keep theirs; casing follows the ambient locale, so `tr`/`az` get the dotted/dotless `i` right, and it falls back to locale-independent casing with no `Localizations` ancestor). `italic` / `not-italic`. `underline` `line-through` `no-underline`, plus `decoration-{color}/{style}/{thickness}`. `leading-tight` `leading-snug` `leading-normal` `leading-relaxed` `leading-loose` or arbitrary `leading-[24px]`. `tracking-tighter` through `tracking-widest` are em (Tailwind's -0.05em to 0.1em), multiplied by the text's own `text-*` size, else the inherited size, else 14 (`kDefaultFontSize`); `tracking-[-0.02em]` is em, `tracking-[1px]` and a bare `tracking-[1]` are px. Font size + line height combined: `text-xl/8`.
 
-**Effects**: `opacity-N` (5-step scale, plus arbitrary `opacity-[0.5]`). `shadow-sm` `shadow` `shadow-md` `shadow-lg` `shadow-xl` `shadow-2xl` `shadow-inner` `shadow-none`. Colored shadow `shadow-blue-500/20`. `ring-N` `ring-{color}` `ring-offset-N` `ring-inset`. `aspect-square` `aspect-video` `aspect-[4/3]`. `z-0` `z-10` through `z-50`, arbitrary `z-[100]`, `z-auto`.
+**Effects**: `opacity-N` (5-step scale, plus arbitrary `opacity-[0.5]`). `shadow-sm` `shadow` `shadow-md` `shadow-lg` `shadow-xl` `shadow-2xl` `shadow-inner` `shadow-none`. Colored shadow `shadow-blue-500/20`. `ring-N` `ring-{color}` `ring-offset-N` `ring-inset` (an outline over the box, never a fill: a ring on an element with no background stays empty inside; the offset gap is unpainted). `aspect-square` `aspect-video` `aspect-[4/3]`. `z-0` `z-10` through `z-50`, arbitrary `z-[100]`, `z-auto`.
 
 **Overflow**: `overflow-hidden` `overflow-visible` `overflow-scroll` `overflow-auto`, axis-specific `overflow-x-auto` `overflow-y-auto`. On a box with a border, `overflow-hidden` clips inside the border (the padding box, inner radius), so the border stays whole at rounded corners and the box's own `shadow-*` still paints. Scrolling requires the constructor prop `scrollPrimary: true` for iOS tap-to-top (there is no className for it).