Merge pull request #1 from MHToolkit/feat/apple-design-baseline

feat: apply organization Apple design baseline

Author: VincentAdamNemessisX

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: Website checks
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  static-site:
+    name: Static site and design contract
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Verify Apple Design contract
+        run: python -m unittest discover -s tests -p 'test_*.py'
+      - name: Serve and smoke-test the published document
+        run: |
+          python -m http.server 8765 --directory . >/tmp/mhtoolkit-site.log 2>&1 &
+          server_pid=$!
+          trap 'kill "$server_pid"' EXIT
+          curl --fail --retry 5 --retry-connrefused http://127.0.0.1:8765/
+      - name: Reject whitespace errors
+        run: git diff --check

assets/design-tokens.css

@@ -0,0 +1,67 @@
+:root {
+  color-scheme: dark;
+  --surface-window: #071019;
+  --surface-sidebar: rgba(12, 26, 40, 0.78);
+  --surface-content: rgba(18, 39, 58, 0.94);
+  --separator: rgba(150, 210, 255, 0.22);
+  --label-primary: #ecf7ff;
+  --label-secondary: #a9bdcd;
+  --accent: #4dd2ff;
+  --state-success: #89ffcb;
+  --state-warning: #ffd166;
+  --state-error: #ff7b86;
+  --motion-response: 380ms;
+  --motion-easing: cubic-bezier(.2, .8, .2, 1);
+  --target-minimum: 44px;
+  --focus-ring: 0 0 0 3px rgba(77, 210, 255, 0.55);
+}
+
+a, button {
+  transition: color var(--motion-response) var(--motion-easing),
+              background-color var(--motion-response) var(--motion-easing),
+              transform var(--motion-response) var(--motion-easing);
+}
+
+a:focus-visible, button:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
+}
+
+.button, .links a {
+  min-block-size: var(--target-minimum);
+  display: inline-flex;
+  align-items: center;
+}
+
+.project-link h2 a {
+  min-block-size: var(--target-minimum);
+  display: inline-flex;
+  align-items: center;
+}
+
+.project-link:hover { transform: translateY(-2px); }
+.status[data-state="planning"] { border-inline-start: 4px solid var(--state-warning); }
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    scroll-behavior: auto !important;
+    transition-duration: 0.001ms !important;
+    animation-duration: 0.001ms !important;
+    animation-iteration-count: 1 !important;
+  }
+}
+
+@media (prefers-reduced-transparency: reduce) {
+  :root {
+    --surface-sidebar: #0c1a28;
+    --surface-content: #12273a;
+  }
+  .logo-card { backdrop-filter: none !important; }
+}
+
+@media (prefers-contrast: more) {
+  :root {
+    --separator: rgba(236, 247, 255, 0.68);
+    --label-secondary: #d6e4ef;
+  }
+}

docs/design/accessibility-tree-2026-07-19.yml

@@ -0,0 +1,54 @@
+- generic [active] [ref=e1]:
+  - banner [ref=e2]:
+    - navigation [ref=e3]:
+      - link "MH Toolkit home" [ref=e4] [cursor=pointer]:
+        - /url: /
+        - img "MH Toolkit Nemessix shield logo" [ref=e5]
+        - generic [ref=e6]: MH Toolkit
+      - navigation "Project navigation" [ref=e7]:
+        - link "Projects" [ref=e8] [cursor=pointer]:
+          - /url: "#projects"
+        - link "Releases" [ref=e9] [cursor=pointer]:
+          - /url: https://github.com/MHToolkit/mh-toolkit
+        - link "GitHub" [ref=e10] [cursor=pointer]:
+          - /url: https://github.com/MHToolkit
+  - main [ref=e11]:
+    - generic [ref=e13]:
+      - generic [ref=e14]: macOS · Android · classic hunting tools
+      - heading "MH Toolkit" [level=1] [ref=e15]
+      - paragraph [ref=e16]: "An organization-level toolkit ecosystem for classic Monster Hunter emulation: focused repositories for overlays, emulator integration, saves, multiplayer, content tooling, and coordinated releases for macOS and Android."
+      - generic [ref=e17]:
+        - link "View the hub" [ref=e18] [cursor=pointer]:
+          - /url: https://github.com/MHToolkit/mh-toolkit
+        - link "GitHub organization" [ref=e19] [cursor=pointer]:
+          - /url: https://github.com/MHToolkit
+    - region "Project areas" [ref=e21]:
+      - article [ref=e22]:
+        - heading [level=2] [ref=e23]:
+          - link "Nemessix" [ref=e24] [cursor=pointer]:
+            - /url: https://github.com/MHToolkit/nemessix
+        - paragraph [ref=e25]: A capability-driven Nintendo engine platform with a unified library and platform-native multiplayer coordination.
+      - article [ref=e26]:
+        - heading [level=2] [ref=e27]:
+          - link "MH Overlay" [ref=e28] [cursor=pointer]:
+            - /url: https://github.com/MHToolkit/mh-overlay
+        - paragraph [ref=e29]: Fail-closed, version-aware battle information with native macOS and Android presentation.
+      - article [ref=e30]:
+        - heading [level=2] [ref=e31]:
+          - link "MH Save Sync" [ref=e32] [cursor=pointer]:
+            - /url: https://github.com/MHToolkit/mh-save-sync
+        - paragraph [ref=e33]: Encrypted, conflict-preserving save history with explicit queue and recovery states.
+      - article [ref=e34]:
+        - heading [level=2] [ref=e35]:
+          - link "MH Field Map" [ref=e36] [cursor=pointer]:
+            - /url: https://github.com/MHToolkit/mh-field-map
+        - paragraph [ref=e37]: Accessible field reference and map states designed for online and offline use.
+      - article [ref=e38]:
+        - heading [level=2] [ref=e39]:
+          - link "Coordinated releases" [ref=e40] [cursor=pointer]:
+            - /url: https://github.com/MHToolkit/mh-toolkit
+        - paragraph [ref=e41]: Exact repository identities, platform support evidence, artifact hashes, and setup paths.
+    - status [ref=e42]:
+      - strong [ref=e43]: "Status:"
+      - text: active platform development. Compatibility remains fail-closed until each product and artifact has reproducible evidence.
+  - contentinfo [ref=e44]: © 2026 MH Toolkit · Built on GitHub Pages

docs/design/apple-design-desktop-runtime-full.png

@@ -0,0 +1,18 @@
+# MHToolkit website Apple Design inventory
+
+## Real UI entry points
+
+- `index.html`: global navigation, hero, project/release navigation, status surface, responsive layout.
+- `assets/design-tokens.css`: semantic surface/label/state/motion/accessibility mapping.
+
+## State and accessibility inventory
+
+- The release status is a persistent `role=status` surface with an explicit `data-state`.
+- Project navigation needs visible focus, 44px targets, reduced-motion behavior, reduced-transparency fallback, increased-contrast tokens, and mobile reflow.
+- The site must not infer compatibility from a repository link; copy remains fail-closed.
+
+## Verification
+
+- Contract: `rtk test python -m unittest tests/test_apple_design.py`
+- Runtime: serve the repository root and capture desktop/mobile screenshots with Playwright.
+- Static gate: `rtk git diff --check`.

docs/design/apple-design-desktop.png

@@ -0,0 +1,31 @@
+# MHToolkit website Apple Design evidence — 2026-07-18
+
+## Runtime capture
+
+The site was served locally with `python -m http.server 8765` and captured with installed Google
+Chrome through Playwright. No emulator, game, account, or restricted asset was launched.
+
+```text
+rtk proxy npx playwright screenshot --channel=chrome --full-page \
+  --viewport-size='1440,1000' http://127.0.0.1:8765 \
+  docs/design/apple-design-desktop.png
+rtk proxy npx playwright screenshot --channel=chrome --full-page \
+  --viewport-size='390,844' http://127.0.0.1:8765 \
+  docs/design/apple-design-mobile.png
+```
+
+| Artifact | SHA-256 |
+| --- | --- |
+| `apple-design-desktop.png` | `f1602218cc9464a1f60f9fd64cd60cbda4ff5bba35e769a488aef59a367a8263` |
+| `apple-design-mobile.png` | `3e4d655d1d6e0a9716ee59734b9211ec70e29a48a87dea3ad2dddf9f81174522` |
+
+## Automated evidence
+
+`rtk test python -m unittest tests/test_apple_design.py` passed 2 tests. The contract covers semantic
+tokens, focus visibility, reduced motion/transparency, increased contrast, all four product links,
+project navigation semantics, and explicit planning state. `rtk git diff --check` passed.
+
+PR [MHToolkit.github.io#1](https://github.com/MHToolkit/MHToolkit.github.io/pull/1) now has a
+real `Website checks / Static site and design contract` workflow. Run `29656576581` passed the
+three-test unittest discovery, served `index.html` over a local HTTP server, fetched it with
+fail-closed `curl --fail`, and checked whitespace on commit `adb31fc601521f6006c3218e839770fa910ff71d`.

docs/design/apple-design-inventory.md

@@ -0,0 +1,46 @@
+# MHToolkit website runtime and accessibility evidence — 2026-07-19
+
+## Runtime
+
+The worktree was served without any game, emulator, account, or restricted asset:
+
+```text
+rtk proxy python3 -m http.server 8765 --bind 127.0.0.1
+rtk proxy curl --fail --silent --show-error http://127.0.0.1:8765/ -o /tmp/mhtoolkit-web-index.html
+```
+
+The HTTP smoke request exited `0`; the fetched document SHA-256 was
+`716c77de84c4f880f7c61920056430ae237d92dbf3deb3fda0ee77afdc32af4b`.
+
+Playwright CLI opened `http://127.0.0.1:8765/` in Chrome, reloaded after the semantic
+contract change, and captured the full scrollable page at both target viewports.
+
+| Artifact | Viewport | SHA-256 |
+| --- | --- | --- |
+| `apple-design-desktop-runtime-full.png` | 1440x1000 | `10952f588c0ac7e68c2e65559257080ed60d4904b0fc1d0646657b8629b233e8` |
+| `apple-design-mobile-runtime-full.png` | 390x844 | `4faf143970c69fcc0708e5dca01d9983b184730fb9542ee23aa03d51612929e5` |
+
+## Semantic/accessibility tree
+
+The captured Playwright accessibility snapshot is checked in at
+`docs/design/accessibility-tree-2026-07-19.yml` (SHA-256
+`00b9b913eb69cd293f66f40f80108db9967ba0df3c8d600a43b0816cb9286dc5`). It confirms:
+
+- document title `MH Toolkit`, language `en`, and banner/main/contentinfo landmarks;
+- explicit `Project navigation` navigation landmark;
+- labelled `Project areas` region with five article entries and links for Nemessix, MH Overlay,
+  MH Save Sync, MH Field Map, and Coordinated releases;
+- a `status` live region containing the fail-closed compatibility state;
+- all 11 links exposed as keyboard focusable controls.
+
+The browser-side computed-style probe confirmed each project link uses
+`display: inline-flex` and `min-block-size: 44px`. The static contract also covers focus-visible,
+reduced-motion, reduced-transparency, and increased-contrast states.
+
+## Verification
+
+```text
+rtk test python -m unittest discover -s tests -p 'test_*.py'  # 3 passed
+rtk git diff --check                                      # exit 0
+```
+