Repository navigation
Nuxt UI v5 Roadmap #6610
Replies: 47 comments 15 replies
This comment was marked as off-topic.
This comment was marked as off-topic.
This comment was marked as off-topic.
This comment was marked as off-topic.
|
I am not sure how much work this needs but supporting UnoCSS (with the tailwind preset) would be fantastic. Our team is used to it (or rather some of its other presets) instead of tailwind and new projects are currently split between Nuxt UI and another component library for that reason |
|
It would be great if the As for 4. (splitting components) I hope you won't go the way of shadcn/ui where you need to include 5 components just to show a nav menu with some links. I like the approach of using props and objects for that more. It's also more typesafe, since afaik there's no way of restricting the type of a child element/component. |
|
@septatrix you can try my preset that enables Nuxt UI to work with Unocss https://github.com/lehuuphuc/unocss-preset-nuxt-ui |
|
@Blechlawine We won't go the shadcn way of course not, what I meant by splitting components is in some specific cases it would be easier to override if moved to its own component like for example the Header mobile menu (https://github.com/nuxt/ui/blob/v4/src/runtime/components/Header.vue#L178). |
|
@lehuuphuc You can make a PR to add your preset to the Community page if it's working 😊 https://ui.nuxt.com/community |
I don't want to derailt this conversation any further but just a quick question, I assume this will not stop tailwind to run and compile the styles in the background? |
This depends on your project setup. My library is a preset for the unocss config, used alongside the "wind4" preset. It adds the necessary classes for Nuxt UI to function without tailwindcss. |
|
Hi @benjamincanac I think you should also add rethinking components for layout as we discussed here: #4955 Right now |
|
Not sure if this is possible, but it would be nice to have the possibility to add new tailwind classes on the fly during execution. Currently classes not used in the code are not complied so I cannot set such a class unless it is safelisted via |
|
I see two nice to have features for this library:
|
|
Since v3, |
|
How about standalone components, like Shadcn? Why? - Certain components can be customized much more deeply depending on specific needs, customizations that aren’t possible using only props or configuration options. For example, the ColorPicker could have a horizontal hue slider instead of a vertical one, and it could also include an alpha slider. These kinds of changes aren’t possible unless you modify the component at the source level. Yes, the components can already be extracted and used as standalone components with some modifications, by removing Nuxt-specific dependencies tied to the node_modules source level, but... just an idea. |
|
Since Nuxt UI is already planning a major primitives migration (e.g. Reka UI 3), I'm curious if Vuetify 0 was evaluated as well. It is also built around a headless/composable approach, while bringing years of maturity and experience from Vuetify with complex enterprise components. |
|
@alihardan I don't think we'll be switching our primitives, the Reka UI v3 migration will be pretty smooth with some internals optimizations which should not bring too many breaking changes. Switching to something like https://0.vuetifyjs.com/ or https://ark-ui.com/ would break everything and make the transition hell like between v2 (which was based on Headless UI) and v3. |
|
I am adding my view regarding this issue/ discussion about Epic C: #6716 (comment) @benjamincanac I think instead of |
|
Mmmh the issue is https://www.tailwind-variants.org/docs/composing-components#using-the-result |
|
While experimenting with theme editor, I notice one really great slider to have would be a set of abstracted spacing and padding tokens to control how compact or spaced out everything feels. You can adjust --spacing but this is too strong a lever over too many other things, you can try it here in the 'general' menu. Shadcn abstracts it away from the user further with 'styles' in their editor https://ui.shadcn.com/create but uses underlying |
|
I would like a better time picker, the current one is very aligned to 12h formats making it hard to use in other locales (or even non-24h international english) |
|
Other component collapse opportunities: BlogPost, PageCard and Card could all be one component. Perhaps Card should stay separate that the other 2 are based off. |
|
Hello, would that be possible also to have these tanstack charts in nuxt ui ? |
|
@GreyXor That's something we could even ship in v4 🤔 |
|
Would really appreciate the "Maybe richer ui values — { class, attrs } per slot" point It would be very helpful for a11y |
|
I think adding support or having access to internal components for animation libraries like motion.dev would be a great idea. As of right now, we find only one way (my finding might be wrong) to animate them: either CSS (limited) or using wrapper components nuxt-motion-block. The idea is to make a prebuilt animation component like shardcn |
|
Components could be made extractable. Let's take the Pricing Plan component as an example. It currently has the
Currently, the component doesn't provide an option to change the order of its import { tv } from "../utils/tv";
import UBadge from "./Badge.vue";
import UButton from "./Button.vue";
import UIcon from "./Icon.vue";It would be useful to have a built-in mechanism in Nuxt UI that allows to extract components into the |








Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
No firm date yet, this tracks the direction for the next major and I'll keep it updated as things land.
v5 is a theming-led major. The flagship is Design Tokens v2, a redesign of our CSS variable system. It genuinely needs breaking changes (token restructure, default appearance and contrast shifts, scoped re-resolution), so the API renames and restructures we've long parked ride along and you migrate once, with a codemod.
The headless foundation stays Reka UI 2.x: Reka dropped its v3 on 2026-11-13, so the v3 migration (#7382) was undone in #7400. v5 hides Reka from its public API instead, so the next generation can move to ui-sdk without another user migration. The new Drawer primitive that lets us drop
vaul-vueships in Reka UI 2.11.A few things stay the same on purpose. We're not going the shadcn copy-paste route, components stay upgradeable through npm. Semantic color names (
primary,secondary,success,info,warning,error,neutral) and:uislot names remain versioned public API. Numbered shade scales (--ui-color-{c}-{shade},bg-primary-600) stay too, and v5 adds role tokens on top rather than dropping them.Phase 0: non-breaking precursors (ship in v4 now, de-risk v5)
Everything here is additive and unblocks/derisks v5. Independent of the v5 cut.
:uiper-slot replace — shipped v4.9.0 (feat(theme): allow replacing slot classes with a function #6562) as a(defaults) => classesfunction form (closes 🎨 Allow replacing all UI classes with new set of classes? #4953/Cant override styles #6169). Default stays merge (replace-by-default rejected as a footgun); only a docs-wording fix (Unable to remove classes from UI elements with ui-prop overwrites #5803) remains.unstyledmode — shipped v4.9.0 (theme.unstyled, feat(module): addtheme.unstyledoption #6551).componentDetectionin the Vue package — shipped in v4 (feat(vue): supportexperimental.componentDetection#6731, merged alongside perf(vue): skip rewriting unchanged templates #6730; relates Everything gets loaded on a fresh app #6296). Ports the theme-CSS tree-shaking (experimental.componentDetection) to the Vite/Vue unplugin build; it was Nuxt-only, so the Vue build always emitted@source "./ui"and every app shipped CSS for all ~168 theme files. Mechanism differs from Nuxt by necessity: Tailwind widens a file@sourceinside the Vite root to a whole-directory scan (upstream bug, fix submitted as Don't scan sibling files of a concrete@sourceinside an auto source root tailwindlabs/tailwindcss#20406), so narrowing the@sourcelist is a no-op for the Vue layout (node_modules/.nuxt-ui). Instead the plugin runs detection in itsconfighook and writes undetected components' theme files blanked via thetheme.unstyledmachinery (applyUnstyled) — works on every Tailwind 4.x,ui.cssbyte-identical either way,#build/ui/*aliases andcomponents.d.tstypes untouched. starter-vue: 187.53 → 84.15 kB (24.72 → 12.25 kB gzip, after theapplyUnstyledbase-shape fix). Additive (opt-in, off by default; Nuxt output byte-identical, zero snapshot changes). De-risks the Epic E flip to on-by-default across Nuxt + Vue; live HMR re-detection deferred to a restart-only note (→ Epic E follow-up).Epic A: Design Tokens v2 (flagship · breaking)
Full token system, freed from additive-only. Three tiers (primitive → theme → calculated),
-foregroundpairing convention, derive-don't-scatter (color-mixrecipes declared once in@theme inline, not/10//75literals across the theme files).A1: Per-color roles through one accent indirection (fixes #1284, #6588, #3307)
Revised 2026-08-20; mechanics verified against a real Tailwind 4.3.3 build + Chrome computed styles. The previous sketch kept classes keyed on the color name, so every theme still multiplied 6 variants × 7 colors. The fix is one indirection: themes consume a single
--ui-accentrole, and thecolorprop resolves to a scope that points--ui-accentat an alias. Radix Themes ships the same shape (per-componentdata-accent-colorre-pointing--accent-*vars); we keep our orthogonalcolor×variantAPI and shade scale on top.Validated against the code 2026-09-23. The generated themes carry 667 color-keyed compound entries (of 1097, in 52 of 117 themes). The 576 chromatic ones collapse to 94 by substituting the color name, with zero exceptions, and that holds for every key combination, not just
color × variant(405):color × highlight,active × color,color × to,color × selectedcollapse the same way. Every color-derived class usesbg/text/ring/outline/borderplus an opacity modifier, so a single--color-accentbridge covers all of them. Three parts of the 2026-08-20 sketch were wrong and are corrected below: the.accent-*scope class names, recipes living on scope classes, and the claim that A1 subsumes A5/#5657.--ui-accentand removetheme.colors#7024, merged, was the bottom of the Epic A/E stack #7069 (refactor(theme)!: resolve colors through--ui-accentand removetheme.colors#7024 → refactor(Theme)!: movetheme.defaultVariantsto the app config and<UTheme :props>#7028 → refactor(Theme)!: movetheme.unstyledto the app config and<UTheme unstyled>#7030 → refactor(theme)!: remove the*Sizeslots #7031 → refactor(theme)!: prefix classes at runtime #7035 → refactor(theme): spell out every theme class #7036 → refactor(theme): move themes to the runtime and type their sources #7040 → refactor(module): ship static themes #7037 → refactor(module): ship the static CSS #7043 → refactor(theme)!: read the app config through the theme context #7044 → feat(Theme): addvariantsandiconsprops #7046 → refactor(theme)!: stack the app config and each<UTheme>as override levels #7050 → refactor(module)!: movetheme.prefixtotailwindPrefix#7052 → refactor(theme)!: move the colors from the app config to the@nuxt/ui/colorsplugin #7053 → feat(module)!: detect the components in use by default #7058 → feat(vite): detect newly used components while the dev server runs #7059 → docs(theme): rework pages #7067 → refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070 → docs: use the renamed semantic tokens #7071; feat(useTheme): new composable to change the colors and radius at runtime #7060 closed). PR numbers are canonical. The color set is closed (decided while reworking refactor(theme)!: resolve colors through--ui-accentand removetheme.colors#7024):primary,secondary,success,info,warning,error,neutral.theme.colorsis removed; the scopes are literal strings insrc/runtime/theme/color.ts(colorVariant,highlightColorVariant,spotlightColorVariant,colors), so Tailwind finds every class by scanning: no safelist, no runtime interpolation, no class built from a color name, class merging intact.'*'/{value}andexpandColorVariants/resolveColorsare gone; compounds that still match colors list them (colors.filter(c => c !== 'neutral')). A custom alias is CSS (--ui-tertiary+ a@theme inlinebridge) applied through[--ui-accent:var(--ui-tertiary)], not through thecolorprop. Rejected on the way: an opencolorvariant with runtime interpolation (needs a safelist once themes are static, the v2 mistake), named@utility ui-color-*scopes (break tailwind-merge), adata-colorattribute keyed on(active && activeColor) || color || default. No theme file reads module options any more, so every theme is a plain object (step 4 below is unblocked). Tokens read--ui-accent-<role>with the recipe as fallback; neutral's roles set by one rule, static inaccent.csssince refactor(module): ship the static CSS #7043, so neutral was pixel-identical in refactor(theme)!: resolve colors through--ui-accentand removetheme.colors#7024; Callout, Code, Calendar, ChatMessage keep explicitneutralentries.--ui-neutralis shade 900 in light and 50 in dark since refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070 (base.css). Verified after the closed set: class differential (163 themes, 3,155,457 slot calls, strict for neutral, 0 diffs) and Chrome computed styles (166 pages, 165,820 elements, 0 diffs). One rule per color points--ui-accent-<role>at--ui-<color>-<role>(unset = recipe, neutral = surface token as fallback;--ui-warning-foregroundis the<UBadge variant="subtle">does not pass lighthouse accessibility audit #1284 lever), and the scopes sit on the component root soclass="[--ui-accent:…]"recolors the whole component (inner scopes only for per-item colors, second colors, Timeline's Avatar indicator and NavigationMenu links in portals). Customcolorvalues (decided 2026-09-25): addingvariants.color.tertiary: { <root slot>: '[--ui-accent:var(--ui-tertiary)]' }per component in app.config works at runtime and the prop type picks it up, butnuxt typecheckerrors inside the components becausetv(theme, appConfig.ui?.x)(props)types its call props from the theme only. Fixed in refactor(Theme)!: movetheme.unstyledto the app config and<UTheme unstyled>#7030, which types the overrides from the app's own config and documents the recipe (app.config / vite.config is the place). Stack review decisions (2026-09-26): (14) the color × variant classes stay invariants, the precedence change againstapp.config.uiis documented in the migration guide; (15)tvtakes the override levels in order, nearest wins across layers,<UTheme>gets real slot overrides (refactor(theme)!: stack the app config and each<UTheme>as override levels #7050); (16)<UTheme unstyled>keeps the[--ui-accent:…]scope classes, socolorstill works under unstyled; (17) internal, tagged@internaland kept out of the docs:useThemeConfig,useRootThemeContext, the context inject/provide,engineFor,ComponentOverrides,defineTheme/extendTheme,applyPrefix,applyUnstyled, the size helpers; public:@nuxt/ui/tailwind(named@nuxt/ui/sourcesuntil refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070) /@nuxt/ui/base, the<UTheme>props,ui.defaultVariants/ui.unstyled/'*',useComponentOverrides. Stack scope (decided 2026-09-27): the stack ended after E + A6 (layer order,tailwindPrefix, A6,componentDetectionon by default). Vue without the emulated app config was dropped: every option removed fromnuxt.configis already gone fromvite.config(NuxtUIOptionsextendsModuleOptions), and Vue'suikey is the counterpart ofapp.config.ui, which stays (Nuxt layers merge it), with identical types. A7 and H got their own stack. Not delivered by the stack: the[data-theme]blocks (selector deferred), A5 (base.cssstill pins--ui-<alias>to a shade), Custom--ui-*CSS variable overrides in@layer baseare silently reverted by@layer themeafter view transitions / color-mode re-application #6172 unconfirmed.useComponentPropsstays public (exported, used for custom components). Design challenge 2026-09-28: the color scope rules are class selectors (.\[--ui-accent\:var\(--ui-primary\)\], prefixed copies in#build/ui.base.css), the:where([class*="[--ui-accent:"])reset stays; style recalc for 5000 scoped buttons 77 → 61 ms initial, 124.8 → 118.3 ms toggle, plain elements 45.8 → 35.8 ms. The roles were cut from 10 to 7 at that point, and got their final names and list in refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070 (see A6). The stylesheets and the@nuxt/ui/colorsplugin moved tosrc/runtime/css/(refactor(module): ship the static CSS #7043, refactor(theme)!: move the colors from the app config to the@nuxt/ui/colorsplugin #7053), public paths unchanged..accent-*classes.accent-primaryis already a Tailwind utility (accent-color): tailwind-merge drops it against a useraccent-red-500, andapplyPrefixToObjectrewrites it totw:accent-primary, which no longer matches a hand-written rule. Thecolorvariant carries[--ui-accent:var(--ui-primary)]instead, the shapepage-card.tsalready uses for[--spotlight-color:var(--ui-{c})]. Tailwind prefixes it, and tailwind-merge groups it by property so a user's[--ui-accent:x]inclassor:uiwins (verified). The scope goes on the same slot that carries the accent classes, so nothing relies on inheritance and teleported content is not a concern (no color-keyed slot is teleported today; DropdownMenu/ContextMenu passitem.colorper slot call).--ui-accentand removetheme.colors#7024 with the v4 values so chromatic output stayed identical; the roles got their final names in refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070. Neutral is an ordinary alias (decided 2026-09-24, replacesblackAsPrimary):--ui-neutralin both the light and dark blocks and the same variant classes as every other color, its roles pointed at the neutral tokens by one rule inaccent.css. The set is closed to the seven aliases,colorVariant()writes one literal[--ui-accent:var(--ui-<color>)]class per color, and a custom color is a CSS var plus acolorvariant entry inapp.config.ui(typed in Nuxt, runtime-only in Vue). The Button pilot verified the mechanics with a class differential over 580k slot calls, Chrome computed styles and 46k snapshot class attributes.<UBadge variant="subtle">does not pass lighthouse accessibility audit #1284, PR feat(theme): let one variable set the text of a color everywhere #7206 (merged 2026-10-16, replaces the closed fix(theme)!: readable colored text in light mode #7100). Opt-in, defaults unchanged.--ui-<color>-text-default/-text-mutedare unset by default;text-<color>andtext-accentread the color's text before the solid through Tailwind's--text-color-*namespace (baretext-accent=text-accent-strong=--ui-accent-text-strong,text-strongfor neutral), so one variable reaches every colored text with no theme file change. Docs recipe for 3:1:color-mix(in oklab, var(--ui-<color>) 70%, var(--ui-color-<color>-950)), muted 80%, unset in.dark; AA = shade700. Link underlines useborder-current. Only default change: dark neutral active items 50 -> white. Tried as defaults and dropped (the docs looked worse): 600/700 shades, alias-relative 30% mix, all aliases on 600. Rejected: fix(theme)!: readable colored text in light mode #7100's halfway mix + rings, a mix toward the foreground, palette swaps. Follow-up: a control for the text in the theme editor.primarysky,secondaryviolet,successemerald,infoblue,warningamber,errorred,neutralgray, so nothing doubles up.primarystays chromatic (open question 8 closed). The semantic tokens keep their v4 shades: a darker light text ladder, a 950 neutral solid and a 950 dark page were all tried and dropped 2026-10-02. Parked for A2: derivebg-soft/bg-strong/border-defaultfrom--ui-bg-defaultas opaque mixes toward--ui-border-strong(950→700 at 33% / 61%, white→300 at 26% / 56%, within ΔE 0.5 of the shades), so re-scoping one token moves the ladder. Fills and borders stay solid shades: translucent mixes modeled on tailwindcss.com were tried and dropped (chroma loss in dark, opacity caveat). PR feat(theme)!: new default colors #7088. A2 follows and its ladders need rebasing on these values.@theme inline, not on scope classes. Tailwind copies an inline theme value into each utility, so--color-accent-hover: color-mix(in oklab, var(--ui-accent) 90%, …)compiles to.bg-accent-hover { background-color: color-mix(… var(--ui-accent) …) }and computes on the element (verified in a 4.3.3 build). That avoids the:rootfreezing problem the scope-class recipe was designed around. Where a color needs a value the recipe can't compute (neutral's solid surfaces, warning's dark foreground), the recipe reads an overridable hook,--color-accent-soft: var(--ui-accent-soft, color-mix(…)), and that color'scolorvariant sets the hook next to--ui-accent. Custom properties inherit into nested scopes, so every scope sets the hooks it uses, chromatic ones toinitial, or a chromatic component inside a neutral one would pick up neutral's values.@theme inline(src/runtime/css/tokens.css):--color-accent: var(--ui-accent)is all the chromatic collapse needs. Opacity modifiers (bg-accent/10) compile to the samecolor-mixasbg-primary/10, and tailwind-merge groupsbg-accentwithbg-elevated(both verified). Derived names (-foreground,-soft, …) only arrive with the neutral fold. The name staysaccent(decided 2026-09-23): an app defining its own--color-accentwould override ours under@theme default inline, which is rare enough in Nuxt UI apps to be a migration-guide note rather than a naming constraint.--ui-accentand removetheme.colors#7024 (decision of 2026-09-26): the color × variant classes live invariantsthroughcolorVariant(), with no color compounds left, and the migration guide (Accent color) documents the precedence change againstapp.config.ui. Where one color meets an element it is plainaccent(TableloadingColor, ContentTochighlightColor, ButtonactiveColor, PageCardhighlightColor), and a second color on one element gets its own scope variable.--ui-accentand removetheme.colors#7024 instead of a separate PR, with the planned oracle: a class differential over every variant combination, Chrome computed styles and the snapshot substitution. The visual retune planned after it is split: the accent recipes shipped in refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070, colored text contrast is fix(theme)!: readable colored text in light mode #7100 above (it replaces thesoft-foregroundmix proposed 2026-09-24, which was never added), and SelectMenu/Select: highlighted option fails WCAG 1.4.11 — ~1:1 contrast between highlight and menu background #6588 / Better handling ofUButton,UBadge, … colors on colored backgrounds #3307 are below.neutralinto the accent shape. Done in refactor(theme)!: resolve colors through--ui-accentand removetheme.colors#7024 and refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070. Neutral is an ordinary alias whose roles point at the neutral tokens, socolor="neutral"shares the variant classes of every other color and the bespoke neutral class sets are gone from the themes (59 of the 91 neutral compound entries were already the chromatic template, measured 2026-09-23). This is what unlocks neutral-as-primary (feat(module): supportprimary: 'neutral'in app config #6608, closed), which was not doable in v4: chromatic variants are opacity blends of one color while the neutral variant used distinct solid surface tokens, so a pure--ui-primaryswap only matchedsolid. The neutral tier utilities stay public API under the refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070 names.--ui-accentand removetheme.colors#7024: thecolorprop type is the seven aliases, so this waits on "The color set" beta blocker) —color="indigo"/color="#5865F2": inline style on the root sets--ui-accent, dark shade flip vialight-dark()(body already setsscheme-light dark:scheme-dark). Tailwind's theme-var pruning can't break it: inline the fallback fromtailwindcss/colorsthe way the default palettes do inbase.css(the oklch table would ship as a runtime util used only for raw values) (var(--color-indigo-500, oklch(58.5% 0.233 277.117))— verified identical to the 4.3.3 emitted palette). Aliases keep the class path (no inline styles → CSP-clean, zero SSR payload change); raw values are the documented escape hatch (needsstyle-src-attr 'unsafe-inline'under strict CSP) and docs keep steering to aliases —color="red"scattered in an app kills global retargeting.--ui-warning-text-contrastto a dark value (yellow needs dark text). The role exists since refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070 and the warning scope already reads it (accent.css), so this is one default, unless auto contrast removes the need. The draft fix(theme)!: readable colored text in light mode #7100 keeps solids at 500 with white on purpose, so settle it there. Open question 2: explicit token vs autooklch(from var(--ui-accent) …)luminance contrast.before:bg-tint(before:bg-elevated/50in v4, ≈1.03:1, also the kbd focus indicator) in the 11 themes that use it (listbox/select/input-menu/command-palette/dropdown-menu/context-menu/navigation-menu + editor/content/prose themes). Open question 3: accent fill (bg-accent+text-accent-contrast, native-select pattern) vs neutral + persistent non-color cue. (Neutral fill alone can't hit 3:1 / SC 1.4.11.)UButton,UBadge, … colors on colored backgrounds #3307 on-colored-surface — a solid colored surface (Banner/PageCTA) re-scopes--ui-text-default/--ui-text-mutedto the color's contrast text for its subtree (Material "on-primary"); removes the need for areversecolor. Same mechanism as the accent scope (adata/class hook re-pointing text tokens).A2: Surface / Overlay / Elevation
The ladders below use the v4 token names and shades. They need rebasing on the #7070 names (
default,tint,soft,strong) and the #7088 values before any of this starts.--ui-bg*ramp into a re-scopable one keyed by[data-elevation="N"]. Level 0 == today (byte-identical). Generate scopes (don't hand-write) into the static package CSS at publish time (no per-appui.cssany more, see Epic E); ladders are neutral-index offsets:bg white→50→100→200,muted 50→100→200→300,elevated 100→200→300→400,accented 200→300→400→500bg 900→800→700→600,muted 800→700→600→500,elevated 800→700→600→500,accented 700→600→500→400color-mixadditive variant kept as documented opt-in.bg-overlay, opt-in, not a default change (decided 2026-10-21, merged 2026-10-21 as 02b536e). feat(components): add an opt-in surface for floating layers #7252. The floating layers (DropdownMenu, ContextMenu, Popover, Tooltip, Select, InputMenu, NavigationMenu viewport and arrow, EditorSuggestionMenu, EditorToolbar bubble / floating, Modal, Slideover, Drawer, Toast, Chart tooltip) paintbg-overlay, which isbg-defaultwhile--ui-bg-overlayis unset: pixel-identical to before. A lighter surface alone breaks, since dark one step up (800) equalsbg-soft/border-defaultand rings, separators and highlighted items vanish. So once--ui-bg-overlayis set,bg-overlaysets--ui-layer-bg-default/-bg-soft/-bg-strong/-border-default/-border-strong, whichtokens.cssand the neutral accent roles read before the page tokens: soft = page strong, border-default = page border-strong, the two strong ones mixed 10% toward--ui-text-strong, each overridable through--ui-overlay-*. A step mixes--ui-bg-overlayat 0% as the first color, so it is unset with it (Tailwind's no-color-mixfallback keeps the first color, so that stays gated too).base.cssalso gates--ui-bg-backdroptobg-defaultat 75% (900 at 75% in dark holds the Modal edge, rendered). So the picked look (d-1-scrim, light unchanged) is one line,.dark { --ui-bg-overlay: var(--ui-color-neutral-800) }, and the theme studio has an Overlay shade (follows: '--ui-bg-default'). Cost: +0.3 kB gzip CSS for every app (point-of-use wrappers). Tried and dropped the same day: re-pointing the page tokens on the layer from--ui-overlay-*declared inbase.css(+0.18 kB, not zero as first claimed), becauseclass="dark bg-overlay"(a forced-dark Modal) forms a same-element cycle and turns transparent even unset (confirmed in Chrome); separate page input tokens would drop user--ui-bg-*overrides. Rejected: changing the default (5.0-or-v6), avariant="subtle"as the switch (turns light menus gray, Card'ssubtleis the see-throughbg-tint, 12defaultVariantsentries to go app-wide; can come later on the same tokens), full A2 elevation now (see below). Known limits: a gray-palette alias (primary: neutral) still resolves its soft role on:root(A5); an explicit--ui-bg-tintwins inside overlays.--ui-layer-*: the[data-elevation="N"]scope andelevationprop above set the same--ui-layer-*variables asbg-overlay, from level values (stacked layers need a provide/inject depth since menus teleport tobody), no change totokens.cssor the themes. Overlays are level 1,--ui-bg-overlaystays its shortcut. Also the answer to Feature: introduce--ui-bg-bodyto decouple body background from the component surface scale #6516 (white cards on a tinted page, decided 2026-10-21): the page stays on a tintedbg-defaultand cards lift to level 1, no separate--ui-bg-bodytoken, abody { background-color }override covers it until then. Not for 5.0: built-in ladders would change the default, and P3 (design challenge) still holds on cost vs demand.elevationprop on container components (Card etc.): atvvariant{0,1,2,3}writing:data-elevation. Likely a shared composable/mixin so every surface component gets it. Escape hatch:data-elevation="1"on any element.ssr()modifier chain fromsrc/runtime/theme/tabs.tsverbatim (in-[[data-slot=tabs-list]:not(:has([data-slot=tabs-indicator]))]:data-[state=active]:before:shadow-none); a barebefore:shadow-nonewon't tailwind-merge against it. Any consumer restyling Tabs hits this. The shadow should ride a token, or the modifier should be reachable.compoundVariantsitself stays).--ui-border-width/--ui-ring-offset(A4) should make width a token instead.A3: Motion tokens
prefers-reduced-motion#6742): standardized on Tailwind’s--ease-*namespace instead of adding a--ui-ease-*layer. Every enter/exit animation and movement transition runs onvar(--ease-out), indeterminate loading on--ease-in-out, so overriding those two in@themeretimes the whole library. Values stay Tailwind’s defaults; the win was killing theease-in-on-exit bug across every overlay plus the one-off curves and durations. Reduced motion handled by redefining the scale/slide presence keyframes to opacity-only underprefers-reduced-motion(src/runtime/css/keyframes.css). Documented under Motion on the Design System page. (No--ui-ease-fluidin the end: Slideover slides on--ease-outlike everything else.)--ui-skeleton-animationtoggle, tooltip delay tokens. Additive, so v4-able, and it should follow the easing shape above: declare--animate-*in@themesoanimate-skeletonis a real utility, and keep the--ui-prefix only for component-level toggles (same shape as--ui-header-height). Design Tokens v2 then has nothing to rename.A4: Structural tokens + primitives + vibrant
--ui-disabled-opacity,--ui-focus-widthand--ui-gutter(decided 2026-10-23): feat(components)!: add gutter, focus width and disabled opacity variables #7280 (merged 2026-10-26). Stacked on it, refactor(theme)!: name sizing variables by subject and property #7283 (merged 2026-10-26) renames--ui-container→--ui-container-widthand--ui-control-icon→--ui-control-icon-sizeand writes the naming rule intotheme-structure.md(family of named values: property first; sizing one thing:<subject>-<property>; a quantity: bare). One value each that the themes repeated:opacity-75on the 31 disabled states,outline-3on every focus outline (plus the two-outline-offset-3insets), andp-4 sm:p-6on the Card, Modal and Slideover parts, the Header menu, PageCard, BlogPost, the Prose card and the dashboard panels plus the Container and ContentToc, Container dropping its 2021lg:px-8step (decided 2026-10-23; Empty keeps its own). Breaking for the gutter only: a padding override on those slots now applies at every width, migration section "Gutter". The rest of this item was dropped on 2026-10-23, see Not adopting. Heading/body fonts (the heading font became--font-heading, a body font token dropped 2026-10-22:--font-sansalready is the body font). Headings in feat(components): add heading font and weight variables #7258 (merged 2026-10-22): a non-inline--font-headingtheme variable (set in@themelike--font-sans, loaded by@nuxt/fonts, unset = inherit) and itsfont-headingutility forh1–h6and the title slots, plus an opt-in--ui-font-weight-headingeach title falls back from and--ui-font-weight-bodyonbody; all unset, additive. The backdrop shipped in refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070 asbg-backdrop/--ui-bg-backdrop(unset,bg-softat 75%).--ui-prose-flow/--ui-prose-leading/--ui-prose-size+--ui-prose-scale-ratio, so a context retunes from one wrapper (compact chat vs docs) instead of an ~11-lineprose:uiblock (shadcn-typeset-inspired, on our component model — nonot-typesethatch). v5, not v4: it only pays off with a clean modular scale as the new default. Retrofitting onto today's hand-tuned values gives ugly coefficients (*2.4,*1.6,*0.3) and asizeknob that can only rescale, not reshape (couldn't flatten a chat's heading scale). Reshaping the default scale is a default-appearance shift → breaking. Consumes--font-headingand the weight variables above; a density API (presets / a<Prose>primitive, vs adisplay:contentswrapper trick) rides Prose × Comark (Epic C).A5: Scoped re-resolution (fixes #5657)
--ui-primaryon a wrapper already retintsbg-primarytoday, since the utility readsvar(--ui-primary)at point of use; that is what the 2026-08-20 Chrome test proved. Dynamic/user-provided theme colors are not applied #5657 is one level down:--ui-color-primary-500: var(--color-custom-500)and--ui-primary: var(--ui-color-primary-500)are substituted on:root, so a subtree override of the scale never reaches--ui-primary, and--ui-accent: var(--ui-primary)inherits that frozen value. The fix is the scale→alias flatten. It was meant to land with A6 and did not: colors are CSS since refactor(theme)!: move the colors from the app config to the@nuxt/ui/colorsplugin #7053, butbase.cssstill pins--ui-<alias>to a shade on:root, and the docs keep their own runtime plugin (docs/app/plugins/theme.ts). The route is a beta blocker, see below. Once it lands, document three override levels, broadest to narrowest: alias var on a wrapper,colorprop, element-level[--ui-accent:x].--ui-<alias>, and the surface tokens when it changesneutral; design-system "Change colors at runtime"). Preferred fix: add a hook selector, e.g.[data-ui-theme], to thebase.cssrules that declare the aliases and tokens (light, and dark under.dark) and to the plugin's shade rules, so an element carrying it re-resolves them from its own shades; ~20 lines of CSS, no runtime cost, works for runtime themes, not prototyped. Rejected: redeclaring the aliases on every element (style recalc cost, and it overwrites a--ui-primary: #hexset on a wrapper). Theselectoroption on@nuxt/ui/colorscan come on top for build-time blocks (A6 multi-theme). Only 5.0 work left: document the order between an unlayered runtime rule and layered blocks. Dynamic/user-provided theme colors are not applied #5657 has 2 users, 0 reactions.A6: Theming surface
[data-theme]var blocks + theme generator + documented stable token contract +llms.txt. Contract done 2026-11-03: "Use your design system" page +nuxt-ui-design-systemskill (feat(theme): add a design system skill and exportcolorVariant#7334) and the control scale tokens (feat(theme): add a shared control scale #7340); the role names are public API from 5.0. Left: the[data-theme]generator andllms.txt. Switching is already doable by hand today at the alias layer (redeclare--ui-primary,--ui-bg-default, … under[data-theme='x']and toggle the attribute, documented in docs(theme): rework pages #7067); scale-var overrides need A5, and the v5 item is generating the blocks from the CSS color config (@pluginoptions or user CSS, A6).colors.tsruntime plugin (decided 2026-09-23). Aliases stay as names (component defaults, semantic branching like Form'scolor="error",bg-primary-600ramps, global retargeting), but the mapping lives in the user's CSS instead ofapp.config.ui.colors+ a reactively generated,useHead-injected<style>. That kills the SPA hydration dance, the docs FOUC scripts (A5,docs/app/plugins/theme.tsregex-patches the injected HTML today), and shippingtailwindcss/colorsto the client (the oklch fallback table stays only for the raw-palette escape hatch). Same shape as the CSS-first libraries: two@imports, no provider, colors as vars on:root/[data-theme], a custom color is a var plus a@theme inlineline. The one DX loss is the shade scale:primary: 'indigo'is one line today, 11--ui-color-primary-*lines in plain CSS. Prototype Tailwind plugin options first (daisyUI v5 does this),@plugin "@nuxt/ui" { primary: indigo; neutral: zinc; }, emitting the shade scale at Tailwind compile time (the accent scopes already ship static inaccent.css, refactor(module): ship the static CSS #7043): one-line retargeting, pure CSS, visible to IntelliSense. The plugin only retargets the seven aliases: the set is closed (refactor(theme)!: resolve colors through--ui-accentand removetheme.colors#7024, see A1 status), so custom aliases are a var plus a@theme inlineline applied through--ui-accent, and thecolorprop type stays the seven names.theme.colorsis already gone with refactor(theme)!: resolve colors through--ui-accentand removetheme.colors#7024, so there is no build-time color option left anywhere. Runtime switching (docs ThemePicker / Epic G playground) becomes writing vars on:rootor toggling[data-theme], the flat-blocks direction above. Likely fixes Custom--ui-*CSS variable overrides in@layer baseare silently reverted by@layer themeafter view transitions / color-mode re-application #6172 (--ui-*overrides in@layer basereverted after view transitions):basebeatsthemein Tailwind's order, so the override only loses when a runtime-inserted stylesheet shifts the layer order, and the prime suspect is thecolors.ts<style>that unhead re-renders; confirm with a repro before linking. The docs say where overrides go (unlayered or@layer base). Breaking:app.config.ui.colorsandupdateAppConfigcolor switching are documented workflows today; needs its own migration note (Epic F), codemodable since the values are static. Status: refactor(theme)!: move the colors from the app config to the@nuxt/ui/colorsplugin #7053 (merged 2026-10-01). Plugin name decided 2026-09-27:@nuxt/ui/colors(@plugin "@nuxt/ui"resolves to the Nuxt module). Options pass through,theme()resolves palette values at compile time (works withprefix(tw)and@themeoverrides), output in@layer base. The default palettes are plain CSS inbase.css(var(--color-<palette>-<shade>, <oklch>), test-synced withtailwindcss/colors) and not a no-options plugin registration, because nuxt-og-image's Tailwind loader only resolves.js/.mjs/.cjsplugins and the OG templates lost their CSS transform. Cost: a prefixed app that also overrides a default palette in@themegets Tailwind's value. The plugin only retargets. Bundle: JS −3.8 kB gzip (Nuxt), −4.1 kB (Vue); CSS +1.7 kB gzip vs base. Docs keep runtime switching on their side (appConfig.colors+ docs plugin in@layer base), studio export emits the@pluginblock. Custom--ui-*CSS variable overrides in@layer baseare silently reverted by@layer themeafter view transitions / color-mode re-application #6172 still unconfirmed, not linked. Layer order (found 2026-09-28): Nuxt UI sets@nuxt/iconcssLayer: 'base', and its runtime icon styles land before the app stylesheet, sobaseis declared first and sits belowtheme. The default palettes (refactor(theme)!: move the colors from the app config to the@nuxt/ui/colorsplugin #7053) and the semantic tokens (refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070) therefore live in@layer basebehind:where(), so a user override inbasewins. Their v4 place in@layer theme, above a user override inbase, is the likely Custom--ui-*CSS variable overrides in@layer baseare silently reverted by@layer themeafter view transitions / color-mode re-application #6172 mechanism.Dropped 2026-09-28 (design challenge), feat(useTheme): new composable to change the colors and radius at runtime #7060 closed. RenameduseThemecomposable for runtime colorsuseThemeTokensfirst (useThemecollides with app code), then dropped: over a docs recipe it only adds value sanitizing and the palette/single-color rule split, it would fix a public API before the A5 route is decided (a[data-theme]swap covers per-tenant themes without JS), and its natural usage shipstailwindcss/colors(2.8 kB gzip, can't be tree-shaken) back to the client. Replaced by "Change colors at runtime" in the design-system docs (refactor(theme)!: move the colors from the app config to the@nuxt/ui/colorsplugin #7053): palettes on:root, :hostonly so subtree shades survive, a single color also on.light, .dark, a picker importing only the palettes it offers, a warning to validate values that land in a<style>. Revisit a composable with A5, for the Feature Request: Utility to Dynamically Override Nuxt UI v3 CSS Variables in<head>#3914 multi-tenant case. Theselectoroption on@nuxt/ui/colors(build-time[data-theme]blocks) is deferred, non-breaking to add later. The docs' own composable was renameduseThemePicker.--ui-accentand removetheme.colors#7024 → refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070 is onv5). One vocabulary shared by the neutral tokens and the accent roles:text-strong/default/muted/faint/contrast,bg-default/tint/backdrop/soft/strong/neutral(+-hover),border-default/strong/neutral,outline-focus. Accent roles mirror them withaccent-: bghover75% /tint5% /soft10% /strong15%, textdefault/muted75%/faint50%/contrast, borderdefault25% /strong40% (nosoft),outline-accent-focus. One recipe per variant on every component: soft =bg-accent-soft, subtle = soft +ring-accent-strong, outline =bg-default+ring-accent-strong;defaultborder for lines and prose. Nocolor: 'neutral'branch in any theme. Variables are--ui-<property>-<level>, tokens in@layer basebehind:where().@nuxt/ui/sourcesrenamed@nuxt/ui/tailwind.'*'/ui.defaultVariantsskip a value a component lacks. Studio: Solid + border sliders, global color, size/color exported asui.defaultVariants. Full tables in the PR description and the migration guide.faint/muted/default/strong, bgtint/soft/strong, borderdefault/strong) shared by the neutral tokens and the accent roles. Raised by @Blechlawine: the v4 names describe intensity, not use, and are hard to tell apart.A7: Size geometry through variables
A1 kills the color multiplication, this kills the geometry one. Most of our
compoundVariantsonly exist to carry a size: one entry persizeto say how much room an icon takes, how thick a track is, how big a cell is. They are also the hardest part of a theme to override from an app config.A size writes variables, plain classes read them.
--ui-control-px,--ui-control-py,--ui-control-gapand--ui-control-iconon buttons, badges, fields and NavigationMenu links, so restyling a size is one line and the room for an icon follows.--ui-control-thicknessfor the track of Slider, Progress and ProgressGroup and the line of Separator, read as a height or a width byorientation.--ui-control-sizefor the cells of Calendar, the trigger of Stepper and the indicator of Timeline. Only where a size was multiplied by another variant, the other themes keep their classes. Opt-in: a plainpx-4on a field still replaces its whole padding, the room for an icon included. refactor(theme)!: size controls through tokens #7116, merged 2026-10-09.squarereads the vertical padding of the size on Button and Badge, and NavigationMenu gains the prop, so a sidebar that collapses no longer hardcodes a padding on its links. Not on the fields: a select always has a trailing icon, so it was never square (refactor(theme)!: size controls through tokens #7116).Compounds that match on one key become variants (refactor(theme)!: size controls through tokens #7116). They were variants written the long way: the focus ring per
varianton the fields,directionon Drawer,positionon Toaster. No change for apps, themes read top to bottom again.Responsive sizes through a utility per size (Buttons size based on device? #2390), after the variables land. Noted 2026-10-08, not prototyped. A size is a set of variables on the element, so one
@utilityper size that writes them gives<UButton class="control-sm lg:control-lg">, with any Tailwind variant, container queries included. No engine or prop change, and additive, so it does not have to make the v5 cut. Needs the font size of a size as a variable first, otherwise the padding and icon grow and the text stays. Open: child components that receivesizeas a prop, like an Avatar in a Button, do not follow. Only covers the components converted to the variables.compoundVariantsstays. The earlier goal of removing it from the engine is dropped: it would have broken a concept apps rely on for an internal gain. The ones that go are the ones a variable replaces. Rules that need two conditions, or that set different properties per side, like the sides of a Slideover, stay as compounds.Remaining compounds, audit 2026-10-14 (parked, not planned). After the fields stack (feat(components)!: hold the leading and trailing in the flow of the box #7192 → feat(components)!: remove the
fixedprop and the larger text of fields on mobile #7201) there are 151 compounds in 29 themes, down from 198 in 38. Three kinds: direction pairs (~75:side×inseton Slideover (Drawer's went with feat(Drawer)!: replacevaul-vuewithreka-uiprimitives #6691),animation×orientationon Progress, Separator, Sidebar, Chip, Marquee, Tabs, Stepper), state pairs (~45:active/disabled/highlight/indicator×varianton NavigationMenu, RadioGroup, Checkbox, CheckboxGroup, Link, Breadcrumb, Tree, InputRating) and link hover (15:to×varianton BlogPost and PageCard). Verdict: most are real two-dimensional rules, removing them swaps a readable compound for a longer selector, and they are not what apps override. Onlyvariant×disabled→cursor-not-allowedon Checkbox, RadioGroup and CheckboxGroup simplifies (has-disabled:cursor-not-allowedin the variant). NavigationMenu's 17 go with the NavigationMenu / NavigationAccordion split, most of them carryorientation. If picked up: no new data attributes, only the ones Reka sets (data-active,aria-current,data-orientation).No data attributes for what a prop decides. A class behind a data attribute is more specific than a plain one, so a class you pass through
class,uior your app config would silently lose. Data attributes stay for state the DOM owns, likedata-stateanddata-disabled.The override order stays as shipped (refactor(theme)!: stack the app config and each
<UTheme>as override levels #7050): the theme, then your app config and each<UTheme>, thenui, thenclass. What you pass wins, and the variables are the way to restyle a size without losing the room a field makes for an icon.Epic B: Prop & class renames (breaking · codemod-able)
input/searchInput→filter, prop and theme slot (merged 2026-10-15: feat(components)!: configure the filter input through afilterprop and slot #7207). The prop isfilteron CommandPalette, DashboardSearch, ContentSearch and SelectMenu, like DropdownMenu and Listbox (feat(DropdownMenu): addfilterprop #6153; ContextMenu has no filter input). The theme slot follows on all six:input→filter,data-slot<component>-filter; AuthForm keeps itsinputslot. Decided 2026-10-14 to go end to end for consistency: the slot is renamed too, the separate props that configured the input move intofilter(placeholder,icon,trailingIcon,autofocuson CommandPalette, DashboardSearch, ContentSearch;autofocus,autofocusDelayon Listbox;loadingstays) and the filter placeholder locale keys are allfilterPlaceholder(wascommandPalette.placeholderandselectMenu/listbox/dropdownMenu.search; plainplaceholderrejected becauseselectMenu.placeholderreads as the trigger placeholder). Kept as is:filterFields(already uniform), thesearchTermmodel. An old prop falls through as an attribute, so a hidden filter input shows again: no error, migration guide only.valueKey(open PR by onmax: feat(Tree)!: addvalueKeyprop and key items byvalue#6189, added to v5 #6918 on 2026-10-15). Breaking, not reviewed yet in this context.left/right→start/endprop values (table pinning, chat-messageside, footer, page, chipposition, drawerside(wasdirection, feat(Drawer)!: replacevaul-vuewithreka-uiprimitives #6691), slideoverside, toaster position) — the whole RTL story, and the only RTL ask in the thread (alireza-ab, seconded by al1maher);dir, logical theme classes andrtl:mirroring all shipped in v4 already. Breaking twice over: the values rename, and rendering starts following the writing direction (todayside="left"stays visually left underdir=rtl). The ~14 physical classes left insrc/runtime/theme/are those values' implementation, so they flip in the same change; the rest stay physical on purpose (centering pairs, Rekatranslate-xanchors). No blanket physical → logical sweep — tailwind-merge keeps them in separate class groups, so it would silently break consumer overrides rather than being additive.tailwindcsspeer^4.2; OG image templates excluded). Deprecated Tailwind classes → canonical — sweep everythingtailwindcss(suggestCanonicalClasses)flags and hold new code to it. In-group renames still merge cleanly so they're v4-able as bugs surface, but the cross-group pairs carry the same silent-override break as the logical flip (flex-shrink-0≠shrink-0,overflow-ellipsis≠text-ellipsisin tailwind-merge 3.6.0), so the systematic sweep rides v5. Tailwind drops the deprecated names in its next major anyway, so the v5 floor bump is the natural moment.better-tailwindcss/enforce-canonical-classesis on forsrc/runtime/theme/**/*.ts, the docs and the playgrounds ineslint.config.mjsonv5. The theme files are linted since plugin 4.8.0 (1c25c62e3onv4, correctness rules only), the rule sits in the plugin'sstylisticset and is autofixable. Trial on v4: 140 findings in 44 theme files, in three groups: collapses (w-full h-full→size-full), arbitrary to named (z-[1]→z-1,data-[disabled]:→data-disabled:,!w-12→w-12!) and renames (start-0→inset-s-0,break-words→wrap-break-word). Not on v4: the renames raise the minimum Tailwind version and the rest rewrites shipped class strings and snapshots for no behavior change.--ui-control-text-*minus0.125rem, line height minus0.25rem; the tag delete icon reads--ui-control-text-<size>. The literals followed that rule already, so only DropdownMenu and ContextMenu labels change (2px smaller at every size). The first plan (label reads the previous size's token,xskept 10px) was dropped the same day: the scale repeats its text atxs/smandmd/lg, so labels matched their items atsmandlg. Examples that used an avatar label as an account row now put the label at the top of the next group, without the avatar; thenuxt-ui-templates/dashboardUserMenu follows when the templates move to v5.--ui-control-text-<size>--leading(the old line heights); Button icon-side padding cut dropped.md/lg/xlmove 4px from the line height topy(line 16/16/20,py8/10/10), the icon matches the line again so icon-only controls keep their height. Avatars and kbds inside controls one step down, Badgesm20 → 16px, NavigationMenu, InputDate and thesize-5icons next totext-smfollow. Wrapping text keeps a reading line (Checkbox/RadioGroup/Switch labels, Textarea with 2px lesspy). Chosen 2026-11-04 over an icon margin, an icon-only padding offset (:has()) and a min-height (breaksp-0overrides), after comparing a 32px default Button from another library: same spacing, smaller icon, 2px less padding on the icon side.softvariant (defaultvariantinfilterPropswasnone) and is as large as an item:mx-1 mt-1,--ui-control-px=--ui-control-py-<size>, so icon and text line up with the items (also fixes the 2px drift of the palette icon since feat(components)!: match the line of a control to a smaller icon #7361). No border under it, no wrapper element (margin on the Inputroot), no focus outline (has-[>:focus-visible]:outline-0, the field holds focus while the menu is open; Listbox keeps the outline on its root). CommandPalette drops[&>input]:h-10..14and moves the divider fromroottofooter; backlinkwith-ms-1, close staysghost, 2px inside the field,rounded-sm,hover:bg-accent-strong(ghost hover = focused soft fill). DashboardSearch and ContentSearch drop--ui-control-text-stepon the filter. Tried and dropped: highlight-sized 30px field,subtle(accent ring stays on),p-2palette (breaks alignment with the other menus), forcingbg-soft(overrides the variant). Follow-up planned: everylinkbutton inside a field goessoft.NavigationMenuItem<TMeta>/DropdownMenuItem/SelectMenuItemetc. carry a typedmeta/generic instead of[key: string]: any; dropany→unknown. Breaking type-signature change.Epic C: Component restructures (breaking)
leadingandtrailingin the flow of the box (merged 2026-10-14). One slot per element:rootis the box andbasestays the native element (Input, Textarea, InputNumber, InputMenu, InputTags), InputTags and InputMenumultiplewrap their tags in atagsslot. InputDate and InputTime are adivaround segments, so their box moves frombasetoroot. Rule: adivat the root isroot, a native element isbase. No padding is reserved for an icon any more, so any content fits and a user padding can't wipe the room. Ring, background and radius classes move frombasetoroot(21 of 104 public configs). feat(components)!: hold the leading and trailing in the flow of the box #7192.fixedprop removed, fields no longer larger on mobile (merged 2026-10-14). Each size adds--ui-control-text-step(0pxby default), an app sets it undermdto stop the iOS zoom. Removes the 16fixed×sizecompounds (Input, field, InputNumber, PinInput). ChatPrompt, DashboardSearch and ContentSearch set the variable in their theme to keep 16px. feat(components)!: remove thefixedprop and the larger text of fields on mobile #7201. Stack #7202 = feat(components)!: hold the leading and trailing in the flow of the box #7192 → fix(components)!: render the trigger avatar with theleadingAvatarslot #7199 → refactor(Select): move theemptyslot to SelectMenu #7200 → feat(components)!: remove thefixedprop and the larger text of fields on mobile #7201.slots, classes are always per slot ([Feature]: Standardize structural slot naming (root, wrapper, container) within the ui prop #6716, closed), refactor(theme)!: declare every class under a slot #6998. The 41 single-element themes (18 insrc/runtime/theme, 23 insrc/runtime/theme/prose) move from a top-levelbasetoslots: { base }, so every component is multi-slot, the hand-writtenui?: { base?: any }becomes the generatedX['slots'], andLinkgains auiprop (its 10 item interfacesOmitit). Bare strings and arrays invariants/compoundVariantsare gone: a class always names its slot, the engine drops the implicit and always-injectedbaseslot, the string-returning invoke path andapplyUnstyled'sbasearm, and warns in dev on a bare class (types can't reachvite.configor plain JS). This removes the inherited tailwind-variants rule that routed a bare class to a slot literally namedbase, which silently dropped classes on any theme without one. Breaking only inapp.config.ui:<c>.baseto<c>.slots.baseon those 41, and string variant classes to{ base: … }.:ui,<UTheme :ui>andclassare untouched. Codemod-able, TypeScript flags both.basetorooton layout components. refactor(theme)!: rename thebaseslot torooton layout containers #7000, stacked on refactor(theme)!: declare every class under a slot #6998. The rule:baseis the element a component stands for, the box of a control (anything that can sit in aFieldGroup) or the HTML element of a prose component, wrapped in arootor not; on every other component the outermost element isroot. Renamed: 12 single-element layout containers (blog-posts,container,dashboard-group,dashboard-resize-handle,field-group,form,main,page-body,page-columns,page-grid,page-list,pricing-plans) andEditorToolbar(toolbarbasetoroot, the bubble/floating wrapperroottomenu). Kept asbase: Button, Link (what Button renders,ButtonPropsextendsLinkPropsso theuitypes stay compatible), Badge, Kbd (same color / variant / size matrix as Badge, renders<kbd>, andprose/Kbdwraps it), Skeleton and ChatShimmer (leaf elements, not containers), the five button wrappers (they forwarduitoUButton), every input and select, all of prose (prose/preandprose/tablealready hadbaseas the<pre>/<table>inside aroot, soh1.baseandp.basekeep prose uniform, andprose: { p: { base } }is written by the dozen in chat apps),toasterandtextarea. Decided 2026-09-21 after trying Button, the Select family and prose asrootand reverting each: the wider rename broke the most-written overrides for a naming gain only. Remaining break is small,:ui="{ base }"andapp.configon those 12: TypeScript flags it, a plain JS config fails silently.uivalues —{ class, attrs }per slot (Add "pt" props in all components , just like https://primevue.dev/passthrough #6725) — let auislot value be an object carrying arbitraryattrs(aria-*/data-*/…) alongsideclass, not just a class string, so users can set attributes on any internal element without a separate PrimeVue-styleptprop. Reuses the existing slot-key contract (no new API); additive / v4-able (string stays the class shorthand); attributes-only (noon*→ keeps styling ≠ behavior). Cost is broad not deep: every internal element binding routes through a sharedv-bindhelper. Sharp edges: precedence vs component-owned attrs (reservedata-slot/role/Rekaaria-*), and keys that forward to sub-components (leadingAvatar→UAvatar) vs plain elements. Replaces the deferred "richer:ui" note.data-slotwith the component name. refactor(components)!: namespacedata-slotwith the component name #7003, merged 2026-09-22. Every element styled by a slot carriesdata-slot="<component>-<slot>"and the outermost one the component name alone (card,card-header,button-leadingIcon), the ui.shadcn.com scheme.<component>is the#build/ui/<path>import in kebab-case (prose-h1,content-tocwithout a secondcontent-,ContextMenuContentsayscontext-menu-…),<slot>is the theme key verbatim. Outermost = therootslot, or thebasethatclasslands on when there is noroot(Button, Select); overlays have neither and keepmodal-content. A parent labelling a child passes its own namespace (<UContainer data-slot="page-hero-container">), caller-wins is unchanged. Written by thenuxt-ui/data-slot-namespacelint rule (eslint.config.mjs, run bypnpm run lint:fix), which derives each value from theui.<slot>()on its tag rather than from the current value, so it is idempotent and replays after av4sync brings bare values back. The first pass was 957 values over 103 files. Prose emits no marker, on purpose: one on every<p>and<li>of a rendered document is DOM weight nobody selects on. Selectors moved with it (tabs.ts,empty.ts,ContentToc, the docs and the specs); ownership is not mechanical (leadingIconisbutton-leadingIconin ChatPromptSubmit andinput-leadingIconin CommandPalette). Breaking for every user selector; no codemod, the migration guide gives the rule, the ownership gotcha and a ripgrep line.sizeonModal/Card) instead of forcing a custom wrapper; aligned across components. Purely-additive one-off variants can still land in v4 as normal feature work; the cross-component consistency is the breaking part.NavigationAccordion(vertical) + mergeContentNavigation; collapsed via CSS transitions (decouple visual vs behavioral collapse, drop manual:collapsedwiring). To fix inNavigationAccordion, both deferred from v4 on 2026-10-13: the trailing toggle of items withto+childrenas a real<button>next to the link (UNavigationMenu fails axe standards #6481, closed PR fix(NavigationMenu): render the vertical trailing trigger as a button next to the link #7194 has the markup and an axe test), anditem.tooltipwhen not collapsed (NavigationMenu: Tooltip should be shown even when not collapsed #6787, closed PR feat(NavigationMenu): support item tooltip when not collapsed #6851). Clears most of its 17 compounds (they carryorientation), so don't refactor them before the split.Dashboardcategory (proposed by @mikenewbon in feat(Sidebar): add resizable functionality #6340) —Sidebar(feat(Sidebar): new component #6038) already covers the core; fold the rest into general components and delete all 10UDashboard*:DashboardSidebar→Sidebargainsresizable(minSize/maxSize/defaultSize/collapsedSize), persisted size/collapsed state (cookie/localStorage) and routeautoClose, built onuseResizable(revisits PR feat(Sidebar): add resizable functionality #6340).#default="{ state }"), but the dashboard template's inbox page puts the collapse button and the mobile toggle in page navbars rendered through the layout's<slot />, outside the sidebar subtree, so slot props can't reach them. Not concluded yet.DashboardGroup→ gone: shared open/collapsed state moves to auseSidebar()composable (same shared-composable pattern asuseOverlay) exposingopen/collapsed/isMobile+toggle()/collapse()/close()—isMobile+close()because route-only auto-close isn't enough in practice (thecalendartemplate also closes on modal/command-palette open); storage defaults come from<UTheme :props>(feat(Theme): override component prop defaults #6031), and thedashboard:*Nuxt hooks are removed. Covers the old "single root div + provider context rework" item.DashboardPanel/DashboardResizeHandle→ a Splitpanes-style<UResizable>/<UResizablePane>/<UResizableHandle>on a public headlessuseResizablecomposable (min/max, direction, keyboard a11y, persistence); the panel header/body/footer chrome becomes a docs pattern.DashboardNavbar+DashboardToolbar→ one genericToolbar(keeps thetitle/icon/toggleconveniences so the migration is mostly a rename).DashboardSearch+ContentSearch→ one genericSearch(Modal + CommandPalette + shortcut).useContentSearchgoes with it (removal planned 2026-10-23): its shared state reads the root config, so it ignores<UTheme>icons.DashboardSidebarToggle/DashboardSidebarCollapse/DashboardSearchButton/ContentSearchButton→ dropped — they're one-lineUButtonrecipes onuseSidebar()/useSearch(), documented instead of shipped.BlogPosts→PageGridand other thin wrappers get the same review.wrapper= title+description,actionsslot) — PR feat(Sidebar): new component #6038. The props already match (title/description/close/closeIcon+actionsslot everywhere); the remaining gap is layout — Modal/Slideover position the close button absolutely while Drawer/Sidebar put it in an in-flow actions row (Empty div on Slideover when title or description props are not used #5336).Drawerto Reka UI's new Drawer primitive (merged 2026-11-10 as dd97571). feat(Drawer)!: replacevaul-vuewithreka-uiprimitives #6691. Built on Reka UI 2.11's Drawer,vaul-vueis gone.direction→side,activeSnapPoint→snapPoint(opens at full height withoutdefault-snap-point),nestedremoved (detected), vaul-only props and thedrag/release/close/animation-endemits removed,modaltakes'trap-focus'. Defaults flip:inset: true,handle: false. Nested drawers stack in the component (Reka's--nested-drawerscounts one level), the ones behind recede and match the frontmost size. No compounds left in the theme.after:enteris emitted from the content'sanimationend, since Reka's open-complete watch isn't immediate. Not handled: nesting drawers on different sides, a nested snap-point drawer reports its full height.DrawerContentin an unstyledDrawerViewportso the DOM shape changes once; documentdata-reka-swipe-ignoreindrawer.md(touch swipes start on buttons and links, reka#2982). 5.0 if tested on iOS and Android, else early 5.x:DrawerVirtualKeyboardProvideron by default forside="bottom"with an opt-out prop, plus--drawer-keyboard-insetin the theme (reka#2889, can't live in UApp, needs the DrawerRoot context, no cost while closed; Reka marks it untested on devices). All three ship in 2.11. Gone with v3: cancelling snap changes or swipe dismissal throughbefore-update:*(2.11 has nobefore-updateemits). Not re-addingdrag/release: Reka keeps its swipe callbacks internal,data-swipingand the--drawer-swipe-*variables cover styling, revisit if Reka exposes swipe events.Carouselto Reka UI's Carousel primitive and drop Embla (opened 2026-11-13). feat(Carousel)!: build on Reka UI primitives #7406, on the primitives ported to Reka v2 in feat(Carousel): add primitives unovue/reka-ui#3262 (pinned to pkg.pr.new06d5863until a 2.x release, CI red outside Carousel until then). The 8embla-carousel*peers and the Carousel entry of the optional-deps plugin are gone.v-modelreplacesstart-index/@select,v-model:playingadded,emblaApiandclass-namesremoved (data-active/data-in-viewon the slides),auto-height/fade/wheel-gesturesare booleans,auto-scrollspeedis px per second. Own prop and emit types, no Reka types in the public API.alignstayscenter, theme gutter unchanged (content-ms-4, itemsps-4) after the Reka gutter fix. Newcarousel.slideLabellocale key.ColorPickerto Reka'sColorArea/ColorSlider(currently hand-rolled oncolortranslator). The Color family ships in Reka 2.11; theColorobjects and one range input per channel came with v3 (reka#3064, feat(Table): add support for pagination & initialState #3065), so check what 2.11 has before sizing. It should fix keyboard control (fix(UColorPicker): Make it keyboard controllable #7016) and opens the door to an alpha slider + horizontal hue layout asked for in the thread.modelValuecan stay a string through Reka's hex output, so not breaking.Maybe drop Fuse.jsDropped 2026-10-15: Fuse stays.useFilteris one substring match per field, so it loses the token search DashboardSearch and ContentSearch use (multi-word, any order, across fields), the<mark>highlighting built from Fuse match indices and the publicfuseprop (resultLimit, keys, threshold); the gain was ~7 kB gzip in apps using CommandPalette. Was: Maybe drop Fuse.js →useFilter(reka-ui backed) already powers SelectMenu/InputMenu/DropdownMenu; CommandPalette is the last Fuse consumer. Open question: fuzzy scoring + match highlighting, whichuseFilterdoesn't do.ChatMessage/ChatMessagesfrom hardcoded Vercel AI SDK types; ship a mapping helper (AI SDK → Nuxt UI message) + a generic chat base (input/message/messages) enhanceable into the AI chat (reasoning/shimmer/tool/prompt) (Normal chat message component without AI,chat person to person #6598)spacingOffsetfromChatMessagesand make the sticky scroll button the default. v4 ships both behind the#footerslot (feat(ChatMessages): addfooterslot #7268, opened 2026-10-23): the prompt in#footeris measured with a ResizeObserver and the auto scroll button turns into a zero-heightstickyelement above it. Without#footer, v4 keeps theabsolute top-[86%]button, which the chat template and the AI chat guide rely on (fix(ChatMessages): keep the auto scroll button at the bottom of the scroll container #7263 made sticky the default and was closed for covering their button).spacingOffsetis@deprecatedin v4. Breaking in v5: the button is always sticky at the bottom of the scroll container. Migration: move a sticky prompt into#footerand dropspacing-offset.ChatMessagesscroll props. The scroll props get clearer names:shouldAutoScroll→autoScroll,shouldScrollToBottom→defaultScrollPosition: 'start' | 'end' | 'last-anchor', the button'sautoScroll/autoScrollIcon→scrollButton/scrollButtonIcon, plus ananchorprop for which new messages pin to the top. AuseChatScrollcomposable is the low-level path for the agnostic base. Verdict: the renames are optional, worth doing only if the agnostic chat touches these props anyway.ChatMessagerenders reasoning, tool and file parts by default, on top of a#partslot shipped in v4, so a basic AI chat needs no#contentoverride.filesmoves intobodynext to the bubble (it starts under the avatar column today) and afooterslot holds status and timestamps. Breaking because apps that already render these parts in#contentwould see them twice. The avatar side follows theleft/right→start/endrename in Epic B.ChatTool/ChatReasoning: astatusprop (running,approval,done,error,denied) replacesstreaming,loadingand theerrorboolean added in v4 (feat(ChatTool): adderrorprop #7253), with agetToolStatus(part, streaming)helper. Not added in v4 first (decided 2026-10-21), it would sit next tostreamingandloadingas a third prop for the same state.suffixbecomesdescription. Both components stay. A compound line primitive was considered and dropped, it moves the AI SDK state mapping into every app.ChatPromptloses itserrorprop and keeps the textarea enabled. In theerrorstatus,ChatPromptSubmitsends when the prompt has text and retries when it is empty, reading the prompt model through a small context fromChatPrompt. The same context carries thestatusadded toChatPromptin v4 (fix(ChatPrompt): ignore submits while the chat is streaming #7248), soChatPromptSubmitno longer needs its own:status. Today the textarea is disabled and the button only retries, although the AI SDK clearserroron the nextsendMessage(). The v4 textarea-only fix (fix(ChatPrompt): keep textarea enabled on error #7219) was closed because Enter would send while the button still retried. Migration: stop passing:errortoChatPrompt.ChatPrompt:submitOnEnterdefaults to'desktop'so Enter inserts a newline on phones.@tanstack/tablev9 #6799). Merged 2026-11-05 as feat(Table)!: migrate to TanStack Table v9 #7282 (fcfde04e5), after a TanStack source audit that added external atoms for synchronousv-modelstate (Possible synchronization issue in UTable update:row-selection event #5408), footer row spans, keyboard cell selection and resizing, grid ARIA, pinned rows in virtualized tables andauto-only built-in fns. Ready for review 2026-10-25: default feature set + afeaturesprop for pagination, grouping and faceting (19.3 kB gzip vs 14.7 kB on v8, 28.1 kB withstockFeatures), oneoptionsprop typed from TanStack'sTableOptionsreplaces the 11*Optionsprops, theon<Slice>Changehandlers are attached in a loop over themodelsmap (a new slice = onedefineModel+ one map entry),useTableno longer cast toany,AggregationFnsaugmented with the built-in names, v9 table logic 4 to 8x faster in a Node benchmark, localFlexRenderfor two upstream bugs: an array returned by a cell (issue drafted, not posted) and the empty string hydration mismatch ([Vue] Hydration error inFlexRenderwhen column is an empty string TanStack/table#6077),facetedOptions/onStateChangeremoved,columnSizingInfo→columnResizing. Docs examples, theme studio, Nuxt playground (Vue playground reuses its pages), skill recipe, table.md and the migration section done; select-all checkboxes testgetIsAll…first. Scope grew 2026-10-26/27 to render every stock feature: cell selection (pointer, drag, arrow keys, scrolls virtualized tables), native cell spanning replacingmeta.colspan/rowspan(skipped when virtualized), opt-in column resize handle, leaf headers spanning down withrowspan(fix(Table): merge grouped headers across rows #7240's approach),aggregatedCell,meta.attrsontr/th/td, rowsenableRowSelectionrejects are inert (UTable row data-selectable attribute not aligned with TanStack API #4968, fix(Table): respectenableRowSelectionindata-selectableattribute #5611), shift-click range selection, new examples for cell selection, resizing, column ordering and faceting. Also resolves Table: Expose column resize handlers to support column resizing #6715, Allow customizing or disabling the row tabindex for clickable rows #6710, UTable multiple select with shift key #5357, Add support for custom HTML data-* attributes on table rows (<tr> elements) #5865, UTable expand issue - row id alias necessary #6327. Found on the way: v9min/max/extentaggregations skip date strings, arefholding aTableRowno longer type-checks (useshallowRef). Original note: migrateTableto@tanstack/vue-tablev9 (9.0.0 shipped 2026-08-04). Internally it's small: exactly one source file imports TanStack (src/runtime/components/Table.vue),useVueTable→useTable, and the four hardcoded row models (core/filtered/sorted/expanded) move into a module-scopetableFeatures()object —getCoreRowModel()is automatic in v9, pagination/grouping stay consumer-supplied viapaginationOptions/groupingOptionsas today.declare module '@tanstack/table-core'just gains theTFeaturesgeneric (declaration merging still works, no need formetaHelper()).TableColumn<T>/TableRow<T>/TableDataare our own aliases, so we supplyTFeaturesourselves and user annotations don't change at all (optionally expose it as a second generic,TableColumn<T, F = typeof features>, so people can register extra features). What makes it breaking isdefineExpose({ tableApi })handing out the raw TanStack instance (40+ call sites across docs/playgrounds/skills): v9 removesgetState()and top-levelonStateChange(→table.store.state/table.atoms.<slice>.get()), renames ~20 pinning methodsleft/right→start/end, splitscolumnSizingInfo→columnResizing, changesgetIsSome*RowsSelected()to mean "at least one" (our indeterminate select-all pattern silently breaks everywhere it appears), and defaultsenableRowRangeSelectionon — shift-range selection as a newUTabledefault is a deliberate call, not a side effect. User column defs change too (sortingFn→sortFn, aggregations →constructAggregationFn()). Not v4-able: no peer range is both non-breaking by default and v9-selectable (peers resolve to the highest satisfying version), andTable.vueships as raw SFC compiled by the consumer'svue-tsc, so with v8/v9 differing in generic arity one file can't type-check against both — dual support means a build-time-swapped second implementation, a third vitest project and duplicated docs, permanently doubling the surface of our most complex component. Payoff: 79% faster core row model, 52% grouping, 37% sorting, 34% filtering, 2.71 GB → 380 MB on 1M rows, tree-shakeable features, plus cell-range selection and native cell spanning (we hand-rollcolspan/rowspanin column meta today). Sweep: 8 direct-importing examples indocs/app/components/content/examples/table/, the Nuxt playground table page, and the REPL (App.vueimport map +vite.config.bundle.tsboth pin the version). Rides Epic B for the pinning value rename and Epic E for the peer move.Contentcategory / own our content types — same move as agnostic Chat above, and the same framework-agnostic driver as Prose × Comark: with v5 leaning on Comark (which works with Vite, not just Nuxt), the Content components must not be Nuxt-specific either. The entire@nuxt/contentcoupling is two imported types (ContentNavigationItem,TocLink) across 6 files, so we define our own (structurally compatible, thin mapping helper for the rest) and drop the@nuxt/contentpeer — it becomes a pure data source:ContentNavigation→ merged into the newNavigationAccordion(see above).ContentToc→PageToc,ContentSurround→PageSurround(codemod renames).ContentSearch/ContentSearchButton→ the genericSearch(its search fn/result types are already ours).Prosecomponents on the@nuxtjs/mdc→ Comark (https://comark.dev) migration. v5 fully embraces Comark, and since Comark works with Vite (@comark/vue) as well as Nuxt (@comark/nuxt), the prose components must carry no Nuxt-specific or@nuxtjs/mdc-specific behavior. They already own their types (zero MDC imports), so it's mechanics:mdc-unwrap→ nativeunwrapslot attr, heading anchor generation drops the deprecatedruntimeConfig.public.mdc.headings.anchorLinksfallback — control moves entirely to the framework-agnosticanchorprop (shipped in v4), which defaults off in the Comark world (Comark has no global anchor config): opt in per heading, or scope a subtree via<UTheme :props="{ prose: { h2: { anchor: true } … } }">/app.config. Module gating swaps@nuxtjs/mdcfor@comark/nuxt(which already auto-registers our prose components), and the deprecatedmdcoption is removed (done separately in refactor(module)!: remove themdcoption #7275).Editormarkdown support can then ride Comark's planned TipTap extension (first party TipTap extension comarkdown/comark#164). No global prose registration (decided 2026-10-06, from the Comark thread): dropglobal: trueon the proseaddComponentsDir(src/module.ts). In Nuxt every global component is its own async chunk, 47 for prose, and it only fires in a Comark app because@comark/nuxtforcesui.prose: truethroughmoduleDependencies. Replacement is the barrel added on v4 in feat(module): export prose components from@nuxt/ui/components/prose#7143 (merged on v4, 2026-10-06):import * as proseComponents from '@nuxt/ui/components/prose'passed to:componentson<Markdown>/<MarkdownDocument>, which reads that prop beforeappContext.components. Breaking: anyone rendering without:componentsloses Nuxt UI prose, so it lands with the@nuxtjs/mdcremoval (MDC resolves globally) and gets a migration guide line plus the v5 #6918 checklist entry in that PR. Both adapters: the Vue plugin registers prose eagerly withapp.component()(src/plugins/plugins.ts), decide there whether it stays or follows. Open: whether theproseoption survives as a theme-only switch or the prose theme is always generated, and@comark/nuxtdropping itsprose: truedefault (their repo).global: 'sync'ruled out, it moves every prose component into the entry. No v4 opt-out (decided 2026-10-06): aprose: { global: false }option was considered and skipped. In v4 the prose theme and the global registration share one condition (src/templates.ts,src/module.ts), so feat(module): export prose components from@nuxt/ui/components/prose#7143 gives the import path but not the chunk win. The gain is small (the chunks are lazy, the cost is build output files and the entry's component map) and the option shape would be thrown away by the v5 default. v4 workaround, untested in an app: acomponents:extendhook settingglobal = falseon components whosefilePathincludes/runtime/components/prose/, then passing the barrel to:components.Epic D: Defaults & behavior (breaking)
expanddefault →false(stacked): feat(Toaster)!: stack toasts by default #7281 (merged 2026-10-24). The keyboard expansion it needs shipped in v4 first, fix(Toaster): expand stacked toasts on keyboard focus #7279 (merged 2026-10-23), onv5since the 2026-10-27 sync. Follow-up, non-breaking: feat(Toaster): smoother stack motion and three visible toasts #7322 (merged 2026-10-29) fades toasts in and out and moves the stack while one closes.pilldrops the color fill: feat(Tabs)!: drop the color fill on thepillvariant #7328 (merged 2026-10-29). Indicatorbg-default+shadow-xson thebg-softtrack,coloronly sets the active text (text-accent,text-strongfor neutral) likelink. Chosen over a new v4 variant (2026-10-29): the docs overrodepillthis way in three places.UColorModeTabson top of it: feat(ColorModeTabs): new component #7331 (merged 2026-11-04), with a newsquareprop on Tabs; icon only by default.pilltrack reads--ui-tabs-track-padding: feat(Tabs): match the height of a button of the same size #7358 (merged 2026-11-04). Follow-up fix(Tabs)!: make the active tab less cramped #7392 (merged 2026-11-13): the half-pytrack left a cramped 24px tab with 14px text atmd, so the track is a fixed3pxand the labels take the text of the size below (md14 → 12px,xl16 → 14px), heights unchanged. An undo back to the v4 heights was tried first and dropped after comparing with the shadcn new-york tabs (list = Button, ~29px tab).Epic E: Foundation & install contract (breaking)
componentDetectionon by default (Nuxt + Vue) — now that the VuecomponentDetectionport has landed (feat(vue): supportexperimental.componentDetection#6731), flip theme-CSS tree-shaking on by default so apps only ship CSS for components actually used. Breaking-ish: dynamicresolveComponent(name)usage can be missed (escape hatches stay — thecomponentDetection: [...]allowlist, orfalse). Also promote the Vue dev-server HMR re-detection (restart-only in feat(vue): supportexperimental.componentDetection#6731) from "manual-validation follow-up" to a supported path here. Status 2026-09-27: feat(module)!: detect the components in use by default #7058 (merged 2026-10-01). Graduated to top-levelcomponentDetection(experimentalremoved), defaulttrue. Fixed the gaps default-on exposes: prose components getProse*graph nodes (what they render is always included when prose is on),.mdfiles scanned for MDC::u-x/:u-x, plus each layer'scontent/on Nuxt. Docs site and Vue playground opt out (dynamic imports / pages outside root). Fixtures set the flag explicitly both ways. Default CSS: Nuxt 24.8 → 10.7 kB gzip, Vue 23.3 → 9.2 kB. Vue dev-server re-detection: feat(vite): detect newly used components while the dev server runs #7059 (merged 2026-10-01),configureServerre-detects on source /.mdchanges and emitschangeforui.css(Vite doesn't watchnode_modules); verified with Vite in middleware mode on thevue-detectionfixture.Superseded by refactor(module): ship static themes #7037 (2026-09-25): with detection (or
prefix),ui.cssexcludes the package theme folder (@source not) and lists the used themes' resolved classes in@source inline(...), the same path on Nuxt and Vue, since per-file sources can't narrow a theme that extends another. No blanking, nothing waits on tailwindcss#20406. Original item: Unify Vue detection with Nuxt via per-file@sourcelines — replace the feat(vue): supportexperimental.componentDetection#6731 theme-blanking with the Nuxt mechanism (emit@source "./ui/<component>.ts";per detected component, sharedgenerateSourcespath) once the Tailwind fix ships: Don't scan sibling files of a concrete@sourceinside an auto source root tailwindlabs/tailwindcss#20406 stops a file@sourceinside the Vite root from scanning its whole parent directory (root causeexpand_restricted_patterns, crates/oxide). Gated on the v5 Tailwind floor including that fix — on older 4.x the narrowed list silently produces full CSS, so swapping in v4 would regress everyone below the fix version, which is why blanking shipped in v4 and this waits (decided 2026-08-11). Deletes theunused/applyUnstyledbranch inwriteThemeTemplateand moves Vue detection back intogenerateSources; theme files on disk keep their real classes again (nicer for debugging/inspection). If #20406 is rejected or reshaped upstream, blanking simply stays — it's equivalent in output (~2.4 kB delta from variant keys likeoutlinebeing valid utilities).Static theme — kill per-project theme compilation. Done: every sub-item below is merged and
options.themeis gone (refactor(module)!: movetheme.prefixtotailwindPrefix#7052). As shipped, components import../theme/<x>from the package, Tailwind scans the package sources, and#build/ui/*stays as one-line re-exports for app code. Original plan: accent (A1) removesoptions.theme.colorsfrom theme files, and removingoptions.theme.transitionsbecomes this item’s own breaking change (it was going to fall out ofdata-reduce-motion, which is dropped, see A3). Those are the only two options any theme file reads (126 + 95 occurrences across 69 of the 168 files), so once both go, theme files become static objects.theme.transitions: falsehas no replacement option; the documented answer isprefers-reduced-motionplus the userland duration override at A3, which is what it was doing anyway. Components import theme from the package instead of#build/ui/*,writeThemeTemplate+ the.nuxt/ui/node_modules/.nuxt-uicopies disappear (the other half of the Everything gets loaded on a fresh app #6296 dev-startup + HMR churn), and Tailwind scans package sources directly. Synergy with Epic H: static theme objects are stable module-scope identities, so tv factories build once at import (or even publish) time and the WeakMap fast path becomes the default case instead of a calling convention. Nothing stays generated per app exceptcomponentDetectionsources and, whenprefixis set, the prefixed class list (see the#build/ui.cssitem below). Goal: removeoptions.themeentirely (decided 2026-09-23). Theme files read onlycolorsandtransitions, butwriteThemeTemplatealso appliesdefaultVariants,unstyledandprefixto every file afterwards, so each option needs a home outside theme compilation:colors: removed in refactor(theme)!: resolve colors through--ui-accentand removetheme.colors#7024 by closing the color set (see A1 status). No open variant, no scopes generated from CSS: the seven scopes are literal insrc/runtime/theme/color.ts, which a static package theme can import as is.transitions: removed in refactor(theme)!: remove thetheme.transitionsoption #7018 (2026-09-24): 97 guards across 53 themes, 23 themes now plain objects, zero snapshot churn.defaultVariants: merged, refactor(Theme)!: movetheme.defaultVariantsto the app config and<UTheme :props>#7028 (2026-09-25, merged 2026-10-01):useComponentProps(name, _props, theme)reads the theme'sdefaultVariantsto apply'*'only overprimary/md;app.config.ui.defaultVariantsread directly by the proxy for now (root-context sugar comes with the app-config item). A'*'key in<UTheme :props>(decided 2026-09-24), below the per-component keys:<UTheme :props="{ '*': { size: 'sm', color: 'neutral' } }">. Same semantics as today'sapplyDefaultVariants:useComponentPropsapplies it only where the component's own default isprimary/md, so intentional exceptions (aneutralKbd, ansmcomponent) stay. Per subtree now (a compact toolbar), app-wide through app config sugar asapp.config.ui.defaultVariants: { color, size }on the root context, same path on Nuxt and Vue. FormField / FieldGroup size inheritance unaffected: the group composables read raw_propsandtv()calls keepsize.value ?? props.size. Distinct from open question 8'sprimary: neutralCSS alias, which recolors everything sayingprimary(utilities included) where'*'only changes what components pick when given no color; docs explain both. Landed alone in refactor(Theme)!: movetheme.defaultVariantsto the app config and<UTheme :props>#7028 (split 2026-09-25):unstyled,<UTheme>variants andprefixneed the engine to read the nearest<UTheme>, which is the "app config becomes a root<UTheme>" item, so that plumbing comes first as its own stacked PR (all 163tv(theme, appConfig.ui?.x)calls take their overrides from context), thenunstyled, thenprefix. The same PR typestv()call props from theme + app.config, so acolorvalue added through app.config variants (custom alias liketertiary) type-checks inside components, then documents that recipe.unstyled: merged, refactor(Theme)!: movetheme.unstyledto the app config and<UTheme unstyled>#7030 (2026-09-25, merged 2026-10-01): components passuseComponentOverrides(() => appConfig.ui?.x)totv()(all 166 call sites); the overrides carryunstyledfrom the nearest<UTheme>/app.config.ui.unstyled, and the engine resolves a blanked copy of the theme (applyUnstylednow insrc/runtime/utils, still used at build for Vue componentDetection). Same PR types the overrides after the app's own config (ComponentOverridesbrand +tv()overload), so app.config-added variant values (customcolor) type-check inside components; the custom-color recipe is documented. Moves into our components (decided 2026-09-24):<UTheme unstyled>(andunstyledin app config, through the root<UTheme>), read by the engine to skip the theme layer, per subtree, same code path on Nuxt and Vue. The flag is what makes it unstyled: our markup is Tailwind utilities, so dropping only the CSS would leave any utility the app also uses (flex,px-2.5) generated and matching our elements, components partly styled. Once the engine stops emitting theme classes, the theme CSS from scanning matches nothing, so skipping it is a size optimisation only: a CSS entry without the theme@source, not named@nuxt/ui/base, which the feat(theme): allow importing@nuxt/uiinto a cascade layer #6602 split uses for the layerable half.prefix: done in refactor(theme)!: prefix classes at runtime #7035 (2026-09-25, merged 2026-10-01):createTV(config, prefix)resolves each theme against aWeakMap-cachedapplyPrefixcopy (prefix read from#build/app.configlike the tailwind-merge prefix, not from<UTheme>context yet: that moves with the app-config item);src/runtime/utils/prefix.tsholdsprefixClasses(idempotent) + structuralapplyPrefix, shared by engine,getThemeClasses(build) andusePrefix; theme templates stay unprefixed and a prefixedui.cssswaps the theme@sourcelines for one sorted@source inline(...)(~40 kB, narrowed by componentDetection on both adapters). Verified:applyPrefixdeep-equals the oldapplyPrefixToObjectfor every theme butprose.codeIcon(old step prefixed its icon names, a bug), and Tailwind 4.3 CSS from old files vs inline list is byte-identical. Theme prefix error #5504/Tailwind Prefix break intellisense #6070 go throughui.static.css, DashboardSidebarCollapse does not respect prefix other than default #4173/custom prefix not working when set with UHeader #4371 are the component prefix: unaffected. Kept (decided 2026-09-23), resolved at runtime. Tailwind only generates prefixed candidates, so static package themes need two things for a prefixed app: the engine prefixes class strings inresolveSpec(once per spec, cached, not per render; prefix provided through the root<UTheme>context by the module), and a build step reads the static themes, prefixes every class and emits them as@source inline(...)in the injected sources file (feat(theme): allow importing@nuxt/uiinto a cascade layer #6602's split). Unprefixed apps get nothing generated.prefixClasseslives insrc/runtime/utilsso the build step and the engine share one implementation and emit identical candidates. The*Sizeslots were removed in refactor(theme)!: remove the*Sizeslots #7031 (2026-09-25, merged 2026-10-01): components derive child sizes in code (getAvatarSize/getItemSize), overrides through child props,isSizeValuegone. Prefix regressions to re-verify on the new path (all closed; Tailwind Prefix break intellisense #6070 was closed stale while still reproducing): Theme prefix error #5504 (ESLint on the unprefixed@apply antialiased) goes with the plain-CSS body rule, and Tailwind Prefix break intellisense #6070 (IntelliSense) should go because the prefixed class list is injected by the module, never@imported. DashboardSidebarCollapse does not respect prefix other than default #4173 / custom prefix not working when set with UHeader #4371 to re-check.Literal classes: refactor(theme): spell out every theme class #7036 (2026-09-25, merged 2026-10-01): oxide's scanner over
src/thememissed 31 resolved classes in 8 themes (chat-promptfocusHighlight, checkbox/checkbox-group/radio-group${hover}, tabsssr(), input-date/time/tags regexreplaceFocus), plus\'-escaped quotes (scanner reads the backslashes; backticks instead). All spelled out, resolved themes JSON-identical,theme classesguard test intheme-slots.spec.ts(text match between quote/space boundaries over the whole dir). Static themes PR stacks on it.Split to keep each PR reviewable (395 files): refactor(theme): move themes to the runtime and type their sources #7040 (merged 2026-10-01) moves + types the themes with
#build/ui/*still generated byte-identical, plus atv.spectype test; refactor(module): ship static themes #7037 merged it in (no force-push) and is based on it (191 files; base changed throughgh stack unstack+ relink, GitHub stack #7042).Static themes: refactor(module): ship static themes #7037 (2026-09-25, merged 2026-10-01).
src/theme→src/runtime/theme, components import../theme/<x>,@source './theme'inindex.css,#build/ui/*kept as one-line re-exports (Nuxt serves#build/*from its vfs, so an alias to the package dir would fight#build). Detection or prefix:@source not <themeDir>+@source inline(resolved classes)on both adapters, since per-file@sourcecan't narrow a theme that extends another (Select only holds its delta over Input); Vue blanking gone, no longer gated on tailwindcss#20406. Types:defineTheme(checks +DefinedThemetypes defaults as variant unions; returningT & TVThemeCheck<T>lettv()re-infer the narrow literal through alias args),extendTheme(base, theme)(defuFntyped byExtendedTheme,const T; defu's types dropped the extension's slots), numeric variant keys accept${n}. mkdistcharset: 'utf8'(esbuild wrotecontent-['\xB7']).--uiDevremoved. Verified: resolved themes identical incl.undefinedkeys; Tailwind CSS from old JSON templates vs package scan identical except 3 selectors the JSON escaping broke (data-[state=\"active\"]:bg-accentedInputTags, Marqueecontent-[\"\"], a real v4 bug); detect drops 11 JSON-key utilities only; Nuxt playground build identical minus those 3; Vue playground builds.root(Vue) now only places.nuxt-ui, kept.Vue
componentDetection: reworked in refactor(module): ship static themes #7037, see the superseded per-file@sourceitem above.Status 2026-09-26: refactor(module): ship the static CSS #7043 (merged 2026-10-01). Static
tokens.css(@theme),accent.css(scope rules),base.css(body as plain declarations, keyframes, layers),sources.css(@source,@custom-variant, tokens,#build/ui.css);index.css= sources + base, exported@nuxt/ui/sources(renamed@nuxt/ui/tailwindin refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070) /@nuxt/ui/base(fixes@import "@nuxt/ui" layer(layer-name);not working #4503:@source/@custom-variantcan't nest,@theme/@keyframescan).#build/ui.csskept as the generated sources file (layers, config classes, not/inline) + prefixed accent rules read fromaccent.cssat build;ui.static.cssnow empty but theimportsmapping stays. Not done: auto-injecting the generated sources to drop#build/ui.cssentirely (Vite transform on the user's CSS entry before@tailwindcss/vite, plus a PostCSS path for webpack/rspack builders). feat(theme): allow importing@nuxt/uiinto a cascade layer #6602 is 404 now; fix: add CSS cascade layer support #5849 (closed) had the same split. Verified: rule-set identical to refactor(module): ship static themes #7037 (order only), prefix adds 7 dead unprefixed scope rules, layered import compiles. Fix found in review: the accent reset is:where([class*="[--ui-accent:"]); at 0,1,0 it came after the prefixed scopes#build/ui.cssadds and wiped their roles in prefixed apps (checked in Chrome).One generated sources file (re-scoped 2026-09-26, was "No
#build/ui.css", decided 2026-09-23). Done with refactor(module): ship the static CSS #7043: the static split (@nuxt/ui/sourcesfor@source/@variant/@themeat top level,@nuxt/ui/basefor the layerable rest,@nuxt/uiimporting both) is what fixes@import "@nuxt/ui" layer(layer-name);not working #4503 (@source cannot be nestedunderlayer(x)), in v5. A per-app file can't go entirely:#build/ui.cssstill carries the Nuxt layers'@sources, the rootAttrs / html / body class inlines, the prose / content@source not, and the detection / prefixnot+ inline. With a prefix, the prefixed accent scopes go in#build/ui.base.css, imported frombase.cssso they share its layer. Decided 2026-09-27: keep#build/ui.cssas the one virtual import, no injection.sources.cssalready pulls it in and theimportsfallback inpackage.jsonkeeps tooling working.Step 1 done 2026-09-26: refactor(theme)!: read the app config through the theme context #7044 (merged 2026-10-01).
ThemeContext.config=app.config.ui;<UApp>provides the root (provideThemeContext(injectThemeContext())),<UTheme>passes it down, fallback = one root context per Vue app (effectScope(true), WeakMap by app). 180 runtime filesuseAppConfig()→useThemeConfig()({ get ui() }, same shape).useComponentOverridesreturns aComponentOverridesclass (entry, unstyled, engine);engineFor(tv, prefix)keyed by content, per-engine spec caches, config snapshotted;tv.tsno longer imports#build/app.config. Breaking: plaintv()calls get the default merger and no prefix (migration note),defaultThemeContextgone. Followed by steps 2 to 4 below.Step 2 2026-09-26: feat(Theme): add
variantsandiconsprops #7046 (merged 2026-10-01).<UTheme :variants>(thevariantsofapp.config.ui.<c>, prose underprose) and<UTheme :icons>merge into the context config over the parent's (defu, nearest wins); components unchanged. Slots stay on:ui(roadmap: covered). TypedThemeVariants/ThemeIcons; runtime-added values aren't in prop types (docs: declare in app config). Followed (decided 2026-09-27, all merged): layer-order PR (refactor(theme)!: stack the app config and each<UTheme>as override levels #7050, below),theme.prefix→tailwindPrefix(refactor(module)!: movetheme.prefixtotailwindPrefix#7052), A6 (refactor(theme)!: move the colors from the app config to the@nuxt/ui/colorsplugin #7053),componentDetectionon by default (feat(module)!: detect the components in use by default #7058).useThemewas dropped (feat(useTheme): new composable to change the colors and radius at runtime #7060 closed). Vue without the emulated app config dropped (see the stack status).ui.tvstays in app config only, no<UApp>/<UTheme>prop: it's app-wide, and Vue passes it throughui({ ui: { tv } })into the root context.Step 3 2026-09-27: refactor(theme)!: stack the app config and each
<UTheme>as override levels #7050 (merged 2026-10-01), override levels (review decision 15).app.config.ui.<c>then each<UTheme>(:variants,:ui/:props.<c>.uias slots) are levels, farthest first. Current order (decided 2026-09-28, in-level order settled 2026-09-29): the theme as one unit (slots, variants, compounds), then each level farthest first in the same order (slots, variants, compounds), thenui, thenclass. Level-major drops theme structural compounds (leading/trailingpadding,square,increment/decrement) under a user padding, documented with a diff; A7 answers it with size variables (refactor(theme)!: size controls through tokens #7116): restyle a size through them and the exceptions follow. Measured against the docs and 10 template configs (6500 slot strings): one change, the calendar NavigationMenu active highlighted pill link hover.useComponentOverrides((ui: X['AppConfig']['ui']) => ui.<c>),props.ui= ownuionly, contextlevels. Vs v4: 39 diffs by class set (27 are bare-string values from "Theme shape"), all documented migrations or intended fixes, plus the calendar template's checkbox ring underhighlight, fixed in fix(app): keep the error ring on highlighted checkboxes nuxt-ui-templates/calendar#24 with ahighlight: falsecompound (avariants.highlight.falseobject breaks on v4). Level function slots keep replacing the theme's slot classes, instance functions run over the whole chain, documented once in "Function slots".Step 4 2026-09-27: refactor(module)!: move
theme.prefixtotailwindPrefix#7052 (merged 2026-10-01).theme.prefix→ top-leveltailwindPrefix(decided 2026-09-27),options.themeremoved. Still a module option (build step needs it), forwarded to the runtime asapp.config.ui.prefix. Docs: both install pages, migration, skill.ui.prefixremoved from theapp.config.ts/ Vueuiinput types, kept in the runtime type.App config becomes sugar for a root
<UTheme>(decided 2026-09-23). Done across refactor(theme)!: read the app config through the theme context #7044, feat(Theme): addvariantsandiconsprops #7046, refactor(theme)!: stack the app config and each<UTheme>as override levels #7050, refactor(module)!: movetheme.prefixtotailwindPrefix#7052 and refactor(theme)!: move the colors from the app config to the@nuxt/ui/colorsplugin #7053; the Vue side is the separate item below. Not removed: Nuxt layers mergeapp.configacrossextends, and Docus and the templates theme through that; a<UTheme>inapp.vuedoesn't merge across layers. In Nuxt,UAppreadsapp.config.uiand provides it as the root theme context; Vue users pass<UTheme>directly. Per key:colorsleaves (A6);unstyledstays in app config, forwarded as<UTheme unstyled>;icons(read in 73 runtime files) is also a<UTheme :icons>prop (feat(Theme): addvariantsandiconsprops #7046); per-component defaults are covered by<UTheme :props>; per-componentvariantswere the gap,<UTheme :variants>(feat(Theme): addvariantsandiconsprops #7046) (compoundVariantsstays in app config only, see A7);tvstays in app config only (decided 2026-09-27: app-wide, a per-subtree merge config has no use);prefixstays a module option, since its@source inline(...)build step needs it (it leavesthemeastailwindPrefix, decided 2026-09-27, since top-levelprefixis already the component-name prefixU), and the module forwards it into the root context. Principle: anything the runtime needs lives in our components (<UTheme>/<UApp>), shared by Nuxt and Vue; module options only remain where a build step needs the value. Wins: the engine stops importing#build/app.config(src/runtime/utils/tv.ts), and the engine's layer-order question collapses into "nearest<UTheme>wins" (refactor(theme)!: stack the app config and each<UTheme>as override levels #7050). Not adopting BEM-in-CSS overrides (.button--primaryin@layer components): the decision record already rejected hand-written component CSS because it breaks:ui, and no data attribute replaces it either (A7: no data attributes for what a prop decides). Slots needed the layer-order PR (decided 2026-09-26, review 15), refactor(theme)!: stack the app config and each<UTheme>as override levels #7050: every level puts its variants, slots and compounds after the whole theme, so<UTheme :ui>and app config slots behave the same.Build on Reka UI v3Dropped 2026-11-13: Reka won't ship v3 and keeps improving v2.feat(components)!: migrate to Reka UI v3 #7382 (v5 on3.0.0-alpha.0, merged 2026-11-12 as 3946168) is undone by refactor(components): go back to Reka UI v2 #7400 (merged 2026-11-13 as 5dedec3), v5 stays on Reka 2.x with@internationalized/date, no Temporal. The next generation targets ui-sdk instead, as a design system for every framework (see the open item below), so v5 should hide Reka from its public API. Original note: , confirmed for v5 on 2026-10-06, 5.0 does not ship on Reka 2.x** ([Epic] v3 Roadmap unovue/reka-ui#2721) — adopt the v3 base:useRender(drops the internalPrimitive/asChildwrapper), per-component subpath imports, ESM-only build, plus the perf overhaul and Shadow DOM support. Reka keeps its public component API intact, so it's mostly internal for us; the ESM-only + subpath-import parts touch our build/install, which is why it rides with the v5 cut. Dev-server payoff (Everything gets loaded on a fresh app #6296): the per-family subpath imports (feat(core): remove barrel file in favor of single exports unovue/reka-ui#2764) mean migrating our ~134from 'reka-ui'barrel-import files, and theSymbol.forcontext keys (fix(shared): create context withSymbol.forto fix duplicates unovue/reka-ui#2763) let us droptranspile: ['reka-ui'](src/module.ts, 0.8–1.2s first-request win) — both pulled forward into v4 as small PRs if they ship in a reka-ui 2.x release before the v3 cut. PR open 2026-11-10: feat(components)!: migrate to Reka UI v3 #7382 onreka-ui@3.0.0-alpha.0(published 2026-11-05 underalpha): Temporal replaces@internationalized/date, Nuxt UI installstemporal-polyfill-litefrom the app plugins (Nuxt server + async client plugin,@nuxt/ui/vue-pluginin Vue, fetched only whenTemporalis missing,temporal: true | 'full' | falseoption) since 2d275f4 (2026-11-10, reverses "no polyfill from us": Node has no Temporal, so every SSR app would throw), Calendar on Reka'sview/granularity,data-staterenames in 7 themes, Drawer on the v3 part names, migration guide section "Reka UI v3". Review fixes in e5d988f (transformMDC andcomponentMetaon Temporal, Calendar re-clamps onmaxView, Drawer allowsimperative-action, InputMenu search only takes typed text, full-calendar shim in the guide). Before merge: browser check (Calendar views, Tooltip delay, Tabs/Stepper states, Toaster/NavigationMenu exits now waiting on CSS transitions, focus return), retest UDropdownMenu, UContextMenu move elements on the page and remove page scroll #4619 / Opened USelect triggers background elements on hover #5350 / UPopover dismisses immediately when opened programmatically after a UDropdownMenu item selection #6463,pnpm run sizeagainstv5. The v3 follow-ups below were rechecked against Reka 2.11 on 2026-11-16: only the ones 2.11 can do stay open.Typegone with v3 (folded into feat(components)!: migrate to Reka UI v3 #7382, undone by refactor(components): go back to Reka UI v2 #7400; 2.11 has nodetails+before-update:modelValueon theupdate:*emits and drop thetoRawequality guardsdetailsorbefore-update).Movegone with v3. [Bug] UPopover appears on top of UModal based on component declaration order #6550 stays open.FieldGroupResetinside the content parts so closed popups skip the portal (reka#3104)gone with v3, 2.11 has nogetNavigationIntentreturningnullfor Home/End on InputMenu and CommandPalette (InputMenu does not support Home and End key navigation inputs #5634, [CommandPalette] move cursor to starting position in input box on pressing home #4145)getNavigationIntent. Those issues need another fix.Per-component subpath imports (reka#2996, Modal and slideover z-index bug #3079)gone with v3, 2.11 only exports the barrel.transpile: ['reka-ui']stays (Everything gets loaded on a fresh app #6296).Passgone with v3, 2.11's{ value, label, disabled }items toSelectRoot(reka#3111)SelectRoothas noitems.useOverlayfromupdate:openCompleteinstead of theafter:leavesplit inModal.vue(2.11 hasopenComplete).selectedin the item slots of Select / SelectMenu / InputMenu / Listbox / menus plus an optional check animation on the*ItemIndicator, which renders throughPresence(no code removed, theme only); Toaster reads--reka-toast-frontmost-heightinstead of its ownfrontHeight(~2 lines). Gone with v3: thehandleprop for detached triggers (reka#2826) and the shadow-root-aware portal default (reka#2725).Bump Reka once it releases fix: keep fallthrough attributes on parts whose template started with a comment unovue/reka-ui#3256 and chore(deps): update tailwindcss to ^4.0.4 (v3) #3257obsolete with v3 dropped, both fixed v3-only regressions.Temporal polyfillobsolete, v5 stays on@internationalized/date(refactor(components): go back to Reka UI v2 #7400).Dashboard template repo on Temporalobsolete, the/templates/dashboardguide onv5has no Temporal code since refactor(components): go back to Reka UI v2 #7400 (checked 2026-11-16).Move tiptap, embla and
@tanstack/vue-tablefromdependencies→peerDependencies+peerDependenciesMeta.optional— feat(components)!: move tiptap, embla and tanstack table to optional peer dependencies #6951. Landed as 15@tiptap/*(droppedextension-collaborationandextension-node-range, nothing in the runtime imports them, they're peers ofextension-drag-handle;extension-bubble-menu/extension-floating-menustay because the SFC compiler can't inferEditorToolbar's runtime props from a derivedComponentProps<typeof BubbleMenu>type), 8embla-carousel*(the plugins are dynamic imports but Vite still resolves them at transform time, so all of them are required),@tanstack/vue-tableat^8for now (the^9bump rides the v9 migration in Epic C).reka-uistays hard dep,@tanstack/table-corestays a devDep,@tanstack/vue-virtualstays a dep. No@tanstack/*renovate group: non-majors are already batched and only the v9 major needsvue-table+table-corebumped together, handled by hand in Epic C.Missing-peer error —
nuxt:ui:optional-depsplugin registered in both the Nuxt module (addBuildPlugin) and the Vue unplugin: an unresolved@tiptap/*/embla-carousel*/@tanstack/vue-tableimport coming from our runtime throws with the component name and the fullnpx nypm addline, only when the component is actually imported. Per-component install blocks on the Editor/Carousel/Table pages + a section in the v5 migration guide.Define a semver boundary for pass-through escape hatches — exactly three components hand out a third-party instance today:
Table(tableApi, the raw TanStackTable),Carousel(emblaApi, removed in feat(Carousel)!: build on Reka UI primitives #7406) andEditor(editor, the TipTap instance). Document that those objects follow their upstream library's semver, not ours, so an upstream major becomes a Nuxt UI minor with a release note instead of forcing a cut. They're literally third-party objects we forward, and we already tell people to read the upstream docs for them. Reka is the counter-example of why this is narrow: 134 files import from it, but it's fully wrapped, so Reka v3 is internal churn (see above). What this does not cover is a third-party type baked into everyday user code —TableColumn=ColumnDefand the 12 TanStack-typedv-models on Table are ours to version, which is exactly why v9 is still a major (Epic C). So the rule is: wrapped surface = our semver, forwarded instance = theirs. Pairs with the peer move above (a peer at^9already says "you pick the version"). Needs the docs pages for those three props to carry the note, plus a line in the versioning/migration doc.Drop
vaul-vueentirely (merged 2026-11-10 in feat(Drawer)!: replacevaul-vuewithreka-uiprimitives #6691). Drawer moves to Reka's native Drawer primitive (Epic C / feat(Drawer): add Drawer primitive unovue/reka-ui#2689 / PR feat(Drawer)!: replacevaul-vuewithreka-uiprimitives #6691), one fewer external dep on top of the Reka base. Checked 2026-10-05: the primitive merged on Reka'sv2on 2026-06-11 and ships in 2.x (2.11.0 release notes), so this does not depend on v3.Drop
motion-v(feat(components)!: removemotion-vdependency #7371, merged 2026-11-13): used byProseImgandChangelogVersionsonly. The zoom runs on the View Transitions API (no animation without it, a request made during the zoom is applied once it ends), the beam on a CSS scroll-driven animation of an inherited--ui-changelog-versions-progresswith ascaletransition for the trailing effect (Baseline since Firefox 159, 2026-10-27, no beam in older browsers).containernow means the nearest scroll container around the component.indicatorisboolean | { container }andindicatorMotiona boolean, so no motion types stay in the public API. Docs keep their ownmotion-v.Maybe rename docs
/vueinstall slugs →/vite(docs-only, non-breaking, v4-able) — the non-Nuxt path is really the Vite plugin (@nuxt/ui/vite+vite.config.ts), not "any Vue setup", so the installation +icons/color-mode/i18nintegration pages read better at/…/vite(pairs as "Nuxt module vs Vite plugin"). Keep the switcher label "Vue" (audience) +framework: vuefrontmatter — only the URL slug changes; ship 301s so old URLs keep working. Catch: the framework value doubles as the slug in the toggle's route-swap watcher (docs/app/pages/docs/[...slug].vue), so it needs a small{ nuxt, vue → vite }slug map; ~75 inbound links to sweep (mostlyicons/vue#themecomponent tips). The switcher label itself stays "Vue" — Vue UI libs organize by framework, not build tool.Explore UnoCSS support (decided to explore 2026-09-27, after this stack, not committed). Asked for since v2 ([Feature Request] UnoCSS #196, Support For UnoCSS #659, Is it possible to use UnoCss rather than tailwind css? #849, Question: Any plans to support UnoCSS in Nuxt UI 3? #2660, [Attempt] Exploring the Coexistence of Nuxt UI v3 and UnoCSS #3011, all closed). The stack made it realistic: static literal themes scannable from
node_modules(refactor(module): ship static themes #7037), no color x variant generation (refactor(theme)!: resolve colors through--ui-accentand removetheme.colors#7024, the scope is an arbitrary property UnoCSS parses), runtime prefix (refactor(theme)!: prefix classes at runtime #7035). Measured 2026-09-27:preset-wind4generates 1356 of the 1600 resolved theme classes out of the box with the aliases and accent roles as plaincolors; 132 need our per-utility tokens (text-mutedvsbg-mutedresolve to different vars through@themenamespaces--text-color-*,--background-color-*,--ring-color-*...); 105 are Tailwind 4 syntax it doesn't parse: 51(--var)shorthand, 26 baredata-*variants (data-selected:), 10not-*, 7transition-[a,b]lists, a few one-offs. The work: a@nuxt/ui/unocsspreset replacing the Tailwind-only plumbing (token rules for the 132,light/darkvariants for@custom-variant, a palette preflight for the@nuxt/ui/colorsplugin, content scanning + safelist for@source/@source inline), plus a choice for the 105: keep the themes to syntax both engines parse (h-[var(--x)],data-[selected]:,[&:not(…)]:, less idiomatic classes users see in the DOM) or add rules for them in the preset. Needs a CI test running the resolved class list through UnoCSS, like the Tailwindtheme classestest. Open question the exploration answers: do we want to own a second engine. Decided 2026-10-05: not in 5.0, a preset is 5.x at best and additive.tailwindPrefixkeeps its name: it is the manual fallback for the prefix Nuxt reads off@import "tailwindcss" prefix(tw), thetw:shape is Tailwind's, and a neutral key can be added later without a break. The coverage numbers above predate refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070.Theme authoring API, follow-up PR after the stack (design challenge 2026-09-28). Public
defineTheme/extendThemefrom@nuxt/ui/utils, a./theme/*package export, augmentableThemeUI/ThemeVariantstypes, an icons accessor, and one docs page for styling your own components with Nuxt UI themes. 2026-10-28, "Bring your own design system" plan, additive (feat(useComponentTheme): new composable #7326, merged 2026-10-29): auseComponentTheme(name, props, theme)composable replacing the three steps (for app components only, decided 2026-10-29: the library components keep the three steps), a publicextendTheme(card, …)with one merge (theapp.configone: classes added, a function replaces), and aCustomThemesinterface typingapp.config.ui.<name>and<UTheme>keys. Anapp/ui/*.tsfolder picked up by both adapters was prototyped and dropped (2026-10-28): it only saved the type lines, for a template splice, watchers, server restarts andjitiat runtime. Same plan: an official@nuxt/ui/eslintconfig onbetter-tailwindcssanswering ESLint integration for enforcing Nuxt UI design-system conventions #7061 (merged on v4 in feat(module): add@nuxt/ui/eslintconfig #7329 on 2026-10-29, replacing feat(module): add an@nuxt/ui/eslintconfig #7325 (closed): opt-inui.eslint: trueon v4, aliases read fromapp.config.ts;no-palette-colorsandno-conflicting-classeson by default,no-unknown-classesandenforce-logical-propertiesopt-in. On v5 since the 2026-10-29 sync (76645eda8): v5 token maps, aliases from@plugin "@nuxt/ui/colors", on by default when@nuxt/eslintand the plugin are installed, migration guide section andno-unknown-classestip), aget-component-themeMCP tool (docs(mcp): addget-component-themetool #7324, merged 2026-10-29: slots withdata-slot, variant values,defaultVariants,compoundVariants, CSS variables read and set,full: truefor variant classes, about 0.8k to 3k tokens per component, the docs chat uses it in place of its owngetComponentTheme), and (plan complete 2026-11-04, skill re-run on the builtdistand aligned in docs(skills): align the design system skill with the control scale #7359) a design-system adoption guide +nuxt-ui-design-systemskill (the A6 stable token contract; feat(theme): add a design system skill and exportcolorVariant#7334, merged 2026-11-02, with a publiccolorVariantin@nuxt/ui/utils/theme; its skill run found fix(colors): read the accent roles from minifiedaccent.css#7333 and chore(module): resolve@nuxt/ui/colorsexport when module is stubbed #7335, both merged. Open gap:--ui-control-*is set inside each component's size variants, so a denser control scale still takes app config entries on ~15 components. 2026-11-02, closing it (additive, no migration entry, no v5 #6918 line, feat(theme): add a shared control scale #7340, merged 2026-11-03): 35 tokens inbase.css(incl.--ui-control-box-<size>: Checkbox/RadioGroup box, Switch thumb and width),--ui-control-{px,py,gap,icon-size}-{xs,sm,md,lg,xl}plus--ui-control-text-<size>and--ui-control-text-<size>--line-height(lengths), the text also read by InputDate, InputTime, PinInput and the Checkbox/RadioGroup/Switch labels, read by the size variants of the themes exactly on the scale (Button, Input, InputNumber, InputTags, Select, FileUpload, Tabs (itsmdpx goes 3 → 2.5 to join the scale), Tree, so Textarea, InputMenu and SelectMenu follow) and by the menu items of DropdownMenu, ContextMenu, Listbox, CommandPalette, EditorSuggestionMenu and the Select/InputMenu/SelectMenu menus (pyas padding, set oncontent); Badge, Checkbox, RadioGroup, InputDate/InputTime, Calendar, Stepper and NavigationMenu keep their literals. Theme studio coverage of the tokens is a follow-up PR. Resolved values checked unchanged with an offline compile). feat(theme): add a design system skill and exportcolorVariant#7334, merged 2026-11-02: the skill +references/roles.md; the guide page was folded into the theme pages on 2026-11-02 (it restated them): then cut to what the docs lacked (2026-11-02: per-component size keys, Timeline fix,colorVariant, ESLint@themecaveat); the contract is CSS Variables documenting every variable, semver covers renames, no stability note on the page. Decided: the--ui-*names and utilities are public from 5.0, their default values may change in a minor, publiccolorVariantfrom@nuxt/ui/utils/theme. Tested on a fake DTCG system in the playground: the control scale is the gap (set inside each size variant, ~15 app config entries for a denser scale, additive fix in 5.x through global per-size variables). Proposed then dropped (2026-11-02): removing--ui-<color>-text-strongwould lighten neutraltext-accentin 18 themes (neutral's strong and default text differ), and--ui-font-headingis undocumented so already internal; the contract freezes as is. The run found fix(colors): read the accent roles from minifiedaccent.css#7333: added colors broke every build fromdist(minifiedaccent.css). Review found fix(colors): reject names whose variables Nuxt UI sets #7338 (merged):radius,gutter,overlaypassed as added color names and overwrote Nuxt UI variables.Stack follow-ups from the design challenge (2026-09-28): Nuxt reads the Tailwind prefix from the app's stylesheet when
tailwindPrefixis unset and warns on a mismatch (refactor(module)!: movetheme.prefixtotailwindPrefix#7052); detection also findsresolveComponent('u-button')and theme imports (#build/ui/<x>,#ui/theme/<x>,@nuxt/ui/runtime/theme/<x>), and a dev-only browser warning names a component that renders without its detected theme, through a self-accepting#build/ui/detectedtemplate (feat(module)!: detect the components in use by default #7058, Vue re-detection reloads it in feat(vite): detect newly used components while the dev server runs #7059, the Nuxt dev path still awaiting a manual check). Detection saves about 9 kB gzip for a typical app (25 components used: 22.5 → 13.1 kB), not the fixture's 14 kB.'*'countsapp.config.ui.<c>.defaultVariantsas the component's own default (refactor(Theme)!: movetheme.defaultVariantsto the app config and<UTheme :props>#7028).Vue: runtime
uiconfig off the virtual app config (noted 2026-09-29, not in the A/E stack). Status: feat(vite)!: move the ui config to the Vue plugin #7271 (merged 2026-10-23, export in docs(theme): export the studio theme as an app config #7272,tsconfig.app.jsonalias in docs(installation): add the bare theme type alias to tsconfig.app.json #7276, both merged):app.use(ui, { ui })merges over the build config in a newvue/plugins/app-configruntime plugin, function slots work; the Viteuioption is replaced by a top-leveliconsoption (bundled), the plugin option rejectsicons.prefix,colorModeandiconstill ride the virtual#build/app.config, thedefinepart was not done. Migration section "Vue pluginuioption".src/plugins/app-config.tsserves#build/app.configasJSON.stringifyof the Vite options:ui(overrides, icons,tv, derivedprefix),colorMode(read by the Vue stubs) andicon(VueIcon.vue). Proposal: runtimeuimoves to the Vue plugin install (app.use(ui, { ui })) or a root<UTheme>(the root context already comes from<UApp>since refactor(theme)!: read the app config through the theme context #7044), which also fixes function slots being dropped by the stringify (and a theme edit no longer restarts Vite); build-derived values (prefix,colorMode,icon) become Vitedefineconstants. Catch: the icons plugin readsui.iconsat build time to bundle them, so Vue keeps build options in the Vite plugin and overrides at runtime, two places unlike Nuxt's app config. Breaking for Vue (ui:leavesvite.config.ts). 2026-10-23, preferred shape (not decided): runtime overrides throughapp.use(ui, { ui }), a plain object like today and a cut-and-paste migration, setting the root context<UApp>reads; icons stay a build option on the Vite plugin for bundling, open whether asui.iconsor a top-levelicons. Touches the export item in Epic G (the Vue pane).Remove the deprecated options (2026-10-23, both merged).
inertiaon the Vite plugin, deprecated since v4.3 forrouter: 'inertia': refactor(vite)!: remove theinertiaoption #7274.mdc, deprecated forprose: refactor(module)!: remove themdcoption #7275, which also drops the@nuxtjs/mdcmodule dependencymdc: trueforced (apps add the module themselves). Pulled out of the Prose × Comark item, it doesn't depend on it.Hide Reka from the public API (decided 2026-11-13). Own prop types instead of
extends XxxRootProps(content, positioning, portal), owndata-*state attributes in the themes instead of Reka'sdata-state, own emit payloads. So the next generation can swap the primitives to ui-sdk without another user migration. Not sized yet: needs an audit ofsrc/runtime/componentsfor every Reka type, payload and attribute that reaches users. Full wrap isn't possible everywhere: TanStack column definitions and tiptap extensions stay upstream types.Next generation: a design system on ui-sdk for every framework (direction 2026-11-13, not v5). Shared themes, tokens and
tvengine (already almost framework-agnostic), one component package per framework on ui-sdk, Nuxt UI becomes the Vue package plus the Nuxt module. Ready-made components plus the ui-sdk behaviours styled with the same tokens. Waiting on: ui-sdk stable.Epic F: Migration & rollout
text-highlighted→text-strong,text-dimmed→text-faint,text-toned→text-default,text-inverted→text-contrast,bg-elevated→bg-soft,bg-accented→bg-strong,bg-inverted→bg-neutral,border-accented→border-strong,border-inverted→border-neutral,bg-muted→bg-tint,border-muted→border-default, andbg-elevated/50→bg-tintreplaced beforebg-elevated, full table in the migration guide) + Epic Capp.config.uislot-shape migration ({ base }→{ slots: { base } }on the 41 single-element themes, plusbase→rooton the 12 layout containers and EditorToolbar'sbase→root/root→menu, inapp.config.uiand literal:uiobjects) + the TanStack v9 renames (sortingFn→sortFn, pinningleft/right→start/end,columnSizingInfo→columnResizing), with non-fixable warnings fortableApi.getState()and thegetIsSome*RowsSelected()semantics flip. Open: there is no CLI to ride yet.cli/is@nuxt/ui-cli, a private workspace package with nobin, noversionand not inpackage.jsonfiles, sopnpm cli make componentis a contributor script andnpx nuxt-ui …does not exist. Pick one before writing transforms: add abinto@nuxt/uiand publish the scaffolding +migratecommands together, or ship the codemod as its own package. Shape staysmigrate v5for all transforms andmigrate v5/<name> <path>for one.app.config.ui.colors→ the@plugin "@nuxt/ui/colors"block in CSS (refactor(theme)!: move the colors from the app config to the@nuxt/ui/colorsplugin #7053),nuxt.configui.theme.*→ new homes (theme.colorsandtheme.transitionsremoved,theme.defaultVariants→app.config.ui.defaultVariants,theme.unstyled→app.config.ui.unstyled,theme.prefix→tailwindPrefix,experimental.componentDetection→componentDetection; same for the Vuevite.configui.theme.*), theapp.config.ui.tvkeys (twMerge→merge,twMergeConfig→ top-levelprefix/cacheSize, refactor(theme)!: rename theui.tvmerge keys and drop deprecated gradient utilities #7007 and refactor(theme)!: swaptailwind-mergeforcnbehind the merger seam #7011),*Sizevalues out of:ui/slots.app.config.ui.iconsstays where it is. Flag, don't rewrite:compoundVariantsinapp.config/<UTheme>(A7), user CSS targeting theme color classes like.bg-primaryinside components (A1).docs/…/3.migration.md— shipped on thev5branch (2026-09-16). Not the planned renumbering and not a3.migration/directory either (that was the first shape, since flattened):3.migration.mdstays one file and simply becomes the v5 guide on thev5branch, with v4’s version living on at the same path onv4. So there is no2.v4.md/navigation: falsechain to carry. The guide points at v5 #6918 and discussion Nuxt UI v5 Roadmap #6610, and tells people@nuxt/ui@next. Same source of truth as the codemod and the migrate skill. Still open: keeping it current as each breaking PR lands (the three-place rule under Branching & release), plus the Epic A6 token-contract doc +llms.txt. Dashboard traps to capture while both implementations are in-tree:collapsibleis a boolean onUDashboardSidebarand a union onUSidebar, andfalsedoes not map to'none'('none'skips the mobile menu branch entirely and renders inline at every width;falsestill gets a slideover on mobile) ·UDashboardGroup'sunit(templates setrem) needs auseResizableequivalent or persisted sizes silently change meaning · sidebar slot props are a codemod rule, not an alias —v-slot="{ collapsed, collapse }"→{ state, close }withcollapsed→state === 'collapsed', noting the semantic shift (dashboardcollapsed= desktop resize collapse;state === 'collapsed'on mobile = sheet closed) ·dashboard:*hooks: no template uses them, no replacement path needed.migrate-nuxt-ui-v4-to-v5agent skill — written 2026-10-08 as a thin runner inskills/migrate-nuxt-ui-v4-to-v5/SKILL.md, not as the codemod's residue. It holds no change list: it fetches3.migration.mdraw from thev5branch (theget-migration-guideMCP tool serves the guide of the site it runs on, soui.nuxt.comgives the v4 one until the v5 docs deploy), then analyzes the project, gives a plan, applies one section at a time and verifies. That removes the 2026-09-17 objection, a fourth place to keep in sync: the guide stays the only place, and its "can't be applied by a find and replace" paragraphs are what the skill reads for the non-mechanical cases. Install isnpx skills add https://github.com/nuxt/ui/tree/v5/skills/migrate-nuxt-ui-v4-to-v5untilv5is the default branch, thennpx skills add nuxt/ui --skill migrate-nuxt-ui-v4-to-v5. The::promptblocks of the migration and both installation pages follow the same analyze, plan, apply, verify shape, and the migration page and the skills page link the skill. Left: switch the guide URL to the docs site once the v5 docs are live, add a "run the codemod first" step when the codemod exists, and the Dashboard and TanStack v9 cases only reach the skill once their sections land in the guide.Epic G: Launch (landing redesign + live theme playground)
Both builds landed in
v4ahead of the branch, so what's left here is the v5 token surface, not the pages./themeroute on the docs layout rather than the dedicated/themeslayout the prototype was heading toward. Toolbar carries preset, colors (palette bezier editor + semantic shade controls), font, icons, radius and defaults; 12 presets, 9 preview views (component wall, landing, docs, saas, portfolio, dashboard, chat, changelog, editor), light/dark tabs, undo/redo, shuffle/reset, and an export modal emittingmain.css+app.config.ts/vite.config.tswith only what changed. A theme travels in?doc=, a query rather than a hash so the server sees it and a shared link paints on its first frame; the view mirrors into?view=.main.css+ config) with the preset pills under them, and below it the component wall and the template views share the studio's switcher, so the same theme reads as a dashboard, a chat, a docs site or a changelog. The nav rework rode along (Docs / Components / Theme / Templates / Showcase, no Resources dropdown), plus/releasesmoving into the docs sidebar, the team page rebuilt on/api/github/contributors.json, and the runtime Markdown move off@nuxtjs/mdcto Comark.Left for v5, every item gated on Epic A rather than on docs work:
docs/app/utils/themeordocs/app/components/theme-studiotoday; they need A2's--ui-shadow-*scale and the elevation ladder.docs/app/pages/theme.vuealready names the gap in a comment: the studio's preview is a card floating on a recessed canvas, the one background the semantic tokens can't express, since--ui-bg-*only ever elevates.--ui-shadow-*and--ui-border-width/--ui-ring-offset(A4). The--ui-shadow-*bridge was dropped on 2026-10-21 (it breaksshadow-<color>, see Not adopting), so a shadow axis needs another route.--font-heading(A4), feat(components): add heading font and weight variables #7258 (merged 2026-10-22): the studio writes--font-headinglive and in the export, the--font-serifelement rule is gone. The four Tailwind weight-step sliders became Body + Heading on the two weight variables, so the export no longer remaps--font-weight-*; doc keys aresans/heading/mono.[data-theme], and the studio's exporter is the first consumer of A6's flat[data-theme]blocks and the stable token contract. It emits the CSS color config (@pluginoptions or vars) instead ofapp.config.ts/vite.config.tscolors, and app config only for what remains root<UTheme>sugar. Done so far: the export emits the@plugin "@nuxt/ui/colors"block (refactor(theme)!: move the colors from the app config to the@nuxt/ui/colorsplugin #7053). Theapp.vue+<UTheme>export of docs(theme): export the studio theme as an app.vue with UTheme #7233 was reverted in docs(theme): export the studio theme as an app config #7272 (merged 2026-10-23): the export ismain.css+app.config.ts(icons included) for Nuxt,main.css+main.tswithapp.use(ui, { ui })for Vue plusvite.config.tsonly for a non-default icon set. Reason: the app config reacheserror.vueand islands, merges across layers, types added variant values and is already bundled (fix(module): bundle the icons set in app config #7238);<UTheme>is for subtrees and runtime switching. Docs (Components page, Theme page) lead with the app config again. The[data-theme]blocks wait on the A5 route.ui.defaultVariants(open question 5, resolved 2026-09-23). Done in refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070:sizeandcolorare app-wide and export asui.defaultVariants,variantexpands into per-componentdefaultVariants(utils/theme/engine/types.ts).Epic H: Own the styling engine (tv + merge layer)
v5 stops depending on
tailwind-variants: 3.3.x shipped a full internal rewrite as a minor with an 18 to 103x invocation regression, and v4 stays pinned to 3.2.2. The engine is one file,src/runtime/utils/tv.ts, and stays in-tree rather than becoming a package (decided 2026-09-17).tailwind-variantswith an in-tree variants engine #6964, refactor(theme)!: calltvwith the theme and its overrides #6975): replacestailwind-variantswith byte-identical output (zero snapshot churn) and is faster on every engine bench. Components calltv(theme, overrides), with the overrides keyed by content since Nuxt clones the app config per request and mutates it in place on HMR, so configured components share one compiled entry. The types derive from a single theme type.app.config.uiclasses win over the theme like:uidoes (fix(theme)!: letapp.config.uislot classes win over theme variants #6976, fix(theme): resolveapp.config.uivariants after the theme variants #6978): slot classes set inapp.config.uiused to lose to every theme variant and compound, and the only way around it was repeating the theme's variant combination. The order is now, last class winning: theme slots and variants,app.config.uivariants, theme compounds,app.config.uislots,app.config.uicompounds,:ui,class. It was chosen against the docs and nine template app configs, where it fixes three silent losses and changes nothing else.activeClass/inactiveClassnow apply afterclassinstead of losing to the theme's compounds. The order was replaced by the override levels of refactor(theme)!: stack the app config and each<UTheme>as override levels #7050 (Epic E, step 3), which is what ships.ui.tvmerge keys, drop deprecated gradient utilities (refactor(theme)!: rename theui.tvmerge keys and drop deprecated gradient utilities #7007):twMerge/twMergeConfigwere named after the library rather than the behaviour, so the public surface moved whenever the merger did; nowmerge/mergeConfig. Themes move off the deprecatedbg-gradient-to-*tobg-linear-*, which also removes the one family wheretailwind-mergemisreads our own classes (it groups the v3 syntax as a background colour, so a laterbg-<color>dropped the gradient). Follow-up straight onv5(chore(eslint): fail on deprecated Tailwind classes):better-tailwindcss/no-deprecated-classesis an error now, the 4 hits in docs fixed.src/runtime/themeis linted too (plugin 4.8.0, retargeted onv5inchore(eslint): lint v5 theme files with better-tailwindcss), and refactor(theme)!: write canonical Tailwind classes #7122 addedenforce-canonical-classes.v5(2026-09-23), no PR:useEditorMenuis no longer exported from the composables barrel (it imports TipTap), the unusedmergeClassesutil is removed, andtvtakes classes on slot functions only. All three are in the migration guide.RemoveDropped 2026-10-05 (see A7):compoundVariantsfrom the enginecompoundVariantsanddefaultVariantsstay engine primitives, in themes and inapp.config.ui. Was: once no theme uses them (see A7). That also removesmatchesCompoundand the compound part of the slot fingerprint.Epic I: Form (breaking)
Most of what's wrong with
UFormis internal and gets fixed in v4. v5 takes what changes behavior or types, independent of the theming chain.validate()includes nested forms by default. Verdict proposed 2026-10-26, not decided yet: flip it, submit already passesnested: true(Form.vueonSubmitWrapper) while the exposedvalidate()defaults tofalse,{ nested: false }stays the opt-out,validate({ name })keeps skipping nested forms. Separate PR from theForm<S>one. The docs say validating the parent validates every nested form, but only submit does: the exposedvalidate()defaults tonested: false. Flip the default,nested: falsestays as the opt-out.Form<S>types what a template ref returns. Verdict proposed 2026-10-26, not decided yet: the sameapiobject is exposed withdefineExpose(unwrapped on the template ref) and handed to nested forms (refs intact), soForm<S>becomes the unwrapped shape and the ref shape an internal type for the nested-forms map;validate()overloads return| falseonly withsilent: true. Types only. It typeserrors,loading,disabledanddirtyas refs, but a template ref unwraps them, soform.value.dirty.valuetype-checks and isundefinedat runtime.validate()is also typed| falsewithoutsilent: true, where it throws instead. Breaking for code that annotatesref<Form<typeof schema>>().UFormFieldon Reka'sFieldRoot,UFormstays as is. (reka#2830,FieldRootships in 2.11; reka#3143, which made every control work inside it, landed on v3, so check the 2.11 controls first.) Overlap:FieldRoot/FieldLabel/FieldDescription/FieldErrorreplace the hand-wired ids, labelfor,aria-describedby/aria-invalidand thebind: falsehack (FormField.vue:90-153,useFormField.ts:62-70,127-143), with better a11y on composite controls (Combobox trigger, PinInput, Slider thumbs, grouparia-labelledby). Conflicts: the field'snamewins over the input's in Reka (ours is the reverse),requiredwould turn on native validation (our<form>has nonovalidate), native inputs (Input, Textarea, FileUpload) needFieldControl, Reka's own validity and dirty/touched would be a second source of truth,error-patternhas no equivalent. Shape:FieldRoot :invalid="!!error" :disabledwithoutname/required, pinned ids, Reka validation left inert; size / color / highlight / the event bus stay inuseFormField. Breaks: newdata-invalid/data-dirty/data-touched/data-filled/data-focusedattributes, description and error ids unless pinned.UFormonFormRoot: not adopting (it rendersnovalidate, blocks submit on field validity before our schema runs, doesn't nest). Wait for the Field API to leave Alpha (Fieldset/FieldItemdeferred upstream).schemaprop isStandardSchemaV1 | Struct), and it validates withoutcoerce, sodefaulted()/coerce()never apply andtransformhas no effect for it. Applying coercion changes validated output for existing users, so it's a major either way: coerce or remove.Sequencing
unstyledand the VuecomponentDetectionport have landed; further non-breaking precursors land here as they come up).tailwind-variantswith an in-tree variants engine #6964 to refactor(theme)!: rename theui.tvmerge keys and drop deprecated gradient utilities #7007), A1 exit (closed color set, no theme reads module options, refactor(theme)!: resolve colors through--ui-accentand removetheme.colors#7024), E static themes and CSS, theme context,<UTheme :variants :icons>(refactor(Theme)!: movetheme.defaultVariantsto the app config and<UTheme :props>#7028 to feat(Theme): addvariantsandiconsprops #7046), layer-order PR (refactor(theme)!: stack the app config and each<UTheme>as override levels #7050), A6 (colors in CSS, refactor(theme)!: move the colors from the app config to the@nuxt/ui/colorsplugin #7053),componentDetectionon by default (feat(module)!: detect the components in use by default #7058) and the token vocabulary (refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070). What is left of the chain is A7 as size variables (refactor(theme)!: size controls through tokens #7116, open; the engine keepscompoundVariants), then the rest of Epics B, C and D.5.0.0-alpha.0until every item in this roadmap is done. A "5.x" or "additive" label says how an item ships, not that it comes after the alpha.Branching & release
v5rebased ontoorigin/v4(ef6b6934b), plus811cf6c3ere-applying the v5 slot conventions after the sync; feat(InputNumber): add leading and trailing slots #7259, feat(Drawer)!: replacevaul-vuewithreka-uiprimitives #6691 and feat(Tree)!: addvalueKeyprop and key items byvalue#6189 rebased onto it.v5is cut and live — branched 2026-09-16, first breaking change on it (feat(components)!: move tiptap, embla and tanstack table to optional peer dependencies #6951, optional peers). Version still reads4.11.3, no alpha published yet.v4; breaking PRs →v5.v5is rebased ontoorigin/v4, not merged — the repo has merge commits disabled, sov5stays “v4plus the breaking commits” and gets force-pushed with a lease after each sync. A PR opened againstv5has to be rebased after each sync.AGENTS.mdonv5): adiffsection under “Changes from v4” indocs/…/3.migration.md, the checklist in v5 #6918, and the roadmap discussion Nuxt UI v5 Roadmap #6610.v4. Pre-renaming means shipping both spellings, documenting the old one as dead, and carrying the shim until the cut, for a migration the codemod handles in one pass anyway.v4stays the default branch + npmlatestuntilv5is close;v5publishes prereleases (5.0.0-alpha.x, then betas) under thenexttag —scripts/release.shonv5already passes--tag nextand the migration guide tells people@nuxt/ui@next. Notalpha/beta, which were the v4 cycle's tags (checked 2026-10-08: the registry only haslatest). CI on both. Flip the default tov5near release.5.0.0release (or whenv5becomes the default branch): remove the paragraph under "Every breaking change must keep three places in sync" inAGENTS.mdthat says theSoonbadge convention does not apply tov5(added 2026-09-30,chore: no Soon badges on the v5 docs). Once v5 docs deploy on merge ahead of npm releases like v4 does, the badges are right again.src/runtime/plugins/colors.ts, rewrotesrc/templates.tsand movedsrc/theme/*tosrc/runtime/theme/*, andv4keeps touching all three. Every conflict resurfaces on each rebase until the v5 commit is reshaped, so land additive token scaffolding inv4first, keep the breaking theme edits in tight batches, and sync often so each replay stays small.Beta blockers (recorded 2026-09-28)
hover,tint,soft,strong,border-default25%,border-strong40%, see the merged entry in A6).selectorblocks on@nuxt/ui/colorsthat re-declare--ui-<alias>for both modes, or the point-of-use contract in 5.0. Note that an unlayered runtime rule, like the "Change colors at runtime" recipe, beats layered[data-theme]blocks, so the two need a documented order.@nuxt/ui/colorsplugin #7327 (merged 2026-11-01). Was closed for 5.0 on 2026-10-21.tertiary: indigoin@nuxt/ui/colorsadds a color everycolorprop takes, the ESLint config reads it too (bare alias for its own shades), the migration guide moves an extra v4 alias into the block withcolor="tertiary"kept. Discovery follows relative imports only. Follow-up: the repo's own lint can't load@nuxt/ui/colorsfrom thediststub, needed before a linted stylesheet in the repo uses the plugin. As built: the@nuxt/ui/colorsplugin accepts new names and emits their alias, role block, utilities and scope rules,tvspots acolorgroup by itsprimaryentry and scopes an unknowncolorat runtime, types through aUIColorsaugmentation the module generates from the plugin block (.nuxt/types/ui.d.ts, rootui.d.tson Vue). Removes the per-componentapp.configentries of the recipe. Original note: open it through the plugin (@plugin "@nuxt/ui/colors" { tertiary: … }adding acolorvalue), or state that it stays closed through v5. Deferred 2026-09-29, not in the Epic A/E stack. Options: keep closed for 5.0 (docs line, manual--ui-<name>+@theme inline+[--ui-accent:…]recipe; opening later is additive), or open through the plugin (tertiary: indigogenerating palette, alias, bridge, role rules, scope class andcolortype augmentation). The stack challenge recommends closed for 5.0.leading/trailing,square,increment/decrementread the size variables, so restyling a size through them keeps the room for an icon and the equal padding. Fields are answered by feat(components)!: hold the leading and trailing in the flow of the box #7192 (open), which reserves no padding for an icon any more. Still open: a plainpx-*on a Button or Badge replaces thesquarepadding.compoundVariantsstays.:root/.light/.dark, so a[data-theme]wrapper setting shades doesn't recolor inside. Settle the route. Meanwhile docs(theme): rework pages #7067 documents the working form, measured 2026-09-29: the subtree sets its shades and--ui-primary(400 under.dark); shades alone only movebg-primary-500.:propsnearest first. Decided 2026-10-05: kept as is, no code change. A nested'*'can't beat a farther component key orapp.config.ui.<c>.defaultVariants. One rule:'*'changes what the library default is, anything that names the component wins. Same as v4's componentdefaultVariantsovertheme.defaultVariants, and asapp.config.ui.defaultVariantstoday; for the same key props are already nearest first, and classes have no general key to compare with. Documented with the nested example at2.components/theme.md:56. Nearest first would need three rules (beats a farther key and the app config default, still loses to a theme's own default) and a Theme context that keeps its levels.'*'is new in v5, 0 of 14 consumers use it.primary: indigo 600andprimary: blackare build errors,primary: indigo 600 400andprimary: black whiteare the only shade forms, a palette alone keeps the defaults. Chosen over ablack/whiteflip (leavesneutral 900broken, irregular grammar) and over an error on loneblack/whiteonly. Relaxing it later is additive. No migration entry, the plugin is new in v5. Text on a dark single shade is a role problem,--ui-<alias>-text-contrast. feat(theme): require two shades in the colors plugin #7114, merged 2026-10-05 (plugin, spec, design-system page, theme studio serializer, docsshiki.ts).export * from './tv'and./utilsare both on v4 and./utilsis unchanged (16 types).tv.tswent from 4 exported types to 22: the 4 from v4, 12 the migration guide documents,SlotClassValue/TVVariantPropsin their signatures, and 4 of engine plumbing (TV,TVThemeCheck,DefinedTheme,ComponentOverrides), now tagged@internal(docs(types): mark the engine types internal, onv5). Rejected: a named export list (too noisy), and moving the types to@nuxt/ui/utils/@nuxt/ui/tv(breaks 20 v4 type imports, the import rewrite is not a find and replace, the four stay public from the subpath; re-exporting the engine types from@nuxt/ui/utils/tvstays possible later, additively). 0 of 14 consumers import any of them.tailwindPrefixname. Decided 2026-10-05: it stays, see the UnoCSS line in Epic E. Follow-up:findTailwindPrefixfollows relative@imports, fix(module): follow relative imports when reading the Tailwind prefix #7115, merged 2026-10-05 (onv5since v4 has no prefix detection). A warning when no Tailwind import is found is left out: it would fire for every app that imports Tailwind through an alias, a layer or a package.useComponentProps/useComponentOverridesstay public with their current signatures (a custom component built per the migration guide gets:propsby name and'*',:ui,:variants,unstyled); fix(module): skip the detection warning for the app's own components #7254 drops the "may still change" note and stops the dev detection warning from reporting the app's own components. Was: only one part blocks the beta, deciding whetheruseComponentProps/useComponentOverridesstay public with their current signatures; makingdefineTheme/extendTheme,./theme/*, the augmentable types and the docs page public is additive, 5.x is fine.**useComponentProps/useComponentOverridesare public but only in the migration guide;useThemeConfigisn't exported;ThemeDefaults/ThemeUIaren't augmentable for custom components.scanPackages, debounced and serializedbuilder:watchre-detection; all four reproduced in the playground first. v5 only, v4 detection is experimental and lacks the feat(module)!: detect the components in use by default #7058 scan. Detection is on by default, so a missed file ships a component without its CSS. Module layouts (app.layouts) and Content collections with a customsourcearen't scanned; the Nuxt re-detection isn't serialized; Nuxt has noscanPackages, so an SFC a page imports from outside the layers (monorepopackages/) isn't scanned (feat(module)!: detect the components in use by default #7058 review 2026-09-29, the dev warning points at listing it).usePrefix#7074 at the next v5 sync. Done:prefixedClassesinsrc/templates.tsgoes into the inline list withtailwindPrefix, so theusePrefix()literals are generated.unstyledapps, additive, 5.x.<UTheme unstyled>still ships the theme CSS; the entry without the theme@sourceisn't built.soft/subtleonaccent-soft. Done in refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070:alert.tsreadsbg-accent-softlike Badge and Button. The highlight contrast of SelectMenu/Select: highlighted option fails WCAG 1.4.11 — ~1:1 contrast between highlight and menu background #6588 stays open in A1.bg-muted's place. Settled by refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070:bg-mutedis gone and the code surfaces usebg-tint(migration guide, Semantic tokens).base) and Input (root) as examples, and CSS Variables lists the parts that set their own--ui-accent. No per-component slot table. Original note: The section showsbasefor Button androotfor Input only. Chip, DropdownMenu and ContextMenu items and labels, ProgressGroup, Timeline, NavigationMenu links and the Table loading bar set--ui-accenton other slots, so a custom color needs the slot name for each.--ui-accent,outline-inverted,fill-*,stroke-*), plus dark mode and multi-theme sections.Open questions (feedback welcome)
Motion tokensSettled: the easing shipped in v4 (fix(theme): unify motion easing and respectprefers-reduced-motion#6742) on Tailwind's--ease-*namespace. The rest of A3 (named--animate-*, skeleton toggle, tooltip-delay tokens) is additive and could ship in v4, it stays listed under Epic A for coherence.data-reduce-motionis dropped andtheme.transitionsis removed (decided 2026-09-23).-foreground— explicit token + defaults vs autooklch(from …)luminance.Runtime globalResolved 2026-09-23: app config becomes sugar for a rootdefaultVariants<UTheme>(Epic E), whose:propsalready set per-component defaults at runtime, per subtree;theme.defaultVariantsgoes withoptions.theme.--ui-bgfollow the neutral ramp instead of pure white (also surfaced by docs: add theme editor #6675)? Interacts with the A2 elevation ladders.Accent token namingResolved:accentis the indirection (Radix Themes precedent,data-accent-color), with the role names of refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070. The scope is the arbitrary property[--ui-accent:var(--ui-error)](refactor(theme)!: resolve colors through--ui-accentand removetheme.colors#7024):.accent-*classes collide with Tailwind'saccent-colorutility and a named@utilityscope breaks class merging, see A1.primarystays chromatic, defaultsky(see roadmap A1, default palettes). A monochrome default is not shipping, the caveat from the proposal being that everything signaling "on" (checked, active, selected, focus ring) leans on a chromatic primary.Not adopting / deferred
useToaston Reka's toast store (createToastManager/useToastManager/limit, reka#2985): not adopting (2026-11-10). Net ~50-70 lines deleted, but dedupe with pulse (Reka bumpsupdateKeythe same for a duplicate and anupdate), ourupdate(reopens and re-arms the timer),promise()from feat(useToast): addpromisemethod #7383, theexpandprop, keyboard-only expand and SSR throughuseStatewould all be rebuilt on top. Reka's stacking variables don't cover the viewport--height, the frozen position of a closing toast ordata-visible. Users would lose thetoastsref shape,max(limitkeeps extra toasts mounted and inert),remove(close) and the instantclear(). Revisit only if Reka adds a gap option, a total stack height, frozen closing positions and a way to tell a duplicate from an update.<UDefaults>provider — redundant:<UTheme :props>/<UTheme :ui>already give scoped, deep prop + slot-class defaults via provide/inject. Implicit contextual defaults (auto-restyle based on the ancestor component) intentionally skipped as too magic.--ui-field-*) —app.config.ui.input/<UTheme :ui>already restyle form controls globally and type-safely; a shared "all inputs at once" override is marginal and adds token surface.data-reduce-motionglobal — see the note under A3:prefers-reduced-motioncovers the real accessibility case (theme.transitionsis removed in Epic E), and a runtime toggle would push the whole motion system through var indirection for an opt-in nobody has asked for. Userland recipe documented instead.size="{ initial: 'sm', lg: 'xl' }", Buttons size based on device? #2390): rejected (2026-10-08). Possible now that we own the engine and the@source inline(...)list, butsizeis also passed to child components and injected throughuseFieldGroup/useFormField, so the object form would touch every prop type and every one of those paths, plus opt-in CSS for each size class at each breakpoint. Answered by a utility per size on top of the A7 variables instead.data-scrollbar: rejected (2026-09-23), polish orthogonal to the token story. Same for form-field tokens (--field-*).ChatMessages+ChatMessage, and template refs already cover what a provider is for. Same for aQuestionnairecomponent: clarifying questions are a docs recipe onRadioGroup/CheckboxGroup+addToolOutput.<UTheme unstyled>+ the(defaults) => classes:uireplace, with Reka UI underneath for full headless control.<dialog>refactor, TSisolatedDeclarations— internal/DX, evaluate separately; not v5 blockers.border-strongstays 300 in light. Lowering it to 200 would shift every field outline and neutral ring a second time after refactor(theme)!: one vocabulary for the semantic tokens and accent roles #7070, makestrongequaldefaultin light, and I preferred 300 on the subtle ring when compared.--ui-shadow-*bridge and the dark inset hairline (--ui-shadow-elevated): dropped (2026-10-21). Bridging--shadow-*to a variable removes Tailwind'svar(--tw-shadow-color, …)slot, soshadow-<color>stops recoloring every shadow in the app (checked against the compile output). Shadows stay on Tailwind's--shadow-*. Depth in dark mode comes frombg-overlaylifting the surface (feat(components): add an opt-in surface for floating layers #7252).--ui-container80rem → 90rem: dropped (2026-10-21). A silent 160px widening of every container, Page layout, template and the docs, for no recorded demand;--ui-container: 90remis one line.outlinehas bg-default,solidrenders as inverted/dark #6515): dropped (2026-10-21). The premise is false on v5: Buttonoutlinepaintsbg-defaultlike Card's and Button's neutralsolidis the same invertedbg-neutral, so the change would make Card disagree with Button. PageCard: inconsistent variant naming —outlinehas bg-default,solidrenders as inverted/dark #6515 has no reactions.links/actions→buttons: dropped (2026-10-21). It half-unifies:linksstill means navigation links on PageAnchors, PageLinks, ContentToc and ContentSearch, andactionsmeans something else on Prompt and ChatMessage. A renamed key in Nuxt Content YAML / MDC frontmatter (heroes, Docus pages) renders nothing with no type error and no codemod reach.--ui-border-width,--ui-ring-offset,--ui-cursor-*and afontSizescale (A4): dropped (2026-10-23). A border width variable turns about 150borderand 236ringutilities intoborder-(length:…)for a niche gain, the reason the studio's border axis went too. No theme uses a ring offset, focus draws withoutline-offset. A pointer cursor on buttons is the one-linebutton { cursor: pointer }Tailwind documents. Tailwind's--text-*variables already are the type scale.--ui-disabled-opacitystays planned.mdalready matches Buttonxsat 24px, the offset is intended, and a realignment would make the default Badge as tall as a Buttonmd.2xs/3xsbuttons were declined in feat(button): add support for 2xs and 3xs to button #6666, and since A7 a custom size is a few--ui-control-*variables in the app config.Issue index
#1284 #6588 #3307 (contrast) · #6608 (neutral-as-primary, closed) · #5657 (scoped theming) · #6515 (variant naming) · #6153 (filter) · #5803 (
:uireplace) · #5336 (close buttons) · #4953 #6169 (per-slot replace) · #6038 (unified headers) · #6551 (unstyled) · #6576 (focus rewrite, shipped) · #4955 (layout components) · #6340 (Sidebar resizable, closed — where de-dashboard was proposed) · #6598 (chat) · #6411 (variant coverage) · #6716 (slot naming, closed) · #6725 (pt→ richerui, closed) · #6675 (theme studio, shipped) · #6915 (docs nav + landing rework, shipped) · #6581 (size scales) · #2390 (responsive sizes) · #6296 (perf) · #6731 (componentDetection Vue port) · #6799 (TanStack Table v9) · unovue/reka-ui#2721 (Reka UI v3) · unovue/reka-ui#2689 (Drawer primitive → drop vaul-vue) · unovue/reka-ui#2763 (Symbol.for contexts) · unovue/reka-ui#2764 (subpath imports) · #6562 (:uireplace fn form, shipped) · #6742 (motion tokens, shipped) · #6031 (<UTheme :props>) · https://comark.dev (Comark)Feedback
Feedback on any item above is very welcome, ideally anchored to a specific one (the open questions especially). Please keep feature requests and new component requests out of this thread, since those aren't tied to a major and can ship in v4. As items firm up I'll spin them into their own issues and PRs.
All reactions