(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]

🦋 Changeset detected

Latest commit: e849011

The changes in this PR will be included in the next version bump.

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

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another 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	Jul 31 2026, 12:00 AM (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) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — merged latest v1 into the redesign branch and ported the upstream announcement badge update into the redesigned homepage.

• Resolved merge conflict in page.tsx — kept the redesign's thin server page that renders HomePageClient and discarded the old hero markup from v1.
• Updated homepage announcement badge — changed apps/www/app/(home)/home-page-client.tsx to link to /docs/cli/hosting-presets with the label "Next.js, Netlify presets".

  ^{｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) (GPT Sol not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}

[pkg-pr-new]

Open in StackBlitz

arkenv

npm i https://pkg.pr.new/arkenv@1161

@arkenv/build

npm i https://pkg.pr.new/@arkenv/build@1161

@arkenv/bun-plugin

npm i https://pkg.pr.new/@arkenv/bun-plugin@1161

@arkenv/core

npm i https://pkg.pr.new/@arkenv/core@1161

@arkenv/fumadocs-ui

npm i https://pkg.pr.new/@arkenv/fumadocs-ui@1161

@arkenv/nextjs

npm i https://pkg.pr.new/@arkenv/nextjs@1161

@arkenv/nuxt

npm i https://pkg.pr.new/@arkenv/nuxt@1161

@arkenv/standard

npm i https://pkg.pr.new/@arkenv/standard@1161

@arkenv/vite-plugin

npm i https://pkg.pr.new/@arkenv/vite-plugin@1161

commit: e849011

[pullfrog]

✅ No new issues found.

Reviewed changes — synced latest v1 into the redesign branch. No homepage files were touched; the merge brings in v1 features that landed in separate PRs.

• Optional internal/shared.ts in strict layout — isStrictLayoutDir now only requires client.ts + server.ts; findSchemaPath no longer requires shared.ts; Nuxt module aliases #arkenv/shared-schema to the empty stub when the file is omitted; boot-gate skips the shared schema when absent.
• Standardized missing-schema errors — formatMissingSchemaError in @arkenv/build produces consistent "Could not find schema file … run npx arkenv@latest init" messages across Bun, Vite, Next.js, and Nuxt plugins, without embedding starter env.ts modules.
• Split CLI --help into Global and init sections — help.ts now groups shared flags (--yes, --quiet, --json, --agent) under Global options and scaffolding flags (--example, --force, --no-codegen, --host-preset) under init options.
• GitHub Actions improvements — new deploy-www-manual.yml (maintainer escape hatch for manual SHA deploys), enhanced preview-www-reusable.yml with git metadata passed to Vercel deploys, and polished preview-www-default.yml fork-PR + label-gate logic.
• Docs updates for optional shared.ts — Next.js strict layout and Nuxt configuration/validation docs now describe shared.ts as optional throughout.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) (GPT Sol not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}

[yamcodes]

Gonna close this in favor of #1509