Skip to content

feat(site): restyle inner pages to the editorial drafted-sheet identity - #104

Merged
tt-a1i merged 5 commits into
mainfrom
feat/site-editorial-redesign
Aug 25, 2026
Merged

feat(site): restyle inner pages to the editorial drafted-sheet identity#104
tt-a1i merged 5 commits into
mainfrom
feat/site-editorial-redesign

Conversation

@tt-a1i

@tt-a1i tt-a1i commented Aug 22, 2026

Copy link
Copy Markdown
Owner

Summary

The three inner pages (guide.html, gallery.html, start.html) used a midnight-console visual world while the project page uses the warm-paper editorial one — clicking through felt like leaving the site. This PR rewrites the three templates (scripts/guide-template.html, gallery-template.html, start-template.html) into the index page's drafted-sheet identity and rebuilds the generated pages.

  • Shared language: warm paper + grid + grain, Fraunces display type with orange italic emphasis, mono micro-labels, ink selected states. Dark survives only where the product is dark: command blocks and the live artifact preview plates.
  • Unified nav across all four pages: Guide / Proof Lab / GitHub / language toggle / Install Skill (primary), with aria-current on the active page. Index nav: the Docs label (an in-page anchor) is now a real Start link, and Gallery is labeled Proof Lab to match the page's own name.
  • Index extras: closing CTA section before the footer, palette section now renders real mini light/dark node pairs instead of flat swatches, export-format strip no longer misuses semantic hues, quickstart cards equal height, tighter section rhythm.
  • Zero logic changes: the start switcher, guide recommender, gallery filters/preview-theme/hash deep-links, i18n dictionaries, and all build pipelines work exactly as before. Card accents in build-gallery.mjs now derive from a shared print-depth TYPE_ACCENTS map (same hues the guide uses).

Test plan

  • node scripts/build-start.mjs && build-guide.mjs && build-gallery.mjs — all rebuild clean
  • node scripts/check-release-identity.mjsrelease identity ok: 2.15.0
  • Visual QA: desktop 1440px, narrow 500px, and zh toggle screenshotted for all four pages; guide recommendation flow exercised end-to-end
  • CI

Note: a local full run-tests.mjs run shows one failure in real-repository-proof.test.mjs that is pre-existing and environment-dependent — it only runs its strict comparison when a sibling mco clone exists, and it fails identically on clean origin/main with that clone present. Unrelated to this diff.

Review focus: template rewrites are large but mechanical (style + chrome only); the meaningful review surface is visual — open the four built pages under docs/.

Unify guide, gallery, and start with the project page's visual world:
warm paper, Fraunces display type, international-orange accent, mono
labels, and dark only where the product itself is dark (command blocks
and live artifact plates). All page logic, i18n, and build pipelines
are unchanged; templates were rewritten and pages rebuilt.

- start: editorial lead, ink tab states, dark command plates
- guide: editorial hero, paper chooser/result cards, print-depth type hues
- gallery: editorial hero and proof cards on paper, type-hue accents
  derived from the shared TYPE_ACCENTS map in build-gallery.mjs
- shared fixed nav across all four pages (Guide / Proof Lab / Start /
  GitHub / language / Install Skill) with aria-current markers
- index: nav 'Docs' anchor renamed to a real Start link, Gallery label
  aligned to Proof Lab, closing CTA section, mini-node palette strip,
  equal-height quickstart cards, tighter section rhythm
@tt-a1i
tt-a1i requested a review from YunyueLi August 22, 2026 17:25
- gallery: restore the 44px touch-target contract on nav-logo,
  filter-button, and card-link; update the gallery test's brand hook
  to the renamed .nav-logo selector
- guide: restore the footer CLI hint 'archify guide "your scenario"'
  asserted by the guide page contract test
@YunyueLi

Copy link
Copy Markdown
Collaborator

Visual review — the Diagram Types deck mixes themes without a semantic rule

The dark/light alternation in the Diagram Types section currently feels accidental rather than intentional.

What I see:

  • T·01 Architecture uses a large, fully dark artifact capture.
  • T·02 Workflow starts with another dark artifact, then abruptly switches to a light description panel.
  • T·03 Sequence uses a light artifact capture.
  • The remaining cards continue the section using screenshots with different tonal treatments.

Because these cards represent five peer diagram types, their theme should not imply importance or state. At the moment, luminance is creating an unintended hierarchy:

  • Architecture receives most of the visual weight because it is both the largest card and the darkest surface.
  • Workflow feels visually split into two unrelated layers.
  • Sequence recedes because its light preview merges into the surrounding paper.
  • The eye reads the section as an alternating dark/light composition instead of one coherent family of diagram types.

This is different from the dark plate in the hero. The hero treatment works because darkness has a clear semantic role there: it is the live product artifact, mounted inside the editorial paper frame. The dark specimen card also communicates a selected state. In the Diagram Types deck, however, dark and light do not correspond to selection, interaction, category, or any other visible rule.

I checked the implementation and this appears to come from the source captures themselves:

  • assets/archify-dark.png
  • assets/archify-workflow.png
  • assets/archify-sequence.png
  • assets/archify-dataflow.png
  • assets/archify-lifecycle.png

So this is not a CSS striping effect; the preview assets were captured using inconsistent themes. These assets were already present before this PR, but the mismatch becomes much more noticeable now that the rest of the site is being unified around the warm-paper editorial identity.

Recommended direction

My preferred solution is to normalize all five previews to the light theme in this section.

That would:

  • preserve the paper-based identity of the section;
  • make the five diagram types read as peers;
  • reserve dark surfaces for live product plates, command blocks, and deliberate selected states;
  • prevent the largest Architecture card from overpowering the entire composition.

A consistent all-dark preview treatment could also work, provided every card uses the same preview framing, crop, and light description surface. The important point is that theme should be controlled at the section level rather than chosen independently for each screenshot.

If demonstrating dual-theme support is the intent, that should be made explicit through either:

  1. one section-level theme control that switches all five previews together; or
  2. a consistent paired light/dark specimen inside every card.

Alternating themes case by case does not clearly communicate dual-theme capability.

Acceptance criteria

Before considering the section visually resolved, I would expect:

  • all five peer previews to share the same default theme;
  • consistent capture framing, viewport scale, and crop;
  • consistent separation between the artifact preview and the paper description panel;
  • dark surfaces to have a clear, repeatable semantic meaning across the page;
  • no single type to gain disproportionate hierarchy purely because its screenshot is darker;
  • the five cards to read as one designed system when viewed without reading their labels.

Could we normalize these preview assets as part of this visual-unification pass?

tt-a1i added 2 commits August 25, 2026 20:40
…rule

The Diagram Types deck mixed dark and light source captures with no
semantic rule, letting the largest Architecture card dominate through
luminance. Recapture all five previews in the light theme with one
framing spec (1440px viewport, 2x scale, diagram-plate crop, floating
viewer chrome hidden) so the five peer types read as one family and
dark surfaces stay reserved for live product plates and selected
states. Architecture moves to a dedicated archify-architecture.png so
archify-dark.png keeps its role in the README dark/light pair.
@tt-a1i

tt-a1i commented Aug 25, 2026

Copy link
Copy Markdown
Owner Author

Thanks for the detailed read — agreed on all counts, and this is now addressed in 1c0e403.

What changed

  • All five previews are recaptured in the light theme from their canonical sources (examples/web-app.html, workflow-agent-tool-call.html, sequence-cache-miss-request.html, dataflow-product-analytics.html, lifecycle-agent-run.html).
  • One capture spec applies to every card: 1440px viewport, 2× device scale, ?theme=light, clipped to the diagram plate (.diagram-container) with the floating viewer chrome (theme/export toolbar, PATH·MAP·LENS dock, semantic radar) hidden — so framing, viewport scale, and crop are a section-level rule, not per-screenshot choices.
  • Architecture moves to a new docs/assets/archify-architecture.png; archify-dark.png keeps its job in the README's explicit dark/light pair, which remains the place where dual-theme capability is demonstrated side by side.
  • The branch is now merged up to latest main (sponsor table), so the BEHIND state is resolved.

Against the acceptance criteria

  • ✅ All five peer previews share the same default (light) theme
  • ✅ Consistent capture framing, viewport scale, and crop (single spec above)
  • ✅ Consistent separation between artifact preview (light plate) and paper description panel (unchanged card body)
  • ✅ Dark surfaces now have one semantic meaning on the page: the hero live-artifact plate, command blocks, and the ink "Browse the full proof gallery" CTA card
  • ✅ Architecture no longer gains hierarchy from darkness — only from its grid span, which is layout, not luminance
  • ✅ The five cards read as one designed system without their labels

One local note: archify/test/real-repository-proof.test.mjs fails in my environment because it regenerates the MCO artifact from a local mco checkout that has drifted from the pinned revision; it fails identically on the clean base and is not exercised in CI. All 9 CI checks are expected to stay green.

The release-identity gate requires a prerelease version whenever
CHANGELOG Unreleased carries entries; this site-only PR stays on the
stable identity like its earlier commits.

@YunyueLi YunyueLi left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved — the visual direction is now coherent and merge-ready. The five diagram-type previews follow one light capture rule, so the section no longer creates an accidental hierarchy between dark and light artifacts.

I rechecked the remaining polish notes: the featured Architecture crop at the current card ratio, the Install Skill CTA clipping at 320px, and the small cyan Architecture kicker contrast. These are real but minor and non-blocking; none should hold up this PR, and they can be handled as follow-up polish.

All current CI checks pass. From a visual/UI review perspective, this is good to merge.

@tt-a1i
tt-a1i merged commit 96d2d5d into main Aug 25, 2026
9 checks passed
@tt-a1i
tt-a1i deleted the feat/site-editorial-redesign branch August 25, 2026 17:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants