feat(docs): apply maintainer house style to the VitePress docs site

docs/.vitepress/config.ts

@@ -50,10 +50,39 @@ export default withMermaid(
     ignoreDeadLinks: true,
 
     head: [
-      ['meta', { name: 'theme-color', content: '#1f6feb' }],
+      ['meta', { name: 'theme-color', content: '#0073e6' }],
+      ['link', { rel: 'icon', type: 'image/png', href: '/logo.png' }],
+      ['meta', { property: 'og:type', content: 'website' }],
+      ['meta', { property: 'og:title', content: 'MTConnect.NET' }],
+      [
+        'meta',
+        {
+          property: 'og:description',
+          content:
+            'The .NET implementation of the MTConnect Standard — 100% public-surface API coverage, 100% MTConnect Standard compliance.',
+        },
+      ],
+      ['meta', { property: 'og:image', content: '/logo.png' }],
+      ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+      ['meta', { name: 'twitter:title', content: 'MTConnect.NET' }],
+      [
+        'meta',
+        {
+          name: 'twitter:description',
+          content: 'The .NET implementation of the MTConnect Standard.',
+        },
+      ],
+      ['meta', { name: 'twitter:image', content: '/logo.png' }],
     ],
 
     themeConfig: {
+      // The maintainer-supplied logo (`docs/img/mtconnect-net-03-md.png`,
+      // copied into `docs/public/logo.png`) already carries the
+      // 'mtconnect .NET' wordmark, so the text site title is hidden to
+      // avoid the wordmark rendering twice in the top nav.
+      logo: '/logo.png',
+      siteTitle: false,
+
       // Top nav: Compliance / Configure & Use / API / Concepts / Wire
       // formats / Modules / CLI / Cookbook / Troubleshooting.
       nav: [
@@ -224,6 +253,7 @@ export default withMermaid(
             text: 'Repository development',
             items: [
               { text: 'Documentation site', link: '/development/docs-site' },
+              { text: 'Docs-site house style', link: '/development/house-style' },
               { text: 'Release builder', link: '/development/builder' },
             ],
           },

docs/.vitepress/theme/index.ts

@@ -0,0 +1,15 @@
+/**
+ * VitePress theme entry for the MTConnect.NET documentation site.
+ *
+ * Extends the default theme and layers a small CSS override that
+ * remaps the brand palette to the TrakHound accent (`#0073e6`).
+ * Keeping the override in `./style.css` (rather than inlining a
+ * `<style>` block) lets VitePress hash the asset for cache-busting
+ * on each build.
+ *
+ * @see {@link https://vitepress.dev/guide/extending-default-theme}
+ */
+import DefaultTheme from 'vitepress/theme';
+import './style.css';
+
+export default DefaultTheme;

docs/.vitepress/theme/style.css

@@ -0,0 +1,24 @@
+/*
+ * Brand-palette override for the MTConnect.NET documentation site.
+ *
+ * The maintainer-supplied accent is #0073e6 (confirmed in discussion
+ * #184). VitePress derives the navigation highlight, link color,
+ * active-state border, and CTA button fill from --vp-c-brand-1, with
+ * -2 and -3 used for hover / pressed states. Light mode darkens the
+ * shade as the index grows; dark mode lightens it. The soft variant
+ * is the same hue at ~14-16% alpha for surface tints.
+ */
+
+:root {
+  --vp-c-brand-1: #0073e6;
+  --vp-c-brand-2: #1f86eb;
+  --vp-c-brand-3: #4ba0f0;
+  --vp-c-brand-soft: rgba(0, 115, 230, 0.14);
+}
+
+.dark {
+  --vp-c-brand-1: #4ba0f0;
+  --vp-c-brand-2: #1f86eb;
+  --vp-c-brand-3: #0073e6;
+  --vp-c-brand-soft: rgba(75, 160, 240, 0.16);
+}

docs/development/house-style.md

@@ -0,0 +1,39 @@
+# Docs-site house style
+
+This page records the documentation-site visual choices the maintainer signed off on. Each row cites the GitHub discussion thread the answer came from so a future contributor can see who decided what, when, and why. Treat this page as the canonical answer when a new docs PR proposes a brand, palette, typography, or social-share change — match what shipped, or open a new discussion to revise it.
+
+The source of record for the current set is [Discussion #184](https://github.com/TrakHound/MTConnect.NET/discussions/184), maintainer reply dated 2026-06-01.
+
+## What shipped
+
+| Surface | Answer | Source |
+| --- | --- | --- |
+| Logo | `docs/img/mtconnect-net-03-md.png`, copied into `docs/public/logo.png` and wired through `themeConfig.logo`. The asset already carries the `mtconnect .NET` wordmark, so `themeConfig.siteTitle` is hidden to avoid the wordmark rendering twice in the top nav. | Discussion #184 |
+| Accent color | `#0073e6` — the TrakHound brand accent. Overrides `--vp-c-brand-1`, `--vp-c-brand-2`, `--vp-c-brand-3`, and `--vp-c-brand-soft` for both light (`:root`) and dark (`.dark`) modes. Implementation lives in `docs/.vitepress/theme/style.css`. | Discussion #184 |
+| Typography | VitePress default. The maintainer expressed no strong preference, so no font-family override is applied. | Discussion #184 |
+| Hero block | A third call-to-action — `Download latest release` — links to `https://github.com/TrakHound/MTConnect.NET/releases/latest`. Sits between `Get started` and `View on GitHub`. | Discussion #184 |
+| Code-block syntax theme | VitePress default. Kept per the maintainer's preference. | Discussion #184 |
+| Favicon | `<link rel="icon" type="image/png" href="/logo.png">`. Same asset as the hero logo. | Discussion #184 |
+| Social-share preview | Open Graph (`og:type`, `og:title`, `og:description`, `og:image`) and Twitter Card (`twitter:card=summary_large_image`, `twitter:title`, `twitter:description`, `twitter:image`) meta tags in `head[]`. `og:image` and `twitter:image` both point at `/logo.png`. | Discussion #184 |
+| `theme-color` | `#0073e6` — updated from the previous `#1f6feb` to match the new brand accent. Drives mobile browser chrome color. | Bonus alignment with the accent change, not separately requested in #184. |
+| Google Analytics | Out of scope. The maintainer is wiring analytics on the deploy side; no GA `<script>` tag is added to the source. | Discussion #184 |
+
+## File map
+
+| Surface | File |
+| --- | --- |
+| Logo asset | `docs/public/logo.png` |
+| Brand-palette CSS override | `docs/.vitepress/theme/style.css` |
+| Theme entry that loads the override | `docs/.vitepress/theme/index.ts` |
+| Favicon + OG / Twitter meta + `theme-color` | `docs/.vitepress/config.ts` (`head[]`) |
+| `themeConfig.logo` + `themeConfig.siteTitle: false` | `docs/.vitepress/config.ts` (`themeConfig`) |
+| Hero `Download latest release` CTA | `docs/index.md` (front-matter `hero.actions`) |
+
+## Changing any of this
+
+The list above is a maintainer decision, not a contributor preference. Before opening a PR that revises an entry — re-skinning the palette, replacing the logo, switching the syntax theme, adding analytics — open a discussion that proposes the change and tag the maintainer. Link the resulting answer here once it merges, replacing the row that changed.
+
+## See also
+
+- [Documentation site](/development/docs-site) — how the site is built and how `DOCS_BASE` works.
+- [Discussion #184](https://github.com/TrakHound/MTConnect.NET/discussions/184) — the source-of-record thread for the current answers.

docs/index.md

@@ -5,10 +5,16 @@ hero:
   name: MTConnect.NET
   text: The .NET implementation of the MTConnect Standard
   tagline: 100% public-surface API coverage. 100% MTConnect Standard compliance.
+  image:
+    src: /logo.png
+    alt: MTConnect.NET
   actions:
     - theme: brand
       text: Get started
       link: /getting-started
+    - theme: alt
+      text: Download latest release
+      link: https://github.com/TrakHound/MTConnect.NET/releases/latest
     - theme: alt
       text: View on GitHub
       link: https://github.com/TrakHound/MTConnect.NET