Documentation

lucUI 2 · Prism v2.1.3 · Semantic versions on npm

Start here

Getting Started

lucUI is plain CSS + a small JS helper. No framework, no bundler, no config. Include two files, add classes, and you have a design system.

Generation & package version

Public identity: lucUI 2 (Prism). Package: v2.1.3 on npm as lucui-css-framework. Both are shown in the site header.

Installation

Three supported methods — all install the same files.

Terminal
npm install lucui-css-framework
HTML
<link rel="stylesheet" href="node_modules/lucui-css-framework/lucUI.min.css">
<script src="node_modules/lucui-css-framework/lucUI.js"></script>

Package: lucui-css-framework · License MIT.

HTML — CDN
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/lucui-css-framework@2.1.3/lucUI.min.css">
<script src="https://cdn.jsdelivr.net/npm/lucui-css-framework@2.1.3/lucUI.js"></script>

Also: https://unpkg.com/lucui-css-framework@2.1.3/lucUI.min.css

Terminal
git clone https://github.com/lucaf1-15/lucUI.git
cd lucUI
npm run build  # rebuilds lucUI.css + lucUI.min.css

Repo: github.com/lucaf1-15/lucUI

Quick Start

Minimal page that uses theme toggle, stage, and a card.

index.html
<!doctype html>
<html data-theme="dark">
<link rel="stylesheet" href="lucUI.min.css">
<body>
  <nav class="luc-navbar">…</nav>
  <section class="luc-stage">
    <h1 class="luc-gradient-text">Hello</h1>
    <button class="luc-btn luc-btn-primary">Action</button>
  </section>
<script src="lucUI.js"></script>

Hello

Set data-theme="dark|light" on <html>. Toggle with data-luc-theme-toggle.

Design Tokens

All values are CSS variables. Override in :root or scoped.

TokenValueUsage
--luca-navy#1d2d44Canvas, text on light
--studio-gold#ae9d5dPrimary accent
--designer-azure#00bbffFocus, links
--luc-surfacetheme-awareCard / nav surfaces
--glass-bgtheme-awareGlass panels
--space-41remSpacing scale 1–32
--radius-full9999pxPills, toggles
--shadow-lglayeredElevation
tokens.css
:root {
  --studio-gold: #ae9d5d; /* your brand gold */
  --font-display: 'Manrope', sans-serif;
}

Typography

Manrope 800 for display, DM Sans 500 for body. Fluid scales via clamp().

Heading 1

Heading 2

Heading 3

Body copy with accent voice and inline code.

.luc-display.luc-kicker.luc-gradient-text
type.html
<span class="luc-kicker">Label</span>
<h1 class="luc-gradient-text">Title</h1>
<p class="luc-measure">Body…</p>
<p class="luc-text-fluid-2xl">Fluid</p>
ClassEffect
.luc-kickerUppercase label, gold track
.luc-gradient-textGold→azure gradient on text
.luc-text-fluid-*xs–5xl fluid scale
.luc-measure72ch max width

Layout & Grid

.luc-container (1400px), .luc-grid, .luc-flex, and spacing utilities.

layout.html
<div class="luc-container">
  <div class="luc-grid luc-grid-cols-3 luc-gap-6">
    <article class="luc-card">…</article>
  </div>
</div>
col 1
col 2
col 3

Spacing: .luc-m-* .luc-p-* .luc-gap-* using --space-*. Responsive: columns collapse at 1024/768/480.

Theming

Two themes via data-theme="light|dark" on <html>. Semantic tokens (--luc-canvas, --luc-ink, --glass-bg) do the work.

theme.html
<html data-theme="light">
<button class="luc-theme-toggle" data-luc-theme-toggle>
  <svg data-luc-theme-icon="moon"></svg>
  <svg data-luc-theme-icon="sun"></svg>
</button>
<script>lucUI.setTheme('light')</script>
persists

This page uses the real toggle — it writes luc-theme to localStorage and fires luc:themechange.

APINotes
data-luc-theme-toggleButton toggles light↔dark
data-luc-theme-switch="light"Explicit switch
lucUI.getTheme()Read current
lucUI.setTheme('dark')Persist = true by default

Customization

Override tokens — keep the components.

custom.css
/* brand tweak — no rebuild needed */
:root {
  --studio-gold: #c8b87a;
  --luca-navy: #0f1f36;
  --font-display: 'Manrope', sans-serif;
  --radius-xl: 28px;
}
.luc-btn-primary { letter-spacing: 0.04em; }
Don't recreate components

If lucUI provides a button, card, or navbar, use it. Custom CSS is for genuinely site-specific details only.

40+ components

Components

Each section shows live rendering + copyable HTML. All classes are verified against the actual lucUI bundle.

ButtonsCardsFormsNavbarAlertsBadgesTabsModalsDropdownsToastsAccordionCarouselDataTablesTimelinePricing…

Buttons

Base .luc-btn + variants. Sizes: .luc-btn-sm .luc-btn-lg. State: disabled, .loading.

buttons.html
<button class="luc-btn luc-btn-primary">Primary</button>
<button class="luc-btn luc-btn-azure">Azure</button>
<button class="luc-btn luc-btn-outline">Outline</button>
<button class="luc-btn luc-btn-ghost">Ghost</button>
<button class="luc-btn luc-btn-sm">Small</button>
ClassVariant
.luc-btn-primaryGold gradient, navy text
.luc-btn-azureAzure
.luc-btn-outlineTransparent + gold border
.luc-btn-transparencyGlass border, sheen on hover
.luc-btn-groupJoined group

Cards

.luc-card is the base glass surface. .luc-prism + data-luc-spotlight adds reactive lighting. .luc-card-transparency is the dimensional glass variant.

Base card

Blur 24, glass edge.

Prism

Hover to see spotlight.

Clickable

Adds hover lift.

With header

Subtitle

Header / body / footer.

card.html
<article class="luc-card luc-prism" data-luc-spotlight>
  <h3 class="luc-card-title">Prism</h3>
  <p>Content…</p>
</article>

Forms & Inputs

Inputs use glass surfaces and gold focus. Includes floating labels, input groups, checkboxes, radios.

forms.html
<div class="luc-form-group">
  <label class="luc-label" for="email">Email</label>
  <input id="email" class="luc-input" placeholder="you@studio.com">
</div>
<select class="luc-select">…</select>
<label class="luc-checkbox-group">
  <input type="checkbox" class="luc-checkbox"> Label
</label>
ClassNotes
.luc-input .luc-textarea .luc-selectGlass, focus ring, blur
.luc-checkboxCustom check with ✓
.luc-form-groupSpacing wrapper

Navbar

Fixed glass bar. Hamburger toggles .luc-navbar-links.active via lucUI.js. Supports mega menu, search, user menu.

lucUI
DocsGitHub
navbar.html
<nav class="luc-navbar" aria-label="Primary">
  <div class="luc-navbar-container">
    <a class="luc-navbar-brand" href="/">lucUI</a>
    <div class="luc-navbar-links" id="nav">
      <a class="luc-navbar-link" href="#">Docs</a>
    </div>
    <button class="luc-navbar-toggle"
            aria-controls="nav" aria-expanded="false">…</button>
  </div>
</nav>

Alerts

Glass alerts with icon + dismiss.

Heads up

Use for informational states.

Warning

Check your tokens before publishing.

Error

Something went wrong.

alert.html
<div class="luc-alert luc-alert-info">
  <div class="luc-alert-content">
    <strong class="luc-alert-title">Title</strong>
    <p class="luc-alert-message">Message</p>
  </div>
</div>

Variants: .luc-alert-info .luc-alert-success .luc-alert-warning .luc-alert-error .luc-alert-gold

Badges

DefaultGoldAzureTangerineViridian
badge.html
<span class="luc-badge luc-badge-gold">Gold</span>
<span class="luc-badge luc-badge-azure">Azure</span>

Tabs

Wired via lucUI.js. Keyboard: ArrowLeft/Right, Home/End.

Tab content is live — check the homepage installation tabs for a real example.

API panel.

Examples panel.

tabs.html
<div class="luc-tabs">
  <div class="luc-tab-list" role="tablist">
    <button class="luc-tab active">One</button>
    <button class="luc-tab">Two</button>
  </div>
  <div class="luc-tab-panel active">…</div>
  <div class="luc-tab-panel">…</div>
</div>

Modals

Trigger with data-luc-toggle="modal" + data-luc-target. Focus trap, Escape, backdrop click, and trigger return handled.

modal.html
<button data-luc-toggle="modal" data-luc-target="#my-modal">Open</button>
<div id="my-modal" class="luc-modal-backdrop" style="display:none">
  <article class="luc-modal" role="dialog" aria-modal="true">
    <h3 class="luc-modal-title">Title</h3>
    <button data-luc-dismiss="modal">Close</button>
  </article>
</div>

Dropdowns

Profile Settings Sign out
dropdown.html
<div class="luc-dropdown">
  <button class="luc-dropdown-toggle">Menu</button>
  <div class="luc-dropdown-menu">
    <a class="luc-dropdown-item" href="#">Item</a>
  </div>
</div>

Click the button above — lucUI.js handles open/close, Escape, and keyboard navigation.

More components

All verified against the bundle. Each has its own CSS module in lucCOMPONENTS/.

Breadcrumbs

.luc-breadcrumb

Pagination

.luc-pagination

Accordion

Native <details> or .luc-accordion

What is lucUI?

A CSS framework + design system.

Progress & Skeleton

.luc-progress .luc-skeleton

Carousel

.luc-carousel with indicators

DataTables

.luc-table sortable

Avatar · Chips · Divider · Loader

.luc-avatar .luc-chip .luc-divider

Timeline · Stepper · Pricing · Features

.luc-timeline .luc-stepper

Full list: alerts, avatars, badges, breadcrumbs, buttons, cards, carousel, chips, cookie consent, data tables, datepicker, dividers, dropdowns, features, file upload, footer, forms, gallery, hero, loaders, modals, navbar, notifications, pagination, pricing, progress, range slider, search, sidebar, skeletons, stepper, tabs, testimonials, theme toggle, timeline, toasts, tooltips, toggles, user cards.

Advanced: Command · Prism · Reveal

Command palette

Press ⌘K / Ctrl+K. Filterable, keyboard navigable, focus-trapped.

command.html
<button data-luc-toggle="command">Search</button>
<div class="luc-command-backdrop">
  <div class="luc-command">
    <input class="luc-command-search" placeholder="Search…">
    <div class="luc-command-list">
      <button class="luc-command-item">Docs</button>
    </div>
  </div>
</div>

Prism & Reveal

.luc-prism with data-luc-spotlight for pointer lighting. .luc-reveal for scroll reveals.

Reactive

Hover this card — spotlight follows.

prism.html
<article class="luc-card luc-prism" data-luc-spotlight>
  Content
</article>
<div class="luc-reveal" data-luc-delay="120ms">…</div>
Accessibility

All interactive components handle keyboard, focus, and ARIA. Respects prefers-reduced-motion. Never remove :focus-visible — lucUI provides it.

Learn by building

Tutorials

20 standalone tutorials — each is one page with live preview, copyable code and exercises. 1–2 for every major area, 1 for every secondary group. All plain HTML + lucUI.

Browse all 20 tutorials →
01 · 8 min

First page

Stage, container, prism card — the minimum viable page.

 02 · 10 min

Layout & Grid

Container, auto-fit and responsive collapse.

 04 · 12 min

Buttons

All accents, sizes and groups.

 05 · 10 min

Cards & Prism

Glass levels and spotlight.

 06 · 12 min

Forms

Inputs, selects and checks.

 07 · 12 min

Navbar

Hamburger, mega and search.

 08 · 10 min

Theming

Light/dark and tokens.

 09 · 12 min

Modals & Toasts

Overlays and Cmd+K.

Secondary groups also each have a dedicated tutorial:

Alerts & Badges Breadcrumbs Carousel Pricing Timeline Advanced Inputs All 20 →

Ready to build?

Install once, use everywhere.

Get Started GitHub