` to present a short status message with a generated icon. Bare text and direct-child elements share the card's normal one-column flow, with space reserved at the logical inline start for the icon: ```html

Uploaded file could not be processed.

``` Supported variants are: - `info` for neutral information - `success` for a completed or successful action - `warning` for a condition that may require attention - `error` for a failed action or problem - `unavailable` for a feature or resource that cannot currently be used The base `data-variant` styling defaults to the informational treatment, but authors should use one of the supported values so the message's intent remains explicit. Keep alert messages concise. A plain paragraph is sufficient for a very short message. When a title helps people scan the message, use `hgroup` with one context-appropriate heading and one supporting paragraph. Use a card or dialog instead when content needs lists, multiple explanatory paragraphs, or a complex workflow. An alert may expose one or two actions in a `footer`. Prefer one primary action when possible; when there are two, make the recommended action primary and the other secondary. Actions remain inline when space permits and stack in narrow alert containers. To make an informational or non-blocking alert dismissible, load htmx in the consuming application and add a native icon button with an `hx-on:click` handler. Alerts about destructive actions or unresolved errors generally should not be dismissible. When dismissal represents a lasting choice, the application should remember it instead of showing the same alert again: ```html

Registration opens Monday

Review your academic plan now so you are ready to add classes.

``` If the consuming application's Content Security Policy applies nonce restrictions that block inline handlers, reconfigure the alert with a CSP-compatible dismissal implementation before using it. Alert articles preserve the card's normal one-column content flow. Logical inline-start padding reserves space for the absolutely positioned circular status icon, so content stacks and wraps without entering the icon area in either left-to-right or right-to-left layouts. The status icon and optional native dismiss button align to the alert's block start. The optional action footer is the only responsive layout region. Use this component when a short piece of content needs its own surface, separation, and clear boundary from surrounding layout. Avoid using alerts excessively. In many scenarios, other indicators can be used in place of an alert. Use a plain section, list item, or table row instead when the content is part of a continuous document flow, repeated structured data, or a layout that should stay visually flat. ## Behavior Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js). - CRD-001: The card should style native `

` and `

` elements directly rather than require a component class. - CRD-002: Padding, radius, spacing, and foreground/background colors should come from the shared layout and color tokens. - CRD-003: The shell should expose `--card-border-radius` and `--card-border-width` so its shape and boundary can be customized consistently; nested footer controls derive their inner corner radius from the shell values. - CRD-004: The component should accept normal flow content such as headings, paragraphs, lists, and button rows. - CRD-005: The first and last child margins should collapse cleanly against the card padding so authored content does not create uneven outer spacing. - CRD-006: Optional `header` and `footer` regions should lay out with shared spacing tokens instead of card-specific measurements, with footer content aligned to the end. - CRD-007: The component should work without JavaScript and without decorative helper elements inside the article. - CRD-008: Busy cards should retain their layout while direct child content is shown at `48%` opacity with a `4px` blur. - CRD-009: The generated loading indicator should remain sharp and centered over the dimmed content. - CRD-010: Busy-card children should ignore pointer interaction while the update is in progress. - CRD-011: Articles with `data-variant` should reserve logical inline-start padding for the absolutely positioned generated icon while retaining the card's normal one-column content flow. - CRD-012: Bare text and arbitrary direct-child alert content should stack and wrap within the reserved content area without entering the icon area in left-to-right or right-to-left layouts. - CRD-013: Dark-theme alerts should use the same inverse surface treatment as tooltips so they remain distinct from card and page backgrounds. - CRD-014: Alert icon size, symbol size, background, and foreground should be controlled through the alert custom properties and shared design tokens. - CRD-015: Images placed directly inside figure cards should cover their available dimensions full-bleed while captions and other figure content retain the card padding. - CRD-016: Direct card children should be allowed to shrink within the card so intrinsically wide content can manage its own overflow without widening or clipping the page layout. - CRD-017: Figure cards should allow descendant overlays to extend beyond the card boundary while full-bleed images preserve the card's rounded corners directly. - CRD-018: A dismissible alert should expose a native `.icon` button with a descriptive label and an htmx click handler. - CRD-019: The dismiss button should occupy the alert's block-start, inline-end control area, show a pointer cursor, and receive a visible focus ring when focused. - CRD-020: Alert dismissal should be expressed by the documented htmx click attribute rather than generated content or card-specific JavaScript; consuming applications must load htmx. - CRD-021: Native article and figure cards should retain their surface and subtle border while rendering without a shadow in light and dark themes, without requiring a variant class. - CRD-022: A card that introduces a navigation choice should use a descriptive heading and summary with a native button-styled link in its footer rather than a linked heading or clickable card surface. - CRD-023: A concise titled alert should group one context-appropriate heading and one supporting paragraph in `hgroup`, while a very short alert may use a plain paragraph. - CRD-024: An alert action region should use a direct-child `footer` containing no more than two actions and align those actions to the content start. - CRD-025: Alert footer actions should remain inline when space permits and stack when the alert container is narrower than `28rem`. ## Accessibility - Use `

` when the content is independently meaningful in the page outline or feed. - Use `

` when the card contains self-contained media, a diagram, a chart, a table, or code that benefits from a caption. - Provide a heading when the card content benefits from a clear accessible label. - Keep interactive controls inside the card keyboard reachable and descriptive on their own. - For card navigation, keep the heading as text and use a descriptive `` in the footer so link semantics and open-in-new-tab behavior remain available. - Use `aria-busy="true"` only while the card is being updated, and remove it when the update finishes. - Disable native controls individually when they must not be activated during loading; visual dimming and `pointer-events` alone do not prevent keyboard interaction. - Write alert text that communicates the status without relying on the generated icon or color. - Static alert content does not need a live-region role. When a message is inserted or updated dynamically and must be announced, use `role="status"` for non-urgent information or `role="alert"` for urgent problems. - Do not use `role="alert"` for non-urgent information, as this will interrupt accessibility APIs. - Do not include an additional decorative icon in alert markup; the visual icon is generated by CSS. - Use a native ` ``` Use this component when the user should complete or dismiss a focused task while keeping the surrounding page available. Use a modal dialog opened with `showModal()` instead when the surrounding page must become inert. Triggering a dialog from a separate button does not require JavaScript when the dialog is exposed as a popover. Use `popovertarget` on the trigger and `popovertargetaction="hide"` on dismissal controls. ## Behavior Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js). - DLG-001: The dialog surface should size within the viewport and center itself without requiring a wrapper. - DLG-002: The dialog shell exposes `--dialog-border-radius` and `--dialog-border-width` so its shape and edge definition can be customized consistently. - DLG-003: Open and close transitions should fade opacity while preserving a reduced-motion fallback. - DLG-004: The body layout should stack header, content, and actions with shared spacing tokens instead of one-off gaps or helper wrappers. - DLG-005: Action rows should align to the end and wrap cleanly when space is constrained. - DLG-006: The component should work with `popover` and `popovertarget` attributes so open and close actions can stay declarative. - DLG-007: The dialog shell should rely on semantic elements and scoped descendant selectors rather than component-specific class names. - DLG-008: Trigger buttons should open the dialog with `popovertargetaction="show"` when a popover interaction is needed. - DLG-009: The bordered dialog surface should remain visually flat without an elevation shadow. ## Accessibility - Provide an accessible name with `aria-labelledby` or `aria-label`. - Use a heading inside the dialog so the purpose is immediately clear. - Keep dismiss controls keyboard reachable and give icon-only buttons an accessible name. - Use native dialog behavior rather than replacing it with custom overlays or focus trapping logic unless product requirements exceed platform support. - Keep the body content concise enough that the modal surface remains scannable on smaller screens. ## Variables | Variable | Type | Description | | --- | --- | --- | | `--dialog-backdrop-color` | `` | Sets the modal backdrop overlay color; change it to make the page behind dialogs more or less visually suppressed. | | `--dialog-border-radius` | `` | Sets the outer dialog corner radius and feeds the inner radius calculation; change it to align dialogs with the product surface shape. | | `--dialog-border-width` | `` | Sets the dialog border width and inner-radius offset; change it when dialogs need stronger or subtler edge definition. | | `--dialog-color-accent-subtle` | `` | Sets --dialog-color-accent-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dialog-color-border-subtle` | `` | Sets --dialog-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dialog-color-text` | `` | Sets --dialog-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dialog-control-gap` | `` | Sets --dialog-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dialog-font-size` | `` | Sets --dialog-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dialog-max-inline-size` | `` | Sets the preferred maximum dialog width before viewport gutters are applied; change it for narrower confirmations or wider form dialogs. | | `--dialog-space-inline` | `` | Sets --dialog-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dialog-space-stack` | `` | Sets --dialog-space-stack so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dialog-transition-duration` | `` | Sets the open and close animation duration for the dialog and backdrop; change it when modal motion should feel faster or calmer. | ## Depends On - `--color-accent-strong` - `--color-accent-subtle` - `--color-border-subtle` - `--color-text` - `--font-size` - `--layout-control-gap` - `--layout-control-radius` - `--layout-space-inline` - `--layout-space-stack` - `--layout-surface-border-width` --- # Dropdown ## Overview The dropdown component presents a short list of actions or links through a native `

` disclosure that visually matches the select control. The component uses a scoped `.dropdown` class on `

` so it can style the trigger and menu without colliding with the global accordion treatment. ## When to use Use a dropdown to reveal a short, compact list of navigation links or in-place actions from one trigger. ## When not to use Do not use a dropdown for a submitted form value or primary navigation that should remain visible; use select or nav. ## Usage ```html ``` Use this component when the user needs to reveal a compact list of navigation targets or actions from a single trigger. The list can also contain labels with direct child checkbox or radio inputs when users need to make compact, browser-managed choices without JavaScript. Use `select` instead when the field is part of form submission and the browser should manage value selection, validation, and picker semantics. Keep the summary label short enough to read like a control label rather than a sentence. ## Behavior Covered by [Playwright behavior tests](../../tests/e2e/components.spec.js). - DRP-001: The closed trigger should align visually with the shared select control, including border, padding, focus ring, and downward chevron treatment. - DRP-002: The disclosure remains native `

` and `

` behavior, so keyboard interaction and open state management stay browser-driven. - DRP-003: The menu panel should stay scoped to `.dropdown` and should not restyle unrelated `details` disclosures. - DRP-004: The revealed list should accept simple anchor-only menu items without extra wrapper markup. - DRP-005: Menu item hover and focus surfaces should stay flush with the list while clipping to the panel's rounded border. - DRP-006: The indicator uses `--dropdown-icon-source` as a mask and `--dropdown-icon-color` as its theme-aware fill so consumers can customize its artwork and color independently. - DRP-007: Comfortable and compact density should both come from shared layout tokens. - DRP-008: A dropdown list item may contain a label with a direct child checkbox or radio, making the full padded row clickable while preserving native form behavior. - DRP-009: Choice rows should expose native checked, radio-group, focus, and disabled behavior without closing the disclosure automatically. - DRP-010: The chevron should remain centered at the trigger's configured inline offset, point down while closed, and rotate 180 degrees to point up while open. ## Accessibility - Use a native `

` as the visible trigger label. - Keep menu item text descriptive on its own because each link may be announced without surrounding context. - Use real links for navigation destinations and buttons only when the revealed items trigger in-place actions. - Use `select` or another true form control when the user is choosing a submitted value rather than opening a short action list. - Keep native checkbox and radio inputs visible, put each input inside its visible label, and use a shared `name` for related controls. ## Variables | Variable | Type | Description | | --- | --- | --- | | `--dropdown-color-accent-subtle` | `` | Sets --dropdown-color-accent-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-color-border-subtle` | `` | Sets --dropdown-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-color-focus-ring` | `` | Sets --dropdown-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-color-primary` | `` | Sets --dropdown-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-color-primary-subtle` | `` | Sets --dropdown-color-primary-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-color-text` | `` | Sets --dropdown-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-control-border-width` | `` | Sets --dropdown-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-control-gap` | `` | Sets --dropdown-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-control-min-height` | `` | Sets --dropdown-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-control-padding-block` | `` | Sets --dropdown-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-control-padding-inline` | `` | Sets --dropdown-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-control-radius` | `` | Sets --dropdown-control-radius so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-focus-ring-size` | `` | Sets --dropdown-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-font-size` | `` | Sets --dropdown-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-icon-color` | `` | Sets the dropdown chevron color; change it when the disclosure indicator needs a different semantic emphasis. | | `--dropdown-icon-offset` | `` | Sets the inline offset between the dropdown chevron and the control edge; change it when padding or icon alignment changes. | | `--dropdown-icon-size` | `` | Sets the chevron size in dropdown controls; change it when the icon should scale differently from the control text. | | `--dropdown-icon-source` | ` | none` | Sets the chevron mask used for dropdown controls; change it to swap the indicator artwork independently from its color. | | `--dropdown-line-height` | `` | Sets --dropdown-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--dropdown-panel-offset` | `` | Sets the gap between the trigger and dropdown panel; change it when the popover should sit tighter to or farther from the control. | ## Depends On - `--color-accent-subtle` - `--color-border-subtle` - `--color-focus-ring` - `--color-primary` - `--color-primary-subtle` - `--color-text` - `--color-text-accent` - `--font-line-height-body` - `--font-size` - `--layout-control-border-width` - `--layout-control-gap` - `--layout-control-icon-size` - `--layout-control-min-height` - `--layout-control-padding-block` - `--layout-control-padding-inline` - `--layout-control-radius` - `--layout-focus-ring-size` - `--layout-space-inline` --- # File ## Overview The file component is a native file picker that mirrors the input component's border, spacing, typography, and focus treatment while keeping the browser's built-in filename readout. The pattern uses a wrapping native `` and a native ``, with the chooser button styled through `::file-selector-button` and no component-specific classes. ## When to use Use a file input when users need to choose a local document, image, or other file for upload. ## When not to use Do not use a file input to collect a path, URL, or existing remote file, and do not treat its browser constraints as a replacement for server-side validation. ## Usage The wrapping label uses the file input's intrinsic inline size by default. Add `class="fluid"` to the label when the complete field should fill its container. ```html Attachment ``` Use this component when the user needs to upload a document, image, or other local file. Keep the native file input in the DOM so browser file selection, keyboard behavior, and form submission continue to work normally. Let the browser render the selected filename text. This component intentionally avoids JavaScript and does not replace the native file selection UI. Wrap the visible label text in a `[data-role="label"]` element so required fields can render the red asterisk immediately after the label text. For native validation, place a `[data-role="message"]` element directly after the input inside the same label and pair that with native constraints such as `required` or `accept`. This component follows the same classless authoring approach as the text input component and should not require a named wrapper class. ## Behavior Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js). - FIL-001: The chooser button should align with the shared outline button treatment so it feels consistent with the rest of the system, including the subtle brand hover surface. - FIL-002: File input color changes should transition smoothly, with reduced-motion preferences disabling the transition. - FIL-003: The overall control should use the same border, radius, padding, and focus treatment as the text input component. - FIL-004: The filename text comes from the browser's native file input rendering and may vary slightly by engine. - FIL-005: Validation feedback should appear only after user interaction by using `:user-invalid`. - FIL-006: Disabled file inputs should communicate their state through muted text and disabled surfaces. ## Accessibility - Keep the native `` focusable and available to assistive technology. - Use a visible label so the purpose of the upload control is always clear. - Do not hide or replace the browser's native filename feedback unless a documented accessible enhancement is required. - Provide clear helper or error text when accepted file types, size limits, or count limits need explanation. ## Variables | Variable | Type | Description | | --- | --- | --- | | `--file-action-padding-inline` | `` | Sets --file-action-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-border-color` | `` | Sets the file input wrapper border color; change it for validation states or when file controls need stronger container separation. | | `--file-color-border-subtle` | `` | Sets --file-color-border-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-color-error-strong` | `` | Sets --file-color-error-strong so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-color-focus-ring` | `` | Sets --file-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-color-primary` | `` | Sets --file-color-primary so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-color-text` | `` | Sets --file-color-text so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-color-text-accent` | `` | Sets --file-color-text-accent so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-color-text-subtle` | `` | Sets --file-color-text-subtle so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-control-border-width` | `` | Sets --file-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-control-gap` | `` | Sets --file-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-control-min-height` | `` | Sets --file-control-min-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-control-padding-block` | `` | Sets --file-control-padding-block so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-control-padding-inline` | `` | Sets --file-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-control-radius` | `` | Sets --file-control-radius so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-focus-ring-size` | `` | Sets --file-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-font-family-sans` | `Any` | Sets --file-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-font-size` | `` | Sets --file-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-font-size-caption` | `` | Sets --file-font-size-caption so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-line-height` | `` | Sets --file-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. | | `--file-message-color` | `` | Sets helper and validation message text color for file inputs; change it when status messaging should read as neutral, subtle, or error. | | `--file-space-inline` | `` | Sets --file-space-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. | ## Depends On - `--color-border-subtle` - `--color-error-strong` - `--color-focus-ring` - `--color-primary` - `--color-text` - `--color-text-accent` - `--color-text-subtle` - `--font-family-sans` - `--font-line-height-body` - `--font-size` - `--font-size-caption` - `--layout-action-padding-inline` - `--layout-control-border-width` - `--layout-control-gap` - `--layout-control-min-height` - `--layout-control-padding-block` - `--layout-control-padding-inline` - `--layout-control-radius` - `--layout-focus-ring-size` - `--layout-space-inline` --- # Footer ## Overview The footer component provides a page-level content info region for site ownership and closing legal or utility content. Like the header, the footer is built as a semantic contract around native HTML instead of a legacy class tree. For exact styles, use [footer.css](/Users/stuft2/Projects/design-tokens/src/css/footer.css) as the source of truth. ## When to use Use the footer once per page for BYU branding, ownership, legal metadata, and optional contact or structured secondary links. ## When not to use Do not use the footer for primary navigation, page-specific content, or the page's main actions. ## Usage Sticky-footer behavior is a page-shell concern, not a footer variant. The shared layout baseline now handles that automatically for the standard page contract: ```html

...

``` Minimal footer: ```html ``` Enhanced footer with site-info band and layout utilities: ```html ``` Use this component when a page needs a clear page footer with BYU branding and compact legal metadata. Add the optional site-info band when the footer also needs contact information or structured link groups. ## Variants Social media links belong in the optional theme-aware site-info band when a site needs a compact "follow us" section. Use semantic navigation and keep the accessible name on each icon-only link: ```html ``` ## Behavior Covered by [Playwright behavior tests](../../tests/e2e/data-branding-tokens.spec.js). - FTR-001: The component styles the last top-level `

Quarterly update

Review changes

Color Preview

Quarterly update