Alloy CSS: CSS Framework with Native HTML Components

Category: CSS & CSS3 , Frameworks , Recommended | November 20, 2026
Authoralloyhtml
Last UpdateNovember 20, 2026
LicenseMIT
Views0 views
Alloy CSS: CSS Framework with Native HTML Components

Alloy CSS is a CSS framework for server-rendered websites that includes responsive utility classes, form styles, and interactive UI components.

Features

  • Scroll-snap carousels and hover/focus tooltips.
  • Radio-based tabs, <details> accordions, and checkbox toggles.
  • Styled form fields, buttons, mobile tables, and loading skeletons.
  • Utilities for flex layouts, spacing, sizing, typography, and colors.
  • Dark and Midnight themes with customizable colors and fonts.
  • A CLI checker that reports undefined classes in templates.

How To Use It

Installation

Add the stylesheet to your page’s <head>:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@alloyhtml/css@1/dist/alloy.min.css">

For an npm project, install @alloyhtml/css:

npm install @alloyhtml/css

Alloy applies a global reset and styles the body, headings, and links. Check for conflicts with existing .button, .field, .dialog, .flex, .tab, and .tooltip styles before adding it to an established site.

Basic Usage: Open a Modal Dialog

<main class="container-960 padding-y-40">
  <div class="bg-raised border border-subtle rounded-8 padding-24">
    <h2 class="h4 text-primary margin-bottom-12">Your account</h2>
    <p class="text-body-2 text-secondary margin-bottom-20">Check your current notification preferences.</p>
    <button type="button" commandfor="settings-dialog" command="show-modal"
      class="button bg-primary-1 border-primary-1 text-white hover-bg-primary-2 padding-x-16">
      View account details
    </button>
  </div>
</main>
<dialog id="settings-dialog" closedby="any"
  class="dialog bg-raised rounded-8 padding-24 width-50 width-100-sm">
  <h2 class="h5 text-primary margin-bottom-12">Account details</h2>
  <p class="text-body-2 text-secondary margin-bottom-20">Email updates are enabled for this account.</p>
  <button type="button" commandfor="settings-dialog" command="close"
    class="button bg-surface border-subtle text-primary padding-x-16">Close</button>
</dialog>

Create a Dropdown Menu

<button type="button" popovertarget="account-menu"
  class="button bg-raised border-subtle text-primary padding-x-16">
  Account
</button>
<nav id="account-menu" popover
  class="menu bg-raised border border-subtle rounded-8 shadow-3 padding-8"
  aria-label="Account menu">
  <a class="a a-color-reset block padding-x-12 padding-y-8 text-primary hover-bg-surface" href="/profile">Profile</a>
  <a class="a a-color-reset block padding-x-12 padding-y-8 text-primary hover-bg-surface" href="/settings">Settings</a>
</nav>

Create Tabs With Radio Inputs

Place radio inputs inside .tab labels, followed by a matching .panel for each tab.

<div class="tabs">
  <div class="flex flex-gap-24 border-bottom border-subtle">
    <label class="tab padding-y-8 text-body-2 font-weight-600">
      <input type="radio" name="product-info" checked>Details
    </label>
    <label class="tab padding-y-8 text-body-2 font-weight-600">
      <input type="radio" name="product-info">Shipping
    </label>
  </div>
  <div class="panel padding-y-16 text-body-2 text-secondary">
    Handcrafted ceramic mug with a matte glaze.
  </div>
  <div class="panel padding-y-16 text-body-2 text-secondary">
    Dispatches within two business days.
  </div>
</div>

Show a Toast After an Application Event

For an application event such as a successful save, call showPopover() from your event handler.

<button type="button" popovertarget="save-toast"
  class="button bg-primary-1 border-primary-1 text-white padding-x-16">
  Show notification
</button>
<div id="save-toast" popover="manual" role="status"
  class="toast flex flex-items-center flex-gap-12 bg-inverse text-inverse rounded-8 shadow-3 padding-16">
  <span class="text-body-2 grow-1">Settings saved.</span>
  <button type="button" popovertarget="save-toast" popovertargetaction="hide"
    class="button bg-transparent border-transparent text-inverse padding-4">Dismiss</button>
</div>
// Run after the save succeeds.
document.getElementById('save-toast').showPopover();

Customize the Brand and Dark Theme

Load a brand stylesheet after Alloy’s CSS to set the primary colors, fonts, and control radius.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@alloyhtml/css@1/dist/alloy.min.css">
<link rel="stylesheet" href="/my-brand.css">
/* my-brand.css */
-root {
  --brand-primary-1: hsl(158, 80%, 29%);
  --brand-primary-2: hsl(158, 82%, 25%);
  --brand-primary-3: hsl(158, 85%, 21%);
  --font-family-base: system-ui, sans-serif;
  --font-family-heading: system-ui, sans-serif;
  --control-radius: 8px;
}

For dark mode based on the visitor’s system preference, add the Dark theme after the base stylesheet:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@alloyhtml/css@1/dist/themes/dark.min.css"
  media="(prefers-color-scheme: dark)">

To use Midnight at all times, use this link instead:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@alloyhtml/css@1/dist/themes/midnight.min.css">

Check Classes in Your Templates

The package’s CLI finds undefined class names in HTML and server-rendered templates. It reports the filename and line number, and exits with an error when it finds a match.

npx @alloyhtml/css check templates/

Pass --css styles/site.css for your own classes, or --allow icon-name for a class supplied by another library.

For AI-assisted page generation, Alloy also provides an agent skill containing its markup rules and class reference:

npx @alloyhtml/css skill

Component and HTML Reference

ComponentClasses and HTML contract
Modal dialog<dialog> with .dialog; commandfor="id" and command="show-modal" or command="close" on buttons; closedby="any" for outside-click dismissal where supported.
Responsive drawerpopover, popovertarget, .drawer, and optional .drawer-end; .hidden-md-greater for the mobile-only trigger. Customize width with --drawer-width.
Dropdown menupopover, popovertarget, .menu, and optional .menu-end for right-aligned menus.
Header dropdown<details> and <summary> with .show-when-closed and .show-when-open for state-specific icons.
Accordion<details> and <summary>; shared name groups exclusive rows, open selects an initial row, .rotate-when-open rotates an indicator.
Carousel.flex, .flex-nowrap, .overflow-x-auto, and .scroll-snap-x on the container; .shrink-0 and .snap-start on slides.
Tabs.tabs wrapper, .tab labels containing same-name radio inputs, and ordered .panel elements; maximum 12 tabs per set.
Toggle.toggle with a checkbox; .show-when-off and .show-when-on for alternate content. Toggles cannot be nested.
Choice buttons.choice labels containing radio inputs sharing a name; --choice-picked adjusts the selected border.
Toastpopover="manual", .toast, and role="status"; popovertargetaction="hide" closes it. The browser’s showPopover() / hidePopover() methods support application-driven messages.
Tooltip.tooltip on an accessible control and .tip on its text; .tooltip-up and .tooltip-end adjust placement.
Copy controldata-copy="#id", data-copy-idle, and data-copy-done provide the markup pattern. You must add a Clipboard API handler to perform the actual copy.

Layout, Sizing, and Spacing Classes

Responsive suffixes apply at a maximum viewport width: -lg (1200px), -md (992px), -sm (768px), and -xs (576px). Write the desktop class first, followed by the overrides for smaller screens.

Responsive variants apply to the supported layout, sizing, spacing, display, flex, and typography families. Colors, borders, shadows, and animations keep the same values at every width.

Class or familyPurpose and available values
.container-1320, .container-960Centered fluid containers with 1320px or 960px maximum widths and 24px horizontal padding.
.flex, .inline-flex, .flex-row, .flex-columnFlex containers and directions; also -reverse directions and .flex-wrap / .flex-nowrap.
.flex-justify-*, .flex-items-*, .flex-content-*Justification: start, end, center, between, around; item alignment: start, end, center, baseline, stretch; wrapped-content alignment adds stretch.
.flex-gap-{n}, .flex-gap-x-{n}, .flex-gap-y-{n}Flex gaps using 0, 4, 8, 12, 16, 20, 24, 32, or 40px.
.flex-gutter-{n}, .flex-gutter-x-{n}, .flex-gutter-y-{n}Column gutters in the same values as gaps.
.grow-0, .grow-1, .shrink-0, .shrink-1, .fill, .equalFlex growth, shrinking, fill, and equal-width items.
.align-*, .order-*Self-alignment: auto, start, center, end, baseline, stretch; order from .order-min-1 to .order-5.
.block, .inline, .inline-blockDisplay utilities.
.static, .relative, .absolute, .fixed, .stickyPositioning modes.
.top-*, .right-*, .bottom-*, .left-*Edge offsets of 0, 100, or auto; .center-x, .center-y, .center for centering positioned children.
.z-n2, .z-n1, .z-0 through .z-5, .z-max, .z-unsetStacking order.
.hidden, .hidden-{breakpoint}, .hidden-{breakpoint}-greaterHide globally, below a breakpoint, or above a breakpoint; also .hidden-print, .hidden-screen, .visually-hidden.
.overflow-*, .overflow-x-*, .overflow-y-*auto, visible, or hidden; also .overflow-scroll-hidden, .overflow-overlay, and .scrollbar-thin. Overlay scrollbar support is partial.
.size-{n}pxSquare dimensions: 8, 12, 16, 20, 24, 28, 32, 36, 40, 48, 56, 64, or 80px. .height-24px is also available.
.width-{n}, .height-100Percentage widths: 0, 10, 20, 25, 30, 40, 50, 60, 70, 75, 80, 90, 100; full parent height.
.width-1-3, .width-2-3, .width-1-6, .width-1-12Fractional widths; also .width-100v, .height-100v, .width-auto, .height-auto.
.min-width-0, .max-width-100, .min-height-0, .max-height-100Min/max-size helpers.
.margin-{n}, .padding-{n}, .margin-{side}-{n}, .padding-{side}-{n}Spacing values: 0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 60, 80, 100, 120, 140px. Sides include x, y, top, right, bottom, left.
.margin-auto, .margin-x-auto, .margin-y-auto, .margin-{side}-autoAutomatic margins; negative helpers include .margin-right-n8, .margin-top-n20, and .margin-x-n24 / .margin-x-n24-sm.
.rounded-{n}, .circleRadius 0, 4, 8, 12, 16, 20px; top/bottom/left/right and individual-corner variants. Only .rounded-0 has responsive variants.

Color, Typography, and State Classes

Color utilities use .bg-*, .text-*, and .border-*. For semantic styling, use bg-base, bg-surface, bg-raised, bg-sunken, bg-inverse; text-primary, text-secondary, text-muted, text-inverse; and border-subtle, border-strong. The primary-* palette follows your brand tokens.

Fixed palettes include violet, amber, red, magenta, blue, cyan, green, and orange, plus neutral light, gray, dark, white, black, and transparent.

Palette color steps are 1 to 3, with -light-1 to -light-3 and -dark-1 to -dark-3 for supported hues.

Class or familyPurpose and available values
.hover-bg-*, .active-bg-*, .hover-text-*, .active-text-*, .hover-border-*, .active-border-*Interaction states for supported semantic, brand, and neutral colors.
.border, .border-none, .border-x, .border-y, .border-{side}Border application; .border-width-2, -3, -4, .border-current.
.shadow-none, .shadow-1 to .shadow-4Elevation; .hover-shadow-1 to -4 and .active-shadow-1 to -4.
.has-bg-img, .bg-img, .bg-img-repeat, .bg-img-fixedBackground-image wrappers and scrolling behavior.
.h1 through .h6Heading sizes: 40/48, 32/42, 28/36, 24/34, 20/28, 18/28px (font size/line height). Headings also receive these styles as native HTML elements.
.text-body-1, .text-body-2, .text-body-3, .text-body-4Body sizes: 16/24, 14/20, 12/16, and 10/16px (font size/line height).
.text-left, .text-center, .text-right, .text-justifyText alignment.
.text-uppercase, .text-lowercase, .text-capitalizeText case.
.text-line-none, .text-strike, .text-underline, .text-underline-primaryText decoration.
.text-wrap, .text-nowrap, .text-ellipsis, .text-ellipsis-2, .text-ellipsis-3Wrapping and truncation.
.font-weight-100 through .font-weight-800, .font-weight-normal, .font-weight-boldFont weight.
.font-style-italic, .font-style-normal, .font-family-serifFont style and serif face.
.line-height-1, .letter-spacing-1, .letter-spacing-2Line height and letter spacing.
.cursor-pointer, .cursor-default, .cursor-progress, .cursor-not-allowedCursor variants.
.a, .a-color-reset, .ul-square, .ul-unstyledLink styling and list markers.
.icon-{n}, .material-iconsIcon sizes 12, 16, 20, 24, 32, 48px; supply an icon font separately.
.show-on-parent-hover, .show-on-parent-focusReveal children based on parent hover or focus.
.fullscreen-on-focus-sm, .close-fullscreenExpand focused search controls on small screens; spacing uses --fullscreen-padding.
.opacity-0, .opacity-005, .opacity-02, .opacity-04, .opacity-06, .opacity-08, .opacity-1Opacity values 0, .05, .2, .4, .6, .8, and 1.
.animate-fade-in, .animate-fade-in-up, .animate-fade-in-down, .animate-fade-in-left, .animate-fade-in-rightFade and directional fade entrances.
.animate-slide-in-up, .animate-slide-in-down, .animate-slide-in-left, .animate-slide-in-right, .animate-zoom-inSliding and zoom entrances.
.animate-repeat-1 to -3, .animate-delay-1s to -3s, .animate-speed-*Repetition, start delays, and animation duration (0.2s to 3s).
.skeleton, .skeleton-whole, .no-skeletonLoading placeholders, whole-block skeletons, and exclusions.

Forms, Buttons, and Tables

Class or attributeBehavior
.field, .field-sm, .field-lgStyled inputs, selects, and textareas. Heights are 40/32/48px with a mouse and 48/40/56px with touch, respectively.
.field-bare, .float-labelBare field styling within a custom wrapper, and floating labels. Floating fields need placeholder=" " and an adjacent label.
aria-invalid="true", .error-messageInvalid field appearance and associated error message; use aria-describedby to connect them.
.check-stroke, .check-fill, .radio-stroke, .radio-fillStyled native checkbox and radio labels, each containing an input and an <i> indicator.
.switchNative checkbox rendered as a switch.
.button, .button-sm, .button-lgMatching default, small, and large button heights. Pair with color utilities for filled or outlined variants.
.table, .table-compact, .table-border-none, .table-bordered, .table-striped, .table-hoveredTable layout, density, borders, striping, and hover state.
.th-shrinkKeep a header column near its content width.
.table-stack-sm, .expand-row, data-labelMobile stacked-table cards and expandable rows.

Theme and Component CSS Variables

TokenPurpose
--brand-primary-1, --brand-primary-2, --brand-primary-3Base, hover, and pressed brand shades.
--brand-primary-light-1 through -3Brand tints for light backgrounds.
--brand-primary-dark-1 through -3Brand text colors on light tints.
--brand-dark-primary-1 through -3, --brand-dark-on-primaryBrand colors and contrast text for dark themes.
--color-bg-base, --color-bg-surface, --color-bg-raised, --color-bg-sunken, --color-bg-inverseTheme background surfaces.
--color-text-primary, --color-text-secondary, --color-text-muted, --color-text-inverseTheme text colors.
--color-border-subtle, --color-border-strongTheme border colors.
--color-link, --color-link-hover, --color-focus-ring, --color-on-primaryLink, focus, and text-on-brand colors.
--font-family-base, --font-family-heading, --font-family-serifBase, heading, and serif typefaces.
--control-radiusForm-control and button corner radius.
--drawer-width, --choice-pickedDrawer width and selected choice outline.
--fullscreen-padding, --shell-topFocused mobile search padding and sticky-header offset in app layouts.
--skeleton-colorPlaceholder color.

Alternatives and Related Resources

You Might Be Interested In:


Leave a Reply