shellui-dev · Shewart · Jul 24, 2026 · Jul 24, 2026 · Jul 24, 2026 · Jul 24, 2026
diff --git a/ShellUI.slnx b/ShellUI.slnx
@@ -8,10 +8,15 @@
     <Project Path="src/ShellUI.CLI/ShellUI.CLI.csproj" />
     <Project Path="src/ShellUI.Components/ShellUI.Components.csproj" />
     <Project Path="src/ShellUI.Core/ShellUI.Core.csproj" />
+    <Project Path="src/ShellUI.Docs/ShellUI.Docs.csproj" />
     <Project Path="src/ShellUI.Templates/ShellUI.Templates.csproj" />
   </Folder>
   <Folder Name="/tools/">
     <Project Path="tools/ShellUI.SafelistGenerator/ShellUI.SafelistGenerator.csproj" />
   </Folder>
+  <Project Path="../docs/shelldocs/shelldocs/src/ShellDocs.Components/ShellDocs.Components.csproj" />
+  <Project Path="../docs/shelldocs/shelldocs/src/ShellDocs.Core/ShellDocs.Core.csproj" />
+  <Project Path="../docs/shelldocs/shelldocs/src/ShellDocs.Markdown/ShellDocs.Markdown.csproj" />
+  <Project Path="../docs/shelldocs/shelldocs/src/ShellDocs.Tokens/ShellDocs.Tokens.csproj" />
   <Project Path="ShellUI.Tests/ShellUI.Tests.csproj" />
 </Solution>
diff --git a/src/ShellUI.Docs/Components/App.razor b/src/ShellUI.Docs/Components/App.razor
@@ -0,0 +1,49 @@
+@using ShellUI.Docs.Components
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ShellUI — shadcn-flavoured Blazor components</title>
+    <base href="/" />
+
+    @* Cascade order matters — later files override earlier ones:
+       1. ShellDocs.Tokens  — neutral token baseline (--foreground, --card, …)
+       2. ShellDocs theme   — docs-chrome-specific extensions
+       3. ShellUI theme     — brand palette; overrides tokens where they collide
+       4. ShellUI utilities — compiled Tailwind classes used by ShellUI components
+       5. Site styles       — this project's own overrides *@
+    <link rel="stylesheet" href="_content/ShellDocs.Tokens/tokens.css" />
+    <link rel="stylesheet" href="_content/ShellDocs.Components/shelldocs-theme.css" />
+    <link rel="stylesheet" href="_content/ShellUI.Components/shellui-theme.css" />
+    <link rel="stylesheet" href="_content/ShellUI.Components/shellui-all.css" />
+    <link rel="stylesheet" href="site.css" />
+    <link rel="stylesheet" href="ShellUI.Docs.styles.css" />
+
+    <script>
+        (function () {
+            var q = new URLSearchParams(location.search).get('theme');
+            var saved = null;
+            try { saved = localStorage.getItem('shelldocs-theme'); } catch (e) {}
+            var systemDark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
+            var mode = q || saved || (systemDark ? 'dark' : 'light');
+            if (mode === 'dark') document.documentElement.classList.add('dark');
+        })();
+    </script>
+    <HeadOutlet @rendermode="RenderMode.InteractiveServer" />
+</head>
+<body>
+    <Routes @rendermode="RenderMode.InteractiveServer" />
+    <script src="_content/ShellDocs.Components/shelldocs.js"></script>
+    <script src="_content/ShellUI.Components/shellui.js"></script>
+    <script type="module">
+        import { createHighlighter } from 'https://esm.sh/shiki@1.24.0';
+        window.__shiki = await createHighlighter({
+            themes: ['github-light', 'github-dark'],
+            langs: ['razor', 'csharp', 'html', 'json', 'yaml', 'bash', 'typescript', 'javascript', 'markdown']
+        });
+        if (window.shelldocsHighlight) window.shelldocsHighlight();
+    </script>
+    <script src="_framework/blazor.web.js"></script>
+</body>
+</html>
diff --git a/src/ShellUI.Docs/Components/Pages/DocsPage.razor b/src/ShellUI.Docs/Components/Pages/DocsPage.razor
@@ -0,0 +1,62 @@
+@page "/docs/{*Path:nonfile}"
+@layout DocsLayout
+@using Microsoft.AspNetCore.Components.Sections
+@inject NavigationGraph Graph
+@inject MarkdownRenderer Renderer
+
+<PageTitle>@_title</PageTitle>
+
+@if (_document is not null)
+{
+    <MarkdownContent Document="_document" />
+    <PrevNextNav Prev="_prev" Next="_next" />
+
+    <SectionContent SectionName="docs-toc">
+        <TableOfContents Headings="_document.Headings" />
+    </SectionContent>
+}
+else
+{
+    <div class="doc-not-found">
+        <h1>Page not found</h1>
+        <p>The page <code>@Path</code> doesn't exist yet.</p>
+        <p><a href="/docs/introduction">Back to introduction</a></p>
+    </div>
+}
+
+<style>
+    .doc-not-found { padding: 3rem 0; }
+    .doc-not-found h1 { font-size: 1.5rem; font-weight: 600; margin: 0 0 0.5rem; }
+    .doc-not-found code {
+        background: var(--muted); padding: 0.125rem 0.375rem; border-radius: 4px;
+        font-family: var(--font-mono); font-size: 0.875em; border: 1px solid var(--border);
+    }
+</style>
+
+@code {
+    [Parameter] public string? Path { get; set; }
+
+    private RenderedDocument? _document;
+    private string _title = "";
+    private NavigationNode? _prev;
+    private NavigationNode? _next;
+
+    protected override void OnParametersSet()
+    {
+        var url = "/docs" + (string.IsNullOrEmpty(Path) ? "" : "/" + Path);
+        var node = Graph.ResolveByUrl(url);
+        if (node?.Path is not null && System.IO.File.Exists(node.Path))
+        {
+            _document = Renderer.RenderFile(node.Path);
+            _title = node.Title + " — ShellUI";
+            (_prev, _next) = Graph.GetPrevNext(node);
+        }
+        else
+        {
+            _document = null;
+            _title = "Not found — ShellUI";
+            _prev = null;
+            _next = null;
+        }
+    }
+}
diff --git a/src/ShellUI.Docs/Components/Pages/Home.razor b/src/ShellUI.Docs/Components/Pages/Home.razor
@@ -0,0 +1,46 @@
+@page "/"
+@layout HomeLayout
+
+<PageTitle>ShellUI — shadcn-flavoured Blazor components</PageTitle>
+
+@* Placeholder landing until the content branch adds a real hero. Keeps the
+   scaffold branch focused on wiring; a proper home page ships in
+   content/intro-and-3-proof-components. *@
+<div class="scaffold-home">
+    <h1>ShellUI</h1>
+    <p class="tagline">shadcn-flavoured Blazor components — the CLI-first component library.</p>
+    <p>
+        <a class="home-cta" href="/docs/introduction">Read the docs</a>
+    </p>
+</div>
+
+<style>
+    .scaffold-home {
+        max-width: 40rem;
+        margin: 6rem auto;
+        padding: 0 1.5rem;
+        text-align: center;
+    }
+    .scaffold-home h1 {
+        font-size: 3rem;
+        font-weight: 700;
+        letter-spacing: -0.025em;
+        margin: 0 0 0.75rem;
+    }
+    .scaffold-home .tagline {
+        color: var(--muted-foreground);
+        font-size: 1.1rem;
+        margin: 0 0 2rem;
+    }
+    .home-cta {
+        display: inline-block;
+        padding: 0.6rem 1.25rem;
+        background: var(--primary);
+        color: var(--primary-foreground);
+        border-radius: 9999px;
+        text-decoration: none;
+        font-weight: 500;
+        transition: background 150ms;
+    }
+    .home-cta:hover { background: color-mix(in oklch, var(--primary) 88%, transparent); }
+</style>
diff --git a/src/ShellUI.Docs/Components/Routes.razor b/src/ShellUI.Docs/Components/Routes.razor
@@ -0,0 +1,9 @@
+<Router AppAssembly="typeof(Routes).Assembly">
+    <Found Context="routeData">
+        <RouteView RouteData="routeData" DefaultLayout="typeof(ShellDocs.Components.Layouts.DocsLayout)" />
+    </Found>
+    <NotFound>
+        <PageTitle>Not found — ShellUI</PageTitle>
+        <p>Page not found.</p>
+    </NotFound>
+</Router>
diff --git a/src/ShellUI.Docs/Components/_Imports.razor b/src/ShellUI.Docs/Components/_Imports.razor
@@ -0,0 +1,15 @@
+@using System.Net.Http
+@using System.Net.Http.Json
+@using Microsoft.AspNetCore.Components
+@using Microsoft.AspNetCore.Components.Forms
+@using Microsoft.AspNetCore.Components.Routing
+@using Microsoft.AspNetCore.Components.Web
+@using Microsoft.AspNetCore.Components.Web.Virtualization
+@using Microsoft.JSInterop
+@using ShellDocs.Components
+@using ShellDocs.Components.Chrome
+@using ShellDocs.Components.Content
+@using ShellDocs.Components.Layouts
+@using ShellDocs.Core
+@using ShellDocs.Markdown
+@using ShellUI.Docs.Components
diff --git a/src/ShellUI.Docs/Program.cs b/src/ShellUI.Docs/Program.cs
@@ -0,0 +1,51 @@
+using ShellDocs.Components;
+using ShellUI.Docs.Components;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.WebHost.UseStaticWebAssets();
+
+builder.Services.AddRazorComponents()
+    .AddInteractiveServerComponents();
+
+builder.Services.AddShellDocs(o =>
+{
+    o.ContentRoot = Path.Combine(builder.Environment.ContentRootPath, "content");
+    o.SiteName = "ShellUI";
+    o.SiteTagline = "shadcn-flavoured Blazor components";
+    o.GitHubRepo = "shellui-dev/shellui";
+    o.LayoutVariant = DocsLayoutVariant.Sidebar;
+
+    o.AddNavLink("Documentation", "/docs/introduction");
+    o.AddNavLink("Components", "/docs/components");
+
+    /* Sidebar package selector — one entry per ShellUI monorepo package.
+       ShellDocs' PackageSelector hides itself if fewer than 2 packages are
+       declared; four is comfortably above that threshold. RootUrl paths are
+       matched by longest-prefix against the current URL to resolve which
+       package is "active". IconPath is optional — omit to fall through to
+       the default box glyph. */
+    o.AddPackage("shellui",            "ShellUI",            "The component library.",     "/docs/introduction",     "M3 3h7v7H3z M14 3h7v7h-7z M3 14h7v7H3z M14 14h7v7h-7z");
+    o.AddPackage("shellui.components", "ShellUI.Components", "60+ Blazor primitives.",     "/docs/components",       "M12 2 4 6v6c0 5 3.5 9.5 8 10 4.5-.5 8-5 8-10V6z");
+    o.AddPackage("shellui.cli",        "ShellUI.CLI",        "Add, list, scaffold.",       "/docs/cli",              "m8 6-6 6 6 6 M16 6l6 6-6 6");
+    o.AddPackage("shellui.templates",  "ShellUI.Templates",  "Starter markdown + files.",  "/docs/templates",        "M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z M14 2l6 6 M14 2v6h6");
+
+    /* Register every public ShellUI component under its type name so any of
+       them can be embedded in markdown via <Button />, <Alert />, etc. — or
+       inside a razor:preview fence. Marker type: any concrete ShellUI
+       component; Button is a stable anchor. Filter narrows the scan to the
+       ShellUI.Components assembly's own components (skips any nested test
+       doubles or generic base types). */
+    o.RegisterComponentsFromAssembly<ShellUI.Components.Button>(
+        t => t.Namespace?.StartsWith("ShellUI.Components") == true);
+});
+
+var app = builder.Build();
+
+app.UseStaticFiles();
+app.UseAntiforgery();
+
+app.MapRazorComponents<App>()
+    .AddInteractiveServerRenderMode();
+
+app.Run();
diff --git a/src/ShellUI.Docs/Properties/launchSettings.json b/src/ShellUI.Docs/Properties/launchSettings.json
@@ -0,0 +1,13 @@
+{
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": false,
+      "applicationUrl": "http://localhost:5299",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}
diff --git a/src/ShellUI.Docs/ShellUI.Docs.csproj b/src/ShellUI.Docs/ShellUI.Docs.csproj
@@ -0,0 +1,47 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <IsPackable>false</IsPackable>
+    <UserSecretsId>shellui-docs</UserSecretsId>
+    <RootNamespace>ShellUI.Docs</RootNamespace>
+  </PropertyGroup>
+
+  <!-- ShellDocs framework. Sibling repo on disk (docs/shelldocs/shelldocs/).
+       Swap to <PackageReference Include="ShellDocs.Components" Version="..." />
+       the moment 0.2.0-alpha lands on NuGet. -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\docs\shelldocs\shelldocs\src\ShellDocs.Core\ShellDocs.Core.csproj" />
+    <ProjectReference Include="..\..\..\docs\shelldocs\shelldocs\src\ShellDocs.Markdown\ShellDocs.Markdown.csproj" />
+    <ProjectReference Include="..\..\..\docs\shelldocs\shelldocs\src\ShellDocs.Tokens\ShellDocs.Tokens.csproj" />
+    <ProjectReference Include="..\..\..\docs\shelldocs\shelldocs\src\ShellDocs.Components\ShellDocs.Components.csproj" />
+  </ItemGroup>
+
+  <!-- ShellUI itself — the subject of these docs. Assembly-scanned at startup
+       so every component (Button, Alert, Command, …) is markdown-authorable. -->
+  <ItemGroup>
+    <ProjectReference Include="..\ShellUI.Components\ShellUI.Components.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Content Update="content/**/*.md;content/**/meta.json" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+
+  <!-- Sync the root-level images/ folder into wwwroot/images/ before build.
+       Source of truth stays at shellui/images/ — this target keeps
+       wwwroot/images/ in lockstep so Blazor's static-web-assets picks the
+       logos up under /images/*.png at runtime. Cheaper than Content <Link>
+       here because the static-web-assets pipeline only registers files that
+       physically live under wwwroot/. -->
+  <Target Name="SyncBrandLogos" BeforeTargets="AssignTargetPaths;Build">
+    <ItemGroup>
+      <_BrandLogo Include="..\..\images\*.png" />
+    </ItemGroup>
+    <Copy SourceFiles="@(_BrandLogo)"
+          DestinationFolder="$(MSBuildThisFileDirectory)wwwroot\images\"
+          SkipUnchangedFiles="true" />
+  </Target>
+
+</Project>
diff --git a/src/ShellUI.Docs/content/docs/installation.md b/src/ShellUI.Docs/content/docs/installation.md
@@ -0,0 +1,17 @@
+---
+title: Installation
+description: Set up ShellUI in a new or existing Blazor project.
+order: 2
+---
+
+# Installation
+
+Two paths depending on whether you're starting fresh or attaching to an existing Blazor project.
+
+<Callout Variant="info" Title="Placeholder">
+Full installation walkthrough migrates in the next content branch. This page exists so the scaffold has a second navigable route.
+</Callout>
+
+## Next
+
+- **[Introduction](/docs/introduction)** — back to the overview
diff --git a/src/ShellUI.Docs/content/docs/introduction.md b/src/ShellUI.Docs/content/docs/introduction.md
@@ -0,0 +1,25 @@
+---
+title: Introduction
+description: What ShellUI is and why it exists.
+order: 1
+---
+
+# Introduction
+
+ShellUI is a Blazor component library inspired by shadcn/ui — CLI-first, source-owned, Tailwind-styled. Every component you install lands as source in your project so you can restyle, extend, or delete it without a package upgrade.
+
+## What you get
+
+- 60+ accessible, keyboard-first Blazor components
+- Tailwind-driven, shadcn-flavoured design tokens
+- `shellui add <component>` CLI — copy source into your project on demand
+- SSR + WASM compatible out of the box
+
+## Where next
+
+- **[Installation](/docs/installation)** — get ShellUI running in a new or existing Blazor project
+- **[Components](/docs/components)** — the full component reference
+
+<Callout Variant="info" Title="Scaffold in progress">
+This docs site is being built with [ShellDocs](https://github.com/shellui-dev/shelldocs) — the docs framework by the same team. Content is being migrated from the previous Fumadocs-based site page-by-page.
+</Callout>
diff --git a/src/ShellUI.Docs/content/docs/meta.json b/src/ShellUI.Docs/content/docs/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Documentation",
+  "pages": ["introduction", "installation"]
+}
diff --git a/src/ShellUI.Docs/wwwroot/images/Shellui-dark.png b/src/ShellUI.Docs/wwwroot/images/Shellui-dark.png
diff --git a/src/ShellUI.Docs/wwwroot/images/Shellui-light.png b/src/ShellUI.Docs/wwwroot/images/Shellui-light.png