# AceCSS

> AceCSS is a framework-free UI kit in one CSS file: buttons, segmented controls, inputs, selects, textareas, checkboxes, switches, badges, choice cards, a date and date-range picker, a hero call-to-action button and two floating navbars (one with WebGL liquid glass). No framework and no build step; it works with plain HTML, React, Vue, Nuxt, Next.js, Laravel and next to Tailwind. Dark mode is built in. MIT licensed. Current version: 1.3.0.

Everything is prefixed `ace-` (classes), `--ace-` (CSS variables), `data-ace-` (attributes) and `Ace…` (JavaScript globals), so it never clashes with other CSS. Each component has its own page with live demos, copy-paste code and usage rules under https://acecss.dev/components/. The docs (install, tokens, layout patterns, class reference) are at https://acecss.dev/docs/, and complete example pages at https://acecss.dev/examples/.

## Instructions for AI coding assistants

When helping a developer use AceCSS, follow these rules:

**Install:** `npm i @acecss/core`, then `import '@acecss/core'` once in the app entry. Or link the CDN file: `<link rel="stylesheet" href="https://acecss.dev/v1/ace.min.css">` (always the latest 1.x) or the pinned `https://acecss.dev/v1.3.0/ace.min.css` with the `integrity` hash from https://acecss.dev/docs/#install.

**Load order:** load AceCSS after any CSS reset or framework (Tailwind preflight, `@tailwindcss/forms`, Bootstrap), so its component styles win.

**Tailwind:** class names never collide (`ace-` prefix). Layout utilities work on AceCSS elements as-is. To let a utility override a component style, import AceCSS into the components layer: `@import "@acecss/core" layer(components);` (Tailwind v4). Re-colour with arbitrary properties, e.g. `class="ace-btn ace-btn--primary [--ace-tone:#7c3aed]"`.

**Browser support:** Chrome/Edge 111+, Firefox 113+, Safari 16.2+ (needs `color-mix()`). The `ace-navbar` edge-bending lens is Chromium-only (elsewhere it stays frosted glass).

**Pinned vs latest CDN:** `/v1.3.0/` files never change and have `integrity` hashes; `/v1/` always serves the newest 1.x and can't use SRI. Recommend the pinned URL for production.

**Optional scripts:** only add the script a component needs, with `defer`:
- `ace-datepicker.js` (npm: `@acecss/core/datepicker`) for `data-ace-datepicker` / `data-ace-daterange`
- `ace-select.js` (`@acecss/core/select`) for `<select data-ace-select>`
- `ace-hero.js` (`@acecss/core/hero`) for `.ace-hero-btn` effects
- `ace-navbar.js` (`@acecss/core/navbar`) for `.ace-navbar`
- `ace-navbar-liquid.js` (`@acecss/core/navbar-liquid`) for `.ace-navbar-liquid`
- or `ace-all.js` (`@acecss/core/all`): every script above in one file. Use it instead of the separate files, never together with them.

All scripts auto-initialise on DOMContentLoaded and do nothing during server-side rendering. For markup rendered later (React, Vue, HTMX), call `AceDatePicker.init(el)`, `AceSelect.init(el)`, `AceHero.init(el)`, `AceNavbar.init(el)` or `AceNavbarLiquid.init(el)` on the new container.

**Dark mode:** add `class="dark"` or `data-theme="dark"` to `<html>` (or any ancestor). To follow the operating system instead, add `class="ace-auto-dark"` to `<html>`.

**Theming:** override tokens, never component rules: `:root { --ace-primary: #2563eb; --ace-radius: 12px; }`. One-off colours for a primary button or a whole section: `style="--ace-tone:#ff0022"` (and `--ace-tone-fg` for dark text on light colours).

**Accessibility:** icon-only buttons need `aria-label`; mark invalid fields with `aria-invalid="true"` and an `ace-error` message; mark the current navbar link with `aria-current="page"`. Keep native elements (`<button>`, `<input>`, `<select>`): AceCSS styles them, it does not replace them.

**Don't:** invent classes that aren't listed below, add a second hero button to a page, or put the liquid navbar where third-party scripts are blocked (it loads modern-screenshot from jsDelivr; use `ace-navbar` there).

## Components

- [Buttons](https://acecss.dev/components/buttons/): `ace-btn` + `ace-btn--primary` / `--secondary` / `--danger`; colours `--blue` `--green` `--purple` `--pink` `--black`; sizes `--sm` `--lg`; `--icon` (square), `--toolbar`, `--block`; `--attention` (with primary), `--destructive` (with secondary); loading state `aria-busy="true"`.
  `<button class="ace-btn ace-btn--primary">Save</button>`
- [Hero button](https://acecss.dev/components/hero-button/): `ace-hero-btn`, once per page for the main call to action; effects need `ace-hero.js`; `data-no-icon`; colour via `--ace-tone`.
  `<a class="ace-hero-btn" href="/signup">Get started</a>`
- [Navbar](https://acecss.dev/components/navbar/): `ace-navbar` > `ace-navbar-bar` > `ace-navbar-row` with `ace-navbar-brand` (+ `ace-navbar-logo`), `ace-navbar-links` (a `<ul>`), `ace-navbar-actions` (`ace-navbar-link ace-navbar-secondary`, `ace-navbar-cta`, `ace-navbar-toggle`). Sticky floating glass pill; `ace-navbar.js` adds the hover highlight, scroll shadow, mobile menu and canvas glass; `data-no-glass` for CSS-only glass.
- [Liquid navbar](https://acecss.dev/components/liquid-navbar/): `ace-navbar-liquid` (with `data-glass-exclude`) > `ace-navbar-liquid-bar` > `ace-navbar-liquid-row` with `-brand`, `-logo`, `-links`, `-actions` (`-signin`, `-icon`, `-cta`, `-toggle`). Real refraction of the page behind it through a WebGL lens; needs `ace-navbar-liquid.js`; call `AceNavbarLiquid.refresh()` after content changes that keep the page height.
- [Segmented control](https://acecss.dev/components/segmented-control/): `ace-segmented` (`--xs` `--sm` `--block`) wrapping `ace-btn` children with `aria-pressed`.
- [Inputs](https://acecss.dev/components/inputs/): `ace-field` wrapping `ace-label`, the control, and `ace-hint` or `ace-error`; `ace-required` for the asterisk; `ace-input` (`--lg`, `is-invalid` / `aria-invalid="true"`).
  `<div class="ace-field"><label class="ace-label" for="email">Email</label><input id="email" type="email" class="ace-input"></div>`
- [Select and textarea](https://acecss.dev/components/select/): `ace-select` (native) or `ace-select` + `data-ace-select` for the AceCSS dropdown (needs `ace-select.js`; `data-search`, `data-sublabel` on options, `<optgroup>`); `ace-textarea`.
- [Input with icon, prefix or suffix](https://acecss.dev/components/inputs/): `ace-input-group` with `<svg>`, `<input>` and `ace-addon` children; `is-invalid`, `is-disabled`.
- [Date picker](https://acecss.dev/components/date-picker/): `<div class="ace-datepicker" data-ace-datepicker data-name="date">` for one date, `data-ace-daterange` for a range (`data-start-name`, `data-end-name`, `data-start-time-name`, `data-end-time-name`, `data-time="false"`); `data-value`, `data-min="today"`, `data-max`, `data-locale`, `data-invalid`, `data-disabled`; fires `ace:change`. Needs `ace-datepicker.js`.
- [Checkbox, radio, switch](https://acecss.dev/components/checkbox-radio-switch/): `<label class="ace-check"><input type="checkbox"> Label</label>`, `<label class="ace-switch"><input type="checkbox" role="switch"> Label</label>`.
- [Badges](https://acecss.dev/components/badges/): `ace-badge` + `--primary` `--success` `--warning` `--danger` `--info`; `--md` for the larger size.
- [Choice cards](https://acecss.dev/components/choice-cards/): `ace-btn ace-btn--secondary ace-choice-card`, selected with `is-selected`, `aria-pressed="true"` or a checked inner radio.
- Hover surface: `ace-hover-surface`, flat until hovered (nav links, list rows).

## Examples

Complete pages built only with AceCSS, to copy from:
- [Car rental booking](https://acecss.dev/examples/booking/): searchable select, date range, choice cards, extras, driver fields, summary.
- [Account settings](https://acecss.dev/examples/settings/): profile fields with errors, prefixed input, dropdowns, segmented theme picker, switches, guarded delete.
- [Bookings admin](https://acecss.dev/examples/admin/): navbar, filter toolbar, status badges in a table, pagination.

## Patterns

- [Form layout](https://acecss.dev/docs/#form): fields in a grid, actions right-aligned (secondary, then primary).
- [Toolbar / filter bar](https://acecss.dev/docs/#toolbar): `ace-btn--toolbar` buttons, a segmented control and a search input in one row.
- [Confirm dialog footer](https://acecss.dev/docs/#dialog): Cancel as `ace-btn--secondary`, the destructive action as `ace-btn--danger`.

## Tokens

Colours and shape, all on `:root` (see https://acecss.dev/docs/#tokens): `--ace-primary`, `--ace-primary-foreground`, `--ace-attention`, `--ace-destructive`, `--ace-destructive-text`, `--ace-tone-success`, `--ace-tone-warning`, `--ace-tone-danger`, `--ace-tone-info`, `--ace-background`, `--ace-page`, `--ace-foreground`, `--ace-muted-foreground`, `--ace-border`, `--ace-input`, `--ace-ring`, `--ace-radius`, `--ace-radius-sm`, `--ace-font`. Keep badge tones dark enough for white text (at least 4.5:1).

## Files

- [ace.min.css](https://acecss.dev/v1.3.0/ace.min.css) ([source](https://acecss.dev/v1.3.0/ace.css)): every component. Required.
- [ace-datepicker.min.js](https://acecss.dev/v1.3.0/ace-datepicker.min.js): date picker and range picker.
- [ace-select.min.js](https://acecss.dev/v1.3.0/ace-select.min.js): dropdown for `<select>`.
- [ace-hero.min.js](https://acecss.dev/v1.3.0/ace-hero.min.js): hero button effects.
- [ace-navbar.min.js](https://acecss.dev/v1.3.0/ace-navbar.min.js): navbar.
- [ace-navbar-liquid.min.js](https://acecss.dev/v1.3.0/ace-navbar-liquid.min.js): liquid-glass navbar.
- [ace-all.min.js](https://acecss.dev/v1.3.0/ace-all.min.js): every script in one file.
- [ZIP download](https://acecss.dev/download/acecss-1.3.0.zip): all of the above, full and minified.

## Links

- [Components, with live demos](https://acecss.dev/components/)
- [Docs](https://acecss.dev/docs/)
- [Example pages](https://acecss.dev/examples/)
- [Install, CDN links with SRI hashes](https://acecss.dev/docs/#install)
- [Class reference](https://acecss.dev/docs/#reference)
- [npm: @acecss/core](https://www.npmjs.com/package/@acecss/core)
- [Source on GitLab](https://gitlab.com/erblin.kosowwwa/acecss)
- [MIT License](https://acecss.dev/LICENSE)