policy:
  allow_implicit_invocation: true

# Tailwind Engineering Preferences

> Fallbacks only: local design-system and component conventions win.

## Choices that prevent churn

- Use this ladder: utility composition; local component/template extraction; `@theme` token for a shared product value;
  `@utility` for a repeated low-level behavior; scoped CSS for a stable primitive or markup the app does not control. Do
  not abstract a genuine one-off.
- Use `gap` for flex/grid spacing, `size-*` for equal dimensions, and `min-h-dvh` for full-height mobile layouts. Prefer
  top/left margins, parent padding for trailing space, and the container/spacing scales before arbitrary pixels.
- Prefer `text-{size}/{line-height}` to a separate `leading-*` utility. Use theme color and sizing scales before
  arbitrary values; promote recurring values to tokens.
- Use `cn` for reusable class constants, conditional classes, caller overrides, and conflict resolution; keep static
  `className` strings direct. Size images with utilities and define stacking levels as `@theme` tokens rather than
  arbitrary `z-[…]` values.
- Put light styles first and append `dark:` overrides.

## Markup outside application control

Scope CMS, rich-text, and third-party output under a dedicated wrapper or the local typography integration. Target its
final DOM, including nested, focus, hover, and motion states. Use `@apply` only as a narrow adapter in such custom or
transformed markup; ordinary component styling remains utility composition.

# ESLint Integration

When the project already uses `eslint-plugin-better-tailwindcss`, preserve its installed rule set and run its local
command after class changes. Treat conflicting or unknown classes as correctness failures; follow local canonical or
shorthand ordering rules rather than adding the plugin merely to format utilities. Consult the package documentation for
version-specific rules.

# Tailwind CSS v4 Rules

> Read for v4 configuration, migration, source detection, or CSS directives. The installed packages, integration,
> browser matrix, CSS entrypoint, and local `@theme` declarations are authoritative.

## Configuration and migration

Keep the existing Vite, PostCSS, CLI, or other documented adapter. For an explicit migration, check the browser matrix
first: v4 relies on modern CSS and may require remaining on v3. Use the official upgrade tool when applicable, inspect
its diff, and verify the build and rendered UI. Do not copy v3 directives, utility rename lists, or JavaScript config
assumptions into v4 without checking the [upgrade guide](https://tailwindcss.com/docs/upgrade-guide).

In v4, use `@import "tailwindcss"`; use `@theme` only for values that should create utilities or variants, and ordinary
CSS variables otherwise. Preserve `@reference` in CSS modules or separately processed component styles when they need
main-sheet theme values, custom utilities, variants, `@apply`, or `@variant`. Prefer scoped CSS or variables there;
follow [coding preferences](coding-preferences.md#markup-outside-application-control) for the narrow `@apply` case.

## Source detection

Tailwind scans plain text. Map state or props to complete class strings; interpolation such as `bg-${color}-600` is not
discoverable. Register ignored/external paths with `@source`, set an unambiguous monorepo base with import `source()`,
and use `@source inline()` only when no scanned static mapping can express a required utility.

## Current documentation

- [Upgrade guide](https://tailwindcss.com/docs/upgrade-guide)
- [Compatibility](https://tailwindcss.com/docs/compatibility)
- [Functions and directives](https://tailwindcss.com/docs/functions-and-directives)
- [Detecting classes](https://tailwindcss.com/docs/detecting-classes-in-source-files)

# tailwind-variants

Use only if `tailwind-variants` is already installed or requested. Keep every emitted Tailwind class static and match
the installed package version.

- Use a normal `tv` recipe for one element and `slots` for multipart components; slot variants return per-slot classes.
- Use `compoundVariants` or `compoundSlots` only for state combinations that cannot be expressed by one variant axis.
- Compose related recipes with `extend` instead of duplicating bases, slots, variants, or defaults.
- Keep one-off configuration local. `createTV` is for an intentionally shared configuration; mutating `defaultConfig`
  changes every recipe in the process. Extend merge groups only for local custom tokens and prefer `extend`/`override`
  over replacing configuration.
- The lite entrypoint does not provide merge resolution. Do not select it when callers depend on conflict resolution.

Consult the [API](https://www.tailwind-variants.org/docs/api-reference),
[slots](https://www.tailwind-variants.org/docs/slots), [extending](https://www.tailwind-variants.org/docs/extending),
and [configuration](https://www.tailwind-variants.org/docs/configuration) for the installed version.

# tw-animate-css

Use only when the project already imports `tw-animate-css` or the request adds it. Preserve its CSS entrypoint import
and pair `animate-in` or `animate-out` with the selected parameter utilities; verify the changed motion, reduced-motion
behavior, and end state in the rendered UI. Check the installed version's
[upstream documentation](https://github.com/Wombosvideo/tw-animate-css), especially before relying on slide-value or
duration syntax: its release line is changing and `duration-*` is documented as deprecated upstream.