Create a BEEQ Component

When to Use

• Adding a new bq-* web component to the design system
• Scaffolding all required files for a component from scratch
• Resuming work on an in-progress component scaffold

Before You Start

1. Read the instruction files for this task:
   • Components instructions
   • Styles instructions
   • Accessibility instructions
2. Pick a similar existing component as a reference:
   • Simple / display: packages/beeq/src/components/badge/bq-badge.tsx
   • Interactive with events: packages/beeq/src/components/button/bq-button.tsx
   • Form-associated: packages/beeq/src/components/checkbox/bq-checkbox.tsx
   • Compound (host + item): packages/beeq/src/components/accordion/ + accordion-group/

Procedure

1. Run the Plop generator

pnpm g

Answer the prompts: component name (no bq- prefix), whether to add styling, style variables, and Storybook files. This creates the scaffolded files. Then update the generated e2e.ts extension to .e2e.tsx.

2. Implement the component (bq-<name>.tsx)

Follow the section order, naming and prop rules in the components instructions. Do not reorder sections.

3. Create the types file (bq-<name>.types.ts)

Only when the component has typed props. Export type aliases and const arrays so the component (@Watch validators) and Storybook can share them:

export type TMyComponentSize = 'small' | 'medium' | 'large';
export const MY_COMPONENT_SIZE = ['small', 'medium', 'large'] as const;

4. Write the component-level JSDoc block

Use the JSDoc template in the components instructions. List every prop, event, method, slot, part and CSS custom property.

5. Style the component (scss/bq-<name>.scss)

• Import variables file: @import './bq-<name>.variables'
• Use native SCSS/CSS.
• Define CSS custom properties (e.g. --bq-name--border-radius) in bq-<name>.variables.scss
• Use BEEQ semantic classes only where stable styling hooks are needed, e.g. .bq-name and .bq-name__content.
• Use CSS logical properties for layout, sizing, spacing, positioning, borders, and radii.
• Use shared SCSS mixins for repeated focus, hover, and active patterns.
• Keep SCSS nesting depth at 2 or less.

6. After all files are created and implemented, ask the user:

Ask the user:

• What public props does this component need, and which are required?
• Does it need form association (formAssociated: true)?
• What events should it emit, and what detail payloads do they carry?
• What named slots does it expose beyond the default?
• What are the accessibility requirements — role, ARIA attributes, keyboard interactions?
• Should it support any size, appearance, or variant props?

Then run review-component on the new component to confirm everything is in order.

7. Verify the scaffold

Verify that the build passes without errors:

pnpm exec nx run beeq:build