Skip to content

docs: sell the standards, type-safety and defaults case, and give the landing page a narrative spine - #1393

Merged
vivek7405 merged 2 commits into
mainfrom
docs/website-standards-copy
Aug 11, 2026
Merged

docs: sell the standards, type-safety and defaults case, and give the landing page a narrative spine#1393
vivek7405 merged 2 commits into
mainfrom
docs/website-standards-copy

Conversation

@vivek7405

Copy link
Copy Markdown
Collaborator

Closes #1392

Two commits on website/ only. No framework source touched.

1. The claims the site was not making

Several things that are true of WebJs and that a reader decides on were stated nowhere on a marketing page.

  • Web standards as a stance. The home hero listed the pieces (web components, SSR, progressive enhancement) without saying what they add up to. It now leads with leaning on web standards.
  • No build, with a precedent. The Zero build step card asserted the bet and cited nothing. It now notes Rails has shipped its default frontend without a bundler since Rails 7 in 2021. Kept to one clause on purpose: articles/no-build-javascript-framework.md owns that keyword, and website/AGENTS.md forbids two pages chasing the same one.
  • Full-stack type safety. Present on /docs/typescript and in a blog post, absent from all three marketing pages. Now on the home bento (the RPC card became Server actions, fully typed), in the code-windows lede, as a card on /why-webjs, and as a FAQ entry on /what-is-webjs.
  • Defaults, not lock-in. /why-webjs listed what a scaffolded app arrives with and never said any of it was replaceable, which is exactly the objection that grid raises. A paragraph under the grid now says so, and the home templates section names the stack (light DOM, Tailwind, Drizzle, modules layout, tokens, the agent skill).
  • The agent skill. Documented on /docs/ai-first, never sold on the pitch page. Now a card in ARRIVES.

2. A narrative spine for the landing page

The page listed seven true things and none of them set up the next, so nothing on it earned a scroll. Sections and order are unchanged; each lede now opens by picking up what the previous section closed on.

Section The hand-off
Real HTML first Frameworks got good at hiding the platform, and for years that paid for itself. What changed is when the bill arrives.
Nothing is compiled away (was Server action & SSR page) That first paint is only honest if what you wrote is what shipped.
Modern full-stack, on web standards Everything below falls out of that one decision.
Light enough for AI A framework that compiles nothing away is a framework you can read.
Start where you are All of it arrives in one command. (This section had no lede at all before.)

The opening beat credits the trade rather than mocking it, matching the register /why-webjs already uses for the same move.

Two things a future editor needs

Grid parity. Three grids here paint an empty cell in the grid's own border colour when the entry count goes odd (gap-px over bg-border). That is why type safety folded into the existing bento card instead of becoming a seventh, and why ARRIVES went 4 to 6 rather than to 5. A comment above ARRIVES records it.

The spine is fragile in a way no test catches. The hand-off lives in the first sentence of each lede, so rewriting one in isolation silently reverts the page to a spec sheet. A comment above STATS in page.ts records the chain and says so.

Verification

webjs typecheck clean, webjs check clean, webjs test --server 471/471. Booted locally and read end to end.

The site sold no-build and web components but never said the framework
leans on web standards as a stance, never claimed full-stack type safety
on a marketing page, never cited a production precedent for shipping
without a bundler, and never mentioned the agent skill or that the
scaffold's stack is a default rather than a dependency.

Grid geometry decided the placement: the home bento and both /why-webjs
grids paint an empty cell in the border colour when the entry count goes
odd, so new points either replaced a card body or arrived in pairs.
The page listed seven true things and none of them set up the next, so
nothing on it earned a scroll. The sections are unchanged; each lede now
opens by picking up what the previous section closed on, turning the page
into one argument that runs from the trade every framework made to the
command that starts an app.

"Server action & SSR page" became "Nothing is compiled away", since the
code windows already caption themselves and the h2 was the only place the
hand-off could live. "Start where you are" had no lede at all.
@vivek7405
vivek7405 merged commit 1a21003 into main Aug 11, 2026
10 checks passed
@vivek7405
vivek7405 deleted the docs/website-standards-copy branch August 11, 2026 10:51
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.

docs: sell the standards, type-safety and defaults case on the site, and give the landing page a narrative spine

1 participant