mirror of
https://github.com/bitwarden/clients.git
synced 2026-11-16 07:03:29 +00:00
* [CL-1016] Add review guidelines to components CLAUDE.md * [CL-1016] Move CL guidelines to CODE_STYLE.md and address review * [CL-1016] Move scope and process rules to CONTRIBUTING.md * [CL-1016] Remove external links from CODE_STYLE.md * [CL-1016] Simplify design sign-off requirement * [CL-1016] Allow CODE_STYLE.md in capital filename lint * [CL-1016] Address review feedback on a11y, testing, and promotion guidance
5.4 KiB
5.4 KiB
Code Style for @bitwarden/components
How we write components in this library. For what belongs in the library and PR requirements, see CONTRIBUTING.md.
Public API Design
- Keep the API small, with one way to do each thing. No overlapping inputs (
loading+showLoadingSpinner), hybrid APIs (projected children and an options array), or two paths to the same value. - Match sibling components: reuse established names (
startIcon/endIcon,variant,title) and mechanics (e.g. trigger directives likebitMenuTriggerFor). Model new APIs on native HTML and the ARIA APG pattern. - Don't add inputs that just proxy CSS (widths, alignment, margins,
modeflags). Let the parent control layout. - Use
slot-attribute content projection (<ng-content select="[slot=end]">) when consumers pass varied content; use data inputs when the content is fixed. - Build what the current design needs, but choose an API shape that can grow without a breaking change. Slots usually extend better than text inputs.
- Boolean inputs default to
falseand usetransform: booleanAttribute. - Emit outputs for state changes consumers may care about, rather than making them reach into the component. Outputs have no
onprefix and don't repeat the component name (dismissed, notchipDismissed). - Variants and options are lowercase string-literal unions, not enums or enum-like objects. Type names describe what they are (
ProgressBarVariant, notBackgroundType). - Component selectors are kebab-case (
bit-foo); camelCase is for directives. Prefer element selectors unless native semantics require an attribute selector (button,tr). - Typically, only inputs and outputs are public. Template-only members are
protected; everything else isprivate. - Helper components are marked
@internaland not exported fromindex.ts. - Build reusable behavior into the CL primitive (or a host directive) instead of having each consumer re-implement it.
- Wrap third-party dependencies behind a facade. Never expose them or their config in the public API, and don't break our API because a dependency changed.
Angular Style
- Use
input()/output()/model(),inject(),host: {}(not@HostBinding/@HostListener),@if/@for, andOnPush. Dropstandalone: trueand empty constructors. - Mark all class properties
readonly. - Derive state with
computed()instead of getters, setters, or method calls in templates. Don't wrap non-reactive values incomputed(). Keep input transforms pure. - Prefer declarative reactivity: computed signals or piped observables over manual subscribe-and-assign. No side effects inside
pipe. Use plain signals when no stream operators are needed; usefirstValueFromfor single-emission observables. - Don't communicate through the DOM (
nativeElement,querySelector,setAttribute). Use DI,contentChild/viewChild, inputs, or host bindings. - Use
@letto create new values in templates, never to alias signals. - Prefer Angular/CDK built-ins (
FormRecord,LiveAnnouncer, CDK focus restoration) over hand-rolled equivalents. - Inline single-use helpers, types, and wrapper components. Remove unnecessary wrapper DOM nodes.
- Bind dynamic values with
[x]="y()"and static values with attribute syntax. Never use{{ }}interpolation in attributes. - Comments explain a non-obvious why, especially bug workarounds. No narration, explanations of how Angular works, or history of what used to exist.
Styling
- Prefer CSS (
:has(),group-*, media/container queries, transitions) over JS (ResizeObserver,setTimeout, computed class strings) when possible. - Never concatenate partial Tailwind class names; map values to full literal class strings. For dynamic values or values shared with TS, use CSS variables or
[style.x]instead of "keep in sync" comments. - No unexplained
!important. Preferremso sizes respect zoom. - Bind classes with
[class]array syntax, not[ngClass]. Keep static classes in the template orhost, not in TS properties. - Scope Tailwind groups to the component (
tw-group/bit-form-field). - Don't write dark-mode-specific styles; the theme colors in
tw-theme.cssalready work in dark mode. - Use logical directions (
start/end,tw-ms-*,tw-ps-*), notleft/right. - Use
focus-visible:for focus styles, notfocus:. - Lay out with flex/grid, and make components respond to their container rather than assuming a viewport.
Accessibility
- Meet WCAG 2.2 AA. Check the current WCAG and ARIA APG guidance for the pattern being built rather than relying on memory.
- Prefer native elements and semantics over ARIA. Add ARIA only to fill gaps native HTML can't.
- Every interactive state must be reachable by keyboard, with defined screen reader behavior (accessible names, roles, state announcements).
- Manage focus for overlays and dynamic content: move focus in on open, trap it where the pattern requires, and restore it on close.
Docs, Stories & Tests
- Every component class and public input gets a JSDoc comment (
/** */, not//). Use@deprecatedto point to replacements. - MDX describes usage only: no internals, no restating what the story already shows.
- Use play functions to capture interactive states (hover, focus, open, validation errors) for visual regression.
- Prefer Storybook coverage over unit tests. Unit tests never cover Angular internals or styling.
- Test internal helper components through their public component.