cv-guidance-panel

Product-agnostic guidance body layout for coach marks, inline hints, warnings, and blocked-action explanations. It owns only visual structure and styling; app-layer guidance state, overlay semantics, progress, dismiss, snooze, and completion live outside UIKit.

Usage

View source

<div class="guidance-panel-demo-shell" data-demo="guidance-panel" data-live-demo-height="760">
  <section class="guidance-panel-demo-brief" aria-labelledby="guidance-panel-demo-title">
    <div class="guidance-panel-demo-copy">
      <span class="guidance-panel-demo-kicker">Guidance body primitive</span>
      <h3 id="guidance-panel-demo-title">One readable panel for every guidance placement.</h3>
      <p>
        Use the panel when the product needs to explain a next step, a warning, or a blocked action. The app
        guidance host decides when and where it appears; this component keeps the message, variant, progress,
        and actions visually consistent.
      </p>
    </div>

    <dl class="guidance-panel-demo-contract" aria-label="Guidance panel responsibility split">
      <div>
        <dt>UIKit owns</dt>
        <dd>Slots, density, variant color, and action styling.</dd>
      </div>
      <div>
        <dt>Host owns</dt>
        <dd>Placement, progress state, dismiss, snooze, and focus behavior.</dd>
      </div>
    </dl>
  </section>

  <section class="guidance-panel-demo-product" aria-labelledby="guidance-panel-demo-product-title">
    <header class="guidance-panel-demo-toolbar">
      <div>
        <span class="guidance-panel-demo-kicker">Vault setup</span>
        <h4 id="guidance-panel-demo-product-title">The same panel body in product context</h4>
      </div>
      <span class="guidance-panel-demo-status">3 placements</span>
    </header>

    <div class="guidance-panel-demo-grid">
      <div class="guidance-panel-demo-workspace" aria-label="Guided vault setup preview">
        <div class="guidance-panel-demo-vault-row">
          <span>
            <strong>Recovery key</strong>
            <small>generated locally</small>
          </span>
          <span class="guidance-panel-demo-state">done</span>
        </div>

        <div class="guidance-panel-demo-vault-row guidance-panel-demo-vault-row--active">
          <span>
            <strong>First secret</strong>
            <small>waiting for user action</small>
          </span>
          <cv-button variant="primary" size="small">Create item</cv-button>
        </div>

        <div class="guidance-panel-demo-coach-mark">
          <span class="guidance-panel-demo-rail" aria-hidden="true"></span>
          <cv-guidance-panel variant="coach-mark" density="comfortable">
            <span slot="icon" aria-hidden="true">i</span>
            <span slot="title">Create the first vault item</span>
            <p>
              A coach mark can sit near the action it explains while the host tracks this as step 2 of the
              onboarding sequence.
            </p>
            <span slot="progress">2 / 4</span>
            <button slot="actions" type="button" data-guidance-action="primary">Start</button>
            <button slot="actions" type="button" data-guidance-action="secondary">Later</button>
          </cv-guidance-panel>
        </div>
      </div>

      <aside class="guidance-panel-demo-stack" aria-label="Guidance variants preview">
        <cv-guidance-panel variant="hint" density="compact">
          <span slot="icon" aria-hidden="true">?</span>
          <span slot="title">Inline hint</span>
          <p>Place compact help below a field or empty state without opening an overlay.</p>
        </cv-guidance-panel>

        <cv-guidance-panel variant="warning" density="compact">
          <span slot="icon" aria-hidden="true">!</span>
          <span slot="title">Risk before export</span>
          <p>Warn before an operation changes the user's threat model or leaves the local vault.</p>
          <button slot="actions" type="button" data-guidance-action="secondary">Review</button>
        </cv-guidance-panel>

        <cv-guidance-panel variant="blocked" density="compact">
          <span slot="icon" aria-hidden="true">x</span>
          <span slot="title">Action blocked</span>
          <p>Explain why the action is unavailable and point to the next recoverable step.</p>
          <button slot="actions" type="button" data-guidance-action="primary">Connect device</button>
        </cv-guidance-panel>
      </aside>
    </div>
  </section>

  <section class="guidance-panel-demo-note" aria-labelledby="guidance-panel-demo-note-title">
    <div>
      <span class="guidance-panel-demo-kicker">Accessibility boundary</span>
      <h4 id="guidance-panel-demo-note-title">The panel is content, not a dialog.</h4>
    </div>
    <p>
      It renders neutral note content. Put it inside a popover, bottom sheet, inline region, or blocked-action
      surface when the owning app layer supplies the right semantics.
    </p>
  </section>
</div>

Anatomy

<cv-guidance-panel> (host)
└── <section part="base" role="note">
    ├── <header part="header">
    │   ├── <span part="icon">
    │   │   └── <slot name="icon">
    │   ├── <div part="title">
    │   │   └── <slot name="title">
    │   └── <div part="progress">
    │       └── <slot name="progress">
    ├── <div part="body">
    │   └── <slot>
    └── <div part="actions">
        └── <slot name="actions">

Attributes

Attribute	Type	Default	Description
variant	String	"coach-mark"	Visual variant: "coach-mark" | "hint" | "warning" | "blocked"
density	String	"comfortable"	Spacing density: "comfortable" | "compact"

Slots

Slot	Description
icon	Optional leading visual.
title	Guidance title exposed through the stable title part.
(default)	Main body content.
actions	Optional action controls supplied by the app host or owning surface.
progress	Optional progress text or indicator, such as 1 / 4.

CSS Parts

Part	Element	Description
base	<section>	Outer neutral content container.
header	<header>	Layout row for icon, title, and progress.
icon	<span>	Wrapper around the icon slot.
title	<div>	Wrapper around the title slot.
progress	<div>	Wrapper around the progress slot.
body	<div>	Wrapper around the default slot.
actions	<div>	Wrapper around the actions slot.

CSS Custom Properties

Property	Default	Description
--cv-guidance-panel-background	var(--cv-color-surface-elevated, #1d2432)	Base background.
--cv-guidance-panel-border-color	var(--cv-color-border, #2a3245)	Base border color.
--cv-guidance-panel-border-radius	var(--cv-radius-md, 8px)	Base border radius.
--cv-guidance-panel-color	var(--cv-color-text, #e8ecf6)	Host text color.
--cv-guidance-panel-body-color	var(--cv-color-text-muted, #bac4d8)	Body text color.
--cv-guidance-panel-title-color	var(--cv-color-text-strong, currentColor)	Title text color.
--cv-guidance-panel-icon-color	currentColor	Icon color before variant overrides.
--cv-guidance-panel-padding-inline	var(--cv-space-4, 16px)	Horizontal padding.
--cv-guidance-panel-padding-block	var(--cv-space-4, 16px)	Vertical padding.
--cv-guidance-panel-gap	var(--cv-space-3, 12px)	Main layout gap.
--cv-guidance-panel-actions-gap	var(--cv-space-2, 8px)	Gap between action controls.
--cv-guidance-panel-compact-padding-inline	var(--cv-space-3, 12px)	Compact horizontal padding.
--cv-guidance-panel-compact-padding-block	var(--cv-space-3, 12px)	Compact vertical padding.
--cv-guidance-panel-compact-gap	var(--cv-space-2, 8px)	Compact main layout gap.

Accessibility

cv-guidance-panel renders neutral supplementary content with role="note" on part="base". It does not set dialog, popover, modal, live-region, focus-trap, dismiss, snooze, or completion semantics. app-guidance-host or the owning surface decides whether the panel appears inside a popover, bottom sheet, inline region, or another accessible container.

Boundaries

The component must not import WebView app state, navigation, module access, i18n data, guidance registry, or guidance model modules. It is a dumb visual primitive that renders slots and reflected presentation attributes.