# Ring Width, Color, and Offset

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)
- [Variants](#variants)
- [Responsive Design](#responsive-design)
- [Dark Mode](#dark-mode)
- [Arbitrary Values](#arbitrary-values)
- [Customizing Theme](#customizing-theme)
- [Related Documentation](#related-documentation)

```dart
// Default ring (3px blue-500)
WDiv(className: 'ring')

// Custom width and color
WDiv(className: 'ring-4 ring-red-500')

// With offset
WDiv(className: 'ring-2 ring-offset-2')
```

## Basic Usage

Use `ring-{width}` utilities to draw a solid outline around an element. By default, this adds a 3px blue ring.

> [!NOTE]
> 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(
  className: 'ring-4 ring-blue-500 rounded-lg p-4',
  child: WText('Ring Example'),
)
```

## Quick Reference

| Class | Value | Description |
|:------|:------|:------------|
| `ring-0` | 0px | No ring |
| `ring-1` | 1px | 1px ring width |
| `ring-2` | 2px | 2px ring width |
| `ring` | 3px | Default ring width (3px) |
| `ring-4` | 4px | 4px ring width |
| `ring-8` | 8px | 8px ring width |
| `ring-inset` | - | Forces ring to be on the inside |
| `ring-offset-{width}` | - | Moves the ring out, leaving an unpainted gap |

## Variants

### Ring Color

Use `ring-{color}` to set the color of the ring. You can also use opacity modifiers like `/50`.

```dart
WDiv(className: 'ring-2 ring-blue-500')
WDiv(className: 'ring-2 ring-red-500/50') // 50% opacity
```

### Ring Offset

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')
```

| Class | Value | Description |
|:------|:------|:------------|
| `ring-offset-0` | 0px | No offset |
| `ring-offset-1` | 1px | 1px offset |
| `ring-offset-2` | 2px | 2px offset |
| `ring-offset-4` | 4px | 4px offset |
| `ring-offset-8` | 8px | 8px offset |

### Ring Inset

Use `ring-inset` to force the ring to render on the inside of the element instead of the outside. This is useful for elements that shouldn't overflow their container.

```dart
WDiv(className: 'ring-2 ring-inset ring-pink-500')
```

## Responsive Design

Apply different ring utilities at different breakpoints using the standard `sm:`, `md:`, `lg:`, `xl:`, and `2xl:` prefixes.

```dart
WDiv(className: 'ring-2 md:ring-4 lg:ring-8')
```

## Dark Mode

Use the `dark:` prefix to apply different ring styles when the application is in dark mode.

```dart
WDiv(className: 'ring-slate-900/5 dark:ring-white/10')
```

## Arbitrary Values

If the built-in scale doesn't meet your needs, use bracket notation to apply custom values directly.

```dart
// Custom color
WDiv(className: 'ring-[#50d71e]')

// Custom color with opacity
WDiv(className: 'ring-[#50d71e]/50')
```

> [!NOTE]
> Currently, arbitrary values are supported for **colors only** (`ring-[#hex]`). Arbitrary widths (`ring-[10px]`) are not yet supported in the parser.

## Customizing Theme

To extend or override the default scale for rings, modify the `WindThemeData` in your app root.

```dart
WindTheme(
  data: WindThemeData(
    // Default color when no ring color class is present
    ringColor: Colors.blue, 
    
    // Custom ring widths
    ringWidths: {
      'DEFAULT': 3,
      '6': 6,
      '10': 10,
    },
    
    // Custom offset widths
    ringOffsets: {
      '3': 3,
      '6': 6,
    },
  ),
  child: MyApp(),
)
```

## Related Documentation

- [Borders](https://anilcancakir.com/wind_kit/docs/v1.11/borders/borders.md)
- [Box Shadow](https://anilcancakir.com/wind_kit/docs/v1.11/styling/shadow.md)