chore: scaffold ShellUI.Docs : ShellDocs-driven docs site skeleton

[Shewart]

Summary

Bootstraps the ShellUI docs site on top of ShellDocs — infrastructure only, no content migration. First branch in the shellui-docs Phase 3 dogfood series.

What ships

New project at src/ShellUI.Docs/ — a Blazor Web App wired to consume ShellDocs primitives + auto-register the whole ShellUI component surface. Added to both ShellUI.slnx and shellui.sln; dotnet sln add also brought in the transitive shelldocs project references so the IDE shows the whole two-repo dogfood tree in one solution.

Project structure

src/ShellUI.Docs/
  ShellUI.Docs.csproj             — Microsoft.NET.Sdk.Web
  Program.cs                      — AddShellDocs (Sidebar variant) + assembly-scan + AddPackage × 4
  Properties/launchSettings.json  — dev port 5299 (5099 belongs to shelldocs-preview)
  Components/
    App.razor                     — HTML shell + layered CSS cascade + theme script
    Routes.razor                  — Router, DefaultLayout = DocsLayout
    _Imports.razor                — usual ShellDocs.* + local namespaces
    Pages/
      Home.razor                  — placeholder home, @layout HomeLayout (top-nav)
      DocsPage.razor              — /docs/{*Path:nonfile} handler (from ShellDocs.Preview)
  content/docs/
    introduction.md               — placeholder with a <Callout> to prove inline components render
    installation.md               — placeholder second page so the sidebar has siblings
    meta.json                     — sidebar ordering
  wwwroot/
    site.css                      — site-level CSS overrides (font re-assertion — see below)

Registration — one line for the whole ShellUI surface

builder.Services.AddShellDocs(o =>
{
    o.LayoutVariant = DocsLayoutVariant.Sidebar;
    o.SiteName = "ShellUI";
    o.SiteTagline = "shadcn-flavoured Blazor components";
    o.GitHubRepo = "shellui-dev/shellui";
    o.AddNavLink("Documentation", "/docs/introduction");
    o.AddNavLink("Components", "/docs/components");

    o.AddPackage("shellui",            "ShellUI",            "The component library.",    "/docs/introduction", "…");
    o.AddPackage("shellui.components", "ShellUI.Components", "60+ Blazor primitives.",    "/docs/components",   "…");
    o.AddPackage("shellui.cli",        "ShellUI.CLI",        "Add, list, scaffold.",      "/docs/cli",          "…");
    o.AddPackage("shellui.templates",  "ShellUI.Templates",  "Starter markdown + files.", "/docs/templates",    "…");

    o.RegisterComponentsFromAssembly<ShellUI.Components.Button>(
        t => t.Namespace?.StartsWith("ShellUI.Components") == true);
});

Two ShellDocs APIs exercised end-to-end for the first time on a real consumer:

• RegisterComponentsFromAssembly<TMarker>(filter) from shelldocs' feat/consumer-registration-dx — one line registers ShellUI's ~60 public ComponentBase subclasses under their type names, so any of them is inline-renderable in markdown.
• AddPackage(id, title, description, rootUrl, iconPath) from shelldocs' fix/consumer-package-selector — sidebar dropdown now reflects ShellUI's four-package family (ShellUI, ShellUI.Components, ShellUI.CLI, ShellUI.Templates) instead of the hardcoded ShellDocs family that shipped before.

Cross-repo dependency chain

ShellDocs isn't on NuGet yet, so the csproj project-references the sibling shelldocs repo:

<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" />

Swap to <PackageReference Include="ShellDocs.Components" Version="0.2.0-alpha" /> etc. the moment shelldocs cuts its NuGet release — one-commit change, whole tree flips.

CSS cascade — deliberate layering

App.razor orders stylesheets so ShellUI's brand tokens win over ShellDocs' defaults:

1. _content/ShellDocs.Tokens/tokens.css              — neutral token baseline
2. _content/ShellDocs.Components/shelldocs-theme.css — docs chrome extensions
3. _content/ShellUI.Components/shellui-theme.css     — ShellUI brand palette (wins colors)
4. _content/ShellUI.Components/shellui-all.css       — compiled Tailwind bundle
5. site.css                                          — site-level overrides (wins font)

The site.css step re-asserts --font-sans: 'Inter var', 'Inter', … after ShellUI's theme file overrode it to Geist, sans-serif (ShellUI declares Geist but never ships or imports the webfont, so without this override the whole site falls through to system-ui). ShellDocs' tokens.css already @imports Inter from rsms.me at step 1, so with the re-assertion at step 5 the Inter webfont actually renders.

Dogfood fixes surfaced (all resolved in shelldocs before this branch merged)

• Hardcoded package selector — sidebar dropdown always showed ShellDocs / ShellDocs.Markdown / ShellDocs.Core / ShellDocs.CLI / ShellDocs.Components regardless of consumer. Logged in shelldocs' docs/SHELLUI_DOGFOOD_FIXES.md, fixed in shelldocs' fix/consumer-package-selector (new AddPackage(...) API + selector hidden when < 2 packages configured). This branch's Program.cs uses the new API from day one.

Verified

curl http://localhost:5299/                    → renders scaffold home (HomeLayout, top-nav)
curl http://localhost:5299/docs/introduction   → sidebar populated, dropdown shows "ShellUI"
curl http://localhost:5299/docs/installation   → renders, active-page state correct
build: dotnet build src/ShellUI.Docs           → 0 warnings, 0 errors

Not in scope (belongs on the content branch)

• Real Home page hero (this ships a deliberate placeholder with "Read the docs" CTA)
• Any actual content migration from docs/shellui-docs-fuma/
• CSS token collision testing between the three theme files under real inline-component pressure
• <ShellIcon> refs — waiting on the ShellIcons package; today's hand-embedded SVGs stay as-is

Next branch

content/intro-and-3-proof-components:

• Port introduction.mdx → introduction.md
• Port installation.mdx → installation.md
• Port quickstart.mdx → quickstart.md
• Port three diverse components (Button / Alert / Command — one per shape category) to prove the migration flow
• Log any friction into docs/SHELLUI_DOGFOOD_FIXES.md in the shelldocs repo as it surfaces

Test plan

• dotnet build src/ShellUI.Docs — 0 warnings, 0 errors
• Project appears in both ShellUI.slnx and shellui.sln — IDE picks it up
• dotnet run --project src/ShellUI.Docs → http://localhost:5299
  • / renders scaffold home via HomeLayout (top-nav visible, no sidebar)
  • /docs/introduction renders via DocsLayout with sidebar
  • /docs/installation renders, sidebar navigation active state correct
  • Inline <Callout Variant="info" Title="Scaffold in progress"> in introduction.md renders as a live Callout, not raw markup
  • Package-selector dropdown shows "ShellUI" as the active package, with ShellUI.Components / ShellUI.CLI / ShellUI.Templates as siblings
  • Inter font renders (verify by inspecting body computed font-family — should start with 'Inter var')
  • Dark-mode toggle (bottom-left of sidebar) flips theme, persists via localStorage