docs: brand-aligned syntax theme for code blocks

[auricom]

Summary

Replaces the default Shiki theme (which used light-mode token colors on a black background, producing low-contrast dark-blue-on-black text).

Before

After

Test plan

• yarn dev — open any guide page with code blocks and verify all token types are readable on the black background
• Check bash comments (# …), YAML keys, string values, keywords, and numbers each render in a distinct, readable color

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Introduced a new dark theme for the documentation site featuring comprehensive syntax highlighting enhancements.
  • Enhanced code block styling with refined color schemes to improve readability across multiple programming languages.
  • Updated visual styling for better clarity and consistency throughout the documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new dark theme (ev-dark) has been added to the VitePress documentation site. The theme definition includes color schemes and syntax highlighting rules, integrated via configuration updates and minor CSS adjustments to code block styling.

Changes

Cohort / File(s)	Summary
Dark Theme Configuration docs/.vitepress/config.ts, docs/.vitepress/ev-dark.json	Added import and application of new evDarkTheme markdown theme to VitePress config, with comprehensive theme definition including semantic highlighting and token color mappings for syntax highlighting across multiple language constructs.
Code Block Styling docs/.vitepress/theme/style.css	Adjusted code block foreground color from pure white (#ffffff) to #dbd7ca for improved contrast alignment with the vitesse-black default text.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰✨ A darkened burrow, cozy and bright,
Where docs now gleam through the digital night,
Token by token, from shadows we weave,
A theme so grand, you won't want to leave! 🌙💻

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The PR description lacks a structured overview section and misses linking to the issue number, though it provides visual before/after context and test plan.	Add a brief overview explaining the problem being solved and rationale. Include issue link (e.g., 'Closes #') per the template guidelines.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: introducing a custom, brand-aligned syntax theme for documentation code blocks.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch auricom/docs-style

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

The latest Buf updates on your PR. Results from workflow CI / buf-check (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	⏩ skipped	✅ passed	✅ passed	Apr 28, 2026, 12:11 PM

[claude]

Claude finished @auricom's task in 1m 32s —— View job

---

Code Review: docs: brand-aligned syntax theme for code blocks

Summary: Clean, well-structured docs-only PR. The theme follows standard VSCode/TextMate conventions, colors align with the brand palette in style.css, and the integration with VitePress is correct. A few low-priority observations below.

---

Checklist

• Read changed files and CLAUDE.md
• Understand the request
• Analyze docs/.vitepress/ev-dark.json
• Analyze docs/.vitepress/config.ts
• Analyze docs/.vitepress/theme/style.css
• Post review

---

docs/.vitepress/config.ts

Integration looks correct. Using a single theme object (rather than { light, dark }) is the right call given appearance: false at line 28, since the site runs in a fixed mode with no toggle.

Minor — type assertion vs satisfies (config.ts:32):

// current
theme: evDarkTheme as ThemeRegistration,

// safer — catches schema mismatches at compile time
theme: evDarkTheme satisfies ThemeRegistration,

as ThemeRegistration is a forced cast that bypasses TypeScript checking. Using satisfies would confirm the JSON actually matches the expected type. Practically harmless since Shiki is lenient about extra/missing keys, but the latter is better practice.

---

docs/.vitepress/ev-dark.json

Structure is well-formed and follows the standard VSCode/TextMate theme JSON schema. Color assignments are consistent with brand tokens declared in style.css.

Low priority — semanticHighlighting: true is a no-op here (ev-dark.json:9):

"semanticHighlighting": true,

Semantic highlighting requires a live language server (LSP). In static site generation with Shiki, there is no LSP — only TextMate grammar tokenisation is used. This field is harmless but semantically incorrect for this context. Removing it would be a minor clarity improvement.

Low priority — duplicate scope, intentional but worth a comment (ev-dark.json:152-163):

{ "scope": ["string.regexp.character-class", "string.regexp constant.character.escape", ...],
  "settings": { "foreground": "#BFF3C2CC" } },
{ "scope": "string.regexp constant.character.escape",
  "settings": { "foreground": "#FFECB6" } }   ← overrides the first

The second entry intentionally overrides the alpha-tinted value for constant.character.escape inside regexps. This is valid and works correctly (later rules win). A short comment would clarify intent for future maintainers.

---

docs/.vitepress/theme/style.css

The change is correct. #dbd7ca aligns the CSS fallback color for code blocks with editor.foreground in ev-dark.json (line 7) and with --vp-code-block-color already set to #dbd7ca at line 156. The three values now agree, which eliminates the previous #ffffff flash before Shiki tokens render.

Nit — stale comment (style.css:183):

color: #dbd7ca;  /* vitesse-black default text */

#dbd7ca was originally borrowed from Vitesse Black but this is now the ev-dark theme. Consider updating to /* ev-dark default text */ to avoid confusion.

---

Overall

No blocking issues. The theme is well-crafted, brand-consistent, and the VitePress integration is correct. The test plan in the PR description is appropriate — the main verification is visual (yarn dev). The preview deployment at https://evstack.github.io/docs-preview/pr-3294/ is the right way to validate this.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.47%. Comparing base (49ef5c9) to head (ff85ff0).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3294      +/-   ##
==========================================
+ Coverage   62.45%   62.47%   +0.01%     
==========================================
  Files         122      122              
  Lines       13047    13047              
==========================================
+ Hits         8149     8151       +2     
+ Misses       4012     4011       -1     
+ Partials      886      885       -1     

Flag	Coverage Δ
combined	62.47% <ø> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-04-28 13:56 UTC