vscode best-practices.instructions.md

Best Practices

Buttons & Actions

• Don't create a new class or custom CSS to render a button or action. Reuse the existing Button class (vs/base/browser/ui/button/button.ts) and the existing Action types (vs/base/common/actions.ts). This keeps theming, accessibility, and behavior consistent.
• Render actions inside a toolbar rather than by hand. Prefer MenuWorkbenchToolBar (vs/platform/actions/browser/toolbar.ts): give it a MenuId so actions can be contributed from anywhere (contributions, other components) without coupling.
• Use WorkbenchToolBar when you need explicit control over which actions render and where separators go.
• Never add a separator while rendering an action. Add separators with the existing Separator class (vs/base/common/actions.ts).
• If a MenuWorkbenchToolBar lives in a widget/view that can be rendered multiple times at once, give the toolbar a scoped IContextKeyService which is scoped to the dom element of that widget/view and set the context keys per individual widget/view instance.

Editor/Session Actions

• Don't assume the action runs on the active editor/session. An action (e.g. one contributed to some editor or session related toolbar) can be triggered for an editor/session that isn't active. The run method receives arguments describing the invocation context (such as the originating editor group or the originating session).
• Resolve editor action arguments with resolveCommandsContext (vs/workbench/browser/parts/editor/editorCommandsContext.ts) to get the correct editor(s) instead of reading editorService.activeEditor.
• Support multi-selection. The resolved editor actions context can contain several editors (e.g. multi-selected tabs).

Context Keys

• Don't use context keys as a source of truth for application logic (for example, by reading IContextKeyService.getContextKeyValue() and branching on the result). Read the state from its owning service or model instead. Context keys are intended for declarative enablement and visibility, such as when clauses, command preconditions, and menu contributions.