# DV Layer — full component reference > Generated from `@ai-*` JSDoc headers (v0.22.0). For the index, see llms.txt. ## accordion Groups expandable content sections under disclosure buttons. - Base class: `dv-accordion` - React: `` - Element: `div` - Source: packages/html/src/css/components/_accordion.css, packages/react/src/components/Accordion.tsx, packages/html/src/js/components/accordion.js - Modifiers: `dv-accordion__item--open`, `dv-accordion__item--disabled` ### HTML ```html

Panel content here

``` ### React ```tsx Section 1 Content for section 1 Section 2 Content for section 2 ``` ### Props ```ts open?: string[] defaultOpen?: string[] onOpenChange?: (open: string[]) => void allowMultiple?: boolean allowCollapse?: boolean borderless?: boolean ``` ### Events - `open` — Fired before panel opens (cancelable with preventDefault) - `opened` — Fired after panel has opened - `close` — Fired before panel closes (cancelable with preventDefault) - `closed` — Fired after panel has closed ### Keyboard - Up/Down arrows: Navigate between items - Home: Go to first item - End: Go to last item ### Options - `allowMultiple` (default: `false`) - `allowCollapse` (default: `true`) - `announceChange` (default: `true`) ### Accessibility - Trigger button MUST have aria-expanded - Author closed panels with the hidden attribute (no-JS-safe). At runtime the JS removes hidden and instead toggles inert + aria-hidden="true" so the panel stays mounted and the open/close height transition can run both ways — it never re-applies hidden/display:none - Use aria-controls to associate trigger with panel - Wrap each trigger in the __header heading element (APG Accordion) at the level the surrounding document calls for — without it the panels are unreachable by heading navigation, which is how screen-reader users skim an accordion ### Avoid - Nesting accordions more than one level deep --- ## alert Displays an inline informational, success, warning, or error message. - Base class: `dv-alert` - React: `` - Element: `div` - Source: packages/html/src/css/components/_alert.css, packages/react/src/components/Alert.tsx - Variants: `dv-alert--info`, `dv-alert--success`, `dv-alert--warning`, `dv-alert--error` ### HTML ```html

Information

This is an informational message.

Operation completed successfully.

Error

Something went wrong.

``` ### React ```tsx This is an informational message. Something went wrong. Operation completed successfully. ``` ### Props ```ts variant?: 'info'|'success'|'warning'|'error' title?: ReactNode icon?: ReactNode hideIcon?: boolean iconBox?: boolean ``` ### Accessibility - Use role="alert" for important messages that need immediate attention (error/warning), role="status" for informational ones. An alert with no role is silent when inserted dynamically — the colour and icon carry the severity visually and nothing carries it to AT - An alert rendered in the initial page HTML needs no live-region role — reserve role="alert"/"status" for alerts inserted or revealed after load - Include descriptive icon with aria-hidden="true" ### Avoid - Combining multiple status variants (info, success, warning, error) - Alerts without icon or clear visual indicator --- ## alert-dialog Requests confirmation for a consequential action in a modal dialog. - Base class: `dv-alert-dialog` - React: `` - Element: `dialog` - Source: packages/html/src/css/components/_alert-dialog.css, packages/react/src/components/AlertDialog.tsx, packages/html/src/js/components/alert-dialog.js ### HTML ```html ``` ### React ```tsx Delete Item? This action cannot be undone. Cancel Delete ``` ### Props ```ts open?: boolean defaultOpen?: boolean onOpenChange?: (open: boolean, details: DialogOpenChangeDetails) => void onCancel?: () => void onConfirm?: () => void | Promise onConfirmError?: (error: unknown) => void confirmationErrorMessage?: ReactNode children?: ReactNode ``` ### Events - `open` — Fired before the alert dialog opens (cancelable with preventDefault) - `opened` — Fired after the alert dialog has fully opened - `confirm` — Fired when the confirm action button is clicked - `cancel` — Fired when the user dismisses (Cancel button, Escape key, or backdrop click when closeOnBackdrop is enabled) - `close` — Fired before the alert dialog closes (cancelable with preventDefault) - `closed` — Fired after the alert dialog has fully closed ### Options - `closeOnBackdrop` (default: `false`) - `closeOnEscape` (default: `true`) - `restoreFocus` (default: `true`) ### Accessibility - Always render on a native with role="alertdialog", aria-labelledby (title), aria-describedby (message). Call .showModal() for focus trap and ::backdrop. Default focus to Cancel, never the destructive action. ### Avoid - Nesting .dv-alert-dialog inside .dv-dialog — they are parallel primitives, not a content block + shell. --- ## app Provides the application shell and content area around topbar and sidebar navigation. - Base class: `dv-app` - React: `` - Element: `div` - Source: packages/html/src/css/components/_app.css, packages/react/src/components/App.tsx - Modifiers: `dv-app--header-top`, `dv-app--inset` ### HTML ```html

Content

``` ### React ```tsx ... ... ... ``` ### Props ```ts layout?: 'default'|'header-top' inset?: boolean ``` --- ## avatar Represents a person or entity with an image, initials, or a fallback icon. - Base class: `dv-avatar` - React: `` - Element: `div|span` - Source: packages/html/src/css/components/_avatar.css, packages/react/src/components/Avatar.tsx - Variants: `dv-avatar--accent`, `dv-avatar--success`, `dv-avatar--info` - Sizes: `dv-avatar--xs`, `dv-avatar--sm`, `dv-avatar--md` (default), `dv-avatar--lg`, `dv-avatar--xl` ### HTML ```html

``` ### React ```tsx ``` ### Props ```ts size?: 'xs'|'sm'|'md'|'lg'|'xl' variant?: 'default'|'accent'|'success'|'info' src?: string alt?: string initials?: string name?: string ``` ### Accessibility - Images must have alt text; initials provide fallback - Avatar groups should have aria-label describing the group ### Avoid - Combining multiple color variants (accent, success, info) - Using images without alt text --- ## badge Labels status, counts, or categories with compact inline text. - Base class: `dv-badge` - React: `` - Element: `span|button` - Source: packages/html/src/css/components/_badge.css, packages/react/src/components/Badge.tsx - Variants: `dv-badge--neutral`, `dv-badge--success`, `dv-badge--warning`, `dv-badge--error`, `dv-badge--info`, `dv-badge--accent`, `dv-badge--solid-accent`, `dv-badge--solid-success`, `dv-badge--solid-warning`, `dv-badge--solid-error`, `dv-badge--interactive`, `dv-badge--removable` - Sizes: `dv-badge--sm`, `dv-badge--lg` - Modifiers: `dv-badge--multiline` ### HTML ```html Waiting for editorial approval Default Neutral (explicit) Accent Success Large Error Active Label Tag Operational ``` ### React ```tsx Waiting for editorial approval New Active }>Verified Tag ``` ### Props ```ts multiline?: boolean variant?: 'neutral'|'success'|'warning'|'error'|'info'|'accent'|'solid-accent'|'solid-success'|'solid-warning'|'solid-error' size?: 'sm'|'lg' dot?: boolean dotPulse?: boolean icon?: ReactNode removable?: boolean onRemove?: () => void interactive?: boolean render?: RenderProp ``` ### Accessibility - Removable badges MUST have remove button with aria-label - A status dot ACCOMPANIED by visible text ("* Active") is decorative — mark it aria-hidden="true" so the label is not read twice - A STANDALONE status dot is the only carrier of its meaning, so it must not be aria-hidden: give it role="img" + aria-label (or an adjacent .dv-sr-only span). The dot variants differ by hue alone — --active/--success, --pending/--warning and --inactive/--neutral are literally the same fill — so a bare dot with no name conveys nothing to AT and nothing to a colour-blind user either (WCAG 1.4.1). Prefer the dot + visible text form wherever the layout allows it - Count bubbles (`--count`) are decorative (aria-hidden); the count MUST be conveyed on the trigger instead, e.g. aria-label="Notifications, 3 unread" ### Avoid - Combining multiple status variants (success, warning, error) - Using solid- variants with other color variants --- ## banner Presents a page-level announcement with optional actions and dismissal. - Base class: `dv-banner` - React: `` - Element: `div` - Source: packages/html/src/css/components/_banner.css, packages/react/src/components/Banner.tsx, packages/html/src/js/components/banner.js - Variants: `dv-banner--info`, `dv-banner--success`, `dv-banner--warning`, `dv-banner--error`, `dv-banner--accent` - Modifiers: `dv-banner--sticky` ### HTML ```html ``` ### React ```tsx Scheduled maintenance tonight at 2:00 AM UTC. Upgrade}>Your trial ends in 3 days. ``` ### Props ```ts variant?: 'info'|'success'|'warning'|'error'|'accent' sticky?: boolean persistId?: string icon?: ReactNode action?: ReactNode dismissible?: boolean onDismiss?: () => void live?: boolean // announce through a separate primed status host; visible banner keeps role=region ``` ### Events - `dismiss` — Fired before the banner hides (cancelable with preventDefault) - `dismissed` — Fired after the banner has hidden ### Options - `persist` (default: `true`) ### Accessibility - A persistent system announcement uses role="region" with an aria-label; the dismiss button needs an aria-label. - React keeps the visible banner as a region and announces through a separate, initially empty status host. For custom HTML updates, prime an empty polite live region before inserting announcement text; do not rely on inserting a populated status element. ### Avoid - Combining multiple status variants on one banner. --- ## breadcrumb Shows the current page within a navigable hierarchy. - Base class: `dv-breadcrumb` - React: `` - Element: `nav` - Source: packages/html/src/css/components/_breadcrumb.css, packages/react/src/components/Breadcrumb.tsx ### HTML ```html ``` ### React ```tsx Home Products }>Widget Detail ``` ### Props ```ts children?: ReactNode maxItems?: number · itemsBeforeCollapse?: number · itemsAfterCollapse?: number // Breadcrumb.Item: href?: string · current?: boolean · render?: RenderProp ``` ### Accessibility - Use a

wrapping an

so list semantics announce position/size - Current page should not be a link; mark it aria-current="page" - Automatic middle-collapse is React-only; in plain HTML the ellipsis must initialize a real menu containing every omitted destination, as in the second snippet. ### Avoid - Linking the current/last breadcrumb item --- ## bulk-bar Groups selection counts and actions that apply to multiple selected items. - Base class: `dv-bulk-bar` - React: `
` - Element: `div` - Source: packages/html/src/css/components/_bulk-bar.css, packages/react/src/components/BulkBar.tsx - Modifiers: `dv-bulk-bar--static`, `dv-bulk-bar--top` ### HTML ```html
8 selected
``` ### React ```tsx }>Download }>Share } danger>Delete } iconOnly aria-label="Clear selection" onClick={onClear} /> ``` ### Props ```ts count?: number label?: ReactNode placement?: 'bottom' | 'top' | 'static' open?: boolean ``` ### Accessibility - role="group", not role="toolbar". `toolbar` is a PROMISE of arrow-key roving between the actions, and plain HTML ships no bulk-bar controller to deliver it — a toolbar whose arrow keys do nothing is worse than no toolbar, because AT tells the user to use keys that are dead. Every action stays in the tab order, which is fully accessible. The React
DOES implement the APG roving tabindex, and uses role="toolbar" accordingly. --- ## button Triggers an action with variants for emphasis, loading, and icon-only controls. - Base class: `dv-button` - React: ` Link Button ``` ### React ```tsx
``` ### Props ```ts multiline?: boolean variant?: 'accent'|'neutral'|'outline'|'ghost'|'danger'|'success'|'link' size?: 'sm'|'md'|'lg' block?: boolean iconOnly?: boolean loading?: boolean active?: boolean dot?: boolean startIcon?: ReactNode endIcon?: ReactNode href?: string render?: RenderControl disabled?: boolean ``` ### Accessibility - Icon-only buttons MUST have aria-label ### Avoid - Labels stay on one line by default; use --multiline for long labels in constrained containers - Using Button.Group for responsive action sets — it is a joined control; use a wrapping Stack or PageHeader.Actions - Do not combine --link with size modifiers --- ## calendar Calendar display surface with month, week, day and year views. Presentational shell — it builds the date scaffold, the consumer supplies the events. - Base class: `dv-calendar` - React: `
` - Element: `div` - Source: packages/html/src/css/components/_calendar.css, packages/react/src/components/Calendar.tsx, packages/html/src/js/components/calendar.js - Variants: `dv-calendar--month`, `dv-calendar--week`, `dv-calendar--day`, `dv-calendar--year` - Modifiers: `dv-calendar--week-columns`, `dv-calendar__day--today`, `dv-calendar__day--selected`, `dv-calendar__day--outside`, `dv-calendar__day--disabled`, `dv-calendar__daylabel--today`, `dv-calendar__event--accent`, `dv-calendar__event--success`, `dv-calendar__event--warning`, `dv-calendar__event--error`, `dv-calendar__event--info`, `dv-calendar__event--tentative`, `dv-calendar__event--cancelled`, `dv-calendar__dot--accent`, `dv-calendar__dot--success`, `dv-calendar__dot--warning`, `dv-calendar__dot--error`, `dv-calendar__dot--info`, `dv-calendar__day--drop`, `dv-calendar__column--drop` ### HTML ```html
July 2026
Mon
10:00Design review
29
1. Design review10:00
Wed29
All day
Offsite
Breakfast6:00 AM
January
``` ### React ```tsx ``` ### Props ```ts view?: 'month' | 'week' | 'day' | 'year' date?: LocalDate defaultDate?: LocalDate onDateChange?: (date: LocalDate) => void selected?: LocalDate | null defaultSelected?: LocalDate | null onSelect?: (date: LocalDate | null) => void firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6 min?: LocalDate max?: LocalDate locale?: string nowIndicator?: boolean today: LocalDate scrollToNow?: boolean swipe?: boolean days?: 1 | 2 | 3 | 4 | 5 | 6 | 7 maxEventsPerDay?: number weekLayout?: 'timegrid' | 'columns' dropDate?: LocalDate | null onMoreClick?: (date: LocalDate, hidden: number) => void agenda?: boolean title?: ReactNode actions?: ReactNode hideNav?: boolean ``` ### Events - `navigate` — Period changed (detail: { view, date }) - `view-change` — View changed (detail: { view, date }) - `changed` — Day selection changed (detail: { value, date }) - `render` — Scaffold (re)built (detail: { view, date }) - `show-more` — Overflow marker used (detail: { date, hidden, total }) — button form only ### Keyboard - Enter/Space: Activate/select ### Options - `view` (default: `'month'`) - `date` (default: `null`) - `selected` (default: `null`) - `firstDayOfWeek` (default: `0`) - `days` (default: `7`) - `min` (default: `null`) - `max` (default: `null`) - `nowIndicator` (default: `true`) - `scrollToNow` (default: `true`) - `swipe` (default: `true`) - `today` (default: `null`) - `maxEventsPerDay` (default: `DEFAULT_MAX_MONTH_CHIPS`) - `weekLayout` (default: `'timegrid'`) - `moreButton` (default: `false`) ### Accessibility - The month/year grid is role="grid"; the weekday strip is its first role="row" of role="columnheader" cells, each week is a role="row" of role="gridcell" days. Exactly one day carries tabindex="0" (roving), the rest tabindex="-1" — the APG layout-grid pattern, so the event links inside a cell stay reachable by Tab - Today carries aria-current="date"; the selected day carries aria-selected="true" - The weekday header keeps its long form in the a11y tree at every width — the single-letter form is aria-hidden and the long form is only visually hidden - A horizontal TOUCH swipe pages the period (`data-dv-calendar-swipe="false"` opts out). Measured between pointerdown and pointerup only — no pointer capture, no preventDefault, no touch-action, so it never swallows a tap, the page scroll or pinch-zoom - The arrow-key grid model is month/year ONLY — week/day have no day cells. There `__timegrid` is instead a focusable scroll container (tabindex="0", role="group", named by the period), because a scroller with no focusable child is not keyboard-operable in WebKit - Every navigation that leaves focus where it is (prev/next/today/setDate/setView) announces the new period; the arrow keys do not, because the cell they focus already states its full date - Decorative scaffold (hour gutter, grid lines, day columns, event dots, now-indicator) is aria-hidden="true"; events stay real links/buttons in DOM order. The day columns carry data-dv-date so a drag-and-drop app layer can resolve the day under the pointer, and they stay aria-hidden because a drop target is not a control — a keyboard route to the same action (a "move to…" item in the event's own menu) is the CONSUMER's to provide - The `__agenda` carries an aria-label naming the day it is showing, and falls back to a day in the rendered period when nothing is selected — below 36rem it is the only place the event detail survives, so it must never render empty - A linked event renders its `__agenda-title` as the anchor, because the chip it duplicates is display:none at that width - `__event--cancelled`'s strike-through and `__event--tentative`'s dashed edge are DECORATION — a screen reader hears neither, and the chip's text is the consumer's, so the word ("Cancelled", "Tentative") must be in the event's own title ### Avoid - Rendering a second, duplicate grid for small screens — one grid adapts via @container --- ## card Groups related content and actions in a bordered or elevated surface. - Base class: `dv-card` - React: `
` - Element: `div|article|section` - Source: packages/html/src/css/components/_card.css, packages/react/src/components/Card.tsx - Variants: `dv-card--elevated`, `dv-card--interactive`, `dv-card--hover`, `dv-card--hero`, `dv-card--selectable`, `dv-card--fill` ### HTML ```html
Content

Content with media — defaults to 16:9; override via style="--dv-card-media-aspect: 4/3"

Title
Content

Title
Description
Content

Article title
Article summary

Feature
Surface lifts on hover; the real action is the link below.
Learn more

Title
Body grows so the footer pins to the bottom — pair with a stretch grid for equal-height rows
Footer
``` ### React ```tsx Card Title A brief description Card content goes here ``` ### Props ```ts elevated?: boolean affordance?: 'interactive'|'hover' hero?: boolean selectable?: boolean fill?: boolean render?: RenderProp // Card.Action: render?: RenderProp // Card.Media: aspectRatio?: 'square'|'portrait' ``` ### Accessibility - Interactive cards need tabindex="0" and keyboard support - --hover is a decorative hover affordance only (invisible to keyboard/touch); never make it the sole affordance for an action — the real interaction must be a focusable child (link/button) - Card titles should use appropriate heading level ### Avoid - Using --interactive without tabindex and role - Nesting cards more than one level deep --- ## carousel Presents a sequence of slides with navigation and optional autoplay controls. - Base class: `dv-carousel` - React: `
` - Element: `section` - Source: packages/html/src/css/components/_carousel.css, packages/react/src/components/Carousel.tsx, packages/html/src/js/components/carousel.js - Variants: `dv-carousel--fade`, `dv-carousel--vertical` - Modifiers: `dv-carousel--draggable`, `dv-carousel--dragging`, `dv-carousel--single`, `dv-carousel--auto-width`, `dv-carousel--adaptive-height`, `dv-carousel__control--playing`, `dv-carousel__slide--active`, `dv-carousel__slide--clone` ### HTML ```html
Slide 1
Slide 2
``` ### React ```tsx Slide 1 Slide 2 ``` ### Props ```ts effect?: 'slide'|'fade' axis?: 'horizontal'|'vertical' loop?: boolean slidesPerView?: number | 'auto' | { base: number | 'auto'; sm?: number | 'auto'; md?: number | 'auto'; lg?: number | 'auto'; xl?: number | 'auto'; '2xl'?: number | 'auto' } spacing?: number | { base: number; sm?: number; md?: number; lg?: number; xl?: number; '2xl'?: number } adaptiveHeight?: boolean autoplay?: number intervals?: Record pauseOnHover?: boolean drag?: boolean keyboard?: boolean mousewheel?: boolean threshold?: number velocityThreshold?: number cooldown?: number announceChange?: boolean arrows?: boolean control?: boolean pagination?: boolean index?: number defaultIndex?: number onIndexChange?: (index: number) => void onChange?: (detail: { from: number; to: number }, event: CustomEvent) => void onChanged?: (detail: { index: number }) => void apiRef?: Ref<{ goTo, next, prev, play, pause }> aria-label: string labels?: Partial<{ prev, next, play, pause, slide, slidePosition, pagination, goToSlide, announce }> Children are elements. Prev/next arrows, the play/pause control (when autoplay is set), and pagination bullets render automatically (toggle with arrows / control / pagination = false). Arrows + control reuse .dv-button. ``` ### Events - `change` — Before the active slide changes (cancelable). detail: { from, to } - `changed` — After the active slide has changed. detail: { index } ### Keyboard - Left/Right arrows: Navigate between items - Up/Down arrows: Navigate between items - Home: Go to first item - End: Go to last item ### Options - `effect` (default: `'slide'`) - `axis` (default: `'horizontal'`) - `loop` (default: `false`) - `slidesPerView` (default: `1`) - `spacing` (default: `0`) - `adaptiveHeight` (default: `false`) - `autoplay` (default: `0`) - `pauseOnHover` (default: `true`) - `drag` (default: `true`) - `keyboard` (default: `true`) - `mousewheel` (default: `false`) - `threshold` (default: `0.1`) - `velocityThreshold` (default: `0.5`) - `cooldown` (default: `300`) - `announceChange` (default: `true`) ### Accessibility - Root carries role="region" + aria-roledescription="carousel" + an aria-label - Each slide is role="group" aria-roledescription="slide" aria-label="N of M" - Slides outside the visible window get `inert` + aria-hidden="true" so Tab never reaches a clipped slide (which would scroll the viewport and desync the track); the slide holding focus is spared until focus leaves it - RTL is mirrored end-to-end: track translate, drag/wheel resolution, the horizontal arrow keys and the chevron glyphs. The vertical axis is unaffected - Pagination is the APG "grouped" picker set: role="group" holding plain buttons, the current one aria-disabled="true" (never natively disabled, so it stays reachable). No roving tabindex — every picker is its own tab stop, by design - The .dv-carousel__control must come FIRST inside the root so it is the first tab stop; it carries no aria-pressed — its changing label is the state - Prev/next/control buttons reuse .dv-button (.dv-button--icon-only) for chrome - All AT strings are localizable via data-dv-carousel-*-label attrs (React: labels prop) - Autoplay pauses on hover, off-screen and reduced-motion, and STOPS for good on keyboard focus — only the control restarts it (APG). It stays out of the live region while rotating; only manual navigation announces ### Avoid - Auto-advancing without a .dv-carousel__control — WCAG 2.2.2 fail; the engine warns on it at init - The --vertical variant without a definite block-size on .dv-carousel__viewport — the slides' percentage flex-basis resolves against the track's main size, which on the block axis is the viewport's, so leaving it auto resolves circularly and the track collapses to nothing --- ## chart Plots data on a canvas using the documented chart types and options. - Base class: `dv-chart` - React: `` - Element: `div` - Source: packages/html/src/css/components/_chart.css, packages/react/src/components/Chart.tsx, packages/html/src/js/components/chart.js ### HTML ```html
``` ### React ```tsx ``` ### Props ```ts type?: 'bar'|'horizontal-bar'|'line'|'area'|'donut'|'stacked-bar'|'stacked-area' curve?: 'smooth'|'linear'|'monotone' data: { labels: string[]; series: { name: string; values: number[] }[] } showGrid?: boolean showLegend?: boolean showTooltip?: boolean showPoints?: boolean yMin?: number|null yMax?: number|null onHover?: (detail: { seriesIndex: number; dataIndex: number } | null) => void onRendered?: () => void onLegendToggle?: (detail: { seriesIndex: number; hidden: boolean }) => void aria-label: string ``` ### Events - `rendered` — Fired after chart renders - `hover` — Fired on data point hover (detail: { seriesIndex, dataIndex } | null) - `legend-toggle` — Fired when a legend item is toggled (detail: { seriesIndex, hidden }) ### Options - `type` (default: `'bar'`) - `curve` (default: `'smooth'`) - `showGrid` (default: `true`) - `showLegend` (default: `true`) - `showTooltip` (default: `true`) - `showPoints` (default: `true`) - `yMin` (default: `null`) - `yMax` (default: `null`) ### Accessibility - Use role="figure" and aria-label on the container - A sr-only data table is generated for screen readers ### Avoid - Hardcoding colors — use semantic tokens - Default curve="smooth" on spiky line/area data — it can visually overshoot; use curve="linear" or "monotone" --- ## checkbox Self-contained checkbox with error and disabled support - Base class: `dv-checkbox` - React: `` - Source: packages/html/src/css/components/_checkbox.css, packages/react/src/components/Checkbox.tsx, packages/html/src/js/components/checkbox.js - Modifiers: `dv-checkbox--error`, `dv-checkbox--success`, `dv-checkbox--disabled`, `dv-checkbox--card` ### HTML ```html
Label text

Accept terms
Required

Disabled

Card optionThe whole card is clickable; selecting it highlights the border + background.
``` ### React ```tsx ``` ### Props ```ts checked?: boolean defaultChecked?: boolean onCheckedChange?: (checked: boolean) => void label?: ReactNode description?: ReactNode error?: string hint?: string success?: boolean indeterminate?: boolean disabled?: boolean card?: boolean ``` ### Events - `changed` — Fired when any checkbox state has changed (post-commit; a - `select-all` — Fired when all checkboxes are selected - `deselect-all` — Fired when all checkboxes are deselected - `error` — Fired when error is set - `error-cleared` — Fired when error is cleared ### Options - `parentSelector` (default: `'.dv-checkbox__parent'`) - `childSelector` (default: `'.dv-checkbox__child'`) ### Accessibility - Use for/id association between label and input - --card needs a visible __label; don't place other interactive elements inside a --card — the stretched label overlays the whole surface - Use aria-describedby when description is present ### Avoid - Combining --card with --error/--success — per-item validation isn't supported on cards; validate at the group level --- ## code Formats inline code or a preformatted code block. - Base class: `dv-code` - React: `` - Element: `code|pre` - Source: packages/html/src/css/components/_code.css, packages/react/src/components/Code.tsx - Variants: `dv-code--block`, `dv-code--dark`, `dv-code--success`, `dv-code--error`, `dv-code--warning` ### HTML ```html inline code const x = 1; $ npm install ``` ### React ```tsx const x = 42; {'const x = 1;'} {'$ npm install'} ``` ### Props ```ts variant?: 'dark'|'success'|'error'|'warning' block?: boolean ``` ### Accessibility - Use appropriate semantic elements (code, pre) - Consider aria-label for code samples with context ### Avoid - Using --block without wrapping in pre element --- ## collapsible Shows or hides one content region through a disclosure trigger. - Base class: `dv-collapsible` - React: `` - Element: `div` - Source: packages/html/src/css/components/_collapsible.css, packages/react/src/components/Collapsible.tsx, packages/html/src/js/components/collapsible.js - Modifiers: `dv-collapsible--disabled` ### HTML ```html Collapsible content here ``` ### React ```tsx Toggle details Collapsible content here ``` ### Props ```ts open?: boolean defaultOpen?: boolean onOpenChange?: (open: boolean) => void disabled?: boolean borderless?: boolean ``` ### Events - `open` — Fired before content opens (cancelable with preventDefault) - `opened` — Fired after content has opened - `close` — Fired before content closes (cancelable with preventDefault) - `closed` — Fired after content has closed ### Options - `defaultOpen` (default: `false`) - `announceChange` (default: `true`) ### Accessibility - Trigger button MUST have aria-expanded reflecting the open state - Use aria-controls to associate the trigger with the content element - Collapsed content MUST have the hidden attribute (or data-state="closed") ### Avoid - Using Collapsible for multiple independent sections — use Accordion instead --- ## color-picker Swatch-trigger color picker: 2D SV surface, hue/opacity sliders, HEX/RGB/HSL inputs, swatches - Base class: `dv-color-picker` - React: `` - Source: packages/html/src/css/components/_color-picker.css, packages/react/src/components/ColorPicker.tsx, packages/html/src/js/components/color-picker.js - Sizes: `dv-color-picker--sm`, `dv-color-picker--lg` - Modifiers: `dv-color-picker--open`, `dv-color-picker--disabled` ### HTML ```html ... ``` ### React ```tsx ``` ### Props ```ts triggerProps?: FieldTriggerProps // visible trigger attributes and composed events triggerRef?: Ref value?: string defaultValue?: string onValueChange?: (value: string) => void onValueCommit?: (value: string) => void output?: 'hex' | 'oklch' alpha?: boolean swatches?: string[] size?: 'sm' | 'md' | 'lg' disabled?: boolean open?: boolean defaultOpen?: boolean onOpenChange?: (open: boolean) => void ``` ### Events - `open` — Fired before the popover opens (cancelable with preventDefault) - `opened` — Fired after the popover has opened - `close` — Fired before the popover closes (cancelable with preventDefault) - `closed` — Fired after the popover has closed - `input` — Fired live on every drag move or field keystroke - `changed` — Fired on commit: drag release, keyboard step, swatch pick or ### Keyboard - Left/Right arrows: Navigate between items - Up/Down arrows: Navigate between items - Home: Go to first item - End: Go to last item - Escape: Close/dismiss ### Options - `output` (default: `'hex'`) - `alpha` (default: `true`) - `format` (default: `'hex'`) - `swatches` (default: `DEFAULT_SWATCHES`) - `value` (default: `'#000000'`) - `recentKey` (default: `'dv.colorPicker.recents'`) - `maxRecent` (default: `8`) ### Accessibility - Trigger is a button with aria-haspopup="dialog", aria-expanded - SV surface + hue/alpha tracks are role="slider" with aria-valuemin/max/now and aria-valuetext; arrow-key driven - Panel is role="dialog" with aria-label; focus is trapped and returns to the trigger on close --- ## combobox Self-contained single-select dropdown with label, hint, error support - Base class: `dv-combobox` - React: `` - Source: packages/html/src/css/components/_combobox.css, packages/react/src/components/Combobox.tsx, packages/html/src/js/components/combobox.js - Sizes: `dv-combobox--sm`, `dv-combobox--lg` - Modifiers: `dv-combobox--open`, `dv-combobox--disabled`, `dv-combobox--error`, `dv-combobox--success` ### HTML ```html Country Start typing Option 1 Country... ``` ### React ```tsx ``` ### Props ```ts inputProps?: FieldInputProps // visible input attributes and composed events inputRef?: Ref // visible input focus options: { value: string; label: string; disabled?: boolean }[] value?: string defaultValue?: string onValueChange?: (value: string) => void placeholder?: string clearable?: boolean disabled?: boolean error?: string hint?: string optional?: boolean size?: 'sm'|'md'|'lg' label?: string minWidth?: string|number // widen the listbox panel past the input highlightMatch?: boolean // bold the matched substring in filtered options (default true) open?: boolean // controlled open state of the listbox defaultOpen?: boolean onOpenChange?: (open: boolean) => void ``` ### Events - `open` — Fired before dropdown opens (cancelable with preventDefault) - `opened` — Fired after dropdown has opened - `close` — Fired before dropdown closes (cancelable with preventDefault) - `closed` — Fired after dropdown has closed - `changed` — Fired after the selection has changed (detail: { value, label }) - `filter` — Fired when filter text changes (detail: { query, matches }) - `error` — Fired when error is set - `error-cleared` — Fired when error is cleared ### Keyboard - Up/Down arrows: Navigate between items - Home: Go to first item - End: Go to last item - Enter/Space: Activate/select - Escape: Close/dismiss ### Options - `clearable` (default: `false`) - `debounceMs` (default: `FILTER_DEBOUNCE_MS`) - `emptyMessage` (default: `null`) - `highlightMatch` (default: `true`) ### Accessibility - Input must have role="combobox", aria-autocomplete="list", aria-expanded, aria-controls, aria-haspopup="listbox" - The __label needs an explicit for/id pair to the __input — a placeholder is not an accessible name. The JS wires this on init; static (JS-less) markup must ship it. - Listbox must have role="listbox" — but only while it owns at least one visible option; with every option filtered out the JS drops it to role="presentation" and removes the name, because a listbox owning no option fails aria-required-children - Options must have role="option", aria-selected - Use aria-activedescendant for current focused option --- ## command Offers a searchable command palette with keyboard navigation. - Base class: `dv-command` - React: `` - Element: `dialog` - Source: packages/html/src/css/components/_command.css, packages/react/src/components/Command.tsx, packages/html/src/js/components/command.js - Modifiers: `dv-command--open` ### HTML ```html ESC Actions New Article ⌘N ↑↓ Navigate ↵ Select ``` ### React ```tsx ESC navigate('/dashboard')}>Dashboard navigate('/settings')}>Settings ``` ### Props ```ts open?: boolean defaultOpen?: boolean onOpenChange?: (open: boolean) => void closeOnBackdrop?: boolean keyboardShortcut?: boolean onSearch?: (query: string) => void ``` ### Events - `open` — Fired before command palette opens (cancelable with preventDefault) - `opened` — Fired after command palette has opened - `close` — Fired before command palette closes (cancelable with preventDefault) - `closed` — Fired after command palette has closed ### Keyboard - Up/Down arrows: Navigate between items - Enter/Space: Activate/select ### Options - `closeOnBackdrop` (default: `true`) - `closeOnEscape` (default: `true`) - `closeOnSelect` (default: `true`) - `keyboardShortcut` (default: `true`) - `restoreFocus` (default: `true`) ### Accessibility - Uses native dialog element with showModal() for built-in focus trap, inert background, and top-layer - The role="combobox" input needs an aria-label — a placeholder is not an accessible name. The JS fills one in on init when the author supplied none - `.dv-command__results` carries role="listbox" only while it holds at least one `.dv-command__item`; Command filters nothing itself, so an empty result list is a normal state and the JS drops the role to "presentation" (with the name) there — a listbox owning no option fails aria-required-children. Author the empty state that way too on the JS-less path, where nothing repairs it - Keyboard navigation with arrow keys and Enter ### Avoid - Never use dialog.show() — always use dialog.showModal() for modal behavior --- ## data-table Adds sorting, selection, reordering, and expandable rows to a native table. - Base class: `dv-data-table` - React: `` - Element: `table` - Source: packages/html/src/css/components/_data-table.css, packages/react/src/components/DataTable.tsx, packages/html/src/js/components/data-table.js - Variants: `dv-data-table--stack`, `dv-data-table--priority` ### HTML ```html Ada ... ... Name Ada ... ``` ### React ```tsx setSort('name')}>Name Status AdaActive ``` ### Props ```ts striped?: boolean density?: 'compact'|'mini' stack?: boolean stickyCol?: boolean priority?: boolean DataTable.SortHeader sortDirection?: 'asc'|'desc'|'none'; onSort?: () => void DataTable.Header/Cell priority?: 'low'|'medium'|'high' DataTable.Disclosure expanded: boolean; controls?: string; onToggle?: () => void DataTable.Detail colSpan: number; open?: boolean ``` ### Events - `sort` — Fired when a column is sorted - `sort-clear` — Fired when sorting is cleared - `selection-change` — Fired when checkbox selection changes - `reorder` — Fired when a row is reordered - `row-toggle` — Fired when an expandable detail row changes ### Options - `sortedClass` (default: `'dv-data-table__header--sorted'`) - `descClass` (default: `'dv-data-table__header--desc'`) - `headerSelector` (default: `'.dv-data-table__header--sortable'`) ### Accessibility - Sortable headers contain a native button; aria-sort belongs only on the currently sorted th - Checkbox selection is exposed by the checkbox; native tr elements do not use aria-selected - The scroll wrapper needs role="region", a programmatic name, and tabindex="0" - --stack requires data-label on every data cell and restores roles removed by CSS display reflow - Reorder and disclosure actions use native labelled buttons ### Avoid - Adding role="grid" without the complete composite grid keyboard and focus model - Making th focusable instead of putting a button inside it --- ## date-picker Self-contained date picker with label, hint, error support - Base class: `dv-date-picker` - React: `` - Source: packages/html/src/css/components/_date-picker.css, packages/react/src/components/DatePicker.tsx, packages/html/src/js/components/date-picker.js - Sizes: `dv-date-picker--sm`, `dv-date-picker--lg` - Modifiers: `dv-date-picker--open`, `dv-date-picker--disabled`, `dv-date-picker--error`, `dv-date-picker--success` ### HTML ```html Date Select a date ... Date... ``` ### React ```tsx ``` ### Props ```ts inputProps?: FieldInputProps // visible input attributes and composed events inputRef?: Ref // visible input focus today: LocalDate value?: LocalDate|null defaultValue?: LocalDate onValueChange?: (date: LocalDate|null) => void min?: LocalDate max?: LocalDate placeholder?: string allowInput?: boolean // click opens without moving the caret; ArrowDown focuses the grid clearable?: boolean disabled?: boolean size?: 'sm'|'md'|'lg' label?: string minWidth?: string|number // widen the calendar popover open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean) => void ``` ### Events - `open` — Fired before calendar opens (cancelable with preventDefault) - `opened` — Fired after calendar has opened - `close` — Fired before calendar closes (cancelable with preventDefault) - `closed` — Fired after calendar has closed - `changed` — Fired after the date selection has changed (detail: { value, formatted }) - `error` — Fired when error is set - `error-cleared` — Fired when error is cleared ### Keyboard - Input focus: Does not open the calendar - Input click: Opens the calendar; editable inputs keep the caret in the field - ArrowDown / Alt+ArrowDown on the input: Open the calendar and focus the active day - Left/Right arrows: Previous/next day — inverted under RTL, where the previous day sits to the right - Up/Down arrows: Previous/next week - Home/End: First/last day of the focused week, per `firstDayOfWeek` - PageUp/PageDown: Previous/next month, or year with Shift — clamped to the last valid day of the target month - Enter/Space: Select the focused day - Escape: Close the calendar ### Options - `format` (default: `{ year: 'numeric', month: 'short', day: 'numeric' }`) - `min` (default: `null`) - `max` (default: `null`) - `clearable` (default: `true`) - `todayButton` (default: `true`) - `today` (default: `null`) - `firstDayOfWeek` (default: `0`) ### Accessibility - Input must have role="combobox", aria-expanded, aria-haspopup="dialog" - Calendar is a non-modal popover: role="dialog", aria-label. Background is not inert. - Focus alone does not open the popup. Click opens it; editable inputs keep the caret. ArrowDown or Alt+ArrowDown moves focus into the grid. Tab may leave and closes the popup. - Grid must have role="grid", days have role="gridcell" - Out-of-range days use aria-disabled="true", NOT disabled — they stay focusable so arrow-key grid navigation reaches them and AT can say "unavailable" rather than skip them. - Omit `readonly` on the __input to allow typing a date as well as picking one (WCAG 2.5.6). The JS parses ISO plus the active locale's numeric order, and reverts invalid text. --- ## description-list Pairs terms with definitions or values for structured metadata. - Base class: `dv-dl` - React: `` - Element: `dl` - Source: packages/html/src/css/components/_description-list.css, packages/react/src/components/DescriptionList.tsx - Variants: `dv-dl--raised`, `dv-dl--borderless`, `dv-dl--compact`, `dv-dl--striped`, `dv-dl--inline`, `dv-dl--space-between`, `dv-dl--stacked` ### HTML ```html Label Value ... Status Active file.pdf2.4 MB ``` ### React ```tsx Full name John Doe Email john ``` ### Props ```ts borderless?: boolean raised?: boolean compact?: boolean striped?: boolean layout?: 'inline'|'space-between'|'stacked' ``` ### Accessibility - Use semantic dl, dt, dd elements - Wrap each term-definition pair in a div for proper grouping ### Avoid - Using dv-dl for interactive lists (use dv-list instead) --- ## dialog Presents modal content with a title, body, and optional actions. - Base class: `dv-dialog` - React: `` - Element: `dialog` - Source: packages/html/src/css/components/_dialog.css, packages/react/src/components/Dialog.tsx, packages/html/src/js/components/dialog.js - Sizes: `dv-dialog--sm`, `dv-dialog--lg`, `dv-dialog--xl`, `dv-dialog--full`, `dv-dialog--sheet` ### HTML ```html Title Content ... ``` ### React ```tsx Confirmation Are you sure? ``` ### Props ```ts open?: boolean defaultOpen?: boolean onOpenChange?: (open: boolean, details: DialogOpenChangeDetails) => void size?: 'sm'|'md'|'lg'|'xl'|'full'|'sheet' closeOnBackdrop?: boolean closeOnEscape?: boolean onClose?: () => void ``` ### Events - `open` — Fired before the dialog opens (cancelable with preventDefault) - `opened` — Fired after the dialog has fully opened and animations complete - `close` — Fired before the dialog closes (cancelable with preventDefault) - `closed` — Fired after the dialog has fully closed and animations complete ### Options - `closeOnBackdrop` (default: `true`) - `closeOnEscape` (default: `true`) - `restoreFocus` (default: `true`) - `announceTitle` (default: `true`) - `sheet` (default: `false`) - `onBeforeClose` (default: `null`) ### Accessibility - Uses native dialog element with showModal() for built-in focus trap, inert background, and top-layer. Pairs with role="dialog" semantics; use dv-alert-dialog for role="alertdialog". ### Avoid - Never use dialog.show() — always use dialog.showModal() for modal behavior --- ## drawer Presents dialog content in a panel that enters from a viewport edge. - Base class: `dv-drawer` - React: `` - Element: `dialog` - Source: packages/html/src/css/components/_drawer.css, packages/react/src/components/Drawer.tsx, packages/html/src/js/components/drawer.js - Variants: `dv-drawer--left`, `dv-drawer--right`, `dv-drawer--top`, `dv-drawer--bottom`, `dv-drawer--level-2`, `dv-drawer--level-3` - Sizes: `dv-drawer--sm`, `dv-drawer--md` (default), `dv-drawer--lg`, `dv-drawer--xl` - Modifiers: `dv-drawer--loading` ### HTML ```html Title Content ... Title Section Content Nested drawer Push mode ``` ### React ```tsx Settings Settings content here ``` ### Props ```ts open?: boolean defaultOpen?: boolean onOpenChange?: (open: boolean, details: DialogOpenChangeDetails) => void onClose?: () => void side?: 'left'|'right'|'top'|'bottom' size?: 'sm'|'md'|'lg'|'xl' loading?: boolean level?: 2|3 closeOnBackdrop?: boolean closeOnEscape?: boolean restoreFocus?: boolean ``` ### Events - `open` — Fired before drawer opens (cancelable with preventDefault) - `opened` — Fired after drawer has fully opened and animations complete - `close` — Fired before drawer closes (cancelable with preventDefault) - `closed` — Fired after drawer has fully closed and animations complete ### Options - `closeOnBackdrop` (default: `true`) - `closeOnEscape` (default: `true`) - `restoreFocus` (default: `true`) - `announceTitle` (default: `true`) - `onBeforeClose` (default: `null`) ### Accessibility - Uses native dialog element with showModal() for built-in focus trap, inert background, and top-layer - Title should be linked via aria-labelledby - Close button MUST have aria-label ### Avoid - Never use dialog.show() — always use dialog.showModal() for modal behavior --- ## dropdown-menu Opens a menu of actions or links from a trigger. - Base class: `dv-dropdown-menu` - React: `` - Element: `div` - Source: packages/html/src/css/components/_dropdown-menu.css, packages/react/src/components/DropdownMenu.tsx, packages/html/src/js/components/dropdown-menu.js - Modifiers: `dv-dropdown-menu__content--open`, `dv-dropdown-menu__content--right`, `dv-dropdown-menu__item--destructive`, `dv-dropdown-menu__item--disabled`, `dv-dropdown-menu__item--checkbox`, `dv-dropdown-menu__item--radio` ### HTML ```html EditDuplicate Delete ... ... ... ``` ### React ```tsx Options Actions Edit Delete ``` ### Props ```ts open?: boolean defaultOpen?: boolean onOpenChange?: (open: boolean) => void placement?: Placement align?: 'start' | 'center' | 'end' offset?: number closeOnSelect?: boolean dismissMode?: 'light' | 'manual' ``` ### Events - `open` — Fired before dropdown opens (cancelable with preventDefault) - `opened` — Fired after dropdown has opened - `close` — Fired before dropdown closes (cancelable with preventDefault) - `closed` — Fired after dropdown has closed - `select` — Fired when an item is selected (detail: { item, checked }) ### Keyboard - Left/Right arrows: Navigate between items - Up/Down arrows: Navigate between items - Enter/Space: Activate/select - Escape: Close/dismiss ### Options - `closeOnSelect` (default: `true`) - `closeOnClickOutside` (default: `true`) - `closeOnEscape` (default: `true`) - `placement` (default: `'bottom-start'`) - `offset` (default: `4`) ### Accessibility - Trigger should have aria-haspopup="true" and aria-expanded - Menu items should be keyboard navigable - Use Escape key to close dropdown ### Avoid - Opening dropdown without proper focus management --- ## empty-state Explains an empty content area and offers a next action. - Base class: `dv-empty-state` - React: `` - Element: `div` - Source: packages/html/src/css/components/_empty-state.css, packages/react/src/components/EmptyState.tsx - Variants: `dv-empty-state--compact` ### HTML ```html No items found Try adjusting your search or filters Error loading data No files found Try adjusting your filters. ``` ### React ```tsx Clear filters} /> ``` ### Props ```ts variant?: 'default'|'error'|'success'|'info'|'warning' title?: ReactNode description?: ReactNode icon?: ReactNode actions?: ReactNode titleLevel?: 1|2|3|4|5|6 // heading level for the title (default 3) compact?: boolean // container-scoped tier (inside a List/Card/Table/panel) ``` ### Accessibility - Use appropriate heading level for title - Icon should be decorative (aria-hidden) ### Avoid - Empty states without clear call-to-action --- ## eyebrow The kicker above a heading — "CASE STUDY", "WHAT WE DO" — and the label above a stat or a form section. It is a LABEL, not a heading: it takes no `` element and no heading role, because an eyebrow and the heading under it are one unit, and marking both makes a screen-reader outline that reads the same section twice. Pair it with the heading rather than nesting it inside one. - Base class: `dv-eyebrow` - React: `` - Element: `p` - Source: packages/html/src/css/components/_eyebrow.css, packages/react/src/components/Eyebrow.tsx - Variants: `dv-eyebrow--accent`, `dv-eyebrow--rule` ### HTML ```html Case study What we do Since 1998 Case study Rebuilding the archive ``` ### React ```tsx Case study What we do Since 1998 ``` ### Props ```ts variant?: 'accent' | 'rule' as?: 'p' | 'span' | 'div' children?: ReactNode ``` ### Accessibility - Use a `` or ``, never an ``. Screen readers list headings as a navigable outline, and an eyebrow in that list duplicates the section it labels. - The text is uppercased by CSS, not by the author — write "Case study", not "CASE STUDY". Some screen readers spell out all-caps source text letter by letter, and a `text-transform` is styling that AT does not read. ### Avoid - Using it as a section heading (it has no heading semantics and no outline). - Sentences. It is a label; at 12px uppercase, anything past a few words stops being scannable, which is the only thing it is for. --- ## file-upload Provides file selection and a drop area with upload feedback. - Base class: `dv-file-upload` - React: `` - Element: `label|div` - Source: packages/html/src/css/components/_file-upload.css, packages/react/src/components/FileUpload.tsx, packages/html/src/js/components/file-upload.js - Sizes: `dv-file-upload--sm`, `dv-file-upload--lg` - Modifiers: `dv-file-upload--dragover`, `dv-file-upload--image`, `dv-file-upload--compact`, `dv-file-upload--error`, `dv-file-upload--success`, `dv-file-upload--disabled` ### HTML ```html Click to upload or drag and drop PNG, JPG up to 10MB Click to upload or drag and drop Click to upload or drag and drop PNG, JPG up to 10MB document.pdf 2.4 MB ``` ### React ```tsx ``` ### Props ```ts accept?: string multiple?: boolean maxSize?: number disabled?: boolean size?: 'sm'|'md'|'lg' compact?: boolean onChange?: (files: File[]) => void files?: File[] (controlled accepted collection for native submission and removal) prompt?: ReactNode hint?: ReactNode ``` ### Events - `changed` — Fired after files have been added or removed - `remove` — Fired when a file is removed - `clear` — Fired when all files are cleared - `error` — Fired when file validation fails - `error-cleared` — Fired when error is cleared - `upload-complete` — Fired when a file upload completes ### Keyboard - Enter/Space: Activate/select ### Options - `accept` (default: `''`) - `maxSize` (default: `10 * 1024 * 1024`) - `maxFiles` (default: `10`) - `multiple` (default: `true`) - `showProgress` (default: `true`) ### Accessibility - File input must have associated label - Remove button should have aria-label - Announce upload status to screen readers ### Avoid - File upload without clear format/size hints - Using orphan dv-file__* classes (use dv-file-upload__file-* instead) --- ## grid CSS Grid layout with BEM modifiers for columns, gap, alignment, and spanning. Use column modifiers for fixed grids, auto-fit for responsive grids, and named layouts for common page structures. - Base class: `dv-grid` - React: `` - Element: `div` - Source: packages/html/src/css/components/_grid.css, packages/react/src/components/Grid.tsx - Variants: `dv-grid--cols-1`, `dv-grid--cols-2`, `dv-grid--cols-3`, `dv-grid--cols-4`, `dv-grid--cols-5`, `dv-grid--cols-6`, `dv-grid--cols-12`, `dv-grid--rows-1`, `dv-grid--rows-2`, `dv-grid--rows-3`, `dv-grid--rows-4`, `dv-grid--rows-5`, `dv-grid--rows-6`, `dv-grid--auto-fit-sm`, `dv-grid--auto-fit-md`, `dv-grid--auto-fit-lg`, `dv-grid--auto-fit-xl`, `dv-grid--auto-fill-sm`, `dv-grid--auto-fill-md`, `dv-grid--auto-fill-lg`, `dv-grid--bento`, `dv-grid--joined`, `dv-grid--flow-row`, `dv-grid--flow-column`, `dv-grid--flow-dense`, `dv-grid--flow-row-dense`, `dv-grid--flow-column-dense` ### HTML ```html Card 1 Card 2 Card 3 Responsive tile 1 Responsive tile 2 Responsive tile 3 Responsive tile 4 Sidebar (4 cols) Main (6 cols) Aside (2 cols) Full-width footer Hero metric Stat Stat Chart row Tall list Tile 1 Tile 2 Tile 3 Fills down each column before moving right 2 3 4 Header Sidebar Main ``` ### React ```tsx Item 1 Item 2 Item 3 ``` ### Props ```ts cols?: number | BreakpointMap<1|2|3|4|5|6|12> rows?: number flow?: 'row'|'column'|'dense'|'row-dense'|'column-dense' areas?: string gap?: 0|1|2|3|4|5|6|8|10|12|16 | BreakpointMap gapX?: 2|4|6|8 gapY?: 2|4|6|8|10 align?: 'start'|'center'|'end'|'stretch' | BreakpointMap justify?: 'start'|'center'|'end'|'between' | BreakpointMap autoFit?: 'sm'|'md'|'lg'|'xl' autoFill?: 'sm'|'md'|'lg' place?: 'center' bento?: boolean joined?: boolean as?: ElementType `areas` sets grid-template-areas via inline style; place children with their own `style={{ gridArea: 'name' }}` (area names are arbitrary, so there is no class form). Responsive props (`cols`/`gap`/`align`/`justify`) accept a breakpoint object — `` — which compiles to the `dv:` responsive utility classes. `cols`/`autoFit`/`autoFill` all set grid-template-columns; don't combine them or enable `bento` alongside them. Auto-fit collapses empty tracks; auto-fill preserves them. Both use flexible tracks whose tier minimum is clamped to the available width. `rows` and `flow` remain scalar because no responsive utility backing exists for them. ``` ### Accessibility - Dense flow can place later DOM items into earlier visual gaps. Use it only for independent, non-sequential tiles; keep DOM, reading and focus order aligned for actions, instructions and ranked content. The same rule applies to reversed flex/grid compositions. ### Avoid - Using fixed columns when auto-fit/auto-fill would provide better responsiveness --- ## heading Styles semantic headings with the system type scale. - Base class: `dv-heading` - React: `` - Element: `h1|h2|h3|h4|h5|h6` - Source: packages/html/src/css/components/_heading.css, packages/react/src/components/Heading.tsx - Variants: `dv-heading--truncate`, `dv-heading--clamp-2`, `dv-heading--clamp-3` - Sizes: `dv-heading--2xl`, `dv-heading--xl` (default), `dv-heading--lg`, `dv-heading--md`, `dv-heading--sm`, `dv-heading--xs` ### HTML ```html Page Title Section Header Card Title Subsection Small Heading Serif Centered Small on mobile, display on desktop ``` ### React ```tsx Page Title Large H2 Card Title Centered title Long card title… Multi-line clamped heading Small on mobile, display on desktop ``` ### Props ```ts level: 1|2|3|4|5|6 (required) size?: '2xl'|'xl'|'lg'|'md'|'sm'|'xs' (defaults from level: 1→xl, 2→lg, 3→md, 4→sm, 5/6→xs) — also accepts a breakpoint object, e.g. size={{ base: 'sm', md: 'xl' }} color?: 'default'|'muted'|'subtle'|'accent'|'success'|'error'|'warning'|'info'|'inverse' weight?: 'normal'|'medium'|'semibold'|'bold'|'extrabold' align?: 'start'|'center'|'end'|'justify' leading?: 'none'|'tight'|'snug'|'normal'|'relaxed'|'loose' truncate?: boolean clamp?: 2|3 For font, tracking, transform, decoration, and italic: use className. ``` ### Accessibility - Use correct heading level for document outline (h1-h6) - Size is decoupled from level — use size modifier for visual styling ### Avoid - Skipping heading levels in the document outline --- ## icon Sizes and aligns SVG icons consistently with surrounding content. - Base class: `dv-icon` - React: `` - Element: `svg` - Source: packages/html/src/css/components/_icon.css, packages/react/src/components/Icon.tsx - Sizes: `dv-icon--xs`, `dv-icon--sm`, `dv-icon--md` (default), `dv-icon--lg`, `dv-icon--xl`, `dv-icon--2xl`, `dv-icon--3xl`, `dv-icon--4xl` - Modifiers: `dv-icon--spin`, `dv-icon--pulse`, `dv-icon--filled` ### HTML ```html ``` ### React ```tsx ``` ### Props ```ts path?: string size?: 'xs'|'sm'|'md'|'lg'|'xl'|'2xl'|'3xl'|'4xl' color?: 'default'|'muted'|'subtle'|'accent'|'success'|'error'|'warning'|'info'|'inverse' spin?: boolean pulse?: boolean filled?: boolean label?: string ``` ### Accessibility - Decorative icons should have aria-hidden="true" - Meaningful icons need aria-label or title element - Icon-only buttons MUST have aria-label on the button ### Avoid - Icons without .dv-icon class - Inline width/height attributes (use CSS classes instead) --- ## icon-box Places an icon in a colored surface for visual emphasis. - Base class: `dv-icon-box` - React: `` - Element: `span` - Source: packages/html/src/css/components/_icon-box.css, packages/react/src/components/IconBox.tsx - Variants: `dv-icon-box--neutral`, `dv-icon-box--accent`, `dv-icon-box--info`, `dv-icon-box--success`, `dv-icon-box--warning`, `dv-icon-box--error` - Sizes: `dv-icon-box--sm`, `dv-icon-box--md`, `dv-icon-box--lg`, `dv-icon-box--xl` ### HTML ```html ``` ### React ```tsx ``` ### Props ```ts variant?: 'neutral'|'accent'|'info'|'success'|'warning'|'error' size?: 'sm'|'md'|'lg'|'xl' ``` ### Accessibility - Decorative wrapper — the icon must be hidden from assistive tech (aria-hidden="true"). ### Avoid - Using as a status chip with a text label — that is the Badge component. - Adding a size modifier defensively. NO modifier means "defer to the surrounding tier" (EmptyState, AlertDialog size their hero chip); `--md` re-asserts 40px and opts out of that. Outside a tier the two render identically, so the mistake is invisible. --- ## kbd Displays a keyboard key or shortcut in a keycap style. - Base class: `dv-kbd` - React: `` - Element: `kbd|span` - Source: packages/html/src/css/components/_kbd.css, packages/react/src/components/Kbd.tsx ### HTML ```html ⌘K ⌘S to save ``` ### React ```tsx ⌘ ⌘K ``` ### Props ```ts children?: ReactNode ``` ### Accessibility - Keyboard hints are hidden on touch devices - Use appropriate symbols (⌘, ⇧, ⌥, ⌃) for Mac keys ### Avoid - Using keyboard hints without visible text alternative --- ## link Styles navigational links with semantic emphasis and interaction states. - Base class: `dv-link` - React: `` - Element: `a` - Source: packages/html/src/css/components/_link.css, packages/react/src/components/Link.tsx - Variants: `dv-link--action`, `dv-link--destructive`, `dv-link--muted`, `dv-link--underline`, `dv-link--no-underline`, `dv-link--external`, `dv-link--icon` - Modifiers: `dv-link--disabled` ### HTML ```html Default link Action link External link Link with icon Delete Unavailable destination ``` ### React ```tsx About us External link } variant="action">Profile Disabled link ``` ### Props ```ts variant?: 'default'|'action'|'destructive'|'muted' decoration?: 'underline'|'none' disabled?: boolean external?: boolean icon?: ReactNode render?: RenderProp ``` ### Accessibility - External links should indicate they open in new tab - A disabled HTML link removes href, sets aria-disabled="true" and tabindex="-1". If an integration must retain href, cancel both click and keyboard-originated activation in JavaScript. - Underlined at rest (SC 1.4.1) — fg-accent clears 3:1 against the page but only ~2.8:1 against body text, so colour alone cannot mark an inline link ### Avoid - Using links for actions (use buttons instead) - --no-underline on a link inside a paragraph — it is for standalone links only --- ## list Arranges related content in rows with optional borders and spacing variants. - Base class: `dv-list` - React: `` - Element: `div` - Source: packages/html/src/css/components/_list.css, packages/react/src/components/List.tsx - Variants: `dv-list--raised`, `dv-list--borderless`, `dv-list--compact`, `dv-list--loose`, `dv-list--unframed`, `dv-list--striped`, `dv-list--align-top`, `dv-list--plain` - Modifiers: `dv-list__item--interactive`, `dv-list__item--selected`, `dv-list__item--disabled` ### HTML ```html TitleDescriptionMeta ... Selected item ... ... Section Header Footer content No items Try adjusting filters ``` ### React ```tsx First item Selected item Open details ``` ### Props ```ts borderless?: boolean raised?: boolean density?: 'compact'|'loose' unframed?: boolean plain?: boolean striped?: boolean alignTop?: boolean ``` ### Accessibility - Interactive items should be focusable (use tabindex or button/a) - Disabled HTML rows must disable every action: use native disabled on buttons and remove href and event handlers from links, with role="link", aria-disabled="true", and tabindex="-1". The row modifier only supplies appearance. React List.Item propagates disabled to supplied children; custom action components must honor disabled. - Selected items use aria-current="true" — NOT aria-selected, which is only valid on option/row/tab/gridcell/treeitem. `.dv-list` is a content list, not a listbox. ### Avoid - Using dv-list for key-value data (use dv-dl instead) --- ## load-more Presents an action to request additional items with progress feedback. - Base class: `dv-load-more` - React: `` - Element: `div` - Source: packages/html/src/css/components/_load-more.css, packages/react/src/components/LoadMore.tsx, packages/html/src/js/components/load-more.js - Modifiers: `dv-load-more--loading`, `dv-load-more--complete` ### HTML ```html Showing 60 of 240 Showing 240 of 240 ``` ### React ```tsx ``` ### Props ```ts loaded: number total: number onLoadMore: () => void loading?: boolean auto?: boolean rootMargin?: string label?: ReactNode loadingLabel?: ReactNode completeLabel?: ReactNode status?: ReactNode ``` ### Events - `load` — Fired when a load is requested (click or auto sentinel). detail: { source: 'click' | 'auto' } ### Options - `auto` (default: `false`) - `rootMargin` (default: `'200px 0px'`) ### Accessibility - The trigger is a real Select options...Select one or more Option 1 Tags... ``` ### React ```tsx ``` ### Props ```ts options: { value: string; label: string; disabled?: boolean }[] value?: string[] defaultValue?: string[] onValueChange?: (values: string[]) => void placeholder?: string size?: 'sm'|'md'|'lg' searchable?: boolean maxItems?: number checkboxes?: boolean label?: string error?: string minWidth?: string|number // widen the listbox panel past the trigger ``` ### Events - `open` — Fired before dropdown opens (cancelable with preventDefault) - `opened` — Fired after dropdown has opened - `close` — Fired before dropdown closes (cancelable with preventDefault) - `closed` — Fired after dropdown has closed - `changed` — Fired after the selection has changed (detail: { value, selected }) - `select` — Fired when an option is selected (detail: { value, label }) - `deselect` — Fired when an option is deselected (detail: { value, label }) - `error` — Fired when error is set - `error-cleared` — Fired when error is cleared ### Keyboard - Up/Down arrows: Navigate between items - Home: Go to first item - End: Go to last item - Enter/Space: Activate/select - Escape: Close/dismiss ### Options - `searchable` (default: `false`) - `closeOnSelect` (default: `false`) - `maxItems` (default: `null`) - `placeholder` (default: `null`) ### Accessibility - Trigger must have role="combobox", aria-haspopup="listbox", aria-expanded - The trigger is a div, so `` cannot name it — point the label's id at the trigger via aria-labelledby. JS wires this when absent; static markup must ship it. - Listbox must have role="listbox", aria-multiselectable="true" — but only while it owns at least one visible option; with every option filtered out the JS drops it to role="presentation" and removes the name/aria-multiselectable, because a listbox owning no option fails aria-required-children - Options must have role="option", aria-selected --- ## nav Groups navigation links with active states and optional section labels. - Base class: `dv-nav` - React: `` - Element: `nav|div` - Source: packages/html/src/css/components/_nav.css, packages/react/src/components/Nav.tsx, packages/html/src/js/components/nav.js - Modifiers: `dv-nav__item--active`, `dv-nav__link--active`, `dv-nav__sub-item--active` ### HTML ```html DashboardArticles MainDashboard Inbox5 Engineering ``` ### React ```tsx Dashboard } active>Dashboard Articles 12 {teamsIcon} Teams Engineering Human Resources ``` ### Props ```ts children?: ReactNode // Nav.Item: href?: string · active?: boolean · render?: RenderProp // Nav.Link: active?: boolean · render?: RenderProp // Nav.Group: open?: boolean · defaultOpen?: boolean · onOpenChange?: (open: boolean) => void // Nav.GroupTrigger: render?: RenderProp (default chevron renders automatically) // Nav.SubItem: href?: string · active?: boolean · render?: RenderProp ``` ### Events - `open` — Fired before group opens (cancelable) - `close` — Fired before group closes (cancelable) - `opened` - `closed` ### Accessibility - Use semantic nav element for main navigation - Active items should have aria-current="page" - Collapsible group triggers MUST have aria-expanded and aria-controls pointing at the sub-list id ### Avoid - Using Tabs for links that navigate to another page. Nav owns destinations and aria-current="page"; Tabs owns panels on the same page with tab/tabpanel roles. - Nesting nav groups more than one level deep --- ## number-field Edits a numeric value with increment and decrement controls. - Base class: `dv-number-field` - React: `` - Element: `div` - Source: packages/html/src/css/components/_number-field.css, packages/react/src/components/NumberField.tsx, packages/html/src/js/components/number-field.js - Modifiers: `dv-number-field--sm`, `dv-number-field--lg`, `dv-number-field--error` ### HTML ```html Quantity ``` ### React ```tsx ``` ### Props ```ts value?: number | null; defaultValue?: number onValueChange?: (value: number) => void min?: number; max?: number; step?: number size?: 'sm' | 'md' | 'lg' disabled?: boolean; readOnly?: boolean; error?: boolean enterKeyHint?: 'enter'|'done'|'go'|'next'|'previous'|'search'|'send' ``` ### Events - `input` — Native bubbling event dispatched on the inner input after a step/clamp changes the value. - `change` — Native bubbling event dispatched on the inner input after a step/clamp changes the value. ### Keyboard - PageUp: Jump multiple items - PageDown: Jump multiple items ### Accessibility - Use a native with min/max/step so the field exposes spinbutton semantics and aria-valuenow/min/max for free - Give the input an accessible name via an associated or aria-label; the step buttons each need an aria-label (Decrement / Increment) - On validation failure set --error and mark the input aria-invalid="true"; the plain-HTML :user-invalid fallback covers required/min/max - This is a bare control with no built-in hint/error slot — for WCAG 3.3.1 render the error message in your own field layout and link it to the input via aria-describedby (same pattern as the external label) --- ## otp Collects a one-time code across individual input cells. - Base class: `dv-otp` - React: `` - Element: `div` - Source: packages/html/src/css/components/_otp.css, packages/react/src/components/OTP.tsx, packages/html/src/js/components/otp.js - Modifiers: `dv-otp--sm`, `dv-otp--lg`, `dv-otp--dashed` ### HTML ```html − ``` ### React ```tsx verify(code)} /> ``` ### Props ```ts length?: number (default 6) value?: string; defaultValue?: string onValueChange?: (value: string) => void onComplete?: (value: string) => void pattern?: 'numeric' | 'alphanumeric' separatorAt?: number; separator?: ReactNode size?: 'sm' | 'md' | 'lg' dashed?: boolean; disabled?: boolean; invalid?: boolean ``` ### Events - `changed` — Fired after every value change. detail: { value } - `complete` — Fired when all cells are filled. detail: { value } ### Keyboard - Left/Right arrows: Navigate between items - Home: Go to first item - End: Go to last item ### Options - `pattern` (default: `'numeric'`) ### Accessibility - Wrap the cells in role="group" with an aria-label naming the field (e.g. "Verification code") - Each cell needs its own aria-label ("Digit N of M"); set inputmode="numeric" + autocomplete="one-time-code" so SMS autofill and numeric keypads work - Mark visual separators aria-hidden="true" so they are skipped by screen readers - Numeric and ASCII alphanumeric codes retain left-to-right cell order in RTL layouts; ArrowLeft/ArrowRight move visually, Home/End select the first/last cell - On validation failure mark the cells aria-invalid="true"; OTP has no built-in hint/error slot — for WCAG 3.3.1 render the error (e.g. "Code incorrect") in your surrounding field layout and link it via aria-describedby on the role="group" wrapper --- ## page-header Groups a page title, supporting content, and page-level actions. - Base class: `dv-page-header` - React: `` - Element: `div` - Source: packages/html/src/css/components/_page-header.css, packages/react/src/components/PageHeader.tsx ### HTML ```html Page Title Description ``` ### React ```tsx Dashboard Overview of your account ``` ### Props ```ts children?: ReactNode ``` ### Accessibility - Page title should use appropriate heading level ### Avoid - Multiple page headers on same page --- ## pagination Navigates between pages of a collection. - Base class: `dv-pagination` - React: `` - Element: `nav` - Source: packages/html/src/css/components/_pagination.css, packages/react/src/components/Pagination.tsx, packages/html/src/js/components/pagination.js - Modifiers: `dv-pagination__btn--active` ### HTML ```html Showing 1-10 of 100 ``` ### React ```tsx ``` ### Props ```ts page: number totalPages: number onPageChange: (page: number) => void siblings?: number boundaries?: number showFirstLast?: boolean showPrevNext?: boolean disabled?: boolean ``` ### Events - `changed` — Fired after the page has changed - `per-page` — Fired when per-page selection changes ### Keyboard - Left/Right arrows: Navigate between page buttons - Home: Go to first page button - End: Go to last page button - PageUp/PageDown: Jump 5 pages - Enter/Space: Activate focused page ### Options - `totalPages` (default: `0`) ### Accessibility - Disabled buttons should have disabled attribute - Use aria-label for icon-only navigation buttons - Use aria-current="page" on active page button - Use native links for URL navigation and buttons for in-place data changes. The JS controller requires --prev/--next on directional controls; first/last use data-dv-pagination-page="first|last"; declare data-dv-pagination-total-pages for truncated numeric windows --- ## panes Index-navigated, full-canvas morphing slideshow. Drive it with data attributes: each block sets data-dv-pane-{i}="row/col/row/col" (grid-area shorthand) for each pane it appears on; pane count is the max index + 1. A block present on consecutive panes MORPHS between its cells (its box resizes/ repositions); a block on a single pane slides on/off along the configured axis. Wrap a block's text in a .dv-panes__content layer with a .dv-panes__media sibling (image/bg/video, reframes via object-fit:cover); style the text with the design system's .dv-heading / .dv-text. - Base class: `dv-panes` - React: `` - Element: `section` - Source: packages/html/src/css/components/_panes.css, packages/react/src/components/Panes.tsx, packages/html/src/js/components/panes.js ### HTML ```html Titanium Four colors. ``` ### React ```tsx } /> Title ``` ### Props ```ts grid?: string | { base: string; sm?: string; md?: string; lg?: string; xl?: string; '2xl'?: string } aspect?: string autoplay?: number pauseOnHover?: boolean loop?: boolean keyboard?: boolean mousewheel?: boolean touch?: boolean axis?: 'horizontal'|'vertical'|'both' threshold?: number velocityThreshold?: number cooldown?: number scaleText?: boolean announceChange?: boolean overrides?: Record onChange?: (detail: { from: number; to: number }, event: CustomEvent) => void onChanged?: (detail: { index: number }) => void aria-label: string Compose blocks from (reframes with cover) + (text layer — style with /; a tile listed on consecutive panes morphs between cells, so give text a stable measure: nowrap + explicit breaks, or cqw/cqh font sizes. With scaleText the text scales with the tile instead of staying constant — the cqw font-size is the only panes-local override). Panes.Block props: panes (Record, or a breakpoint map { base, md, ... } of those for a responsive grid), radii?, from? ('up'|'down'|'left'|'right') ``` ### Events - `change` — Before the pane changes (cancelable). detail: { from, to } - `changed` — After the pane has changed. detail: { index } ### Keyboard - Left/Right arrows: Navigate between items - Up/Down arrows: Navigate between items - Home: Go to first item - End: Go to last item ### Options - `autoplay` (default: `0`) - `pauseOnHover` (default: `true`) - `loop` (default: `true`) - `keyboard` (default: `false`) - `mousewheel` (default: `false`) - `touch` (default: `false`) - `axis` (default: `'both'`) - `threshold` (default: `0.1`) - `velocityThreshold` (default: `0.5`) - `cooldown` (default: `300`) - `scaleText` (default: `false`) - `announceChange` (default: `true`) ### Accessibility - The root needs an aria-label; the JS sets role="region" and aria-roledescription="carousel" and announces "Slide N of M" on MANUAL change (silent while auto-rotating, per APG). - Whenever autoplay is on, expose the visible play/pause control (.dv-panes__control) — autoplay with no pause is a WCAG 2.2.2 fail. The control reuses .dv-button (.dv-button--neutral .dv-button--icon-only .dv-button--sm) for its chrome, like .dv-carousel__control. It carries no aria-pressed: its changing label is the state, and .dv-panes__control--playing drives the glyph. - Autoplay STOPS for good the moment keyboard focus enters — only the control restarts it (APG). - The .dv-panes__nav is the APG "grouped" picker set: role="group" holding plain buttons, the current one aria-disabled="true" (never natively disabled, so it stays reachable). No roving tabindex — every picker is its own tab stop, by design. - Blocks not on the active pane stay mounted but get `inert` + aria-hidden="true", so they leave the tab order and a11y tree without unloading their media. ### Avoid - Only blocks survive a pane change — don't rely on non-block content persisting (its state resets). - Don't hand-code concentric block radii; set a block's per-pane radius with data-dv-pane-{i}-radius, or a pane's default block radius with data-dv-panes-radius-{i} (token suffix). - To morph a tile, list it on consecutive panes with overlapping cells (e.g. data-dv-pane-0 + data-dv-pane-1) — its box interpolates between them. A tile on a single pane slides instead. - Keep text in .dv-panes__content at a stable measure — white-space:nowrap with explicit , or cqw/cqh font sizes (the viewport is a container-type:size container) — so it can't rewrap as the block resizes mid-morph. - A single-pane tile slides from the deck axis by default; override the edge it enters/exits from with data-dv-from="up|down|left|right" on the block. - To make text scale with the tile (PaneFlow style) instead of staying constant, set data-dv-panes-scale-text on the root and size text in cqw — blocks become cqw containers so cqw resolves against the block. - For a RESPONSIVE grid, restructure (don't just scale): set data-dv-panes-grid-{bp} (sm|md|lg|xl|2xl, mobile-first min-width) and give each block matching data-dv-pane-{i}-{bp} cells so its tile stays valid in the new grid. The base data-dv-panes-grid / data-dv-pane-{i} are the mobile layout; tiers override from that width up. The grid snaps instantly on a breakpoint cross (no morph); autoplay pauses while the carousel is scrolled out of view. --- ## password Self-contained password input with toggle, label, hint, error, strength indicator - Base class: `dv-password` - React: `` - Source: packages/html/src/css/components/_password.css, packages/react/src/components/Password.tsx, packages/html/src/js/components/password.js - Sizes: `dv-password--sm`, `dv-password--lg` - Modifiers: `dv-password--disabled`, `dv-password--error`, `dv-password--success` ### HTML ```html Password Password Too short ``` ### React ```tsx ``` ### Props ```ts label?: string hint?: string error?: string success?: boolean size?: 'sm'|'md'|'lg' optional?: boolean showStrength?: boolean showRequirements?: boolean strengthEstimator?: (password: string) => number | null requirements?: { id: string; label: string; test: (password: string) => boolean }[] showLabel?: string hideLabel?: string fullWidth?: boolean enterKeyHint?: 'enter'|'done'|'go'|'next'|'previous'|'search'|'send' ``` ### Events - `input` — Fired on input change - `focus` — Fired on focus - `blur` — Fired on blur - `toggle` — Fired when visibility is toggled - `clear` — Fired when input is cleared - `error` — Fired when error is set - `error-cleared` — Fired when error is cleared ### Keyboard - Escape: Close/dismiss ### Options - `showStrength` (default: `false`) - `showRequirements` (default: `false`) - `minLength` (default: `15`) - `requirements` (default: `null`) - `strengthEstimator` (default: `null`) - `showLabel` (default: `null`) - `hideLabel` (default: `null`) - `announceVisibility` (default: `true`) - `announceStrength` (default: `true`) ### Accessibility - Labels must be associated with inputs via for/id or wrapping - Error messages should use aria-describedby - showStrength requires a product-supplied strengthEstimator returning 0–4 or null; without an estimate the indicator is unassessed. No built-in character-composition score is provided. - Creation requirements default to 15 Unicode code points and can be replaced with product rules. current-password suppresses creation guidance; server-side password policy remains the application responsibility. ### Avoid - Using dv-text-field wrapper (use dv-password instead) - Using dv-input-password (renamed to dv-password) --- ## popover Generic anchored floating panel — a trigger plus an arbitrary content surface - Base class: `dv-popover` - React: `` - Element: `div` - Source: packages/html/src/css/components/_popover.css, packages/react/src/components/Popover.tsx, packages/html/src/js/components/popover.js - Modifiers: `dv-popover--align-end` ### HTML ```html Any markup here. Right-aligned panel ``` ### React ```tsx Filters Arbitrary content — inputs, text, anything. Apply ``` ### Props ```ts open?: boolean defaultOpen?: boolean onOpenChange?: (open: boolean) => void align?: 'start' | 'end' dismissMode?: 'light' | 'manual' ``` ### Events - `open` — Fired before the popover opens (cancelable with preventDefault) - `opened` — Fired after it has opened - `close` — Fired before it closes (cancelable with preventDefault) - `closed` — Fired after it has closed ### Keyboard - Up/Down arrows: Navigate between items - Enter/Space: Activate/select - Escape: Close/dismiss ### Options - `closeOnClickOutside` (default: `true`) - `closeOnEscape` (default: `true`) - `placement` (default: `'bottom-start'`) - `offset` (default: `8`) ### Accessibility - Trigger needs aria-haspopup="dialog" and aria-expanded; the content gets role="dialog" - Move focus into the panel on open and back to the trigger on close ### Avoid - Using Popover for a list of actions — use DropdownMenu (menu semantics) instead --- ## progress Shows completion or ongoing activity as a progress bar. - Base class: `dv-progress` - React: `` - Element: `div` - Source: packages/html/src/css/components/_progress.css, packages/react/src/components/Progress.tsx, packages/html/src/js/components/progress.js - Variants: `dv-progress--indeterminate`, `dv-progress--striped`, `dv-progress--animated`, `dv-progress--segmented` ### HTML ```html Progress60% ``` ### React ```tsx ``` ### Props ```ts value?: number max?: number variant?: 'default'|'success'|'warning'|'error' size?: 'sm'|'md'|'lg' showLabel?: boolean indeterminate?: boolean striped?: boolean animated?: boolean segments?: { value: number; variant?: 'default'|'success'|'warning'|'error' }[] ``` ### Events - `changed` — Fired after the progress value has changed - `indeterminate` — Fired when indeterminate state changes ### Accessibility - Use role="progressbar" with aria-valuenow, aria-valuemin, aria-valuemax - Include aria-label describing what the progress represents - For --segmented (multi-segment proportion bars) use role="img" + a descriptive aria-label, not progressbar ### Avoid - Setting width without using inline style or JS --- ## prose Applies consistent typography and spacing to long-form content. - Base class: `dv-prose` - React: `` - Element: `div|article|section` - Source: packages/html/src/css/components/_prose.css, packages/react/src/components/Prose.tsx - Variants: `dv-prose--lg`, `dv-prose--leading-tight`, `dv-prose--leading-snug`, `dv-prose--leading-normal`, `dv-prose--leading-loose`, `dv-prose--max-none` ### HTML ```html Title Body copy with a link and inline code. Quoted context Item const ready = true; …larger, open-leading reading size… …full-width, no reading-measure cap… ``` ### React ```tsx Title Body with a link. …larger, open-leading, full-width… ``` ### Props ```ts size?: 'base' | 'lg' (default: base) leading?: 'tight'|'snug'|'normal'|'relaxed'|'loose' (default: relaxed) maxNone?: boolean (default: false — reading-measure capped) as?: ElementType (default: 'div') ``` ### Accessibility - Headings must be a logical h1→h6 outline; Prose styles them but does not enforce order. ### Avoid - Applying dv-prose to app chrome or forms — it restyles bare h/p/a/ul/table elements. - Nesting a dv-prose inside another dv-prose. --- ## qr-code Encodes a value as a QR code for scanning. - Base class: `dv-qr-code` - React: `` - Element: `div` - Source: packages/html/src/css/components/_qr-code.css, packages/react/src/components/QrCode.tsx, packages/html/src/js/components/qr-code.js - Sizes: `dv-qr-code--sm`, `dv-qr-code--lg` ### HTML ```html Open example.com Wi-Fi network: net ``` ### React ```tsx ``` ### Props ```ts value: string size?: 'sm'|'md'|'lg' robustness?: 'L'|'M'|'Q'|'H' foreground?: string background?: string label?: string ``` ### Events - `rendered` — Fired after the QR renders ### Options - `value` (default: `''`) - `robustness` (default: `'M'`) - `label` (default: `''`) ### Accessibility - The rendered Option 1 Error optionRequired Card optionThe whole card is clickable; selecting it highlights the border + background. ``` ### React ```tsx ``` ### Props ```ts value: string label?: ReactNode description?: ReactNode error?: string hint?: string success?: boolean disabled?: boolean card?: boolean ``` ### Events - `changed` — Fired after the selection has changed - `error` — Fired when error is set - `error-cleared` — Fired when error is cleared ### Keyboard - Left/Right arrows: Navigate between items - Up/Down arrows: Navigate between items - Home: Go to first item - End: Go to last item ### Options - `orientation` (default: `'vertical'`) ### Accessibility - Use same name attribute to group radios - Use for/id association between label and input - --card needs a visible __label; don't place other interactive elements inside a --card — the stretched label overlays the whole surface ### Avoid - Combining --card with --error/--success — per-item validation isn't supported on cards; validate at the group level --- ## reading-progress Indicates how far the reader has scrolled through content. - Base class: `dv-reading-progress` - React: `` - Element: `div` - Source: packages/html/src/css/components/_reading-progress.css, packages/react/src/components/ReadingProgress.tsx ### HTML ```html ``` ### React ```tsx ``` ### Props ```ts value?: number ``` ### Accessibility - The canonical snippet ships role="progressbar" + aria-valuemin/max so it is exposed correctly. The fill is pure CSS (scroll-driven), so aria-valuenow does NOT update on its own — set it from JS on scroll for a live value, OR mark the element aria-hidden="true" (second snippet) since the bar duplicates the native scrollbar. ### Avoid - Nesting inside scrollable containers — scroll(root) targets the document viewport --- ## scrollspy Highlights the navigation item for the currently visible content section. - Base class: `dv-scrollspy` - React: `` - Element: `nav` - Source: packages/html/src/css/components/_scrollspy.css, packages/react/src/components/ScrollSpy.tsx, packages/html/src/js/components/scrollspy.js ### HTML ```html Intro Usage API ``` ### React ```tsx Intro Usage API ``` ### Props ```ts rootMargin?: string (default: '0px 0px -70% 0px') threshold?: number (default: 0) onActiveChange?: (id: string | null) => void 'aria-label'?: string // ScrollSpy.Link: href: string (e.g. "#id") ``` ### Events - `change` — Fired before the active link changes (cancelable). detail: { id, link, previous } - `changed` — Fired after the active link has changed. detail: { id, link, previous } ### Options - `rootMargin` (default: `'0px 0px -70% 0px'`) - `threshold` (default: `0`) ### Accessibility - Wrap in with an aria-label (e.g. "On this page"); the active link carries aria-current="location" (the token for "the section currently in view", not the unspecific "true") - Each link's href must point at the id of the section it spies on ### Avoid - Adding data-dv-scrollspy to a nav whose links do not resolve to in-page section ids --- ## section Defines a page section with consistent content width and vertical spacing. - Base class: `dv-section` - React: `` - Element: `section` - Source: packages/html/src/css/components/_section.css, packages/react/src/components/Section.tsx - Variants: `dv-section--muted`, `dv-section--subtle`, `dv-section--accent` - Sizes: `dv-section--sm`, `dv-section--md`, `dv-section--lg`, `dv-section--xl` (default), `dv-section--full` - Modifiers: `dv-section--spacing-lg`, `dv-section--spacing-none` ### HTML ```html Default section Default width content Narrow section Narrow content Feature Medium width, large spacing ``` ### React ```tsx Default (xl, 1152px) width Constrained narrow content Large spacing, narrow ``` ### Props ```ts spacing?: 'none' | 'lg' width?: 'sm'|'md'|'lg'|'xl'|'full' (default: xl / 1152px) bg?: 'muted'|'subtle'|'accent' as?: ElementType ``` ### Accessibility - Use semantic element with accessible name (aria-label or heading) --- ## section-header Groups a section title with supporting text or actions. - Base class: `dv-section-header` - React: `` - Element: `div` - Source: packages/html/src/css/components/_section-header.css, packages/react/src/components/SectionHeader.tsx ### HTML ```html Section Title API Keys API Keys Manage keys used to authenticate API requests ``` ### React ```tsx Users Manage members of this workspace ``` ### Props ```ts children?: ReactNode ``` ### Accessibility - Use appropriate heading level for context ### Avoid - Using for page-level titles (use page-header instead) --- ## select Self-contained native select with label, hint, error support - Base class: `dv-select` - React: ` Category Required Size ``` ### React ```tsx ``` ### React ```tsx `${Math.round(v*100)}%`} /> ``` ### Props ```ts value?: number defaultValue?: number onValueChange?: (value: number) => void range?: boolean rangeValue?: [number, number] defaultRangeValue?: [number, number] onRangeChange?: (value: [number, number]) => void tooltip?: boolean min?: number; max?: number; step?: number label?: ReactNode showValue?: boolean formatValue?: (v: number) => string size?: 'sm' | 'md' | 'lg' disabled?: boolean ``` ### Events - `input` — Native bubbling event dispatched on a range input as the value changes. - `change` — Native bubbling event dispatched on a range input when the committed value changes. ### Options - `format` (default: `null`) - `unit` (default: `''`) ### Accessibility - Use a native with min/max/step — it ships keyboard support (arrows/Home/End/PageUp-Down) and aria-valuenow/min/max natively - Associate a visible with the input; the mirrors the live value for sighted users - After an uncanceled native form reset, enhanced output and React uncontrolled state settle in the next task. Controlled React values remain application-owned. React range form association applies to both submitted inputs. - The focus ring on the thumb must stay visible against the track; never remove :focus-visible outlines - Range/two-thumb: give each input a distinct aria-label ("Minimum"/"Maximum"); each thumb keeps native role=slider --- ## sortable Lets users reorder a collection through drag and keyboard interactions. - Base class: `dv-sortable` - React: `` - Element: `ul|ol|div` - Source: packages/html/src/css/components/_sortable.css, packages/react/src/components/Sortable.tsx, packages/html/src/js/components/sortable.js - Modifiers: `dv-sortable--disabled` ### HTML ```html First Second ``` ### React ```tsx t.id} onReorder={setTasks} renderItem={(t) => {t.label}} /> ``` ### Props ```ts items?: T[] defaultItems?: T[] onReorder?: (items: T[]) => void getItemId: (item: T, index: number) => string | number renderItem: (item: T, index: number) => ReactNode axis?: 'y' | 'x' | 'grid' handle?: string disabled?: boolean canDrop?: (from: number, to: number, ctx?: { fromContainer: Element; toContainer: Element }) => boolean overlay?: boolean | OverlayOptions | ((el: Element) => Element) activationDistance?: number longPressDelay?: number autoScroll?: boolean | { threshold?: number; maxSpeed?: number } modifiers?: DragModifier[] multiSelect?: boolean duration?: number announcements?: SortableAnnouncements onDragStart?: (item: Element, event: PointerEvent) => void onDrag?: (item: Element, delta: { x: number; y: number }) => void onDragEnd?: (item: Element) => void list?: string as?: ElementType apiRef?: Ref ``` ### Events - `dragstart` — When a drag begins. detail: { item, event }. - `drag` — On each pointer move during a drag. detail: { item, x, y }. - `dragend` — When a drag is released. detail: { item }. - `reorder` — After items are reordered. detail: { item, items, oldIndex, - `cross` — On the destination container of a cross-container move. ### Options - `axis` (default: `'y'`) - `handle` (default: `null`) - `items` (default: `null`) - `disabled` (default: `false`) ### Accessibility - Each item is focusable (tabindex="0"); the engine sets aria-roledescription="sortable item", aria-keyshortcuts, and an aria-describedby instructions node - Keyboard: Space/Enter lifts, Arrow keys move, Space/Enter drops, Escape cancels — pointer AND keyboard moves are announced via an aria-live region - For handle-only drag, put the SELECTOR on the container (data-dv-sortable-handle=".dv-sortable__handle") and give each .dv-sortable__handle an accessible label - The drag gesture is pointer-only across containers; provide non-drag move controls calling move(from,to) for a single-pointer / keyboard path (WCAG 2.5.7) ### Avoid - Imposing layout via .dv-sortable — it is a behaviour marker; lay items out with your own CSS or utilities --- ## sparkline Shows a compact data trend as an inline SVG chart. - Base class: `dv-sparkline` - React: `` - Element: `svg` - Source: packages/html/src/css/components/_sparkline.css, packages/react/src/components/Sparkline.tsx, packages/html/src/js/components/sparkline.js - Variants: `dv-sparkline--accent`, `dv-sparkline--success`, `dv-sparkline--error`, `dv-sparkline--warning`, `dv-sparkline--neutral` ### HTML ```html ``` ### React ```tsx ``` ### Props ```ts data: number[] tone?: 'accent'|'success'|'error'|'warning'|'neutral' area?: boolean width?: number height?: number aria-label?: string ``` ### Events - `rendered` — Fired after the sparkline renders ### Options - `width` (default: `100`) - `height` (default: `40`) - `area` (default: `true`) - `tone` (default: `'accent'`) ### Accessibility - Provide role="img" + aria-label, or aria-hidden="true" if purely decorative beside a value - A sparkline is a tiny inline trend glyph, not an interactive chart — no keyboard/point navigation is needed (use the full Chart for explorable data). The single role="img" + aria-label (the trend summary) is the complete, intentional a11y surface; exact values belong in the adjacent number/label. ### Avoid - Hardcoding colors — use semantic tokens --- ## spinner Signals ongoing loading or processing with a rotating indicator. - Base class: `dv-spinner` - React: `` - Element: `span` - Source: packages/html/src/css/components/_spinner.css, packages/react/src/components/Spinner.tsx - Variants: `dv-spinner--accent`, `dv-spinner--success`, `dv-spinner--warning`, `dv-spinner--error`, `dv-spinner--info`, `dv-spinner--inverse` - Sizes: `dv-spinner--xs`, `dv-spinner--sm`, `dv-spinner--lg`, `dv-spinner--xl`, `dv-spinner--2xl`, `dv-spinner--3xl`, `dv-spinner--4xl` ### HTML ```html Loading... ``` ### React ```tsx ``` ### Props ```ts size?: 'xs'|'sm'|'md'|'lg'|'xl'|'2xl'|'3xl'|'4xl' color?: 'accent'|'success'|'warning'|'error'|'info'|'inverse' label?: string ``` ### Accessibility - MUST have role="status" and aria-label - Use --inverse variant on dark backgrounds ### Avoid - Spinners without accessibility attributes --- ## stack Flex layout primitive for vertical/horizontal stacking with gap, alignment, and justification modifiers. Vertical (column) by default. Cross-axis alignment default is stretch for column stacks (children fill the container width — matches block-flow expectation and Radix/Chakra/MUI/Mantine convention) and center for row stacks (vertical centering of mixed-height items). The --inline variant (inline-flex column) keeps intrinsic widths. Use dv-stack--align-start to opt column children back to intrinsic width, or dv-stack--align-stretch on rows to make children share equal heights. - Base class: `dv-stack` - React: `` - Element: `div` - Source: packages/html/src/css/components/_stack.css, packages/react/src/components/Stack.tsx - Variants: `dv-stack--row`, `dv-stack--row-nowrap`, `dv-stack--row-reverse`, `dv-stack--column-reverse`, `dv-stack--inline`, `dv-stack--wrap`, `dv-stack--nowrap`, `dv-stack--wrap-reverse` ### HTML ```html Full-width Item 1 Full-width Item 2 Full-width Item 3 Intrinsic-width Item 1 Intrinsic-width Item 2 Left Right Start End Grows to fill space Fixed size First Wraps upward ``` ### React ```tsx Tag Label ``` ### Props ```ts gap?: 0|1|2|3|4|5|6|8|10|12|16 | BreakpointMap direction?: 'column'|'row'|'row-nowrap'|'row-reverse'|'column-reverse'|'inline' | BreakpointMap<'row'|'column'> wrap?: 'wrap'|'nowrap'|'wrap-reverse' align?: 'start'|'center'|'end'|'stretch'|'baseline' | BreakpointMap justify?: 'start'|'center'|'end'|'between'|'around'|'evenly' | BreakpointMap<'start'|'center'|'end'|'between'> as?: ElementType Responsive props (`gap`/`direction`/`align`/`justify`) accept a breakpoint object — `` — which compiles to the `dv:` responsive utility classes. For fill/fixed children use the element classes: dv-stack__fill dv-stack__fixed ``` ### Avoid - Using Stack when Grid would be more appropriate for 2D layouts --- ## stepper Step progress indicator with pending, active, completed, error, and disabled states on __step elements. Horizontal lays out as a stacked rail (indicator above label); vertical lays out as an inline timeline. Connectors are drawn as a pseudo-element anchored to the indicator center, so they never detach from the circles regardless of label length. Auto-collapses to the vertical layout on narrow containers. - Base class: `dv-stepper` - React: `` - Element: `div` - Source: packages/html/src/css/components/_stepper.css, packages/react/src/components/Stepper.tsx, packages/html/src/js/components/stepper.js - Variants: `dv-stepper--horizontal`, `dv-stepper--vertical` ### HTML ```html Account Create your account Completed 2 Profile Current step 3 Review Not started ``` ### React ```tsx ``` ### Props ```ts activeStep?: number orientation?: 'horizontal'|'vertical' Step supports id, className, ARIA, icon, children, disabled and onClick; an onClick step renders a native full-step button with Enter/Space behavior. ``` ### Events - `change` — Fired before step changes (cancelable with preventDefault) - `changed` — Fired after step has changed - `update` — Fired when step state updates - `complete` — Fired when all steps are completed - `error` — Fired when step validation fails - `reset` — Fired when stepper is reset ### Keyboard - Left/Right arrows: Navigate between items - Up/Down arrows: Navigate between items - Home: Go to first item - End: Go to last item - PageUp: Jump multiple items - PageDown: Jump multiple items - Enter/Space: Activate/select ### Options - `linear` (default: `true`) - `allowSkip` (default: `false`) - `validateOnNext` (default: `true`) - `announceSteps` (default: `true`) ### Accessibility - Wrap in role="list" (or an ) with steps as role="listitem" - Use aria-current="step" on the active step - Convey each step's status to screen readers with a visually hidden .dv-sr-only span ### Avoid - Using stepper without clear step labels --- ## switch Self-contained toggle switch with hint and error support - Base class: `dv-switch` - React: `` - Source: packages/html/src/css/components/_switch.css, packages/react/src/components/Switch.tsx, packages/html/src/js/components/switch.js - Sizes: `dv-switch--sm` - Modifiers: `dv-switch--checked`, `dv-switch--error`, `dv-switch--success`, `dv-switch--disabled` ### HTML ```html Enable feature Required toggleThis must be enabled ``` ### React ```tsx ``` ### Props ```ts checked?: boolean defaultChecked?: boolean onCheckedChange?: (checked: boolean) => void onChange?: (e: ChangeEvent) => void label?: string disabled?: boolean ``` ### Events - `change` — Fired before toggle state changes (cancelable with preventDefault) - `changed` — Fired after toggle state has changed - `error` — Fired when validation sets an error message - `error-cleared` — Fired when a previously set error is cleared ### Keyboard - Enter/Space: Activate/select ### Options - `announceChange` (default: `true`) - `onLabel` (default: `null`) - `offLabel` (default: `null`) ### Accessibility - Toggle wraps input for label association - Use role="switch" on input for explicit semantics --- ## tab-bar Pins three to five primary destinations to the bottom edge of a phone screen. - Base class: `dv-tab-bar` - React: `` - Element: `nav` - Source: packages/html/src/css/components/_tab-bar.css, packages/react/src/components/TabBar.tsx, packages/html/src/js/components/tab-bar.js - Modifiers: `dv-tab-bar--floating`, `dv-tab-bar--labels-hidden`, `dv-tab-bar__item--active` ### HTML ```html HomeSearchInbox3Account HomeSearch ``` ### React ```tsx Home Search Inbox3 setOpen(true)}>More ``` ### Props ```ts floating?: boolean (inset pill instead of the docked full-bleed bar) labelsHidden?: boolean (labels in the accessibility tree only) minimizeOnScroll?: boolean (slide off on scroll-down; skipped under reduced motion) ``` ### Events - `minimize` — Fired before the bar minimizes (cancelable) - `minimized` — Fired after the bar has minimized - `restore` — Fired before the bar restores (cancelable) - `restored` — Fired after the bar has restored ### Options - `threshold` (default: `8`) - `topThreshold` (default: `24`) ### Accessibility - The bar is a with an aria-label; items are destinations with aria-current="page" on the current one, or a 1.249,00 Active Selected visual state ``` ### React ```tsx Name Status Actions John Doe Active ``` ### Props ```ts striped?: boolean density?: 'compact'|'mini' stickyCol?: boolean Table.Header type?: 'numeric'|'shrink'|'actions'|'checkbox' Table.Cell type?: 'numeric'|'shrink'|'actions'|'checkbox' stickyCol pins the first column during horizontal scrolling ``` ### Events - `sort` — Fired when table is sorted - `sort-clear` — Fired when sorting is cleared - `selection-change` — Fired when selection changes - `reorder` — Fired when a row is reordered - `row-toggle` — Fired when an expandable row changes ### Accessibility - Use proper th and td elements - Use caption or an equivalent programmatic table name when context does not identify the data - Horizontal-scroll wrappers need role="region", a programmatic name, and tabindex="0" ### Avoid - Tables without wrapper for responsive scrolling --- ## tabs Switches between related content panels through a tab list. - Base class: `dv-tabs` - React: `` - Element: `div` - Source: packages/html/src/css/components/_tabs.css, packages/react/src/components/Tabs.tsx, packages/html/src/js/components/tabs.js - Variants: `dv-tabs--vertical`, `dv-tabs--pills` ### HTML ```html Content 1 Content 2 Content Content Content Content ``` ### React ```tsx General Inbox 12 General settings Inbox content ``` ### Props ```ts value?: string defaultValue?: string onValueChange?: (value: string) => void orientation?: 'horizontal'|'vertical' variant?: 'default'|'pills' activateOnFocus?: boolean — auto-activate on arrow focus (default true); false = manual (vanilla default) Tabs.Tab props: value, disabled?, iconOnly?, iconPosition?: 'leading'|'top' ``` ### Events - `change` — Fired before tab changes (cancelable with preventDefault) - `changed` — Fired after tab has changed ### Keyboard - Left/Right arrows (horizontal): Navigate between tabs - Up/Down arrows (vertical): Navigate between tabs when orientation is vertical - Home: Go to first tab - End: Go to last tab - Enter/Space: Activate focused tab (when activateOnFocus is false) ### Options - `orientation` (default: `'horizontal'`) - `activateOnFocus` (default: `false`) - `announceChange` (default: `true`) ### Accessibility - Use role="tablist" on the tab container - Use role="tab" on tab buttons with aria-selected - Use role="tabpanel" on content panels - Hidden panels MUST have hidden attribute - Icon-only tabs MUST have aria-label ### Avoid - Using anchor tags for tabs (use buttons) - Combining --icon-top with --icon-only (stacked layout needs a label) --- ## text Styles body text and inline copy with system typography and emphasis. - Base class: `dv-text` - React: `` - Element: `p|span|div|em|strong` - Source: packages/html/src/css/components/_text.css, packages/react/src/components/Text.tsx - Variants: `dv-text--truncate`, `dv-text--clamp-2`, `dv-text--clamp-3` - Sizes: `dv-text--6xl`, `dv-text--5xl`, `dv-text--4xl`, `dv-text--3xl`, `dv-text--2xl`, `dv-text--xl`, `dv-text--lg`, `dv-text--base` (default), `dv-text--sm`, `dv-text--xs` ### HTML ```html Default paragraph text Lead paragraph Form label Caption Large muted Bold centered text Truncated long text... Multi-line clamped... 1,234.50 Balanced headline Hyphenated long-form copy… Body on mobile, lead paragraph on desktop ``` ### React ```tsx Default paragraph Updated 3h ago Large bold text Long-form body copy $1,234.50 Long text... Multi-line clamped text Body on mobile, display on desktop ``` ### Props ```ts as?: ElementType (default 'p') size?: '6xl'|'5xl'|'4xl'|'3xl'|'2xl'|'xl'|'lg'|'base'|'sm'|'xs' — also accepts a breakpoint object, e.g. size={{ base: 'base', md: '4xl' }} color?: 'default'|'muted'|'subtle'|'accent'|'success'|'error'|'warning'|'info'|'inverse' weight?: 'normal'|'medium'|'semibold'|'bold'|'extrabold' font?: 'sans'|'serif'|'mono'|'display'|'editorial' align?: 'start'|'center'|'end'|'justify' leading?: 'none'|'tight'|'snug'|'normal'|'relaxed'|'loose' tracking?: 'tighter'|'tight'|'normal'|'wide'|'wider'|'widest' transform?: 'uppercase'|'lowercase'|'capitalize'|'normal-case' decoration?: 'underline'|'line-through'|'no-underline' decorationStyle?: 'dashed'|'dotted'|'wavy' decorationThickness?: 2 underlineOffset?: 2|4 italic?: boolean whitespace?: 'normal'|'nowrap'|'pre'|'pre-line'|'pre-wrap' wordBreak?: 'normal'|'words'|'all' wrap?: 'balance'|'pretty' // text-wrap hyphens?: 'auto'|'manual'|'none' // hyphens-auto needs `lang` on an ancestor tabularNums?: boolean truncate?: boolean clamp?: 2|3 ``` ### Accessibility - Ensure sufficient color contrast for muted/subtle text on its background ### Avoid - Using --subtle for form hints and errors — those are instructions bound to a control; use --muted - Using --subtle on a bg-subtle surface — 4.36:1, below AA for normal-size text - Using dv-text for inline code — use the dv-code component instead --- ## text-field Self-contained text input field with label, hint, error, icon support - Base class: `dv-text-field` - React: `` - Source: packages/html/src/css/components/_text-field.css, packages/react/src/components/TextField.tsx, packages/html/src/js/components/text-field.js - Sizes: `dv-text-field--sm`, `dv-text-field--lg` - Modifiers: `dv-text-field--error`, `dv-text-field--success`, `dv-text-field--disabled`, `dv-text-field--readonly`, `dv-text-field--search` ### HTML ```html Email EmailInvalid email Name Search Max retriesattempts ``` ### React ```tsx ``` ### Props ```ts label?: string hint?: string error?: string success?: boolean size?: 'sm'|'md'|'lg' startIcon?: ReactNode endIcon?: ReactNode prefix?: ReactNode suffix?: ReactNode fullWidth?: boolean enterKeyHint?: 'enter'|'done'|'go'|'next'|'previous'|'search'|'send' ``` ### Events - `input` — Fired on input change - `blur` — Fired on blur - `focus` — Fired on focus - `clear` — Fired when input is cleared - `error` — Fired when error is set - `error-cleared` — Fired when error is cleared ### Options - `showCount` (default: `false`) - `clearable` (default: `false`) - `validateOnBlur` (default: `true`) - `validateOnInput` (default: `false`) - `countFormat` (default: `'{current}/{max}'`) - `announceCount` (default: `true`) - `countThreshold` (default: `10`) ### Accessibility - Labels must be associated with inputs via for/id or wrapping - Error messages should use aria-describedby - Required fields should have aria-required="true" ### Avoid - Using placeholder text as the only label --- ## textarea Self-contained multi-line text input with label, hint, error support - Base class: `dv-textarea` - React: `` - Source: packages/html/src/css/components/_textarea.css, packages/react/src/components/Textarea.tsx, packages/html/src/js/components/textarea.js - Variants: `dv-textarea--auto-resize`, `dv-textarea--editor` - Sizes: `dv-textarea--sm`, `dv-textarea--lg` - Modifiers: `dv-textarea--error`, `dv-textarea--success`, `dv-textarea--disabled`, `dv-textarea--readonly` ### HTML ```html <div class="dv-textarea"><label class="dv-textarea__label" for="ta-msg">Message</label><textarea id="ta-msg" class="dv-textarea__input" placeholder="Enter message"> MessageRequired Note ``` ### React ```tsx <Textarea label="Notes" error="Field is required" rows={4} /> <Textarea label="Reply" enterKeyHint="send" /> ``` ### Props ```ts label?: string hint?: string error?: string success?: boolean size?: 'sm'|'md'|'lg'|'editor' autoResize?: boolean minRows?: number maxRows?: number showCharCount?: boolean fullWidth?: boolean enterKeyHint?: 'enter'|'done'|'go'|'next'|'previous'|'search'|'send' ``` ### Events - `input` — Fired on input change - `blur` — Fired on blur - `focus` — Fired on focus - `clear` — Fired when textarea is cleared - `error` — Fired when error is set - `error-cleared` — Fired when error is cleared - `submit` — Fired when Ctrl+Enter is pressed ### Keyboard - Enter/Space: Activate/select ### Options - `showCount` (default: `false`) - `autoResize` (default: `false`) - `minRows` (default: `2`) - `maxRows` (default: `10`) - `countFormat` (default: `'{current}/{max}'`) - `announceCount` (default: `true`) - `countThreshold` (default: `20`) - `validateOnBlur` (default: `true`) ### Accessibility - Use aria-invalid="true" with error state - Use aria-describedby to link to error messages --- ## time-picker 24-hour time picker — typeable field + Hours|Minutes column panel - Base class: `dv-time-picker` - React: `<TimePicker>` - Source: packages/html/src/css/components/_time-picker.css, packages/react/src/components/TimePicker.tsx, packages/html/src/js/components/time-picker.js - Sizes: `dv-time-picker--sm`, `dv-time-picker--lg` - Modifiers: `dv-time-picker--open`, `dv-time-picker--disabled`, `dv-time-picker--error`, `dv-time-picker--success` ### HTML ```html <div class="dv-time-picker" data-dv-time-picker><label class="dv-time-picker__label" for="tp">Time</label><input type="hidden" name="time" value=""><div class="dv-time-picker__wrapper"><input type="text" id="tp" class="dv-time-picker__input" role="combobox" aria-autocomplete="none" aria-expanded="false" aria-haspopup="dialog" placeholder="--:--"><svg class="dv-icon dv-time-picker__icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" aria-hidden="true"><circle cx="12" cy="12" r="9" stroke-width="2"/><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 7v5l3 3"/></svg></div><div class="dv-time-picker__panel" hidden><div class="dv-time-picker__columns"><ul class="dv-time-picker__column" data-dv-unit="hours" role="listbox" aria-label="Hours"></ul><ul class="dv-time-picker__column" data-dv-unit="minutes" role="listbox" aria-label="Minutes"></ul></div></div></div> ``` ### React ```tsx <TimePicker label="Start time" value={value} onValueChange={setValue} step={15} min="09:00" max="17:00" clearable /> ``` ### Props ```ts inputProps?: FieldInputProps // visible input attributes and composed events inputRef?: Ref<HTMLInputElement> // visible input focus value?: string // canonical 24h "HH:MM" defaultValue?: string onValueChange?: (value: string) => void step?: number // minutes between minute options (default 30) min?: string // "HH:MM" (default "00:00") max?: string // "HH:MM" (default "23:59") snapToStep?: boolean placeholder?: string clearable?: boolean disabled?: boolean error?: string hint?: string optional?: boolean size?: 'sm'|'md'|'lg' label?: string name?: string open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean) => void ``` ### Events - `open` — Fired before the panel opens (cancelable with preventDefault) - `opened` — Fired after the panel has opened - `close` — Fired before the panel closes (cancelable with preventDefault) - `closed` — Fired after the panel has closed - `changed` — Fired after the selection has changed (detail: { value, label }) - `error` — Fired when error is set - `error-cleared` — Fired when error is cleared ### Keyboard - Left/Right arrows: Navigate between items - Up/Down arrows: Navigate between items - Home: Go to first item - End: Go to last item - Enter/Space: Activate/select - Escape: Close/dismiss ### Options - `step` (default: `30`) - `min` (default: `'00:00'`) - `max` (default: `'23:59'`) - `clearable` (default: `true`) - `snapToStep` (default: `false`) ### Accessibility - Input has role="combobox", aria-expanded, aria-controls (the panel), aria-haspopup="dialog" - Each column is role="listbox" with an aria-label (Hours / Minutes) - Options have role="option", aria-selected; the focused listbox owns aria-activedescendant in the React dialog model --- ## timeline Presents events or activity in chronological order. - Base class: `dv-timeline` - React: `<Timeline>` - Element: `ul|div` - Source: packages/html/src/css/components/_timeline.css, packages/react/src/components/Timeline.tsx - Variants: `dv-timeline--vertical`, `dv-timeline--padded` ### HTML ```html <ul class="dv-timeline"><li class="dv-timeline__item"><span class="dv-timeline__time">2:30 PM</span><div class="dv-timeline__content"><div class="dv-timeline__title">Event title</div><div class="dv-timeline__meta">Description</div></div></li></ul> <ul class="dv-timeline dv-timeline--vertical"><li class="dv-timeline__line-wrapper" aria-hidden="true"><span class="dv-timeline__line--vertical"></span></li><li class="dv-timeline__section--vertical"><div class="dv-timeline__heading--vertical"><span class="dv-timeline__marker--vertical" aria-hidden="true"></span>Section</div></li></ul> ``` ### React ```tsx <Timeline> <Timeline.Item time="2024-01-01" title="Project started"> Initial setup completed. </Timeline.Item> <Timeline.Item time="2024-02-15" title="Beta launch"> Released beta to early users. </Timeline.Item> </Timeline> ``` ### Props ```ts padded?: boolean vertical?: boolean line?: boolean ``` ### Accessibility - Use semantic list elements for timeline items - Time elements should use datetime attribute ### Avoid - Timeline without clear time indicators --- ## toast Shows a transient notification with optional actions and dismissal. - Base class: `dv-toast` - React: `<Toast>` - Element: `div` - Source: packages/html/src/css/components/_toast.css, packages/react/src/components/Toast.tsx, packages/html/src/js/components/toast.js - Variants: `dv-toast--success`, `dv-toast--error`, `dv-toast--warning`, `dv-toast--info` - Modifiers: `dv-toast--visible`, `dv-toast--dismissing` ### HTML ```html <div class="dv-toast__container dv-toast__container--bottom-right"><div class="dv-toast dv-toast--success dv-toast--visible" role="status"><div class="dv-toast__content"><svg class="dv-toast__icon">...</svg><div class="dv-toast__body"><p class="dv-toast__message">Saved.</p><p class="dv-toast__description">Optional secondary line.</p></div></div><div class="dv-toast__actions"><button class="dv-toast__action dv-button dv-button--ghost dv-button--sm">Undo</button><button class="dv-toast__close dv-button dv-button--ghost dv-button--icon-only dv-button--sm" aria-label="Dismiss notification"><svg class="dv-icon">...</svg></button></div></div></div> <div class="dv-toast__container dv-toast__container--top-center">...</div> ``` ### React ```tsx <ToastProvider defaultPosition="top-right" maxToasts={5}> <App /> </ToastProvider> ``` ### Props ```ts defaultPosition?: 'top-left'|'top-center'|'top-right'|'bottom-left'|'bottom-center'|'bottom-right' container?: Element | null maxToasts?: number children: ReactNode ``` ### Events - `show` — Fired once the toast is mounted and its timer started - `dismiss` — Fired at the START of dismissal, before the exit - `action` — Fired when the action button is pressed, before its ### Keyboard - Escape: Close/dismiss ### Accessibility - Runtime HTML and React toasts use role="alert" for errors and role="status" otherwise, with aria-live="off" on the visible item. Separate persistent hosts announce errors assertively and other messages politely; custom implementations must prime empty hosts before adding text. - Close button MUST have aria-label="Dismiss notification" - Allow enough reading time, pause dismissal while hovered or focused, and use duration=0 when a notification must persist. ### Avoid - Creating toasts without visible/dismissing state management --- ## toggle-group Groups toggle buttons for single or multiple selection. - Base class: `dv-toggle-group` - React: `<ToggleGroup>` - Element: `div` - Source: packages/html/src/css/components/_toggle-group.css, packages/react/src/components/ToggleGroup.tsx, packages/html/src/js/components/toggle-group.js - Modifiers: `dv-toggle-group--vertical`, `dv-toggle-group--sm`, `dv-toggle-group--lg`, `dv-toggle-group--plain` ### HTML ```html <div class="dv-toggle-group" role="group" aria-label="View" data-dv-toggle-group data-dv-type="single" data-dv-allow-empty><button class="dv-toggle-group__item" type="button" aria-pressed="true" data-value="grid">Grid</button><button class="dv-toggle-group__item" type="button" aria-pressed="false" data-value="list">List</button></div> ``` ### React ```tsx <ToggleGroup type="single" defaultValue="grid" aria-label="View"> <ToggleGroup.Item value="grid">Grid</ToggleGroup.Item> <ToggleGroup.Item value="list">List</ToggleGroup.Item> </ToggleGroup> <ToggleGroup type="multiple" defaultValue={['bold']} aria-label="Format"> <ToggleGroup.Item value="bold">B</ToggleGroup.Item> <ToggleGroup.Item value="italic">I</ToggleGroup.Item> <ToggleGroup.Item value="underline">U</ToggleGroup.Item> </ToggleGroup> ``` ### Props ```ts type: 'single' | 'multiple' value?: string | string[] defaultValue?: string | string[] onValueChange?: (value) => void allowEmpty?: boolean size?: 'sm' | 'md' | 'lg' orientation?: 'horizontal' | 'vertical' variant?: 'default' | 'plain' disabled?: boolean ``` ### Events - `change` — Before the pressed set changes (cancelable with preventDefault) - `changed` — After the pressed set has changed --- ## tooltip Provides a short description when a trigger is hovered or focused. - Base class: `dv-tooltip` - React: `<Tooltip>` - Element: `span|div` - Source: packages/html/src/css/components/_tooltip.css, packages/react/src/components/Tooltip.tsx, packages/html/src/js/components/tooltip.js - Modifiers: `dv-tooltip--visible`, `dv-tooltip--top`, `dv-tooltip--bottom`, `dv-tooltip--left`, `dv-tooltip--right`, `dv-tooltip--inline`, `dv-tooltip--no-arrow` ### HTML ```html <button type="button" class="dv-button" data-dv-tooltip="Tooltip text">Hover me</button> <span data-dv-tooltip="Upgrade to enable" tabindex="0" style="display:inline-flex"><button disabled style="pointer-events:none">Save</button></span> <span class="dv-tooltip"><button type="button" aria-describedby="nested-tip">Hover me</button><span id="nested-tip" class="dv-tooltip__content" role="tooltip">Nested tooltip text</span></span> ``` ### React ```tsx <Tooltip content="Save your changes"><Button>Save</Button></Tooltip> <Tooltip content="More info" placement="right" delay={500}><button type="button">Hover me</button></Tooltip>  <Tooltip content="Upgrade to enable"> <span tabIndex={0} style={{ display: 'inline-flex' }}> <button disabled style={{ pointerEvents: 'none' }}>Save</button> </span> </Tooltip>  ``` ### Props ```ts content: ReactNode children: (props: TooltipTriggerProps) => ReactNode open?: boolean defaultOpen?: boolean onOpenChange?: (open: boolean) => void placement?: 'top'|'bottom'|'left'|'right' offset?: number delay?: number hideDelay?: number trigger?: 'hover'|'focus'|'click'|'hover focus' disabled?: boolean container?: Element | null arrow?: boolean ``` ### Events - `open` — Fired when tooltip starts opening - `opened` — Fired when tooltip becomes visible - `close` — Fired when tooltip starts closing - `closed` — Fired when tooltip is hidden ### Keyboard - Escape: Close/dismiss ### Options - `container` (default: `null`) - `placement` (default: `'top'`) - `offset` (default: `8`) - `delay` (default: `0`) - `hideDelay` (default: `150`) - `trigger` (default: `'hover focus'`) ### Accessibility - Tooltip content should be accessible via focus (keyboard) - Use aria-describedby for complex tooltip associations - Avoid putting interactive content inside tooltips - For a tooltip on a DISABLED control, put data-dv-tooltip on a focusable wrapping <span> (tabindex="0") and set pointer-events:none on the inner disabled control — disabled elements emit no hover/focus events. ### Avoid - Tooltips on touch-only devices without alternative --- ## topbar Groups branding, navigation, and actions in the application header. - Base class: `dv-topbar` - React: `<Topbar>` - Element: `header` - Source: packages/html/src/css/components/_topbar.css, packages/react/src/components/Topbar.tsx - Sizes: `dv-topbar--sm`, `dv-topbar--md`, `dv-topbar--lg`, `dv-topbar--xl` (default), `dv-topbar--full` - Modifiers: `dv-topbar--centered`, `dv-topbar--overflow` ### HTML ```html <header class="dv-topbar"><div class="dv-topbar__inner"><div class="dv-topbar__left"><span class="dv-topbar__title">App</span></div><nav class="dv-topbar__nav" aria-label="Main"><a class="dv-button dv-button--ghost dv-button--active" href="#" aria-current="page">Home</a><a class="dv-button dv-button--ghost" href="#">Products</a><a class="dv-button dv-button--ghost" href="#">About</a></nav><div class="dv-topbar__right"><button class="dv-button dv-button--ghost dv-button--icon-only" aria-label="Settings"><svg class="dv-icon" aria-hidden="true">...</svg></button></div></div></header> <header class="dv-topbar dv-topbar--overflow"><div class="dv-topbar__inner"><div class="dv-topbar__left"><span class="dv-topbar__title">App</span></div><nav class="dv-topbar__nav" aria-label="Main"><a class="dv-button dv-button--ghost dv-button--active" href="#" aria-current="page">Home</a><a class="dv-button dv-button--ghost" href="#">Products</a><a class="dv-button dv-button--ghost" href="#">Solutions</a><a class="dv-button dv-button--ghost" href="#">Pricing</a><a class="dv-button dv-button--ghost" href="#">Docs</a><a class="dv-button dv-button--ghost" href="#">Blog</a></nav><div class="dv-topbar__right"><button type="button" class="dv-topbar__menu dv-button dv-button--ghost" data-dv-drawer-trigger="site-menu"><svg class="dv-icon" aria-hidden="true">...</svg>Menu</button></div></div></header><dialog class="dv-drawer dv-drawer--right" id="site-menu" data-dv-drawer aria-labelledby="site-menu-title"><div class="dv-drawer__container"><div class="dv-drawer__header"><h2 class="dv-drawer__title" id="site-menu-title">Menu</h2><button type="button" class="dv-drawer__close dv-button dv-button--ghost dv-button--icon-only" data-dv-drawer-close aria-label="Close menu"><svg class="dv-icon" aria-hidden="true">...</svg></button></div><div class="dv-drawer__content"><nav class="dv-nav" aria-label="Main"><a class="dv-nav__item dv-nav__item--active" href="#" aria-current="page">Home</a><a class="dv-nav__item" href="#">Products</a><a class="dv-nav__item" href="#">Solutions</a><a class="dv-nav__item" href="#">Pricing</a><a class="dv-nav__item" href="#">Docs</a><a class="dv-nav__item" href="#">Blog</a></nav></div></div></dialog> ``` ### React ```tsx <Topbar> <Topbar.Inner> <Topbar.Left><a href="/">Logo</a></Topbar.Left> <Topbar.Nav aria-label="Main"> <Button variant="ghost" href="/" active aria-current="page">Home</Button> <Button variant="ghost" href="/about">About</Button> </Topbar.Nav> <Topbar.Right> <Button variant="ghost">Sign in</Button> </Topbar.Right> </Topbar.Inner> </Topbar> ``` ### Props ```ts width?: 'sm'|'md'|'lg'|'xl'|'full' (default: xl / 1152px) centered?: boolean overflow?: boolean (hide the nav row below md; Topbar.Menu opens a Drawer) ``` ### Accessibility - Use header element for site navigation bar - Below md the __nav is a visible, horizontally scrolling row — keep it to four or fewer destinations (NN/g's visible-links rule); with more, add --overflow and a trailing __menu button whose `data-dv-drawer-trigger` opens a Drawer holding the same links as a .dv-nav - The __menu button must read "Menu" (text or aria-label) — a bare icon is recognised less than the word. The Drawer it opens is the overlay: focus trap, backdrop, Escape and swipe all come from it ### Avoid - Multiple dv-topbar elements on same page - Hiding the primary navigation behind an icon on a phone when it fits in the row --- ## visually-hidden Keeps content accessible to assistive technology while hiding it visually. - Base class: `dv-sr-only|dv-visually-hidden` - React: `<VisuallyHidden>` - Element: `any` - Source: packages/html/src/css/components/_visually-hidden.css, packages/react/src/components/VisuallyHidden.tsx ### HTML ```html <span class="dv-sr-only">Screen reader only text</span> <span class="dv-visually-hidden">Visually hidden but accessible</span> <a href="#main-content" class="dv-visually-hidden--focusable">Skip to main content</a> ``` ### Accessibility - dv-sr-only hides content visually but keeps it accessible to screen readers - dv-visually-hidden--focusable reveals on keyboard focus (skip-link pattern) ### Avoid - Using display:none for content that should be accessible to screen readers --- ## Utility reference See docs/utilities.md for bundle and composition contracts. Use MCP dvlayer_get_utility for exact class availability. ### Accessibility Forced-colors visibility, motion-preference transitions, touch target, and RTL inline-spacing utilities. Logical text alignment lives alongside the physical text-align utilities in _typography.css; keyframe animations (`.dv\:motion-safe:animate-*`) live in _animations.css. Source: packages/html/src/css/utilities/_accessibility.css .dv\:forced-colors\:{hidden|visible} .dv\:motion-safe\:transition, .dv\:motion-reduce\:transition-none .dv\:touch-target (inline-flex box, minimum 44px target) .dv\:ms-{0|1|2|3|4|5|6|8|10|12|16|24|auto}, .dv\:me-{0|1|2|3|4|5|6|8|10|12|16|24|auto} .dv\:ps-{0|1|2|3|4|5|6|8|10|12|16|24}, .dv\:pe-{0|1|2|3|4|5|6|8|10|12|16|24} .dv\:{start|end}-{0|1|2|3|4|6|8|auto}, .dv\:border-{s|e}{|-0|-2|-4}, .dv\:rounded-{s|e} .dv\:float-{start|end} ### Alignment Everyday flexbox/grid alignment — container cross-axis (`align-items`), main-axis distribution (`justify-content`), the grid centering shorthand (`place-items`), and per-item override (`align-self`). items/justify receive responsive variants at build time; place-items and self are base-only. Multi-line distribution (align-content) and per-item two-axis placement live in the Grid component, not utilities (ADR-026). Source: packages/html/src/css/utilities/_alignment.css .dv\:items-{start|end|center|baseline|stretch} (align-items) .dv\:justify-{start|end|center|between} (justify-content) .dv\:justify-center-safe (base-only, start fallback) .dv\:place-items-{start|end|center|stretch} .dv\:self-{auto|start|end|center|stretch|baseline} (align-self) ### Animations Named keyframe animations for utility consumers (spin, pulse, bounce). All variants are motion-preference-gated: applied only when the user has not requested reduced motion. Pair with `.dv\:motion-reduce:animate-none` to explicitly cancel an inherited animation when reduced motion is requested. Source: packages/html/src/css/utilities/_animations.css .dv\:motion-safe\:{animate-spin|animate-pulse|animate-bounce} .dv\:motion-reduce\:animate-none ### Aspect Ratio Fixed aspect ratio containers Source: packages/html/src/css/utilities/_aspect-ratio.css .dv\:aspect-{auto|square|video|cinema|portrait|landscape|golden|photo|wide|ultrawide} ### Borders Border width, direction, border radius, and divider utilities. Source: packages/html/src/css/utilities/_borders.css .dv\:border, .dv\:border-{0|2|4} .dv\:border-{t|r|b|l}, .dv\:border-{t|r|b|l}-{0|2|4} .dv\:border-{solid|dashed|dotted} .dv\:rounded-{none|xs|sm|md|lg|xl|full} .dv\:rounded-{t|r|b|l}-{none|xs|sm|md|lg|xl|full} .dv\:divide-{x|y} ### Colors Semantic background, foreground, and border color utilities. Every class name 1:1 mirrors a `--dv-color-{bg|fg|border}-X` token — no sub-namespaces, no aliases. Enforced by validate-consistency Pass 15. Source: packages/html/src/css/utilities/_colors.css .dv\:bg-{default|subtle|muted|raised|overlay|inverse|transparent|inherit|white|black} .dv\:bg-accent, .dv\:bg-accent-subtle .dv\:bg-{success|error|warning|info}, .dv\:bg-{success|error|warning|info}-subtle .dv\:bg-{default|muted|subtle|raised|overlay|inverse|accent|accent-subtle|success|success-subtle|error|error-subtle|warning|warning-subtle|info|info-subtle|white|black}\/{5|10|15|20|30|40|50|60|70|80|90} (generated) .dv\:fg-{default|muted|subtle|disabled|inverse|accent|success|error|warning|info|white|black} .dv\:fg-{default|muted|subtle|disabled|inverse|accent|success|error|warning|info|white|black}\/{5|10|15|20|30|40|50|60|70|80|90} (generated) .dv\:fg-on-{accent|success|warning|error|info} (text on a filled surface) .dv\:fg-{inherit|current|transparent} (functional escape hatches) .dv\:border-{default|muted|emphasis|accent|success|error|warning|info|transparent|white|black} .dv\:border-{default|muted|emphasis|accent|success|error|warning|info|white|black}\/{5|10|15|20|30|40|50|60|70|80|90} (generated) ### ColorStates Consumer sets `--dv-color-state-base`; helper derives hover/active/disabled via `oklch(from …)` relative colours. These fixed shifts do not choose a foreground or guarantee contrast. Validate each foreground/background pair in every state and mode. Source: packages/html/src/css/utilities/_color-states.css .dv\:color-states ### Container Queries Container-query context primitives. The actual `.dv:@{bp}:*` responsive variants (display, spacing, sizing, text-align) are emitted by scripts/generate-responsive.mjs at build time — see ADR-019. Source: packages/html/src/css/utilities/_container-queries.css .dv\:cq, .dv\:cq-normal, .dv\:cq-size ### Display Display type, visibility, and print/screen-only utilities. Source: packages/html/src/css/utilities/_display.css .dv\:{block|inline|inline-block|flex|inline-flex|grid|inline-grid|flow-root|hidden|contents|visible|invisible|collapse} .dv\:print\:{hidden|block|inline}, .dv\:screen\:hidden ### Effects Box shadow, opacity, isolation, and gradient background utilities. Source: packages/html/src/css/utilities/_effects.css .dv\:shadow-{none|xs|sm|md|lg|xl|2xl|inner} .dv\:opacity-{0|5|10|25|50|75|90|100} .dv\:isolate, .dv\:isolation-auto .dv\:bg-gradient-to-{t|tr|r|br|b|bl|l|tl}, .dv\:bg-gradient-radial .dv\:from-{transparent|white|black|default|subtle|muted|inverse|accent|accent-subtle} .dv\:to-{transparent|white|black|default|subtle|muted|inverse|accent|accent-subtle} .dv\:{from|to}-accent\/{5|10|15|20} (alpha-tinted accent stops), .dv\:via-transparent .dv\:{from|to}-black\/{5|10|15|20|30|40|50|60|70|80|90} (scrim ladder, parity with bg-black) ### Filters CSS filter and backdrop-filter utilities — blur, brightness, contrast, grayscale, saturate. Each class sets the whole `filter` property, so filters do not stack; for combined effects write custom CSS. Source: packages/html/src/css/utilities/_filters.css .dv\:blur-{none|xs|sm|md|lg|xl|2xl|3xl} .dv\:backdrop-blur-{none|xs|sm|md|lg|xl|2xl|3xl} .dv\:brightness-{50|75|90|100|110|125|150} .dv\:contrast-{50|75|100|125|150} .dv\:saturate-{0|50|100|150|200}, .dv\:grayscale, .dv\:grayscale-0 .dv\:filter-none ### Flexbox Flex-container direction/wrap and the three everyday flex-item idioms. Pair with `.dv\:flex` (display) and the alignment utilities (`items-*`, `justify-*`). Direction, wrap, and the item idioms all receive responsive variants at build time (`.dv\:{bp}\:*` viewport + `.dv\:@{bp}\:*` container). Structured layout lives in the Stack component — these are for ad-hoc composition (ADR-026). Source: packages/html/src/css/utilities/_flexbox.css .dv\:flex-{row|col} (flex-direction) .dv\:flex-{wrap|nowrap} (flex-wrap) .dv\:flex-1 (grow to fill), .dv\:flex-none (don't flex), .dv\:shrink-0 (don't shrink) ### Grid Quick CSS-grid column tracks and child spanning for ad-hoc grids. Pair with `.dv\:grid` (display) and `.dv\:gap-*` (spacing). Column count and child span both get responsive variants (`.dv\:{bp}\:col-span-*`). 2-D layout (rows, flow, auto-fit, bento, areas) lives in the Grid component, not utilities (ADR-026). Scales mirror `.dv-grid`. Source: packages/html/src/css/utilities/_grid.css .dv\:grid-cols-{1|2|3|4|5|6|12} .dv\:col-span-{1|2|3|4|5|6|full} ### Interactivity Cursor, pointer events, focus ring, and hover/active/disabled state utilities Source: packages/html/src/css/utilities/_interactivity.css .dv\:cursor-{auto|default|pointer|wait|text|move|not-allowed|grab|grabbing} .dv\:select-{none|text|all|auto}, .dv\:pointer-events-{none|auto} .dv\:ring, .dv\:ring-{1|2}, .dv\:ring-offset-2, .dv\:ring-primary, .dv\:ring-inset, .dv\:focus-ring, .dv\:focus-visible\:ring .dv\:group, .dv\:group-hover\:{text-accent|text-default|opacity-100|visible|scale-105|translate-x-1} .dv\:group-focus-within\:{visible|opacity-100} .dv\:hover\:{underline|no-underline} .dv\:hover\:shadow-{md|lg|xl|none}, .dv\:hover\:opacity-{100|75|50} .dv\:active\:bg-muted .dv\:disabled\:{opacity-50|cursor-not-allowed|pointer-events-none} .dv\:focus\:{ring|border-primary} .dv\:will-change-{auto|transform|opacity|scroll} .dv\:appearance-{none|auto}, .dv\:accent-{auto|accent}, .dv\:caret-{auto|accent} .dv\:touch-{auto|none|pan-x|pan-y|manipulation} (which gestures the browser keeps) ### Intrinsic Sizing Intrinsic width and height using min-content, max-content, and fit-content Source: packages/html/src/css/utilities/_intrinsic-sizing.css .dv\:w-{min|max|fit}, .dv\:h-{min|max|fit} ### Layout Object fit, object position, and list style utilities Source: packages/html/src/css/utilities/_layout.css .dv\:object-{contain|cover|fill|none|scale-down} .dv\:object-{center|top|bottom|left|right} .dv\:object-{left-top|right-top|left-bottom|right-bottom} .dv\:list-{none|disc|decimal}, .dv\:list-{inside|outside} ### Overflow Overflow behavior and scrollbar visibility utilities. A container these make SCROLLABLE needs `tabindex="0"` plus a name (`role="region"` + `aria-label`) UNLESS it already holds something focusable — a region that scrolls but has no tab stop cannot be scrolled by keyboard at all (WCAG 2.1.1; axe `scrollable-region-focusable`). dv-layer's own scrollers (Table, Calendar, Carousel, Panes) do this for you; a container you compose out of these utilities does not. Source: packages/html/src/css/utilities/_overflow.css .dv\:overflow-{auto|hidden|visible|scroll|clip} .dv\:overflow-{x|y}-{auto|hidden|visible|scroll|clip} .dv\:scrollbar-{thin|none} ### Positioning CSS position type and inset/offset utilities. Offset scale `0 1 2 3 4 6 8` is intentionally a tighter subset of the `--dv-space-*` scale: absolute positioning is for nudges and floating chrome, large offsets are layout-grid territory better expressed with grid/flex. If a future surface needs larger steps, add them then. Source: packages/html/src/css/utilities/_positioning.css .dv\:{static|relative|absolute|fixed|sticky} .dv\:inset-{0|auto}, .dv\:inset-x-{0|auto}, .dv\:inset-y-{0|auto} .dv\:{top|right|bottom|left}-{0|1|2|3|4|6|8|auto|full|1/2} .dv\:{top|bottom|start|end}-safe (inset = the device safe-area inset on that edge) .dv\:-{top|right|bottom|left}-{1|2|3|4} (negative offsets) ### Pseudo-elements Curated `::before` / `::after` utilities for DECORATIVE OVERLAYS only — gradient tints on cards, scrim layers, hover halos. Every rule emits `content: ""` (empty box) and offers no consumer override. Source: packages/html/src/css/utilities/_pseudo.css .dv\:before\:{block|inline-block|hidden|absolute|inset-0} .dv\:after\:{block|inline-block|hidden|absolute|inset-0} ### Scroll Scroll-margin / scroll-padding, overscroll containment, scroll-snap and scroll-behavior utilities. Clearing a sticky topbar for anchor targets is handled document-wide by base.css — these are for per-target fine-tuning on top of it, and adding one to clear the bar would double-count. A snap scroller whose slides hold nothing focusable needs `tabindex="0"` and a name on the CONTAINER, or it is unreachable by keyboard (WCAG 2.1.1) — see `_overflow.css`. Source: packages/html/src/css/utilities/_scroll.css .dv\:scroll-mt-{0|2|4|8|12|16}, .dv\:scroll-mb-{0|2|4|8|12|16|header} .dv\:scroll-pt-{0|2|4|8|12|16}, .dv\:scroll-pb-{0|2|4|8|12|16|header} .dv\:overscroll-{auto|contain|none}, .dv\:overscroll-{x|y}-{auto|contain|none} .dv\:snap-{none|x|y|both|start|center|end|align-none} .dv\:scroll-{smooth|auto} ### Sizing Width, height, square size, min/max constraints, icon sizes, and the semantic container scale on both axes. Source: packages/html/src/css/utilities/_sizing.css .dv\:w-{auto|full|screen|1/2|1/3|2/3|1/4|3/4} .dv\:{w|h|size}-{0|1|2|3|4|5|6|8|10|12|16|24} (spacing scale) .dv\:{w|h|min-h|max-h}-{xs|sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl} (semantic containers) .dv\:max-w-{none|xs|sm|md|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|full|prose} .dv\:h-{auto|full|screen|screen-small|screen-large} .dv\:min-h-{0|auto|fit|full|screen|screen-small|screen-large} .dv\:max-h-{0|8|10|12|16|24|full|screen|screen-small|screen-large} .dv\:min-w-{0|full|fit}, .dv\:size-icon-{xs|sm|md|lg|xl|2xl} ### Spacing Margin, padding, negative margin, and fluid (clamp-based) spacing utilities. Every side shares one uniform step scale: 0 1 2 3 4 5 6 8 10 12 16 24. Source: packages/html/src/css/utilities/_spacing.css .dv\:{m|mx|my|mt|mr|mb|ml}-{0|1|2|3|4|5|6|8|10|12|16|24|auto} .dv\:{p|px|py|pt|pr|pb|pl}-{0|1|2|3|4|5|6|8|10|12|16|24} .dv\:-{m|mx|my|mt|mr|mb|ml}-{1|2|3|4} (negative margins; symmetric + directional) .dv\:{m|mx|my|p|px|py}-fluid-{sm|md|lg|xl} (responsive clamp) .dv\:{gap|gap-x|gap-y}-{0|1|2|3|4|5|6|8|10|12|16|24} (flex/grid gap) .dv\:section-spacing, .dv\:section-spacing-lg .dv\:{pt|pb|ps|pe}-safe (padding = the device safe-area inset on that edge) ### Transforms CSS transform utilities. The translate/rotate/scale family is emitted by `scripts/generate-responsive.mjs` from `TRANSFORM_UTILITIES` in `responsive-utilities.config.mjs` — single source of truth for both per-axis variable assignments and the composed `transform:` expression. Each utility writes its per-axis var AND emits `transform: <composed>` inline (no shared universal-selector declaration), so an element with ONLY a stateful transform utility carries no transform at rest. Hover / active / group-hover variants are emitted from `TRANSFORM_STATEFUL`. Source: packages/html/src/css/utilities/_transforms.css .dv\:translate-x-{0|1|2|4}, .dv\:translate-y-{0|1|2}, .dv\:-translate-{x|y}-{1|1/2} (generated) .dv\:rotate-{0|45|90|180}, .dv\:-rotate-{45|90} (generated) .dv\:scale-{0|50|75|90|95|100|105|110} (generated) .dv\:hover\:{-translate-y-1|-translate-y-2|translate-y-1|scale-105|scale-110} (generated) .dv\:active\:{scale-95|scale-98} (generated) .dv\:group-hover\:{scale-105|translate-x-1} (generated) .dv\:backface-{hidden|visible} ### Transitions CSS transition property, duration, and easing utilities (respects prefers-reduced-motion) Source: packages/html/src/css/utilities/_transitions.css .dv\:transition-none .dv\:transition-{all|colors|opacity|shadow|transform} .dv\:duration-{0|75|150|200|300|400|500|600|750|1000} .dv\:ease-{linear|in|out|in-out|spring-gentle|spring-snappy|spring-bouncy} ### Typography Composition-layer text utilities — alignment, truncation, line clamping, transform, decoration, weight, family, wrapping. Font *size* is intentionally omitted: it stays component-driven (Text / Heading). Source: packages/html/src/css/utilities/_typography.css .dv\:break-anywhere .dv\:text-{left|center|right|justify|start|end} .dv\:truncate, .dv\:text-{ellipsis|clip}, .dv\:line-clamp-{1|2|3|4|5|6|none} .dv\:{uppercase|lowercase|capitalize|normal-case} .dv\:{italic|not-italic}, .dv\:{underline|line-through|no-underline} .dv\:font-{normal|medium|semibold|bold|extrabold} .dv\:font-{sans|serif|mono|display|editorial} .dv\:whitespace-{normal|nowrap|pre|pre-line|pre-wrap} .dv\:break-{normal|words|all|keep} .dv\:text-{wrap|nowrap|balance|pretty} .dv\:tracking-{tighter|tight|normal|wide|wider|widest} ### Z-Index Z-index stacking utilities — a numeric local-stacking scale plus the component-specific semantic layers. Source: packages/html/src/css/utilities/_z-index.css .dv\:z-{0|10|20|30|40|50|auto} .dv\:z-{dropdown|sticky|modal|tooltip|toast}

Section Title...

Another Section...

July 2026

Title

Page Title

Section Header

Card Title

Subsection

Small Heading

Serif Centered

Small on mobile, display on desktop

No items

Page Title

Titanium

Title

Title