About improving the documentation website

[MoOx]

The site does its job, but it's selling RSD short. A lot of what makes the project interesting (write web, render truly native) never actually shows up on the page, and a few things are plain out of date. I'd like to open a reflection so we can fix the low-hanging fruit quickly and discuss the bigger changes together.

Grouping the ideas below by theme. Some are 10-minute PRs, some are real design work. Feel free to add, push back, or reprioritize.

Visual & design

• The site could look more polished and professional. It's clean but generic; nothing about it signals "serious, well-maintained project."
• We could take inspiration from react.dev and reactnative.dev for the homepage — strong hero, clear value prop, interactive examples, visible identity. RSD is in that family, the site could feel like it.

Show, don't tell

• No visual demo anywhere. The whole pitch is "same code → web + iOS + Android, all native." The home only shows code blocks and never the result. A playground (à la StyleX) or even a simple "one snippet, three rendered targets side by side" would do more than any paragraph.
• Real screenshots of native output would already help a lot if a full playground is too much.

Content & positioning

• Hero is abstract. "Create cross-platform, platform-native interfaces using web APIs" doesn't say who it's for or what problem it solves. Something more concrete would land better.
• Project status / maturity is stated nowhere. Is it production-ready? Experimental? What's stable vs not? What's the roadmap? People can't make adoption decisions without this, and the silence reads worse than an honest "early but used in X."
• No positioning vs the ecosystem. Nothing on how RSD differs from React Native Web, Tamagui, Unistyles, or plain RN. A sober comparison section would remove a lot of evaluation friction.
• The web story is undersold. Rendering to HTML + atomic static CSS via StyleX is a strong SEO/SSR/perf differentiator vs runtime-styling solutions, and it's only mentioned in passing.
• The "adopt incrementally" example arguably works against us. It shows Button.web.js (RSD) and Button.native.js (plain RN) as separate files — i.e. the divergent-file pattern. But the core promise is not having to split. Leading with the single unified file, and presenting .native.js as the optional escape hatch, would sell the value better.
• No social proof. No "used by", no logos, no testimonial. Even a single credible usage signal would reassure on seriousness.

Quick fixes

• Code typo on the home. In the strict-CSS example, there's a missing comma after paddingBlock: '0.5rem' (before paddingInline). A non-parsing snippet on a page selling "strict CSS" is a bad look.
• Algolia search is out of date. The design of the search box doesn't look like other react websites.
• No obvious link to a community/discussion space from the home.

---

None of this is a complaint about the existing work — it's a list of opportunities. Happy to take some of the quick fixes as PRs if there's appetite. Curious what others think is worth prioritizing.