docs: redesign the Humanizer documentation experience

.impeccable/design.json

@@ -0,0 +1,101 @@
+{
+  "schemaVersion": 2,
+  "title": "Design System: Humanizer Documentation",
+  "updatedAt": "2026-07-29T20:30:55Z",
+  "northStar": "The Working Proof Sheet: an editorial, code-forward documentation world where real C# input and output prove Humanizer.",
+  "breakpoints": {
+    "smallPhone": "360px",
+    "phone": "480px",
+    "taskGrid": "48rem",
+    "desktopMax": "996px",
+    "desktopMin": "997px"
+  },
+  "colors": {
+    "paper": "#f7f3e9",
+    "paperRaised": "#fffdf7",
+    "ink": "#172026",
+    "inkMuted": "#566269",
+    "rule": "#c9c4b8",
+    "accentTeal": "#056b84",
+    "accentRust": "#ad3e2a",
+    "proofText": "#edf3f2",
+    "proofOutput": "#91d9e8",
+    "promiseTeal": "#045b6e",
+    "white": "#fff",
+    "promiseTextMuted": "#d7f3f8",
+    "promiseTextSoft": "#e5f6f9"
+  },
+  "typography": {
+    "docsDisplay": "Iowan Old Style, Baskerville, Times New Roman, serif",
+    "homeDisplay": "Avenir Next, Segoe UI, Helvetica Neue, sans-serif",
+    "body": "Avenir Next, Segoe UI, Helvetica Neue, sans-serif",
+    "readingMeasure": "72ch",
+    "identity": "0.9rem",
+    "label": "0.78rem",
+    "lede": "clamp(1.1rem, 2vw, 1.35rem)",
+    "proofLabel": "0.72rem",
+    "proofCode": "clamp(0.76rem, 2.4vw, 0.95rem)",
+    "installCode": "clamp(0.85rem, 2vw, 1rem)",
+    "routeHeading": "clamp(1.4rem, 3vw, 2rem)",
+    "referenceHeading": "1.25rem",
+    "promiseCopy": "1.1rem"
+  },
+  "components": [
+    {
+      "name": "Primary Button",
+      "className": "ds-button-primary",
+      "css": "background: var(--ifm-font-color-base); color: var(--ifm-background-color); min-height: 2.75rem; border-radius: 0;"
+    },
+    {
+      "name": "Text Link",
+      "className": "ds-text-link",
+      "css": "color: var(--ifm-link-color); text-decoration: underline; text-underline-offset: 0.2em;"
+    },
+    {
+      "name": "Proof Sheet",
+      "className": "ds-proof-sheet",
+      "css": "background: #172026; color: #edf3f2; border-radius: 0; padding: clamp(1rem, 3vw, 2rem);"
+    },
+    {
+      "name": "Task Route",
+      "className": "ds-task-route",
+      "css": "border-top: 1px solid var(--ifm-color-emphasis-300); padding-block: 1.5rem;"
+    },
+    {
+      "name": "Language Promise",
+      "className": "ds-language-promise",
+      "css": "background: #045b6e; color: #fff; border-radius: 0; padding: clamp(2rem, 5vw, 4rem);"
+    },
+    {
+      "name": "Navigation",
+      "className": "ds-navigation",
+      "css": "border-bottom: 1px solid var(--ifm-color-emphasis-300); box-shadow: none;"
+    },
+    {
+      "name": "Supported Culture List",
+      "className": "ds-supported-culture-list",
+      "css": "display: grid; grid-template-columns: repeat(auto-fit, minmax(7rem, 1fr)); gap: 0.75rem 1rem;"
+    }
+  ],
+  "effects": {
+    "shadow": "0 1px 0 var(--ifm-color-emphasis-300)",
+    "motion": "scroll-behavior: smooth"
+  },
+  "rules": [
+    "Teal signals navigation or capability; rust labels structure or focus.",
+    "Use ruled separation or a tone change instead of elevation.",
+    "Keep every claim version-correct and behaviorally verified.",
+    "Every listed culture supports every applicable localized feature."
+  ],
+  "dos": [
+    "Use deterministic runnable C#.",
+    "Reuse canonical assets.",
+    "Keep NuGet installation and proof in the first viewport.",
+    "Preserve visible focus and reduced-motion behavior."
+  ],
+  "donts": [
+    "Do not add cards, pills, gradients, decorative shadows, or invented imagery.",
+    "Do not invent metrics, customers, testimonials, or benchmarks.",
+    "Do not present partial-culture capability tiers."
+  ]
+}

DESIGN.md

@@ -0,0 +1,176 @@
+---
+name: Humanizer Documentation
+description: An editorial working proof sheet for human-friendly .NET APIs.
+colors:
+  paper: "#f7f3e9"
+  paper-raised: "#fffdf7"
+  ink: "#172026"
+  ink-muted: "#566269"
+  rule: "#c9c4b8"
+  accent-teal: "#056b84"
+  accent-rust: "#ad3e2a"
+  proof-text: "#edf3f2"
+  proof-output: "#91d9e8"
+  promise-teal: "#045b6e"
+  white: "#fff"
+  promise-text-muted: "#d7f3f8"
+  promise-text-soft: "#e5f6f9"
+  dark-paper: "#11191c"
+  dark-paper-raised: "#192327"
+  dark-ink: "#edf3f2"
+  dark-ink-muted: "#a9b9b9"
+  dark-rule: "#3a494d"
+  dark-accent-teal: "#63c4d8"
+  dark-accent-rust: "#f28b73"
+typography:
+  docs-display:
+    fontFamily: "Iowan Old Style, Baskerville, Times New Roman, serif"
+    fontSize: "clamp(2.25rem, 7vw, 4.5rem)"
+    fontWeight: 600
+  home-display:
+    fontFamily: "Avenir Next, Segoe UI, Helvetica Neue, sans-serif"
+    fontSize: "clamp(3rem, 8vw, 6rem)"
+    fontWeight: 760
+    lineHeight: 0.98
+    letterSpacing: "-0.04em"
+  section-heading:
+    fontFamily: "Avenir Next, Segoe UI, Helvetica Neue, sans-serif"
+    fontSize: "clamp(2.3rem, 6vw, 4.75rem)"
+    fontWeight: 720
+    lineHeight: 1
+    letterSpacing: "-0.04em"
+  body:
+    fontFamily: "Avenir Next, Segoe UI, Helvetica Neue, sans-serif"
+    fontSize: "1rem"
+    lineHeight: 1.65
+  label:
+    fontFamily: "Avenir Next, Segoe UI, Helvetica Neue, sans-serif"
+    fontSize: "0.78rem"
+    fontWeight: 800
+    letterSpacing: "0.16em"
+  identity:
+    fontSize: "0.9rem"
+  lede:
+    fontSize: "clamp(1.1rem, 2vw, 1.35rem)"
+  proof-label:
+    fontSize: "0.72rem"
+  proof-code:
+    fontSize: "clamp(0.76rem, 2.4vw, 0.95rem)"
+  install-code:
+    fontSize: "clamp(0.85rem, 2vw, 1rem)"
+  route-heading:
+    fontSize: "clamp(1.4rem, 3vw, 2rem)"
+  reference-heading:
+    fontSize: "1.25rem"
+  promise-copy:
+    fontSize: "1.1rem"
+rounded:
+  square: "0"
+  focus: "0.15rem"
+spacing:
+  xs: "0.4rem"
+  sm: "0.75rem"
+  md: "1rem"
+  lg: "1.5rem"
+  touch-target: "2.75rem"
+  home-gutter: "clamp(1rem, 4vw, 4rem)"
+  section-block: "clamp(5rem, 10vw, 9rem)"
+components:
+  button-primary:
+    backgroundColor: "{colors.ink}"
+    textColor: "{colors.paper}"
+    typography: "{typography.body}"
+    rounded: "{rounded.square}"
+    padding: "0.65rem 1.1rem"
+    height: "{spacing.touch-target}"
+  button-primary-hover:
+    backgroundColor: "{colors.accent-teal}"
+    textColor: "#fff"
+    rounded: "{rounded.square}"
+  proof-sheet:
+    backgroundColor: "{colors.ink}"
+    textColor: "{colors.proof-text}"
+    rounded: "{rounded.square}"
+    padding: "clamp(1rem, 3vw, 2rem)"
+  language-promise:
+    backgroundColor: "{colors.promise-teal}"
+    textColor: "#fff"
+    rounded: "{rounded.square}"
+    padding: "clamp(2rem, 5vw, 4rem)"
+---
+
+# Design System: Humanizer Documentation
+
+## Overview
+
+The Working Proof Sheet is a cream-paper and ink editorial world where real C#
+input and output prove the product. The homepage uses forceful sans-serif type;
+documentation uses an old-style serif for long-form headings. The canonical
+logo, ruled composition, restrained teal and rust accents, and code-forward
+examples replace decorative imagery, invented statistics, and card grids.
+
+The system is task-first, editorial, flat, version-visible, and accessible.
+
+## Colors
+
+Paper and raised paper form the reading surface. Ink and muted ink carry the
+content hierarchy. Teal signals navigation or capability; rust labels structure
+or focus. Neither becomes ambient decoration. Dark mode uses the paired dark
+tokens rather than inverting arbitrary values.
+
+## Typography
+
+Documentation headings use the serif display stack. Body copy, navigation,
+labels, and the homepage use the sans-serif stack. Homepage display text is
+tight and heavy; labels are compact and letter-spaced. Reading copy is limited
+to 72 characters per line.
+
+The Proof-Sheet Split: editorial serif establishes the reference manual while
+precise sans-serif type identifies controls, tasks, and executable proof.
+
+## Layout
+
+The homepage is capped at 90rem with a fluid gutter and generous section
+spacing. Task routes become a grid at 48rem. Documentation text remains within
+72ch. The shell accounts for 360px and 480px phones and the 996px/997px
+navigation transition. Tables stay contained; historical language coverage
+keeps its bounded sticky table. Interactive targets are at least 2.75rem high.
+
+## Elevation and Depth
+
+The interface is flat: no cards, gradients, or shadows. Paper tones,
+one-pixel rules, and whitespace establish hierarchy. The navigation boundary is
+the sole persistent elevation cue.
+
+Ruled-Not-Raised: use a rule or a tone change before introducing visual depth.
+
+## Shapes
+
+Buttons, proof sheets, task routes, and promises are square. A 0.15rem radius is
+reserved for focus treatments and existing shell controls.
+
+## Components
+
+- Primary button: ink on paper, changing to teal on hover.
+- Text link: underlined or rule-led; never disguised as a pill.
+- Proof sheet: dark code surface with distinct output color.
+- Task route: ruled text destination with a clear action.
+- Language promise: teal full-width statement of the localization contract.
+- Navigation: compact, version-visible, and separated by one rule.
+- Supported culture list: readable code list, not a partial-capability matrix.
+
+## Do
+
+- Use deterministic, runnable C# examples.
+- Reuse the canonical Humanizer logo and existing documentation assets.
+- Put the product promise, NuGet install command, and proof in the first viewport.
+- Use one-pixel rules, visible focus, and reduced-motion support.
+- Keep tables contained and use familiar public API names.
+
+## Do Not
+
+- Add card grids, pills, gradients, decorative shadows, or invented imagery.
+- Invent metrics, customers, testimonials, or benchmarks.
+- Use nondeterministic examples or hide keyboard focus.
+- Permit horizontal page scrolling.
+- Present cultures as tiers of partial feature support.

PRODUCT.md

@@ -0,0 +1,73 @@
+# Product
+
+<!-- impeccable:product-schema 1 -->
+
+## Platform
+
+web
+
+## Users
+
+The primary reader is a .NET developer who has a value to present and wants
+the shortest correct Humanizer call. Contributors are a secondary audience
+served by dedicated contribution references.
+
+## Product Purpose
+
+Humanizer is a mature .NET library that turns identifiers, dates, times,
+numbers, quantities, enums, and collections into text people can read.
+Humanizr.net is its versioned documentation and API reference. Success means a
+developer can identify the applicable API, install the matching NuGet package,
+and verify the call without learning Humanizer's internal localization model.
+
+## Positioning
+
+Humanizer exposes focused, familiar .NET extension methods such as
+`Humanize`, `Pluralize`, and `Singularize`. Localization is part of those
+operations rather than a separate formatting pass.
+
+## Operating Context
+
+Readers arrive with a typed .NET value and use the site to install Humanizer,
+find a task guide, copy a runnable example, or confirm an exact signature.
+Versioned guides, examples, search results, and API references must stay aligned
+with the selected NuGet package.
+
+## Capabilities and Constraints
+
+- Locale support is all-or-nothing: every listed culture supports every
+  applicable localized feature. Missing behavior or English fallback is a bug.
+- Current application documentation describes Humanizer 4 as a NuGet package.
+  Source checkout and build instructions belong only in contributor guides.
+- Historical documentation remains version-correct and must not inherit
+  unreleased APIs or current locale claims.
+- Application documentation uses public API language, not source-generator
+  ownership, locale inheritance, or linguistic implementation terminology.
+
+## Brand Commitments
+
+Preserve the Humanizer name, canonical logo, NuGet package identity, and
+direct developer-to-developer voice. Do not invent customers, testimonials,
+benchmarks, or product imagery.
+
+## Evidence on Hand
+
+- Canonical logo: `website/static/img/logo.png`
+- Runnable documentation examples: `website/docs/_examples`
+- Generated API reference: `website/docs/api`
+- Per-version manifest: `website/humanizer-versions.json`
+- Supported-culture inventory: `website/docs/languages/language-coverage.json`
+
+## Product Principles
+
+- Start from the programming task or value the reader already has.
+- Show runnable C# before detailed explanation.
+- Prefer familiar public API terms over internal taxonomy.
+- Keep every claim version-correct and behaviorally verified.
+- Treat accessibility as a release requirement.
+
+## Accessibility & Inclusion
+
+Meet WCAG AA contrast, preserve visible keyboard focus, support reduced motion,
+avoid horizontal page scrolling, and keep touch targets usable at narrow mobile
+widths.

tools/docs/generate-language-coverage.ps1

@@ -329,7 +329,7 @@ function Get-CurrentEvidence {
     return [ordered]@{
         coverageKind = "yaml-capabilities"
         versionKey = "current"
-        generatedFor = "main/preview"
+        generatedFor = "4.0"
         source = "src/Humanizer/Locales/*.yml"
         localesPath = [System.IO.Path]::GetFullPath($LocalesPath)
         package = [ordered]@{

tools/docs/snapshot.ps1

@@ -359,7 +359,7 @@ function Add-ApiLanding {
     )
 
     $provenance = if ($Entry.version -eq "current") {
-        "Generated from the ``main/preview`` ``$($Entry.apiPackage)`` checkout using the ``$($Entry.referenceTfm)`` reference assembly."
+        "Generated from the Humanizer 4 ``$($Entry.referenceTfm)`` reference assembly."
     } else {
         "Generated from ``$($Entry.apiPackage)`` ``$($Entry.source.packageVersion)`` using the ``$($Entry.referenceTfm)`` reference assembly."
     }

website/docs/analyzer/index.mdx

@@ -87,7 +87,7 @@ component selection.
 | Duplicate analyzer/load behavior on `3.0.8` | Upgrade to `3.0.10` for the fallback-selection fix. |
 | IDE and CI disagree | Compare SDK/MSBuild versions and the resolved package lock file, then restart the IDE after a clean restore. |
 
-The current preview also offers a separate words-to-number code fix on compiler
+Humanizer 4 also offers a separate words-to-number code fix on compiler
 diagnostics `CS0029` and `CS0266`. It wraps recognized Humanizer calls in a
 checked `int` conversion. That feature is not part of `HUMANIZER001` and is not
 present in `3.0.1`, `3.0.8`, or `3.0.10`.
@@ -116,7 +116,7 @@ diagnostic is clean.
 ## Version notes
 
 `HUMANIZER001` first appears in supported stable version `3.0.1` and retains
-default severity `error` through `3.0.10` and current preview. Analyzer loading
+default severity `error` through `3.0.10` and Humanizer 4. Analyzer loading
 is materially more robust at the `3.0.8` and `3.0.10` boundaries.
 
 ## Related guides and API

website/docs/api/index.md

@@ -6,4 +6,4 @@ sidebar_position: 2
 
 # Humanizer API reference
 
-Generated from the `main/preview` `Humanizer` checkout using the `net10.0` reference assembly.
+Generated from the Humanizer 4 `net10.0` reference assembly.