# @a4ui/core

> A4ui — "Spatial Glass" design system & component library for SolidJS
> (glassmorphism surfaces, starfield backdrop, light/dark themes). 90+ components
> built on Kobalte (behavior/a11y), a Tailwind preset (visual), and
> Motion (motion.dev, the `motion` package) for JS animation.

Docs: https://a4ui.pages.dev/  ·  Repo: https://github.com/A4uikit/a4ui

## Install

```bash
npm install @a4ui/core
```

Peer dependency: solid-js (>= 1.9).

## Setup

```ts
// tailwind.config.ts — add the preset
import a4ui from '@a4ui/core/preset'
export default {
  presets: [a4ui],
  content: ['./src/**/*.{ts,tsx}', './node_modules/@a4ui/core/dist/**/*.js'],
}
```

```tsx
// entry (once)
import '@a4ui/core/styles.css'

// anywhere — every component is a named export; props are fully typed with
// JSDoc + @example in the shipped .d.ts.
import { Button, Card, Modal } from '@a4ui/core'
```

## Entry points

Styling has two paths: **with Tailwind**, add the `@a4ui/core/preset` and import
`styles.css` (tokens + motion); **without Tailwind**, import `@a4ui/core/full.css`
(fully precompiled — tokens + every utility the components use).

- `@a4ui/core` — all the components listed below (named exports).
- `@a4ui/core/styles.css` — tokens + motion + starfield (needs the Tailwind preset for utilities).
- `@a4ui/core/full.css` — self-contained precompiled CSS for use WITHOUT Tailwind.
- `@a4ui/core/preset` — the Tailwind preset (semantic tokens + glass plugin).
- `@a4ui/core/commerce` — commerce set: ProductCard, ProductGrid, PriceTag, QuantityStepper, CartLine, CartSummary, FilterGroup.
- `@a4ui/core/charts` — charts: Sparkline, BarChart, DonutChart (native SVG).
- `@a4ui/core/elements` + `@a4ui/core/elements.css` — framework-agnostic Web Components (`<a4-button>`, `<a4-clock>`, …) for React/Next.js, Vue, or plain HTML.

The **Commerce** and **Charts** groups below import from `@a4ui/core/commerce` and
`@a4ui/core/charts` respectively; everything else from `@a4ui/core`.

## The "Spatial Glass" look (recipe)

To make a page actually look like A4ui (frosted glass over an ambient backdrop,
a cursor light, restrained motion) — not flat cards on a flat background — follow
this. Full guide: https://a4ui.pages.dev/#/guide-spatial-glass

1. **Backdrop first.** Render `<Aurora/>` once at the top of the layout and keep
   the page root transparent (NO `bg-background` on the root — Aurora paints the
   base). It tints to your theme; `animated` = slow drift; `pointerGlow` (default
   on) = a glow that follows the cursor across the backdrop.
   Glass only reads if there is color behind it — this is what provides it.
2. **Surfaces are glass.** Use `<Card glass>` (not opaque `bg-card` divs) so the
   Aurora shows through the frosted blur. `glow` is on by default; add `spotlight`
   (inner cursor glow) + `tilt` to KEY cards only (hero/feature/product), not all.
3. **Theme via tokens.** Override the 15 CSS vars (`--primary`, `--accent`, radius)
   under `:root`; everything incl. Aurora recolors. Light glass ships slightly
   transparent so the frost reads.
4. **Motion, 4–6 tasteful touches** (reduced-motion aware): `ScrollProgress`,
   `Parallax` hero, `TextReveal` headings, `Magnetic` on the primary CTA, count-up
   `Stat`, `Carousel` swipe. Keep them off the critical path.
5. **Expand, don't modal:** use `Expandable` (shared-element FLIP) for galleries and
   "click to see the full thing".
6. **Structure** with `<Section>` + full-bleed `bg-muted/30` bands.
7. **Ship-quality:** lazy images, ≥24px targets, labeled inputs, a robots.txt.

Common mistakes: flat background (add Aurora), opaque cards (use `Card glass`),
`spotlight`/`tilt` on every card (noisy), over-animating.

## Components

### Get started

- **Themes** — Swap the whole color palette at runtime. Five built-in themes; apply one by name, restore the saved one on boot, or bring your own. Separate from the light/dark switch — a theme recolors under either mode.
- **Icons** — A4ui already ships lucide-solid — 1500+ crisp, consistent icons, no extra install. Tree-shakeable too: import one icon and ONLY that icon ships (~0.3 kB), never the whole set. Size with h-/w-, color with text-*.
- **Templates** — Complete, real company sites built with A4ui — each its own theme, live on Cloudflare Pages. Proof the system builds full pages, not just demos. Source: github.com/A4uikit/templates

### Actions

- **Button** — Button with 4 variants. Defaults to type="button" so it never submits forms by accident. `ripple` bakes in a Material click ripple (engine-free). Pass `href` to render as an <a> link (keeps the look + ripple). Try the controls ↓
- **Dropdown** — Actions menu (Kobalte). The trigger itself IS the button, so its children must be non-interactive.
- **ContextMenu** — Context menu shown on right-click over the child element (the target).
- **Toggle** — Two-state button (pressed / not) — ideal for toolbars.
- **ToggleGroup** — Row of segmented buttons; the value can become null when deselected.
- **SegmentedControl** — Single selection with an animated indicator that slides under the active option.
- **FloatingActionButton** — Prominent circular primary action pinned to a corner of the viewport. `ripple` adds a Material press ripple.
- **SpeedDial** — A FAB that fans out into multiple quick actions. The main button carries a Material press ripple.
- **MoneyActionButton** — A prominent CTA reserved for value-moving actions — one accent, tightly scoped to money movement.
- **MicroButton** — A button that fires a physically-tuned feedback effect — spin, shake, pulse, ring or sparkle on click, or a glare sweep on hover. Transform/opacity only, reduced-motion safe. Click the buttons ↓
- **IconMorphButton** — A two-state icon toggle whose glyph morphs — spring scale + rotate + fade — between states: copy→check, mute, theme. Click ↓
- **Morph presets** — Ready-made two-state buttons built on IconMorphButton — no need to wire the two icons yourself. Click them ↓
- **LikeButton** — Like / favorite / save toggle (heart · star · bookmark via one `icon` prop) with a spring pop and a staggered icon burst. Click ↓
- **SlideArrowButton** — A CTA where the label slides out and an arrow slides in from the opposite edge on hover — pure CSS transform. Hover ↓

### Forms

- **Switch** — Accessible on/off toggle (Kobalte).
- **Input** — Controlled text field. Uses value/onInput (onInput receives the string, not the event).
- **Textarea** — Controlled multi-line field, resizable vertically.
- **Select** — Controlled native select (value/onChange receives the string). The <option>s go as children.
- **Combobox** — Single selection with type-to-search (Kobalte). Options as a list of strings.
- **Checkbox** — Checkbox with a clickable label (checked/onChange).
- **RadioGroup** — Accessible single-choice group (Kobalte), with an optional label.
- **Slider** — Single-value slider (Kobalte), with a visible label and value.
- **NumberInput** — Numeric field with −/+ buttons (Kobalte NumberField).
- **DateField** — Date picker with a calendar. Click the month or year to jump; « » step a year. YYYY-MM-DD.
- **TimeField** — Time picker with hour/minute columns. Value in 24h "HH:MM"; optional 12h AM/PM display.
- **DateTimeField** — Combined date + time picker. Value in "YYYY-MM-DD HH:MM" (local); each half fills independently.
- **DateRangePicker** — Pick a start and end date on one calendar; the range fills in between.
- **FormField** — Accessible field wrapper — label, control, description and error share one id.
- **MultiSelect** — Multi-select dropdown with search and removable chips.
- **FileUpload** — Drag-and-drop uploader with per-file progress, error/retry and remove.
- **Dropzone** — Drag-and-drop area (or click to choose). Hands File[] to onFiles; you control the upload.
- **Rating** — Star rating with hover preview, click-to-set, and keyboard support. Set readonly to just display.
- **Calendar** — Full month grid — navigate months and pick a day. Selected day highlighted; today ringed.
- **TagInput** — Multi-value text entry rendered as removable chips. Enter adds, Backspace removes the last.
- **Transfer** — Dual-list picker — move items between an available and a selected column.
- **TreeSelect** — A select whose options come from an expandable tree; pick a leaf.
- **Cascader** — Cascading columns for hierarchical choices (e.g. country → state → city).
- **Mentions** — Textarea with @mention autocomplete — type @ to search and insert a name.
- **ColorPicker** — Pick a color via the native picker, a hex field, or preset swatches.
- **PromptComposer** — Chat input: auto-growing textarea, removable attachment chips, attach + send. Submits on Cmd/Ctrl+Enter.
- **InlineSelect** — Edit-in-place select: click the value to swap it for a dropdown, pick to commit. For inline status/priority fields.
- **PillSearch** — A rounded-full bar compressing several search fields into segments, with a round search button.

### Data

- **Stat** — KPI card with an animated entrance (solid-motionone) and a count-up on the number (respects reduced-motion). Change the value and watch it count ↓
- **Badge** — Status pill with 5 semantic tones. `pulse` adds a pinging dot for "live" states.
- **Card** — Container surface with sub-parts (Header/Title/Content). With glass, a frosted surface + glow. `tilt` and `spotlight` bake in the cursor interactions from the Motion category — hover the card with them on ↓
- **Table** — Table primitives (Table + Head/Body/Row/HeadCell/Cell). For long lists, virtualize.
- **VirtualList** — Virtualized list: only the visible rows live in the DOM. Requires a fixed height in class.
- **Pagination** — Previous/next pager with "Page X of Y" and an optional summary on the left.
- **Avatar** — User avatar (Kobalte Image): shows the image or, if it fails, the initials.
- **Progress** — Determinate progress bar (Kobalte Progress), with an optional label and value.
- **Meter** — Static gauge for a measurement (Kobalte Meter) — e.g. disk usage or quota.
- **Separator** — Horizontal or vertical visual/semantic divider (Kobalte Separator).
- **Skeleton** — Placeholder while content loads. Set the size with class. `shimmer` sweeps a light band instead of pulsing.
- **BeforeAfter** — Draggable before/after image comparison slider — keyboard-accessible, reduced-motion aware, engine-free.
- **Configurator** — Data-driven "pick options → live preview + running total" builder (select / counter / text groups). Distilled from the templates' engraving customizer and board builder.
- **Carousel** — One slide at a time with arrows, clickable dots, arrow-key nav, drag/touch swipe, and optional autoplay (pauses on hover). Drag the slide ↓
- **Timeline** — Vertical sequence of events with tinted dots, titles, timestamps, and descriptions.
- **Tree** — Hierarchical, expandable node tree with rotating chevrons and keyboard-friendly rows.
- **AvatarGroup** — Overlapping stack of avatars with an overflow "+N" count.
- **Descriptions** — Read-only key/value layout for record details, in 1–3 responsive columns.
- **Highlight** — Highlights every match of a query within a string.
- **List** — Structured list with avatar, title/description, meta, and actions per row. `stagger` cascades the rows in on mount.
- **Countdown** — Live countdown to a target date — days, hours, minutes, seconds.
- **Clock** — Live clock — analog dial or digital readout, with an optional time zone.
- **Sortable** — Drag rows by the grip handle to reorder them (pointer-based, touch-friendly).
- **Image** — Lazy image with a click-to-zoom lightbox. `blurUp` reveals it from blurred to sharp on load.
- **DataGrid** — Sortable, filterable, paginated table — click a header to sort, type to filter.
- **Comment** — Threaded comment layout with avatars, timestamps, actions, and nested replies.
- **CalendarHeatmap** — GitHub-style activity grid — intensity per day over the last weeks.
- **SpecSheet** — A grouped key/value specification table for product specs and tech sheets.
- **RatingsSummary** — A compact social-proof grid of aggregate ratings across multiple review sources.
- **LogoWall** — "As seen in" grid of press/partner logos — grayscale by default, color on hover.
- **ChatThread** — Scrollable, centered reading column that stacks chat messages — the container for conversation/AI UIs.
- **Message** — One chat message row — full-width (no bubble), role-styled, content as children.
- **Citation** — Inline numbered source chips + a compact SourceList — for AI answers with citations.
- **CodeTabs** — Tabbed code blocks with a per-tab copy button — for install snippets or multiple languages.
- **DataView** — One dataset, switchable views — table, board (kanban), and gallery — via a segmented control.
- **BalanceCard** — Balance-first summary card with a formatted amount and an up/down delta chip.
- **TransactionFeed** — Dense transaction/activity list with success-toned incoming amounts and optional date grouping.
- **KpiBlock** — A labelled metric with a signed delta chip and an optional inline chart slot.
- **BlockEditor** — A block stack: drag a handle to reorder, delete on hover, and a slash-menu "+ Add block" picker.

### Commerce

- **PriceTag** — Formatted price with an optional strikethrough compare-at and a discount badge.
- **QuantityStepper** — Increment/decrement control with min/max clamping.
- **ProductCard** — Product tile — image, badge, title, rating, price, add-to-cart. `tilt`/`spotlight` forward to the underlying Card — hover it with them on ↓
- **ProductGrid** — Responsive grid wrapper for ProductCards (2 / 3 / 4 columns).
- **CartLine** — A cart row — thumbnail, title, quantity stepper, line total, remove.
- **CartSummary** — Itemized totals panel with a checkout button.
- **FilterGroup** — A titled facet group of checkboxes with optional counts.
- **PriceBlock** — Richer price than PriceTag: compare-at savings, a coupon chip with the after-coupon price, and a financing estimate.
- **FacetSidebar** — Full faceted-filter panel: collapsible checkbox sections, a price range, active chips, and clear-all.
- **ConditionScale** — A graded-condition meter (e.g. 1–10 for a pre-owned item) with a marker, tier label, and endpoints.

### Charts

- **Sparkline** — Tiny inline trend line (SVG, theme-tinted).
- **BarChart** — Simple labelled vertical bars.
- **DonutChart** — SVG donut with theme-tinted segments and a center total.
- **LineChart** — Multi-series line chart (SVG, no deps) with optional area fill, dots, and a hover tooltip + crosshair. Hover the plot ↓
- **GaugeChart** — A 270° radial gauge with an animated sweep and optional colored thresholds. For single KPI values.
- **RadarChart** — A spider/radar chart for comparing entities across several dimensions at once.

### Overlays

- **Tooltip** — Floating label shown on focus/hover (Kobalte).
- **Modal** — Dialog (Kobalte). variant="center" for short confirmations; "drawer" (default) for forms.
- **Drawer** — Sliding panel anchored to the right (Kobalte Dialog), with an optional fixed header (title/subtitle).
- **Popover** — Floating panel shown on trigger click (Kobalte Popover).
- **HoverCard** — Floating panel that appears on hover over the trigger (Kobalte HoverCard).
- **AlertDialog** — Centered confirmation dialog (Kobalte AlertDialog) for destructive actions.
- **Command** — Reusable ⌘K command palette — fuzzy filter, keyboard nav, grouped items.
- **Tour** — Guided coachmarks — spotlights elements step by step with a tooltip.
- **NotificationCenter** — A bell with an unread count that opens a dismissible notification feed.
- **SlashMenu** — Filterable "/" insert menu — a block/command picker with keyboard navigation.

### Feedback

- **Alert** — Inline banner for contextual messages, with 4 tones. Try the controls ↓
- **Toast** — Imperative notifications: call toast.success/error/info from anywhere. The Toaster is already mounted.
- **Spinner** — Spinning loading indicator with role="status" and an accessible label.
- **Empty** — Placeholder for empty states — icon, title, description, and an optional action slot.
- **Result** — Full-status screen for success/error/404/500 outcomes, with an actions slot.
- **RingProgress** — Circular percentage progress ring.
- **AnnouncementBar** — Full-bleed promo bar — optional dismiss and a copyable coupon-code pill.

### Navigation

- **Tabs** — Accessible tabs (Kobalte) with an animated indicator. Controlled by value/onChange.
- **Accordion** — Accessible accordion (Kobalte) with animated open/close height. multiple lets several sections be open at once.
- **Breadcrumb** — Navigation trail (Kobalte Breadcrumbs). The last item is the current page.
- **PageHeader** — Consistent page header: optional breadcrumb, title, subtitle, and an actions slot on the right.
- **Stepper** — Progress across ordered steps — completed, active, and upcoming states. Horizontal or vertical.
- **BackToTop** — Floating button that appears after scrolling and returns to the top (bottom-right).
- **Anchor** — Table-of-contents scroll-spy that highlights the section currently in view.
- **BottomNavigation** — Mobile-style bottom bar for top-level navigation.
- **CategoryStrip** — Horizontally-scrollable icon + label category filters with an active-underline indicator.
- **Spaces** — Switchable, swipeable context containers — one space at a time, with a pill rail and drag-to-swipe.
- **SideRail** — A vertical icon + label navigation rail — the vertical alternative to top tabs or a compact sidebar.
- **Dock** — A macOS-style dock: icons magnify based on the cursor’s distance. Move your cursor across it ↓

### Layout

- **AppShell** — Slot-based app structure: space background (z-0), sidebar, topbar, banner, and a <main> with a cross-fade between routes.
- **SpaceBackground** — The "space glass" background: a fixed layer (z-0) with stars, nebula, planets, and shooting stars. Respects reduced-motion.
- **ThemeToggle** — Button that toggles light/dark theme. The icon shows the CURRENT theme (🌙 dark, ☀️ light).
- **EffectsToggle** — Turns visual effects on/off (glass + starfield + animations). Off = calm mode, opaque and motionless.
- **Section** — Centered content container — max width (size) + vertical rhythm (py) + optional id anchor. The layout wrapper every page repeats.
- **Aurora** — Ambient theme-tinted blurred-blob backdrop so glass surfaces read as glass. Fixed behind the page; keep the root transparent. The no-starfield alternative to SpaceBackground.
- **PricingTable** — Tiered pricing cards with a highlighted "Popular" tier and an optional monthly/annual toggle.
- **ActionBar** — Sticky action/emergency bar: a status slot + a prominent CTA (renders as <a> for tel:/links). For urgent-service pages.
- **NavGroup** — Collapsible sidebar category (native <details>). Open by default; the chevron rotates when collapsed.
- **Kbd** — Inline keyboard-key indicator for shortcuts.
- **Splitter** — Two resizable panes with a draggable divider (keyboard-resizable too).
- **Collapse** — A single expand/collapse region with a rotating chevron and animated height.
- **Affix** — Pins its content to the top of the viewport once you scroll past it.
- **Marquee** — Seamless infinite scroller — pauses on hover, respects reduced motion.
- **Portal** — Renders children into a detached DOM node (default <body>) — escapes overflow and stacking contexts.
- **ArtifactPanel** — Inline right-side panel for AI-generated output next to a chat — reveals by animating width (not a portalled overlay).
- **FloatingToolbar** — Fixed, centered glass toolbar that condenses as you scroll — a detached action bar (renders fixed-position over the page).
- **MasterDetail** — List + detail-pane layout with keyboard navigation — like an inbox. Controlled or uncontrolled.
- **Refractive glass** — A heavier glass surface with a specular sheen + bright top edge (the `.glass-refractive` utility). For hero/feature panels over a colourful backdrop like Aurora.
- **BentoGrid** — A responsive bento layout — glass tiles that span columns/rows via BentoCard `colSpan`/`rowSpan`.

### Motion

- **Stagger** — Cascade a group in with a per-item delay (stagger) and a spring. Motion (motion.dev) is the engine A4ui uses — the package re-exports animate / inView / scroll / stagger / spring, plus animateIn / revealOnScroll.
- **Spring** — Physics-based spring — fling the ball and it settles with a natural bounce.
- **Scroll reveal** — Reveal items the first time they scroll into view (Motion inView). Scroll the list ↓
- **Hover & press** — Springy scale on hover and a dip on press, driven by Motion animate.
- **Count up** — Tween a number up with createCountUp (Motion under the hood). Replay to run it again.
- **Scramble text** — Text that decodes from random glyphs — reusable as the <ScrambleText> component. Run on mount or on hover.
- **Text reveal** — Reveal a line word-by-word (or char-by-char) with a staggered fade — the <TextReveal> component.
- **Hold to confirm** — Press and hold to confirm a weighty action — a fill sweeps and only fires at 100%. The <HoldToConfirm> component.
- **Loaders** — Loading indicators: <LoadingDots> (staggered bounce) and <FillText> (a band sweeping through text).
- **Curtain transition** — Full-screen page/route wipe with seven variants (fade · doors · blinds · shutter · iris · clip · pixels) — one <Curtain> component. Pick a style and play it.
- **Parallax** — Wrap anything in <Parallax> and it drifts at a fraction of scroll speed for depth. Scroll the panel ↓
- **Notification stack** — Stacked notifications that peek behind one another — click the stack (or "Show all") to expand the full list, "Show less" to collapse. The <NotificationStack> component. Add a few ↓
- **Multi-state badge** — A status pill that morphs color and swaps its icon as state changes (idle · loading · success · error) — the <MultiStateBadge> component.
- **Add to cart** — The classic "fly to basket" — a ghost arcs from the product to the cart, which bumps. The flyToCart() helper.
- **Now playing** — A compact media widget with a live equalizer that dances while playing — the <NowPlaying> component.
- **Expandable (shared layout)** — A card that morphs into a dialog and back with a shared-element (FLIP) transition — the <Expandable> component. "dialog" mimics a family-photo modal, "full" the App-Store card expand. Click a card ↓
- **Typewriter** — Types a string out char-by-char (with a blinking caret), cycling through several — the <Typewriter> component.
- **Ripple** — Material-style click ripple you wrap around anything — the <Ripple> component. Buttons have it baked in: <Button ripple>. Click the tile ↓
- **Magnetic** — Wrap anything in <Magnetic> and it springs toward the cursor as you hover near it. Hover the button ↓
- **Tilt card** — A 3D tilt that follows the cursor — the <TiltCard> component. Cards have it baked in: <Card tilt>. Move your cursor over the card ↓
- **Spotlight** — A soft glow that follows the cursor across the surface — the <Spotlight> component. Cards have it baked in: <Card spotlight>. Move over it ↓
- **Scroll progress** — A reading-progress bar pinned to the top of the viewport that fills as the page scrolls — the <ScrollProgress> component. Scroll this page and watch the very top ↑
- **Gradient text** — Text with a smoothly animated multi-color gradient — the <GradientText> component.
- **StreamingText** — Reveals text as it "streams" in with a blinking caret — for AI answer UIs.
- **PageTransition** — Cross-fades (or slides) keyed content in and out on change — for route/view transitions.
- **ScrollScene** — Binds a render to the element’s scroll progress (0→1) — for scroll-driven storytelling.
- **StickyReveal** — Pins its content while scrolling through a tall section, fading it in — scroll inside the preview to see it.
- **FocusBlurGroup** — Hover or focus one item and it stays sharp while its siblings blur and dim — a spotlight for lists and navs. Hover a link ↓
- **CardSpread** — A stack of cards that fans out into an arc, line, corner, cascade, scatter or wheel. Hover the stack ↓ (the Variations below are pinned open).
- **Carousel3D** — A 3D coverflow / arc carousel — slides curve back around the active one. Drag, use the arrows, the dots, or ← → keys ↓
- **TimeMachineStack** — An Apple-style depth stack: the active card is front and the rest recede into the screen. Use the scrubber on the right or ↑ ↓ keys ↓
- **AnimatedBeam** — An SVG beam with a traveling gradient that connects two elements — great for “how it works” diagrams.
- **BorderBeam** — A light that continuously traces the border of its (relative) parent. Drop one inside any card.
- **Meteors** — A decorative meteor-shower layer for hero/section backdrops. Reduced-motion safe.

### Guides

- **Spatial Glass** — The recipe for the A4ui look — Aurora backdrop, glass surfaces, the cursor light, tasteful motion, Expandable. Follow it and a page looks like A4ui.
- **Integrations** — Use A4ui in Vite + Solid, SolidStart (SSR), Astro, or React/Next/Vue/vanilla via Web Components.
- **Stability** — Versioning policy and the Stable / Experimental / Internal tiers — what is safe to build on before 1.0.
- **Upgrading** — Upgrade notes across the 0.x line — what changed and what (if anything) you need to do.
- **Changelog** — Every release of @a4ui/core, newest first.

See https://a4ui.pages.dev/#/<component-id> for a live example and
copyable code for each component (e.g. #/button, #/modal, #/data-field).