tailwind-dashed-border/TECHNICAL_DESCRIPTION.md

Tailwind Dashed Border Plugin: Technical Description

This plugin provides a small set of Tailwind CSS utilities for drawing configurable dashed borders with an SVG <rect> overlay instead of using the native CSS border-style: dashed. The SVG approach makes dash length, gap, offset, stroke width, color, and rounded corners independently controllable.

What the plugin does

The plugin defines:

• Base CSS custom properties for dashed-border configuration.
• Structural utilities for the container, SVG overlay, and SVG rectangle.
• Generated utility families for gap, dash length, offset, stroke width, stroke color, and border radius.
• Transition helpers so dashed-border visuals can animate consistently with Tailwind transition utilities.

The plugin expects the dashed border to be rendered by an element structure like this:

<div class="dashed-border dashed-border-gap-2 dashed-border-length-4 dashed-border-width-2">
  <svg class="dashed-border-svg" aria-hidden="true">
    <rect class="dashed-border-rect" />
  </svg>

  <!-- content -->
</div>

Core structural utilities

.dashed-border

This is the root utility for any element using the plugin. It:

• Sets default CSS variables.
• Applies position: relative so the SVG overlay can be absolutely positioned.

Default values:

• --tw-dashed-border-gap: calc(var(--spacing, 0.25rem) * 2)
• --tw-dashed-border-length: calc(var(--spacing, 0.25rem) * 3)
• --tw-dashed-border-offset: 0px
• --tw-dashed-border-width: 1px
• --tw-dashed-border-color: currentColor
• --tw-dashed-border-radius: 0px

.dashed-border-svg

This utility is intended for the SVG overlay element. It:

• Makes the SVG fill the container with position: absolute and inset: 0.
• Sets width: 100% and height: 100%.
• Uses overflow: hidden.
• Uses pointer-events: none so the overlay does not block interaction.

.dashed-border-rect

This utility is intended for the SVG <rect> that draws the actual border. It:

• Removes fill with fill: none.
• Uses stroke for the border color.
• Uses stroke-dasharray for dash length and gap.
• Uses stroke-dashoffset for dash phase shifting.
• Uses vector-effect: non-scaling-stroke to keep stroke width stable.
• Positions the rectangle inset by half the stroke width, so the stroke remains visually inside the element bounds.
• Uses rx to simulate rounded corners.

Computed shape rules:

• x / y: calc(var(--tw-dashed-border-width) / 2)
• width / height: calc(100% - var(--tw-dashed-border-width))
• rx: max(0px, calc(var(--tw-dashed-border-radius) - (var(--tw-dashed-border-width) / 2)))

Dash pattern:

stroke-dasharray: <length> <gap>;

Registered custom properties

The plugin registers these @property definitions:

• --tw-dashed-border-gap
• --tw-dashed-border-length
• --tw-dashed-border-offset
• --tw-dashed-border-width
• --tw-dashed-border-radius

These registrations provide typed CSS custom properties so transitions and interpolation behave more predictably in supporting browsers.

Generated utility families

Gap utilities

Class shape:

dashed-border-gap-*

Source values:

• Tailwind theme.spacing

Effect:

• Sets --tw-dashed-border-gap
• Recomputes stroke-dasharray

Example:

<div class="dashed-border dashed-border-gap-4">

Dash length utilities

Class shape:

dashed-border-length-*

Source values:

• Tailwind theme.spacing

Effect:

• Sets --tw-dashed-border-length
• Recomputes stroke-dasharray

Example:

<div class="dashed-border dashed-border-length-6">

Dash offset utilities

Class shape:

dashed-border-offset-*

Source values:

• Tailwind theme.spacing

Effect:

• Sets --tw-dashed-border-offset
• Updates stroke-dashoffset

Example:

<div class="dashed-border dashed-border-offset-2">

Stroke width utilities

Class shape:

dashed-border-width-*

Source values:

• Tailwind theme.borderWidth

Effect:

• Sets --tw-dashed-border-width
• Updates stroke-width
• Recomputes x, y, width, height, and rx

Example:

<div class="dashed-border dashed-border-width-2">

Stroke color utilities

Class shape:

dashed-border-color-*

Source values:

• Flattened Tailwind theme.colors
• Plus explicit aliases:
  • dashed-border-color-current
  • dashed-border-color-inherit
  • dashed-border-color-transparent

Effect:

• Sets --tw-dashed-border-color
• Updates SVG stroke

Example:

<div class="dashed-border dashed-border-color-slate-500">

Nested Tailwind colors are flattened with dash-separated keys, so a theme color like slate.500 becomes:

dashed-border-color-slate-500

Radius utilities

Class shape:

dashed-border.rounded-*

These are not generated as dashed-border-radius-*. Instead, the plugin creates compound selectors that combine .dashed-border with Tailwind rounded classes.

Examples of generated selectors:

• .dashed-border.rounded
• .dashed-border.rounded-sm
• .dashed-border.rounded-lg
• .dashed-border.rounded-full

Source values:

• Tailwind theme.borderRadius

Effect:

• Sets --tw-dashed-border-radius
• Lets the SVG rectangle inherit matching rounded-corner behavior through its computed rx

Example:

<div class="dashed-border rounded-lg">

This means the expected way to apply radius is:

<div class="dashed-border rounded-xl">

not:

<div class="dashed-border-radius-xl">

Transition behavior

The plugin adds transition helpers for dashed-border visuals.

Supported patterns:

• .dashed-border-transition
• .dashed-border.transition
• .dashed-border.transition-all
• .dashed-border.transition-colors

Behavior:

• Inherits Tailwind-style transition duration and timing defaults.
• Applies transitions to the inner .dashed-border-rect.
• transition / transition-all animate:
  • stroke-dasharray
  • stroke-dashoffset
  • stroke-width
  • stroke
  • rx
• transition-colors animates only stroke

Example:

<div class="dashed-border rounded-lg transition-all dashed-border-color-slate-400 hover:dashed-border-color-slate-900">

Expected visual model

When used correctly, the utilities should produce:

• A container element that establishes the positioning context.
• A full-size SVG overlay sitting on top of the container.
• A <rect> inset by half the stroke width so the line is not clipped.
• A dashed stroke whose dash length and gap are independently tunable.
• Rounded corners that visually track Tailwind rounded-* utilities.
• Hover, or others transition triggers should be embedded from main tailwind flow. Use their duration and animation function.

Implementation notes

• The plugin flattens nested color objects from theme.colors into dash-separated utility suffixes.
• DEFAULT keys are handled specially so default theme values map cleanly to rounded and other default-style selectors.
• Radius is adjusted by subtracting half the stroke width, which keeps the visible curve aligned with the outer element radius.
• The plugin is built around Tailwind CSS v4 plugin APIs: addBase, addUtilities, and matchUtilities.