Decision Support Card

DecisionSupportCard is a headless clinical decision support card in the shape of a CDS Hooks card: a one-line summary, an urgency indicator, the source of the guidance, optional detail, suggestions, links, and a way to dismiss it with a reason. CDS Hooks leaves rendering to the host system; this is that rendering, with no styling.

Status: experimental — new, implemented and unit-tested in every headless library; not yet exercised in a composed flow.

Example

Critical Penicillin allergy recorded

Amoxicillin is a penicillin.

Local formulary

Show demo markup
<div class="decision-support-card" role="group" aria-label="Penicillin allergy recorded" data-indicator="critical"><p class="decision-support-card-header"><span class="decision-support-card-indicator">Critical</span> <span class="decision-support-card-summary">Penicillin allergy recorded</span></p><div class="decision-support-card-detail"><p>Amoxicillin is a penicillin.</p></div><p class="decision-support-card-source"><a href="#">Local formulary</a></p><div class="decision-support-card-suggestions"><button type="button" class="decision-support-card-suggestion" data-recommended="true">Cancel amoxicillin</button></div><form class="decision-support-card-override"><label class="decision-support-card-override-label">Reason for dismissing <select class="decision-support-card-override-reason" name="overrideReason" required><option value="">Choose a reason</option><option value="error">Allergy recorded in error</option></select></label><button type="submit" class="decision-support-card-dismiss">Dismiss</button></form></div>
Usage example
<DecisionSupportCard
  summary="Penicillin allergy recorded"
  indicator="critical"
  indicatorLabel="Critical"
  sourceLabel="Local formulary"
  suggestions={[{ id: "cancel", label: "Cancel amoxicillin", isRecommended: true }]}
  dismissLabel="Dismiss"
  overrideReasons={[{ code: "aware", display: "Patient tolerated before" }]}
  overrideReasonLabel="Reason for dismissing"
  overrideReasonPlaceholder="Choose a reason"
>
  <p>Amoxicillin is a penicillin.</p>
</DecisionSupportCard>
Show Svelte source
// In your Svelte component:
import DecisionSupportCard from "lily-design-system-svelte-headless/components/DecisionSupportCard/DecisionSupportCard.svelte";

<DecisionSupportCard>
  <!-- content -->
</DecisionSupportCard>

Usage

<DecisionSupportCard
  summary="Penicillin allergy recorded"
  indicator="critical"
  indicatorLabel="Critical"
  sourceLabel="Local formulary"
  suggestions={[{ id: "cancel", label: "Cancel amoxicillin", isRecommended: true }]}
  dismissLabel="Dismiss"
  overrideReasons={[{ code: "aware", display: "Patient tolerated before" }]}
  overrideReasonLabel="Reason for dismissing"
  overrideReasonPlaceholder="Choose a reason"
>
  <p>Amoxicillin is a penicillin.</p>
</DecisionSupportCard>

Props

  • summary: string (required) — the one-sentence summary (CDS Hooks: under 140 characters); names the card
  • indicator: "info" | "warning" | "critical" (required) — rendered as data-indicator
  • indicatorLabel: string (required) — the indicator in words
  • sourceLabel: string (required) — where the guidance comes from
  • sourceHref: string (optional) — a link to the source
  • suggestions: { id, label, isRecommended? }[] (optional) — each a button
  • links: { label, href }[] (optional) — links to more information
  • dismissLabel: string (optional) — the dismiss button's text; no button without it
  • overrideReasons: { code, display }[] (optional) — when given, dismissing asks for one
  • overrideReasonLabel: string (optional) — the reason select's label
  • overrideReasonPlaceholder: string (optional) — the text of the select's empty first option
  • label: string (optional) — the accessible name, when it should differ from the summary
  • children: slot (optional) — the detail
  • onSuggestion: callback (optional) — called with the chosen suggestion's id
  • onDismiss: callback (optional) — called with the chosen reason's code, or none when no reasons are offered
  • ...restProps: any — additional HTML attributes spread onto the root

Keyboard Interactions

Key Action
Tab Moves to the next control in the card
Enter / Space Activates a suggestion or the dismiss button

ARIA

  • role="group" with aria-label from the summary (or label). Not a landmark and not a live region. aria-invalid on the reason select when a dismissal is refused

When to Use

  • Use to show a CDS Hooks card or any rule-based advice beside the task it concerns.
  • Use when advice can be accepted with one action or dismissed with a reason.
  • Use for information and warnings inline, and inside an alert-dialog only for critical items.

When Not to Use

  • Do not use for a page-wide message — use banner or alert.
  • Do not use for patient-facing care advice — use care-card.
  • Do not make every card interrupt; that is how alert fatigue starts.

Headless

This headless component ships zero CSS and decides nothing visual. The consumer provides all styling targeting the .decision-support-card class hook, and every word.

Styles

.decision-support-card and its parts, and [data-indicator].

Testing

  • The card is a group named by its summary and is not a live region
  • Enter and Space choose a suggestion
  • Dismissing without a reason is refused when reasons are offered, and focus moves to the select

Advice

  • Tier interruption by severity: information inline, a warning visible without blocking, only critical interrupting (AHRQ).
  • Remove a card when the hook it answered is triggered again; the consumer owns that.
  • Record the outcome (accepted, overridden with a reason) through CDS Hooks feedback; the consumer owns that too.

Implementation Notes

  • Renders <div class="decision-support-card" role="group"> named by its summary, with data-indicator (info, warning, critical)
  • The indicator is also text (indicatorLabel), so urgency is never colour alone
  • Suggestions are real buttons; the consumer applies them and enforces CDS Hooks' selectionBehavior
  • Dismissing is a form: when overrideReasons are given the reason select is required, and a dismissal without one is refused (the select is marked aria-invalid and focused). The static catalogs (HTML, Nunjucks, Alpine) rely on the browser's own validation
  • Not a live region: whether a critical card interrupts is the consumer's choice

Related components

  • alert-dialog — a modal dialog for urgent messages requiring acknowledgment
  • care-card — a medical care instruction card with urgency levels
  • medication-view — a medicine with its strength, form, route and frequency

References


Lily™ and Lily Design System™ are trademarks.

Canonical contract

Generated from this component's canonical metadata — the machine-checked source the implementations are held to.

Metadata

  • Component: decision-support-card
  • PascalCase: DecisionSupportCard
  • Description: a clinical decision support card with a summary, urgency indicator, source, suggestions and override reasons
  • Status: experimental — new, implemented and unit-tested in every headless library; not yet exercised in a composed flow
  • HTML tag: <div>
  • CSS class: .decision-support-card
  • Interactive: yes

ARIA

  • role="group" with aria-label from the summary (or label). Not a landmark and not a live region. aria-invalid on the reason select when a dismissal is refused

Keyboard

  • Tab moves through the source link, suggestions, links, the reason select and the dismiss button; Enter or Space activates a suggestion or the dismiss button

Props

  • summary: string (required) — the one-sentence summary (CDS Hooks: under 140 characters); names the card
  • indicator: "info" | "warning" | "critical" (required) — rendered as data-indicator
  • indicatorLabel: string (required) — the indicator in words
  • sourceLabel: string (required) — where the guidance comes from
  • sourceHref: string (optional) — a link to the source
  • suggestions: { id, label, isRecommended? }[] (optional) — each a button
  • links: { label, href }[] (optional) — links to more information
  • dismissLabel: string (optional) — the dismiss button's text; no button without it
  • overrideReasons: { code, display }[] (optional) — when given, dismissing asks for one
  • overrideReasonLabel: string (optional) — the reason select's label
  • overrideReasonPlaceholder: string (optional) — the text of the select's empty first option
  • label: string (optional) — the accessible name, when it should differ from the summary
  • children: slot (optional) — the detail
  • onSuggestion: callback (optional) — called with the chosen suggestion's id
  • onDismiss: callback (optional) — called with the chosen reason's code, or none when no reasons are offered
  • ...restProps: any — additional HTML attributes spread onto the root

Markdown

This page as Markdown, for people and AI tools: decision-support-card.md