State System

Overview

Every interactive Byteion component supports a consistent set of states: default, hover, focus, active, disabled, loading, and error. These states apply across buttons, inputs, tables, modals, alerts, toasts, and async workflows. Consistent state handling makes SaaS dashboards, admin panels, ERP/POS screens, ecommerce back offices, internal tools, templates, starter kits, and plugins feel predictable and accessible.

Inconsistent states create confusing interfaces. If a button shows a loading spinner but a table does not show a loading skeleton, users cannot predict how the system communicates progress. This guide defines the Byteion state vocabulary and its implementation rules.

State model

Core interaction states

These states apply to every interactive component. They are primarily visual and rely on CSS pseudo-classes plus HTML attributes.

Supporting states

These states are contextual — they apply to specific component types or workflows.

Button state examples

Buttons use all core states. Loading must combine with disabled to prevent double submission. All examples use semantic tokens — no text-white, no bg-blue-500.

<!-- Default -->
<button type="button"
        class="inline-flex items-center justify-center gap-2 rounded-button bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow-button transition hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 active:scale-[0.98] disabled:pointer-events-none disabled:opacity-60">
  Save changes
</button>

<!-- Hover (applied via CSS pseudo-class) -->
<!-- Focus-visible (applied via CSS pseudo-class) -->
<!-- Active (applied via CSS pseudo-class) -->

<!-- Loading -->
<button type="button" disabled
        class="inline-flex items-center justify-center gap-2 rounded-button bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow-button opacity-60 cursor-not-allowed">
  <svg class="h-4 w-4 animate-spin" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
    <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" />
    <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
  </svg>
  Saving…
</button>

<!-- Disabled -->
<button type="button" disabled
        class="inline-flex items-center justify-center gap-2 rounded-button bg-primary px-4 py-2 text-sm font-medium text-primary-foreground opacity-60 cursor-not-allowed">
  Save changes
</button>

<!-- Destructive loading -->
<button type="button" disabled
        class="inline-flex items-center justify-center gap-2 rounded-button bg-danger px-4 py-2 text-sm font-medium text-danger-foreground opacity-60 cursor-not-allowed">
  <svg class="h-4 w-4 animate-spin" viewBox="0 0 24 24" fill="none" aria-hidden="true">
    <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" />
    <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
  </svg>
  Deleting…
</button>

Input error example

Production-ready error state with accessible attributes. The error message is linked via aria-describedby and uses text-danger. The input uses aria-invalid="true" and border-danger.

<div class="space-y-1.5">
  <label for="email" class="block text-sm font-medium text-foreground">
    Email address
  </label>
  <input id="email"
         type="email"
         value="invalid-email"
         aria-invalid="true"
         aria-describedby="email-error"
         class="w-full rounded-input border border-danger bg-background px-3 py-2 text-sm text-foreground outline-none placeholder:text-muted-foreground focus:border-danger focus:ring-2 focus:ring-danger/20">
  <p id="email-error" class="flex items-center gap-1 text-sm text-danger" role="alert">
    <i class="ti ti-alert-circle text-xs" aria-hidden="true"></i>
    Please enter a valid email address.
  </p>
</div>

Accessibility rules

• Never remove focus rings without a focus-visible replacement. Removing outline: none without adding focus-visible:ring-* makes the page unusable for keyboard users.
• Use native disabled attribute where possible (buttons, inputs, selects). It prevents interaction at the browser level and is announced by screen readers.
• Use aria-disabled="true" only when the element cannot be disabled natively (links, custom widgets).
• Use aria-invalid="true" and aria-describedby for form errors so screen readers announce the error.
• Use aria-busy="true" on regions that are updating asynchronously (tables, panels) when a visible loading indicator is present.
• Use role="alert" or aria-live="polite" for async success and error messages that appear without user focus.
• Do not communicate state with colour only — always include a text label, icon, or ARIA attribute alongside colour cues.

Async state rules

• Loading buttons must prevent double submission. Combine disabled with a spinner and action-specific text ("Saving…", "Uploading…", "Deleting…").
• Loading state should preserve layout — do not shrink or move elements when switching to loading. Use skeleton placeholders for content areas.
• Use action-specific loading text so users know what operation is in progress. Generic "Loading…" is less informative than "Saving changes…".
• Tables should use skeleton rows or an empty/loading state while data is being fetched. Avoid showing a blank white rectangle.
• Errors should provide recovery actions — a "Retry" button, a "Go back" link, or a dismiss action — not just red text.

Practical scenarios

Form submission flow

Default (inputs + submit button) → Focus (user tabs into input, focus-visible:ring) → Input error (aria-invalid + border-danger + error message) → Loading (button spinner + disabled) → Success (Toast with check icon) or Server error (Alert with recovery action).

Table loading and empty state

Default (populated rows) → Loading (skeleton rows matching table layout, aria-busy="true" on table region) → Empty (centered illustration + "No records found" message) → Error (Alert banner above table: "Failed to load data — Retry").

Modal save flow

Default (form fields + Save button) → Dirty (indicator when form changes) → Loading (Save button shows spinner + "Saving…" + disabled; modal should not close until API responds) → Success (modal closes, Toast confirms save) → Error (inline error in modal body, Save button re-enabled).

Destructive delete confirmation

Default (Cancel + Delete buttons) → Loading (Delete button: bg-danger spinner + "Deleting…" + disabled) → Success (modal closes, Toast confirms deletion, row removed from table) → Error (Toast or Alert: "Failed to delete — Retry").

Ecommerce product update flow

Default (product form + Save button) → Loading (Save shows "Saving product…", all form inputs disabled) → Validation error (inline on specific fields with border-danger + aria-describedby) → Success (Toast: "Product updated") → Server error (Alert in form: "Could not save — network error").

ERP / POS transaction submit flow

Default (order summary + Submit button) → Loading (Submit: "Processing payment…" + disabled; spinner on payment icon) → Success (receipt modal or Toast: "Payment approved") → Error (Alert: "Transaction declined — Try again" or "Retry with different card").

Do and Don't

Developer tips

Related

• Design Principles — the philosophy behind Byteion tokens and components
• Accessibility — ARIA, keyboard navigation, and screen reader support
• Button — button states and variants
• Input — input states, validation, and error patterns
• Form Field — form-level validation and submission states
• Alert — success, warning, error, info banners
• Toast — transient success and error notifications
• Table — loading skeleton, empty state, error state
• Modal — save, loading, and error states in dialogs
• Theming Guide — customising tokens and dark mode contrast