docs(web): add frontend coding style guide + rename pages to kebab-case#30684
Conversation
Covers file/folder naming (kebab-case), directory structure, import conventions (path aliases, import order, destructured React types, type-only imports), TypeScript rules (strict mode, interface vs type, no any, const assertions), component patterns (named exports, function declarations, props naming), hook conventions, constants/enums style, docstring expectations, formatting defaults, and unused code handling. Each section links to authoritative references (TypeScript docs, React docs, Vite docs, eslint plugin docs). Co-Authored-By: ashlee@vellum.ai <ashlee@vellum.ai>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bd601a9d94
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
|
|
||
| Coding style, naming conventions, and formatting rules for the Vellum | ||
| web app. For architectural decisions and patterns see | ||
| [`CONVENTIONS.md`](./CONVENTIONS.md). |
There was a problem hiding this comment.
🟡 STYLE_GUIDE.md references non-existent CONVENTIONS.md in three places
The new STYLE_GUIDE.md links to ./CONVENTIONS.md on lines 5, 75, and 393, but apps/web/CONVENTIONS.md does not exist anywhere in the repository (find . -name CONVENTIONS.md returns no results). Anyone following these links will get a 404. The root AGENTS.md's "Keep Docs Up to Date" rule says docs must reflect current state — shipping documentation with broken cross-references violates this.
Prompt for agents
STYLE_GUIDE.md references ./CONVENTIONS.md in three locations (lines 5, 75, and 393) but that file does not exist in apps/web/ or anywhere else in the repo. Either create the CONVENTIONS.md file in the same PR, or remove/replace the three references. Lines to fix: line 5 (intro paragraph link), line 75 (domain folders section link to CONVENTIONS.md#code-organization), and line 393 (dead code section link to CONVENTIONS.md#dead-code-and-cleanup).
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Acknowledged — CONVENTIONS.md ships in companion PR #30683 which is already open and CI-green. The link will resolve once both merge. Since these are intended to merge together, the temporary broken link window is effectively zero.
| ### kebab-case everywhere | ||
|
|
||
| All files and directories use `kebab-case`. This avoids | ||
| case-insensitive filesystem collisions (macOS HFS+, Windows NTFS) and | ||
| keeps imports predictable. | ||
|
|
||
| ``` | ||
| use-send-message.ts # hook | ||
| message-handlers.ts # module | ||
| conversation-reducer.ts # reducer | ||
| chat-body.tsx # component | ||
| stream-event-types.ts # types | ||
| ``` | ||
|
|
||
| The only exceptions are `App.tsx` (conventional React entry-point name) | ||
| and generated files that follow their generator's convention. |
There was a problem hiding this comment.
🚩 Existing page files already violate the kebab-case rule being introduced
The style guide mandates kebab-case for all files with only App.tsx as an exception (line 28), but the existing scaffold pages in apps/web/src/pages/ use PascalCase: ConversationDetail.tsx, SettingsTab.tsx, NotFound.tsx, LibraryDetail.tsx, ConversationNew.tsx, Library.tsx. These files predate this PR and are part of the scaffold, so they're not introduced by this change — but the style guide should either rename them or acknowledge them as pre-existing exceptions to avoid confusion when the convention is enforced.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Fixed — renamed all 6 PascalCase page files to kebab-case and updated the imports in routes.tsx in commit 8d24021. The convention and the codebase are now consistent.
Renames all scaffold page files to follow the kebab-case convention introduced in STYLE_GUIDE.md and updates imports in routes.tsx. Co-Authored-By: ashlee@vellum.ai <ashlee@vellum.ai>
devin-ai-integration
Bot
changed the title
Unrelated dead code spotted during a PR gets its own separate PR opened at the same time — never just filed as an issue and left. Co-Authored-By: ashlee@vellum.ai <ashlee@vellum.ai>
… dirs, design library imports Co-Authored-By: ashlee@vellum.ai <ashlee@vellum.ai>
![vex-assistant-bot[bot]](https://avatars.githubusercontent.com/in/3399303?s=60&v=4){kind=small}
There was a problem hiding this comment.
✦ APPROVE
Value: Turns 30+ PRs worth of accumulated style decisions from the platform refactoring series into a single authoritative reference. Any agent or contributor opening a PR against apps/web/ now has explicit rules for naming, imports, TypeScript, and formatting — preventing the drift that made the platform codebase hard to navigate.
What this does: Adds STYLE_GUIDE.md to apps/web/ covering file/folder naming, import conventions, TypeScript rules, component/hook patterns, and formatting. Renames 6 PascalCase scaffold page files to kebab-case.
Bot findings — all resolved:
- Devin:
CONVENTIONS.mdforward reference (companion PR #30683, zero broken-link window) ✅ - Devin: kebab-case violation on existing page files — fixed in commit
8d240213✅ - Codex:
@/alias not yet configured in tsconfig/vite — correctly noted as intentional (target-state convention). This needs to land in the first feature PR that adds cross-module imports. Make sure it doesn't get forgotten.
Content looks solid:
- kebab-case +
use-hook prefix +.test.tscolocated tests — consistent with CONVENTIONS.md ✅ - Import order (external →
@/alias → relative) +typeimports ✅ - Named exports (not default), function declarations for components ✅
- No TS enums →
as constobjects/union types — right call ✅ - No
any, strict mode — ✅ - Dead code rules mirror CONVENTIONS.md exactly ✅
Minor: App.tsx is called out as a kebab-case exception but the named-exports rule doesn't explicitly address it. App.tsx is almost certainly a default export. Tiny nit — could add App.tsx as an exception to the named-exports rule too, or just leave it implicit.
Vellum Constitution — Inviting: a readable style guide makes open-source contribution feel structured rather than a guessing game.
Reviewed at 5084a2a2
1 participant
Prompt / plan
Consolidate coding style conventions from 30+ PRs in the
vellum-assistant-platformrefactoring series into a singleSTYLE_GUIDE.mdreference doc. Rename scaffold page files to kebab-case to match the convention from day one.Companion PR: #30683 — CONVENTIONS.md
What this PR does
apps/web/STYLE_GUIDE.md— coding style, naming, formatting, and import rules for the new Vite + React Router v7 SPA.ConversationDetail.tsx→conversation-detail.tsx, etc.) and updatesroutes.tsximports.The style guide covers: kebab-case file naming,
domains/-based directory structure,@/path aliases, import ordering, TypeScript strict mode, named exports, function declarations for components, Zustand store naming (use-{domain}-store.ts), JSDoc conventions, and dead code rules.Why
Key decisions reflected
domains/notfeatures/domains/signals DDD-influenced bounded contexts (messages, conversations, streaming)hooks/,utils/,types/,lib/domains/<name>/lib/for configured third-party wrappersutils/orruntime/packages/design-library/@vellum/design-library, aliased via Vite for monorepo HMRuse-{domain}-store.tsSee CONVENTIONS.md PR #30683 for the full architectural rationale behind these decisions.
Test plan
routes.tsximports match the renamed kebab-case filenamesReferences
Human review checklist
STYLE_GUIDE.mdmatches thedomains/-based layout in CONVENTIONS.md (docs(web): add frontend architecture conventions (CONVENTIONS.md) #30683)@/domains/...consistently (not@/features/...)routes.tsximport updates are correct@vellum/design-libraryimport pattern is acceptable for the design systemLink to Devin session: https://app.devin.ai/sessions/57905118879948a69946c94c6cd332d7
Requested by: @ashleeradka