Beeq

<!-- Generated from packages/beeq-skills/src/beeq/SKILL.md. Edit the source, not this file. -->

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 or --bq-card--padding. Padding, background, 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.