--- name: review-component description: 'Review a BEEQ StencilJS component against design system guidelines and project standards. Use for: code review of bq-* components, checking section order, naming conventions, JSDoc completeness, prop validation, event documentation, accessibility, styling practices, and test coverage. Returns a structured review with pass/fail per category and actionable fixes.' argument-hint: 'Path to the component tsx file (e.g. packages/beeq/src/components/button/bq-button.tsx)' metadata: internal: true --- # Review a BEEQ Component ## When to Use - Before opening a PR for a new or modified `bq-*` component - Reviewing a PR that adds or modifies a `bq-*` component - Auditing an existing component for guideline compliance - Self-checking a component before submitting for review - When a component "feels off" and you want a holistic check across all dimensions. ## Procedure ### 1. Load the instruction files Read these before evaluating: - [StencilJS instructions](../../instructions/stenciljs.instructions.md) - [Styles instructions](../../instructions/styles.instructions.md) - [Accessibility instructions](../../instructions/accessibility.instructions.md) - [Testing instructions](../../instructions/testing.instructions.md) ### 2. Read the component files Read all files for the component: - `bq-.tsx` — component logic - `bq-.types.ts` — type definitions - `scss/bq-.scss` — styles - `scss/bq-.variables.scss` — CSS custom properties - `__tests__/bq-.e2e.tsx` — E2E tests - `_storybook/bq-.stories.tsx` — Storybook stories ### 3. Evaluate each category For each category below, mark ✅ pass, ⚠️ needs improvement, or ❌ fail, and list specific issues. --- #### A. File Structure & Section Order - [ ] Sections appear in the exact prescribed order (Own Properties → `@Element()` → `@State()` → `@Prop()` → `@Watch()` → `@Event()` → lifecycle → `@Listen()` → public methods → private methods → `render()`) - [ ] Sections header comments are present even if the section is empty - [ ] `render()` is the last method in the class - [ ] `shadow: true` is set (or `delegatesFocus: true` only when needed) - [ ] `formAssociated: true` is present only when the component submits form data - [ ] No `#` private fields — only `private` keyword #### B. Naming Conventions - [ ] Tag uses `bq-` prefix and kebab-case - [ ] Class name is `Bq` in PascalCase - [ ] Events are camelCase with `bq` prefix (e.g. `bqChange`, `bqClick`) - [ ] Event handler methods are prefixed with `handle` (e.g. `handleClick`) - [ ] State variables, props, and methods are camelCase - [ ] Constants and enum values are ALL_CAPS - [ ] Private methods use arrow functions with the `private` keyword - [ ] All public methods are `async` - [ ] Type parameters are prefixed with `T` (e.g. `TButtonSize`) - [ ] SCSS class names follow BEM #### C. JSDoc Completeness - [ ] Component-level JSDoc block present above `@Component({})` - [ ] `@example`, `@documentation`, `@status`, `@dependency` tags present - [ ] Every `@Prop()` documented with `@attr` in component JSDoc - [ ] Every `@Event()` has JSDoc on the property and `@event` in component JSDoc - [ ] Every `@Method()` has JSDoc with `@param` and `@returns` - [ ] Every `@Prop()` has an inline JSDoc comment - [ ] Every slot has `@slot` in component JSDoc - [ ] Every shadow part has `@part` in component JSDoc - [ ] Every CSS custom property has `@cssprop` in component JSDoc #### D. Props & Events - [ ] Props with fixed allowed values use `validatePropValue()` + `@Watch()` - [ ] Optional boolean props (`prop?: boolean`) should not also declare `= false`; use either an optional boolean or a required boolean with an explicit `false` default, depending on the intended API shape - [ ] String props should not default to `undefined` if they are required. - [ ] Styling-related props use `reflect: true` - [ ] No prop defaults that contradict the type (e.g. `undefined` typed as `string`) - [ ] Events use typed `EventEmitter` (not `EventEmitter`) - [ ] Events bubble correctly (check `bubbles`, `cancelable` options if needed) #### E. Accessibility - [ ] Interactive elements use semantic HTML (`