Shewart · Oct 20, 2026 · Oct 20, 2026
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -3,7 +3,7 @@
   <!-- One version for every ShellUI package -->
   <PropertyGroup>
     <ShellUIVersion>0.4.0</ShellUIVersion>
-    <ShellUIVersionSuffix>alpha.2</ShellUIVersionSuffix>
+    <ShellUIVersionSuffix>alpha.3</ShellUIVersionSuffix>
   </PropertyGroup>
 
   <PropertyGroup>

diff --git a/README.md b/README.md
@@ -25,11 +25,11 @@
 | Channel | Version | Notes |
 |---|---|---|
 | Latest stable (recommended) | `0.3.4` | Tailwind CSS `4.3.2` |
-| Prerelease | `0.4.0-alpha.2` | This branch; install with `--version 0.4.0-alpha.2` |
+| Prerelease | `0.4.0-alpha.3` | This branch; install with `--version 0.4.0-alpha.3` |
 
 The CLI needs the .NET 10 SDK and works in Blazor projects on .NET 8, 9 and 10. The `ShellUI.Components` NuGet package targets .NET 10 only; on .NET 8 or 9, use the CLI.
 
-`main` is the 0.4 line, so this README and `docs/` describe `0.4.0-alpha.2`, including features that are not in a stable release yet, such as `shellui init --dashboard` and the auth blocks. For the stable version, read the [v0.3.4 docs](https://github.com/shellui-dev/shellui/tree/v0.3.4). Prereleases need `--version` to install.
+`main` is the 0.4 line, so this README and `docs/` describe `0.4.0-alpha.3`, including features that are not in a stable release yet, such as `shellui init --dashboard` and the auth blocks. For the stable version, read the [v0.3.4 docs](https://github.com/shellui-dev/shellui/tree/v0.3.4). Prereleases need `--version` to install.
 
 ShellUI is pre-1.0, so APIs and generated output can still change between minor versions. Validate it in your target Blazor and hosting environments before relying on it.
 

diff --git a/VERSIONING_STRATEGY.md b/VERSIONING_STRATEGY.md
@@ -6,7 +6,7 @@ ShellUI uses one centralized version for the source templates, CLI tool, and pac
 
 | Scope | Value |
 |---|---|
-| Version | `0.4.0-alpha.2` (prerelease; latest stable `0.3.4`) |
+| Version | `0.4.0-alpha.3` (prerelease; latest stable `0.3.4`) |
 | Target framework | .NET 10 |
 | Tailwind version | `4.3.2` |
 
@@ -19,13 +19,13 @@ The root `Directory.Build.props` supplies the version:
 ```xml
 <PropertyGroup>
   <ShellUIVersion>0.4.0</ShellUIVersion>
-  <ShellUIVersionSuffix>alpha.2</ShellUIVersionSuffix>
+  <ShellUIVersionSuffix>alpha.3</ShellUIVersionSuffix>
 </PropertyGroup>
 ```
 
 `Directory.Build.props` composes the package and assembly metadata:
 
-- `Version` becomes `0.4.0-alpha.2` with the suffix above, and `0.4.0` without one.
+- `Version` becomes `0.4.0-alpha.3` with the suffix above, and `0.4.0` without one.
 - `AssemblyVersion` and `FileVersion` use the numeric base `0.4.0`.
 - `InformationalVersion` includes the prerelease suffix.
 - Component metadata reads the centralized properties when running from the repository. `VersionHelper` uses assembly metadata as a fallback when its repository search does not find the solution file.
@@ -57,7 +57,7 @@ The CLI writes the computed version into `shellui.json` for each installed entry
   "InstalledComponents": [
     {
       "Name": "button",
-      "Version": "0.4.0-alpha.2",
+      "Version": "0.4.0-alpha.3",
       "InstalledAt": "2026-01-01T00:00:00Z",
       "IsCustomized": false
     }

diff --git a/docs/CLI_INSTALLATION.md b/docs/CLI_INSTALLATION.md
@@ -5,7 +5,7 @@
 | Context | Version |
 |---|---|
 | Latest stable (recommended) | `0.3.4`, needs the .NET 10 runtime |
-| Prerelease | `0.4.0-alpha.2`, install with `--version 0.4.0-alpha.2` |
+| Prerelease | `0.4.0-alpha.3`, install with `--version 0.4.0-alpha.3` |
 | Previous stable | `0.2.1` |
 | Tailwind | `4.3.2` |
 

diff --git a/docs/CLI_SYNTAX.md b/docs/CLI_SYNTAX.md
@@ -1,6 +1,6 @@
 # ShellUI CLI Syntax
 
-This reference covers CLI `0.4.0-alpha.2` (prerelease): it runs on .NET 10, sets up Blazor projects on .NET 8, 9 and 10, uses Tailwind CSS `4.3.2`, and has 93 direct component targets. Some options, such as `--dashboard`, are not in the stable 0.3.4; see the [v0.3.4 reference](https://github.com/shellui-dev/shellui/blob/v0.3.4/docs/CLI_SYNTAX.md) for that version.
+This reference covers CLI `0.4.0-alpha.3` (prerelease): it runs on .NET 10, sets up Blazor projects on .NET 8, 9 and 10, uses Tailwind CSS `4.3.2`, and has 93 direct component targets. Some options, such as `--dashboard`, are not in the stable 0.3.4; see the [v0.3.4 reference](https://github.com/shellui-dev/shellui/blob/v0.3.4/docs/CLI_SYNTAX.md) for that version.
 
 ## Command prefix
 
@@ -259,7 +259,7 @@ Representative fields look like this:
   "InstalledComponents": [
     {
       "Name": "button",
-      "Version": "0.4.0-alpha.2",
+      "Version": "0.4.0-alpha.3",
       "InstalledAt": "2026-01-01T00:00:00Z",
       "IsCustomized": false
     }

diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -6,7 +6,7 @@ Answers for the current ShellUI source and the currently published packages.
 
 ### Which version should I use?
 
-Use the latest stable release, `0.3.4`. It uses Tailwind CSS `4.3.2`. The `0.4.0-alpha.2` prerelease, with 93 direct component targets, needs `--version 0.4.0-alpha.2`:
+Use the latest stable release, `0.3.4`. It uses Tailwind CSS `4.3.2`. The `0.4.0-alpha.3` prerelease, with 93 direct component targets, needs `--version 0.4.0-alpha.3`:
 
 ```bash
 dotnet tool install -g ShellUI.CLI
@@ -145,7 +145,7 @@ A representative Tailwind and component record is:
   "InstalledComponents": [
     {
       "Name": "button",
-      "Version": "0.4.0-alpha.2",
+      "Version": "0.4.0-alpha.3",
       "InstalledAt": "2026-01-01T00:00:00Z",
       "IsCustomized": false
     }

diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
@@ -1,6 +1,6 @@
 # ShellUI Quick Start
 
-This quick start uses ShellUI `0.4.0-alpha.2`, a prerelease, with Tailwind CSS `4.3.2`. The CLI needs the .NET 10 SDK and works in Blazor projects on .NET 8, 9 and 10.
+This quick start uses ShellUI `0.4.0-alpha.3`, a prerelease, with Tailwind CSS `4.3.2`. The CLI needs the .NET 10 SDK and works in Blazor projects on .NET 8, 9 and 10.
 
 ## Prerequisites
 
@@ -20,7 +20,7 @@ dotnet --version
 A global tool is invoked as `shellui`:
 
 ```bash
-dotnet tool install -g ShellUI.CLI --version 0.4.0-alpha.2
+dotnet tool install -g ShellUI.CLI --version 0.4.0-alpha.3
 shellui --version
 ```
 

diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md
@@ -1,5 +1,61 @@
 # ShellUI Release Notes
 
+# ShellUI v0.4.0-alpha.3 🧪
+
+> The third 0.4 prerelease. A component's `Class` now overrides its own classes, dialogs and sheets keep keyboard focus inside, `add` never downgrades your NuGet packages, and the CLI templates have been brought in line with the NuGet package, fixing several template bugs on the way. It also adds Razor class library support. It is a prerelease, so installs need `--version`. Report issues via [GitHub Issues](https://github.com/shellui-dev/shellui/issues).
+
+## ✨ Improvements
+
+- **`Class` overrides a component's own classes.** `Shell.Cn` used to join strings, so `<Card Class="max-w-lg">` on a component that sets `max-w-md` put both on the element and the stylesheet decided. Now, when two classes set the same CSS property under the same variants, the later one (yours) wins, like tailwind-merge: `p-4` replaces an earlier `px-2`, text colour and text size stay separate, and unknown classes are kept. You no longer need the `!` modifier. The NuGet package and the CLI's `Shell.cs` share the same code.
+- **Focus stays inside open overlays.** `Dialog`, `AlertDialog`, `Sheet` and `Drawer` keep Tab and Shift+Tab inside while they're open, and return focus to where it was when they close. The legacy (non-compositional) `Sheet` and `Drawer` panels now also take focus and close on Escape.
+- **`add` never downgrades a NuGet package.** It used to set the exact version a component pins, so adding `chart` to an app on Blazor-ApexCharts 7 moved it back to 6.0.2. Now it reads the project's `PackageReference` (or `Directory.Packages.props`), adds a missing package or raises an older one, and leaves the same or newer, floating versions and ranges alone.
+- **Razor class libraries.** `init` recognises a library shared by several apps and prints what each app needs, with the library's `_content` path, and adds its `@using` to a root `_Imports.razor`. [Using ShellUI from a Razor class library](https://github.com/shellui-dev/shellui/blob/main/docs/razor-class-library.md) has the full setup for Blazor Web App and MAUI Blazor Hybrid hosts.
+
+## 🐛 Fixes: CLI templates now match the package
+
+The CLI templates and the NuGet package had drifted apart. They're reconciled (210 of 217 components identical, the rest differ by design), and a test now compares them. Bugs this fixed:
+
+- **`RadioGroup`** (template): clicking an item did nothing, because the group never passed itself to its items. `RadioGroupItem` also gains `Disabled`.
+- **`ScrollArea`** (template): long content was clipped instead of scrolling. `Height` and `MaxHeight` now size the scrolling element.
+- **`DatePicker`** (package): day 1 was always drawn under Sunday. It now sits under its real weekday, and the picker opens on the selected month.
+- **`TimePicker`**: `Step` now filters the minutes (it was ignored), the picker opens on the current value, and Cancel or an outside click closes it.
+- **`DateRangePicker`** (template) closes on an outside click; **`EmptyState`** (template) applies `Class`.
+- **`Sheet` and `Drawer`**: clicks inside the panel no longer reach parent click handlers; the close button shows when only `Description` is set; the templates switch to compositional mode by themselves (no `Compositional="true"` needed).
+- **`Label`** renders `For` as the `for` attribute; **`FileUpload`** uses an inline SVG icon instead of the Material Symbols font; **`CarouselItem`** handles zero slides.
+- **`Pagination`** supports `@bind-CurrentPage` in both copies and ignores clicks on the current page; **`Toast`** has success and warning variants, `Position`, auto-dismiss after `Duration` (0 keeps it open) and a labelled close button; **`Skeleton`** has `Variant` (`default`, `circle`, `text`); **`NavigationMenuItem`** is a dropdown when `Title` is set and a link or button otherwise.
+- `Table`, `Separator`, `Slider`, `Navbar`, `Checkbox`, `Switch`, `Tooltip`, `SidebarMenuButton`, `Menubar` and `ThemeToggle` templates now match the package's markup and classes.
+
+## ⚠️ Breaking changes (CLI templates, after `shellui update`)
+
+- **Input variants** moved out of the component: `Input.InputVariant.Error` is now `InputVariant.Error`, from the new `input-variants` template in `Components/UI/Variants` (like `ButtonVariant`). `Textarea` gains `Variant`, `ReadOnly`, `OnFocus` and `OnBlur` through `textarea-variants`.
+- **Stepper** parts read the stepper's `ActiveStep` instead of taking a `CurrentStep` parameter, and the template gains the package's data-driven `StepItems` mode (`StepItem` comes from the new `stepper-models` template).
+- **ScrollArea** drops its `scrollbar-*` classes, which needed a Tailwind plugin nobody shipped.
+- Still working but deprecated: `Pagination.OnPageChange` (use `@bind-CurrentPage`), `DatePicker.SelectedDate` and `TimePicker.SelectedTime` (use `Value` / `@bind-Value`).
+
+`shellui update` installs the new `input-variants`, `textarea-variants` and `stepper-models` templates for you, and skips files you've changed since installing them.
+
+## ⬆️ Upgrading from 0.4.0-alpha.2
+
+- **CLI:** update the tool, then run `shellui update`. Commit first so you can review the changes, and fix any `Input.InputVariant` and Stepper `CurrentStep` uses (see above).
+- **NuGet package:** update `ShellUI.Components` to `0.4.0-alpha.3`.
+- If you used `Class="…!"` to beat a component's own classes, you can drop the `!`.
+
+## 📦 Installation
+
+```bash
+# CLI (prerelease: the version is required)
+dotnet tool install -g ShellUI.CLI --version 0.4.0-alpha.3
+# or upgrade an existing install
+dotnet tool update -g ShellUI.CLI --version 0.4.0-alpha.3
+```
+
+```bash
+# NuGet package
+dotnet add package ShellUI.Components --version 0.4.0-alpha.3
+```
+
+**Full Changelog**: https://github.com/shellui-dev/shellui/compare/v0.4.0-alpha.2...v0.4.0-alpha.3
+
 # ShellUI v0.4.0-alpha.2 🧪
 
 > The second 0.4 prerelease. It fixes `shellui update`, which could leave a project upgraded from 0.3 unable to build, and makes `update` keep the files you changed. The Tailwind CLI is now downloaded once per machine instead of into every project, and the download survives slow connections. It also fixes `remove`, the dark theme and the package `TimePicker`. It is a prerelease, so installs need `--version`. Report issues via [GitHub Issues](https://github.com/shellui-dev/shellui/issues).

diff --git a/src/ShellUI.Core/Models/ComponentMetadata.cs b/src/ShellUI.Core/Models/ComponentMetadata.cs
@@ -66,7 +66,7 @@ private static string GetCurrentVersion()
         if (assemblyVersion != null)
             return assemblyVersion.InformationalVersion.Split('+')[0];
 
-        return "0.4.0-alpha.2";
+        return "0.4.0-alpha.3";
     }
 }
 
diff --git a/src/ShellUI.Templates/VersionHelper.cs b/src/ShellUI.Templates/VersionHelper.cs
@@ -51,7 +51,7 @@ public static string GetCurrentVersion()
             return _cachedVersion;
         }
 
-        return "0.4.0-alpha.2";
+        return "0.4.0-alpha.3";
     }
 
     private static string? FindSolutionRoot()