Designing with BEEQ

BEEQ ships standard custom elements from @beeq/core, design tokens, themes, and wrappers for React, Angular, and Vue. The wrappers change framework ergonomics, not component APIs.

Teams build their product on top of BEEQ. Every run follows the same four steps: discover, scope, build down the ladder, verify. Building with the system brings theming, dark mode, accessibility, and consistency for free; each hand-rolled control or literal value gives one of them back.

Every component name, prop, event, slot, method, CSS custom property, ::part(), token, utility class, and package export you write is verified: it appears on the component's https://www.beeq.design/components/<component-name>.md page or in the installed package. An unverified name is a bug, even when it looks plausible.

Three sources, three jobs:

1. Discover what the project already decided

"The agent ignored our design system" almost always means "the agent never looked." In an existing project, find:

• Installed versions: the @beeq/* versions in package.json. The public docs describe the latest release.
• Theme and mode: bq-theme and bq-mode on <html> or a scoped container, and any stylesheet overriding --bq-* tokens. That stylesheet is the project's theme; extend it.
• Setup: where the BEEQ stylesheet is imported and the icon base path is set. When either is missing, adding it is part of the task: import @beeq/core/dist/beeq/beeq.css once, and add <script data-beeq="https://cdn.jsdelivr.net/npm/@beeq/core/dist/beeq/svg/"></script> to the HTML entry. A plain HTML page with no build step links beeq.css and beeq.esm.js from the CDN; with a bundler, the entry files import them. HTML never links /node_modules/ URLs. Self-hosted SVGs with setBasePath() are for projects that need control over them. All paths: Setup.
• House recipes: wrapper components (<AppButton>, styled(BqButton)), shared form-field layouts, router-link patterns, and form-library bindings.
• Agent briefs: the project's own DESIGN.md, AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md.
• The nearest existing screen: how it handles layout, navigation, spacing, and action placement.

Precedence: project conventions > BEEQ design language > this skill's defaults > your taste.

Done when you can name each item above, or state that it is absent. On a greenfield project, follow Installation and the target framework guide instead. Search commands, where customizations belong, and extending BEEQ without forking: your-design-system.md.

2. Name the stack and the scope

The stack decides imports, prop casing, and event syntax (see Framework essentials). Then name the scope:

• A whole screen or app shell. BEEQ ships no page-layout component or layout classes; the consumer owns the page grid. Build it with semantic HTML and CSS on BEEQ spacing and colour tokens, and place BEEQ components inside it (bq-side-menu for navigation, bq-page-title for the heading). Start from patterns.md.
• A piece of a screen: a section, form, card, dialog body, or widget. Compose inside the existing layout and match the size, density, and emphasis of neighbouring controls.

List the states that change a component's footprint: helper text, validation messages, loading, multiple selected values, open overlays. Spacing rhythm, host sizing, and the polish checklist: layout-and-composition.md.

Then list every UI piece the request names or implies, and write down each piece's job: what people do with it and what it does to the page. It navigates, holds a value, runs an action, reports on content still on screen, stands in for a region with nothing to show, or blocks until a decision. The job picks the component through choosing-components.md; the request's words are only clues. "Dropdown", "panel", "toggle", and "error" each name different components in different contexts, and a piece nobody named, such as the state after a failed save, still needs one. A job no component covers is semantic HTML on tokens; name it as such.

Done when the stack, the scope, the footprint-changing states, and every piece with its job and its component (or "semantic HTML") are written down.

3. Build down the ladder

For every custom class, literal value, or hand-built control, walk down this ladder and stop at the first rung that does the job:

1. A house recipe from step 1.
2. A BEEQ component, chosen by the piece's job from step 2 rather than by its name or its look. Compare the "When to use" guidance on the component overview. Jobs agents most often hand-build: grouping related content in the page flow (bq-card); the page's heading with its context and actions (bq-page-title); an item's state (bq-status), count (bq-badge), or removable category (bq-tag); separating regions (bq-divider); a region with nothing to show, whether empty or failed to load (bq-empty-state); a message about content still on screen (bq-alert); rows that take people to another section (bq-side-menu-item inside bq-side-menu). The job questions, words that change meaning with context, and required parent and child structures: choosing-components.md.
3. A documented prop (variant, appearance, size, disabled, validation-status). Start from defaults and omit props that repeat them.
4. A semantic token for everything around the component: --bq-spacing-*, --bq-background--*, --bq-text--*, --bq-stroke--*, --bq-radius--*, --bq-box-shadow--*, --bq-font-size--*, --bq-stroke-s for border widths, and --bq-font-family, the only font-family token. Copy names from the exact list in theming.md; a guessed name resolves to nothing. beeq.css already sets the font, text colour, and background on html and body, so product CSS starts at layout. Layout dimensions have no token: size containers, grid tracks, and breakpoints as the grid foundations do, in rem, with ch for a text measure; details in layout-and-composition.md. BEEQ Tailwind utilities (gap-m, bg-primary) only when the project configures @beeq/tailwindcss. Safe pairings and brand overrides: theming.md.
5. A documented component CSS custom property on the host, such as --bq-button--border-radius, --bq-card--padding, or --bq-button--primary-background. Padding, every colour the component paints, border, and radius are usually variables; check the component's CSS custom properties table first.
6. A documented ::part() for a property no variable covers. Slotted children stay consumer-owned; style them as ordinary elements.
7. Scoped custom CSS on tokens, only for requirements the API does not cover, leaving BEEQ's states and theme behaviour intact.

When BEEQ has no suitable component, use semantic native HTML styled with BEEQ tokens, and say so.

What is fixed and what is yours. Fixed: component names and APIs, parent/child structure, token names, theme and mode attributes, framework syntax, and the project's conventions. Yours: which component fits, composition and hierarchy, where on the spacing scale a gap sits, which action is primary, and copy.

The rules that matter most

Each row pairs the common mistake with its replacement and the reason. Use the reason to extend the rule to cases the table does not list.

The most common layout complaint, a tooltip around truncated text in a flex row the consumer builds (a card header, a table cell), resolved on the host and the slotted content:

<div class="card-header">
  <bq-tooltip>
    <span class="truncate" slot="trigger">A very long report title that must truncate</span>
    A very long report title that must truncate
  </bq-tooltip>
</div>

<style>
  .card-header {
    display: flex;
    gap: var(--bq-spacing-s);
  }

  .card-header bq-tooltip {
    min-width: 0;
  }

  .card-header .truncate {
    display: block;
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
  }
</style>

Navigation rows skip this recipe: bq-side-menu-item truncates its own label, so put the icon in slot="prefix" and the count in slot="suffix".

The same boundary holds for every bq-* element: consumer CSS positions and sizes the host; everything visual goes through the documented API.

Framework essentials

Bind each event on the element whose Events table lists it. Composite components split their events across parts: in a dropdown, bqSelect comes from bq-option-list, and bq-dropdown itself emits only bqOpen. A framework wrapper binds only the events its own component declares. Read event.detail only when the component documents a payload. Forms bindings, method refs, routing, Angular and Vue examples, and setup troubleshooting: frameworks.md.

4. Verify

The generated markup is a first draft. Models state these rules and then break them halfway through a long file; this pass is what catches it. If your tool can dispatch a subagent, hand it your output and this file and ask it to find violations independently.

Searches. Run each over your output:

Checklist. Judgment the searches cannot make:

• Step 1's findings are honoured: version, theme files, house recipes, nearby screens.
• Every piece, named or implied, uses the component its job calls for, even where the request's word suggests another. Anything hand-built is named in your reply with the reason.
• The stylesheet is imported and the icon base path is set, each exactly once. You added them if the project lacked them.
• Every name and literal prop value is verified against the component page, including which element emits each event, event.detail shapes, and parent/child structure.
• Framework syntax matches the stack.
• One primary action per region; danger only for destructive actions.
• Every control has a visible label or accessible name.
• Keyboard access, visible focus, and source order survive layout reflow.
• Every state has a text or icon cue alongside its colour.
• Overlays (dialog, drawer, dropdown, tooltip, toast) match their docs for placement, open and close, and focus handling.

If you can render the page, check a wide and a narrow width in light and dark modes: hierarchy, alignment, wrapping, contrast, focus rings, and overlay clipping.

Done when every search hit is fixed or explained as a deliberate exception, every checklist item holds, and your reply states the theme and mode you assumed, anything you could not verify in the consuming app (including visual fit if you could not render it), and the BEEQ pages or source you used.

Starting points

A form in HTML, with consumer CSS on BEEQ tokens:

<h2 id="contact-title">Contact us</h2>
<form class="contact-form" aria-labelledby="contact-title">
  <bq-input name="name" required>
    <label slot="label">Name</label>
  </bq-input>
  <bq-input name="email" type="email" required>
    <label slot="label">Email</label>
  </bq-input>
  <div class="contact-form__actions">
    <bq-button appearance="text">Cancel</bq-button>
    <bq-button type="submit">Send</bq-button>
  </div>
</form>

<style>
  .contact-form {
    display: grid;
    gap: var(--bq-spacing-m);
    max-inline-size: 60ch;
  }

  .contact-form__actions {
    display: flex;
    gap: var(--bq-spacing-s);
    justify-content: flex-end;
  }
</style>

The same actions in React:

import { BqButton } from '@beeq/react';

export function FormActions({ onCancel }: { onCancel: () => void }) {
  return (
    <div className="contact-form__actions">
      <BqButton appearance="text" onBqClick={onCancel}>
        Cancel
      </BqButton>
      <BqButton type="submit">Send</BqButton>
    </div>
  );
}

Angular and Vue equivalents are in frameworks.md.

Documentation lookup order

Use the most specific source. Current source and component API references win over docs, examples, generated summaries, and these references.

1. Component overview, then https://www.beeq.design/components/<component-name>.md. Related elements share a page, such as bq-tab-group and bq-tab on tab.md.
2. The framework guide for the stack: React, Next.js, Angular, Vue, HTML.
3. Styling guide, theming (with its global CSS variables, component CSS variables, and custom theme pages), and foundations.
4. Storybook for each component's states.
5. llms.txt, then llms-full.txt, or the MCP server in compatible tools.
6. The installed package: wrapper type definitions, and the Custom Elements Manifest named by the customElements field of node_modules/@beeq/core/package.json when that file is present.
7. Source, with repository access: packages/beeq/src/components/<name>/, the design tokens in packages/beeq/src/global/styles/foundations/, and the Tailwind preset in packages/beeq-tailwindcss/src/.