@gottheflag/ui

A CSS-first component library with useful defaults, native HTML foundations, and deliberately easy customization. Install it, import it, and build—no component runtime or initialization required.

Status: 0.1.0-beta.1 pre-release. The public API may still receive small refinements before 1.0.0.

Install

pnpm add @gottheflag/ui

Import the library defaults and shared design tokens:

@import "@gottheflag/ui";

This root import intentionally does not include any component. Import every component independently so each page ships only what it uses:

@import "@gottheflag/ui/button.css";
@import "@gottheflag/ui/dialog.css";

Bundlers may use equivalent JavaScript-side CSS imports.

Quick start

@import "@gottheflag/ui";
@import "@gottheflag/ui/button.css";
@import "@gottheflag/ui/badge.css";

<button type="button" class="ui-success">Save changes</button>
<a class="ui-btn ui-outline" href="/docs">Read the docs</a>
<span class="ui-badge ui-info ui-subtle">Beta</span>

GTF UI styles native elements where that produces the cleanest accessible contract. Components that need an explicit opt-in use the ui-* classes shown in their documentation.

Customize without fighting the library

Public custom properties handle fast theming:

:root {
	--ui-accent: #c84548;
	--ui-radius: 0.5rem;
}

A consumer class can isolate anything from a token adjustment to a complete reskin:

<aside class="ui-sidebar my-product-sidebar">…</aside>

.my-product-sidebar {
	--ui-sidebar-width: 20rem;
	--ui-sidebar-icon-size: 1.25rem;
	border-radius: 1rem;
}

Library rules live in cascade layers, so ordinary unlayered application CSS wins without selector escalation or !important.

Components

| Component | Public import | Primary contract | | --- | --- | --- | | Accordion | accordion.css | details | | Avatar | avatar.css | .ui-avatar | | Badge | badge.css | .ui-badge | | Breadcrumb | breadcrumb.css | .ui-breadcrumb | | Button | button.css | button, .ui-btn | | Card | card.css | .ui-card | | Carousel | carousel.css | .ui-carousel | | Checkbox | checkbox.css | input[type=checkbox] | | Code | code.css | code | | Color | color.css | input[type=color] | | Datetime | datetime.css | date/time inputs | | Dialog | dialog.css | dialog | | Divider | divider.css | hr, .ui-divider | | Dock | dock.css | .ui-dock | | Drawer | drawer.css | .ui-drawer[popover] | | Fieldset | fieldset.css | fieldset | | File | file.css | input[type=file] | | Input | input.css | text-like inputs | | Keyboard | keyboard.css | kbd | | Link | link.css | a | | Loader | loader.css | .ui-loader | | Menu | menu.css | menu[popover] | | Number | number.css | input[type=number] | | Pattern | pattern.css | .ui-pattern | | Progress | progress.css | progress | | Radio | radio.css | input[type=radio] | | Range | range.css | input[type=range] | | Ribbon | ribbon.css | .ui-ribbon | | Scrollbar | scrollbar.css | global + utility | | Select | select.css | select | | Sidebar | sidebar.css | .ui-sidebar | | Table | table.css | table | | Text | text.css | .ui-text-* | | Textarea | textarea.css | textarea |

CSS-only runtime

The published package contains CSS only and has zero runtime dependencies. Components use semantic HTML and native browser state such as :checked, :open, :popover-open, :hover, :focus-visible, and :active.

Application code may change application data or native element state, but it never unlocks a missing GTF UI styling feature. The playground script controls playground tools only.

For a disabled link, omit href and add aria-disabled="true"; use a native disabled <button> for actions.

Browser support

GTF UI targets modern browsers. Narrower-support features—typed attr(), Anchor Positioning, customizable Select, and CSS sibling functions—are progressive enhancements. Components remain usable when an enhancement is unavailable.

Accessibility

Prefer the documented native element, keep visible labels or accessible names, and preserve keyboard behavior. GTF UI provides presentation and state styling; the application remains responsible for meaningful labels, valid document structure, and product-specific announcements.

Development

pnpm install
pnpm build
pnpm playground

pnpm build compiles the defaults-only root and every independent component entrypoint.

License

Apache-2.0