---
name: byu-application-components
description: Create or extend application-owned semantic UI components using the BYU OIT design system's documented markup, tokens, component variables, and behaviors. Use for product-specific components in an application; do not use for changes to the shared design-system repository.
metadata:
  short-description: Build semantic BYU application components
---

# BYU Application Components

## Overview

Create product-specific semantic components by composing and extending the BYU OIT design system through its documented public contracts.

Build application-owned components by composing the BYU OIT design system's public contracts. Preserve the application's framework, rendering approach, file organization, naming conventions, and test tools.

## Start With The Supported Contract

- Confirm which design-system version and stylesheets the application loads. Read the distributed `llms.txt` and the documentation for every component or token involved.
- Inspect the application's existing components and conventions before choosing markup, file locations, or APIs.
- Start with the smallest semantic HTML structure that represents the content or action. Prefer native elements and browser behavior; use JavaScript only for behavior that HTML and CSS cannot provide.
- Compose documented elements, classes, attributes, and states. Do not depend on undocumented DOM structure, generated content, internal selectors, or source-file ordering.

## Decide Whether To Compose Or Extend

Compose existing design-system components when their documented contracts already express the required semantics and behavior. An application component may give that composition a domain-specific name and stable application API.

Extend an existing component only through its documented markup, attributes, classes, and CSS custom properties. Scope application-owned selectors to the semantic component root, and prefer setting documented component variables over restating design-system declarations.

Create a new application-owned semantic component when the product has a recurring domain concept or interaction that the design system does not model. Keep it local when its meaning, content, or behavior is specific to the application. If the need is broadly reusable across products or requires an undocumented design-system hook, record that as a candidate upstream change instead of coupling the application to design-system internals.

## Markup, Styling, And States

- Give the root an application-specific class or other stable local hook when scope is needed; do not add classes solely to reproduce styles already supplied by semantic elements.
- Avoid decorative wrappers and fragile selectors based on DOM depth. Name hooks for component roles or domain meaning rather than appearance.
- Reuse shared semantic tokens for application-owned styling. Use layout-theme tokens for density-sensitive spacing, gaps, radii, and control sizes so comfortable and compact contexts continue to work.
- Expose application-level custom properties only for intentional, reusable variation. Default them from design-system semantic tokens or documented component variables, then consume the application variables in rendered declarations.
- Cover every applicable state, including hover, focus-visible, active or selected, disabled, invalid, busy, empty, error, and reduced motion. Use native attributes and appropriate ARIA or `data-*` state hooks rather than visual-only classes.
- Keep icons decorative when visible text already names the action. Give icon-only controls an accessible name, and let icons inherit text color unless the application component owns a meaningful documented treatment.

## Behavior And Accessibility

Define the component's contract before adding behavior: valid structure, variants, states, keyboard interaction, focus movement, announcements, and no-JavaScript fallback. Preserve native semantics, labels, names, form behavior, and landmark structure.

Add JavaScript as progressive enhancement and keep state in native attributes where possible. Do not recreate native controls with generic elements. When a composite widget genuinely needs custom keyboard behavior, follow the relevant accessible interaction pattern and test it with the application's supported input methods.

Document the component beside the application code using the repository's established format. Include a minimal realistic example, supported variants and states, accessibility requirements, and any application-level custom properties. Do not copy the design system's full documentation into the application; link or refer to the upstream contract and document only the composition and local decisions.

## Validate In The Application

Use the application's existing verification tools. At minimum, verify:

- semantic structure and accessible names;
- keyboard operation and visible focus;
- meaningful behavior and state transitions;
- light and dark themes when supported;
- comfortable and compact layout themes when the component uses density-sensitive values;
- narrow, wide, zoomed, and long-content layouts relevant to the component;
- no-JavaScript behavior when enhancement is optional; and
- focused regression tests for the application-owned contract.

Before finishing, confirm that the implementation uses only documented design-system contracts, remains locally scoped, and has not silently changed the shared component's semantics or behavior.