@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