feat(readme): visual polish — hero terminal · stats · feature grid#102
Merged
feat(readme): visual polish — hero terminal · stats · feature grid#102
Conversation
Replace the plaintext code-fence demo of `reasonix code` with a self-contained SVG that mirrors the design-doc terminal mockup (`design/agent-tui-terminal.html`) and the website palette: dark chrome, traffic-light dots, JetBrains Mono, ANSI-style color roles (cyan prompt, purple `assistant`, amber path, coral SEARCH, green REPLACE). Bilingual: a separate zh-CN variant carries the Chinese user message and the localized pending-edit footer.
The previous SVG painted the model's raw `<<<<<<< SEARCH` / `=======` / `>>>>>>> REPLACE` markers, but those are an internal protocol — the TUI actually renders pending edits via `formatPendingPreview` from `src/cli/ui/edit-history.ts`, which produces a unified diff with `-`/`+` prefixed lines and a `path (-N +M lines)` file header. Match that format faithfully; shrink the canvas to 880x360 since the diff is more compact than the marker block was.
Two new design-token SVGs continue the hero-terminal aesthetic so the README has consistent visual rhythm instead of a wall of `### heading` subsections. - Add `docs/hero-stats.svg` (+ zh): three gradient numbers (94% live cache hit · ~30× cheaper / task · MIT) below the hero tagline. - Add `docs/feature-grid.svg` (+ zh): 6-card 3x2 grid replacing the eight `###` subsections that ran 25+ lines of wall text. Prose cleanup: - Drop the `--system-append` subsection; it's documented in `reasonix code --help`, doesn't belong in the hero quickstart. - Drop the "Edits stay in memory..." line redundant with the terminal SVG that already shows the /apply gate. - Drop the stale "1665 tests" count from the contributor snippet — the number drifts; "tests" alone is enough. Net: 175 → 132 lines per README, four anchored visual blocks (logo · stats · terminal · features).
esengine
changed the title
The README points at the dashboard and TUI design mockups, but the links resolved to repo paths — GitHub serves `.html` files in repos as syntax-highlighted source, never as a rendered page. Anyone clicking through hit a wall of HTML instead of the intended preview. Move the two mockups into `docs/design/` (already published via GitHub Pages) and switch the README links to absolute `https://esengine.github.io/reasonix/design/...` URLs. Now click- throughs land on the rendered mockup, and the links work the same on github.com, on the npm registry, and anywhere else the README gets reposted. `dashboard/app.css`'s "anchored to ..." comment updated to track the new location.
Drop the 7 universally-yes rows (plan mode, edit review, MCP, skills, hooks, sandbox, surface) and keep the 6 where Reasonix is actually different from peers: backend, cost, license, cache-hit %, dashboard, sessions. Add a one-line note pointing at the feature grid for the rest, so the information isn't lost — just reordered into the section that's already explaining each feature in detail.
Designer-pass cleanup. The hero used to fracture between centered (logo, tagline, lang) and left-aligned (H1, badges, description), making the eye jump as it scanned downward. - Drop the redundant `# Reasonix` H1 — the wordmark in `logo.svg` already says it; the H1 was duplication, not hierarchy. Astro, Bun, Tailwind and similar polished READMEs do logo OR title, not both. - Drop the `<em>` tagline; the description paragraph below conveyed 90% the same info more concretely. Pick one, not two. - Center the badges and the description paragraph inside `<p align="center">` so logo → langs → badges → description → stats SVG all share one vertical axis. - Quick start: drop the "First run: paste a key…" paragraph (the wizard prompts the user when they run it; pre-explaining was reading-overhead). Compact note inline as a `# comment` on the `npx reasonix code` line, plus an API-key link in the trailing requirements line. - Contributing: drop the trailing `git clone … npm install …` snippet that duplicated CONTRIBUTING.md's setup section. The link above already says "read CONTRIBUTING.md" — trust it. Net: 132 → 115 lines per README. Hero feels like one block.
Three places referenced free signup credit: - README.md / README.zh-CN.md "Non-goals" bullet — rephrased as "needs a paid DeepSeek API key" so the air-gapped redirect to Aider+Ollama / Continue still makes sense - docs/index.html + docs/i18n.js Quick start step 1 — "Sign up at ... and create a key" / "到 ... 注册并创建 Key" - src/cli/ui/Setup.tsx + src/cli/ui/Wizard.tsx — drop "free credit on signup" hints from the key-paste prompt
README polish bundle: - Add 2 badges: GitHub stars + Discussions count. Brings the row from 5 → 7 (still under the badge-spam threshold). - Add a contrib.rocks contributor-avatar grid at the bottom of the Contributing section. Auto-updates from `git log` — no bot, no config file. Single `<img>`, fresh forever. - Reference Code of Conduct + SECURITY.md from the Contributing blurb so first-time PR authors land on the right pages. Project hygiene files: - `CODE_OF_CONDUCT.md` — Contributor Covenant 2.1, fetched verbatim from the canonical EthicalSource repo, with the `[INSERT CONTACT METHOD]` placeholder filled in. GitHub's Insights → Community will now show the green check, and the repo nameplate gains a "Code of Conduct" link. - `SECURITY.md` — private-disclosure policy, scope (in: package, dashboard, sandbox; out: third-party MCP servers, upstream Node, the user's own key handling), supported-versions note, and hardening reminders for users. - `CONTRIBUTING.md` "Reporting security issues" reduced to a one-line pointer at SECURITY.md, eliminating the duplicate email address.
The `docs/` directory was a mixed bag: GitHub Pages site source (index.html, styles.css, i18n.js, term-anim.js, logo.svg, favicon.svg), documentation pages (ARCHITECTURE.md), README image assets (six hero / feature-grid / stats SVGs at root), and design mockups (design/). Six SVGs cluttering the listing made it hard to tell website-source from README-only-fixtures at a glance. Move the README-only SVGs into `docs/assets/`: - hero-stats.svg + .zh-CN.svg - hero-terminal.svg + .zh-CN.svg - feature-grid.svg + .zh-CN.svg Update all 6 image references in README.md and README.zh-CN.md. `logo.svg` stays at `docs/` root because it's used by both the website (`docs/index.html` includes it) and the README — it's genuinely a top-level brand asset, not an asset-folder fixture.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three new design-token SVGs replace prose-heavy sections and pull the README's visual language in line with the design docs (
design/agent-tui-terminal.html) and the website palette.docs/hero-terminal.svg▸ N pending edit block(s) — ...plus-/+lines) — matchesformatPendingPreviewfromsrc/cli/ui/edit-history.tsbyte-for-bytedocs/hero-stats.svgdocs/feature-grid.svg### headingsubsections that ran 25+ lines of wall-textAll three reuse the same gradient palette (
#5eead4 → #93c5fd → #c4b5fd), JetBrains Mono / Inter font chains with CJK fallbacks, and#0a0c10chrome — the README, hero, and design docs now read as one identity instead of three.Bilingual: every SVG and README change has a paired
*.zh-CN.svg/README.zh-CN.mdupdate.Cleanup that landed alongside
--system-appendsubsection — it's documented inreasonix code --helpand wasn't earning its place high in the README./applygate.1665 testscount from the contributorverifysnippet — drift bait.testsalone is enough.Test plan
opens === closes + selfClose)formatPendingPreviewfromsrc/cli/ui/edit-history.ts:48(unified diff, not raw SEARCH/REPLACE markers)