Refined UI

An opinionated, customizable superset of shadcn/ui

AgentsPrimitivesSkillsSkins
Guides
  • Overview
  • Get started
  • Shadcn compatibility
  • Architecture
  • Agent surface
CSS-first
  • CSS-first interactivity
  • CSS-first motion & sizing
React code quality
  • Derive, do not duplicate
  • Remount state boundaries
  • One responsibility per file
  • Real stack tests
UI / Tailwind
  • Use existing components first
  • Token discipline
  • Class Name boundaries
  • Tailwind v4 CSS configuration
  • Tailwind v4 migration syntax
  • Generated utilities before arbitrary values
  • Variant-first styling
  • Tailwind v4 capabilities
  • Tailwind v4 behavior & motion
UX
  • State continuity
  • Provenance without noise
  • Dense but scannable
  • Say it once
Refined UI registry
  • Skin authoring
  • Extension authoring
  • Registry-first DX
  • Skin completeness
  • Refined UI composition
  • Runtime-agnostic UI
  • Compound components DX
  • Context vs props
  1. Skills
  3. Tailwind v4 CSS configuration
Skill / UI / Tailwind

Tailwind v4 CSS configuration

Configure Tailwind through CSS directives and tokens instead of adding new JavaScript config.

Goal

Keep Tailwind configuration CSS-first so tokens, utilities, variants, sources, and `@apply` references stay in the stylesheet the build actually reads.

Styling rules for Tailwind v4, token discipline, component reuse, and className boundaries.

Checks

1Check the pinned `tailwindcss` version before relying on a recent utility or directive; at the time this rule was added, the docs app resolved Tailwind 4.3.2.
2Use `@import "tailwindcss"`, `@theme`, `@utility`, `@custom-variant`, `@source`, `@variant`, and `@reference` for new configuration.
3Put utility-generating tokens in `@theme`; use plain CSS variables for runtime-only values that should not generate classes.
4Use `@theme inline` when a token value references another variable so generated utilities resolve at the declaration site.

Avoid

1`@tailwind base/components/utilities`, new `tailwind.config.ts` work, JS plugins, `addVariant`, content arrays, or safelist config for new v4 code.
2The v3 `theme()` function or `resolveConfig` for runtime styling decisions; use CSS variables, `--alpha(...)`, and `--spacing(...)`.

Source

Imported as local Refined UI skill guidance, with this repo owning the final wording.

Mastra tailwind-v4
../mastra/.claude/skills/tailwind-v4

On this page

  • Checks
  • Avoid
  • Source