(v1) Terminal-forward homepage redesign with nautical motif

[yamcodes]

Description

This PR implements a complete redesign of the website homepage using a terminal-forward, CLI-first utility style with a subtle nautical/sailing motif, aligning with Arkenv's brand.

Visual & Architectural Changes

• Design Tokens: Defined a locked design system in design.md utilizing OKLCH colors—anchored on a deep marine navy backdrop (oklch(13% 0.014 225)) and electric cyan accent (oklch(78% 0.16 210)).
• Relocated Theme Toggle: Relocated the theme switcher from the global header in layout files to a tucked-away setting in the home footer to establish dark mode as the default/primary mode.
• Terminal Navigation (N8 style): Renders a simulated command prompt header (> arkenv --init) with navigation flags.
• Workbench Simulation: Implements an interactive step-by-step CLI walkthrough component in the hero section displaying:
  1. Bootstrapping with npx arkenv init.
  2. Defining schema variables in env.ts using ArkType.
  3. Fail-fast error logs showing missing/invalid env variables.
• Compatibility & Technical Specs: Cleaned up the compatibility rails and specs grid to feel clinical, technical, and precise.

Verification

• Checked formatting and linting via pnpm check.
• All 659 unit/integration tests passed successfully.

[changeset-bot]

⚠️ No Changeset found

Latest commit: acb74b1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[arkenv-bot]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (Asia/Almaty)
arkenv	Ready	Preview, Comment	Jun 5 2026, 10:42 PM (Asia/Almaty)

[pullfrog]

Caution

This PR drops homepage <title> and <meta description> metadata and removes the theme toggle from all docs pages.

Reviewed changes — complete homepage redesign with terminal-forward CLI aesthetic, nautical/marine OKLCH design tokens, and a three-tab interactive workbench simulator.

• New design.md design system — locked OKLCH palette, typography, spacing, motion, and microinteraction rules for the app.
• Homepage rewrite — terminal header with --docs / --github nav flags, sonar/radar background animation, CTA copy-command chip, interactive workbench simulator with init/schema/validation tabs, and a dense monospace footer colophon.
• Design token migration — dark.css and light.css migrated to OKLCH colors with marine-cyan accent; AnnouncementBadge and Logo components switched from hardcoded blue to primary CSS variables.
• Theme toggle relocation — removed from global header in both (home)/layout.tsx and docs/layout.tsx, moved to homepage footer.

🚨 Homepage loses <title> and <meta description> metadata

The page was converted from a server component (which exported metadata: Metadata) to a client component ("use client"), removing the title ("ArkEnv") and description ("Environment variable validation from editor to runtime"). The root layout.tsx does not define a title or description override, so the homepage will have no meaningful <title> or <meta description> tags.

Technical details

# Homepage loses `<title>` and `<meta description>` metadata

## Affected sites
- `apps/www/app/(home)/page.tsx` line 81 — `"use client"` directive prevents `metadata` export
- `apps/www/app/(home)/page.tsx` lines 74–76 — removed `export const metadata: Metadata = { title: "ArkEnv", description: "..." }`

## Required outcome
- The homepage must render with a `<title>` and `<meta name="description">` tag.
- Either restore the page as a server component with `metadata` export, or use `generateMetadata` in a separate `layout.tsx` or co-located file.

## Suggested approach
- Move the client-interactive components (workbench simulator, copy button, etc.) into a child client component, keeping the page as a server component with `metadata` export intact.
- Alternatively, add a `title` and `description` to the root `layout.tsx` metadata object as a fallback.

⚠️ Docs pages have no way to toggle themes

The ThemeToggle was removed from both the desktop header (actions array) and mobile menu (menuActions array) in apps/www/app/docs/layout.tsx. Unlike the homepage (which relocated the toggle to its footer), the docs layout has no fallback toggle, leaving docs pages without any theme-switching UI.

Technical details

# Docs pages have no way to toggle themes

## Affected sites
- `apps/www/app/docs/layout.tsx` lines 557–581 — `ThemeToggle` removed from `actions` (desktop header) and `menuActions` (mobile menu)

## Required outcome
- Docs pages must have a visible theme toggle, either in the header or sidebar.
- If the intent is to keep the global header toggle-free, add `ThemeToggle` to the docs sidebar or a similar persistent UI element.

## Suggested approach
- Restore `ThemeToggle` to the `actions` array in the docs layout header, or
- Add it as a sidebar footer element via Fumadocs' `sidebarFooter` configuration.

ℹ️ Nitpicks

• useCopyCommand in apps/www/hooks/use-copy-command.ts shows a toast on copy, but design.md specifies "silent success" for clipboard operations — the hook could be updated to match the design system's microinteraction stance.
• StarUsButton, QuickstartButton, CLICommand, HeroGradientOverlay, and HeroVisual are no longer imported anywhere in the app; their source files and tests can be cleaned up in a follow-up.

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — the second commit addresses both critical issues flagged in the prior review: restoring homepage metadata and re-adding a theme toggle to docs pages. Client code is cleanly extracted into a new file.

• Extracted HomePageClient component — moved the full workbench-simulator homepage into apps/www/app/(home)/home-page-client.tsx, keeping page.tsx as a server component that re-exports metadata: Metadata.
• Restored ThemeToggle to docs sidebar — added as a sidebar footer element in apps/www/app/docs/layout.tsx, with Fumadocs' built-in themeSwitch disabled to avoid a duplicate toggle.
• Cleaned up unused import — removed the dangling ThemeToggle import from apps/www/app/(home)/layout.tsx.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — incremental delta since the prior review: restored Playwright coverage for the redesigned homepage, added Hallmark design-trace artifacts, and fixed light-mode contrast for the OKLCH palette.

• Restored Playwright homepage coverage — updated apps/playwright-www/tests/homepage.test.ts to match the new terminal-forward nav (--docs link and exact-name GitHub link selectors).
• Added Hallmark design-trace files — .hallmark/log.json and .hallmark/preflight.json capture the Workbench macrostructure, theme axes, and preflight findings.
• Fixed light-mode contrast — darkened light.css --primary/--ring to oklch(42% ...) for WCAG AA, and adjusted success/error text in home-page-client.tsx to readable text-green-700 / text-red-700 in light mode.

  ^{｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}