You just implemented or modified a feature. Now add or update its documentation across all relevant files.
-
Read the current help content at src/constants/helpContent.ts to understand the existing structure.
-
Determine where the feature belongs. The 13 existing categories are:
getting-started — First-time setup (accounts, sync, client ID)reading-email — Thread view, reading pane, mark-as-readcomposing — Compose, reply, undo send, schedule, signatures, templates, aliases, draftssearch-navigation — Search operators, command palette, keyboard shortcutsorganization — Labels, smart folders, filters, quick steps, star/pin/mute, archive/trash, multi-select, drag & dropproductivity — Snooze, follow-up reminders, split inbox, spamai-features — AI overview, summaries, smart replies, compose, Ask Inboxnewsletters — Newsletter bundles, unsubscribenotifications-contacts — Notifications/VIP, contact sidebarsecurity — Phishing, auth badges, remote images, link confirmationcalendar — Google Calendarappearance — Theme, accent colors, font/density, layoutaccounts-system — Multi-account, system tray, global shortcut, pop-out windows
-
Add a new HelpCard to the appropriate category's cards array, or update an existing card if the feature enhances something already documented. Each card needs:
{
id: "kebab-case-unique-id",
icon: SomeLucideIcon,
title: "Short user-facing title",
summary: "One-line summary shown when collapsed (~40-60 chars).",
description: "Detailed explanation shown when the card is expanded. 3-5 sentences covering what it does, how it works, and practical details. Write from the USER's perspective, not a developer's.",
tips?: [
{ text: "How to use it or a useful detail" },
{ text: "Keyboard shortcut", shortcut: "key" },
],
relatedSettingsTab?: "general",
}
-
Valid relatedSettingsTab values: general, composing, labels, filters, smart-folders, quickSteps, contacts, accounts, sync, shortcuts, ai, subscriptions, developer
-
If adding a contextual tip (for ? tooltips in the UI), add an entry to the CONTEXTUAL_TIPS record:
"tip-id": {
title: "Short title",
body: "One sentence explaining the setting or feature.",
helpTopic: "category-id",
}
-
Run the help content tests to validate your additions:
npx vitest run src/constants/helpContent.test.ts
The tests check: unique IDs, non-empty titles/descriptions, valid settings tab references, valid contextual tip topic references.
-
Run type-check to make sure icon imports are correct:
npx tsc --noEmit
-
Update project docs if the feature affects them. Check each file and update as needed:
docs/architecture.md — Update if the feature adds new component groups, services, stores, database tables, or changes the project structure tree. Keep counts accurate (component groups, file counts, table counts).docs/development.md — Update if test counts change or new development workflows are introduced.docs/keyboard-shortcuts.md — Update if the feature adds or changes keyboard shortcuts.CLAUDE.md — Update the relevant section (component organization, service layer, key gotchas, etc.) to reflect the new feature.
