@goblin-systems/goblin-design-system
v1.0.0
Published
Sharp-edged desktop UI primitives for vanilla TypeScript apps. The package ships CSS tokens, component classes, built-in `goblin` / `dark` / `light` themes, and headless DOM helpers for the interactive pieces.
Downloads
704
Readme
@goblin-systems/goblin-design-system
Sharp-edged desktop UI primitives for vanilla TypeScript apps. The package ships CSS tokens, component classes, built-in goblin / dark / light themes, and headless DOM helpers for the interactive pieces.
- No framework runtime
- Square visual language driven by CSS custom properties
- Lucide-backed icon helpers
- Headless TypeScript bindings for navigation, overlays, inputs, data display, and layout
- Optional Tauri helpers for frameless window chrome
Installation
npm install @goblin-systems/goblin-design-system lucidelucideis a required peer dependency.@tauri-apps/apiis an optional peer dependency used only bysetupWindowControls()andsetupContextMenuGuard().
Quick start
import "@goblin-systems/goblin-design-system/style.css";
import {
applyIcons,
applyTheme,
bindNavigation,
bindSearch,
bindTabs,
bindTooltips,
showToast,
} from "@goblin-systems/goblin-design-system";
applyTheme("goblin");
bindTabs();
bindNavigation();
bindTooltips();
// After any HTML containing <i data-lucide="..."> is in the DOM:
applyIcons();
showToast("Ready", "success");Built-in theme switching also works without JavaScript:
<html data-theme="light">
<!-- app -->
</html>If data-theme is omitted, the package defaults to goblin.
Themes and tokens
import {
BUILTIN_THEMES,
THEME_LABELS,
applyTheme,
getTheme,
isBuiltinTheme,
setTheme,
type BuiltinTheme,
} from "@goblin-systems/goblin-design-system";
const nextTheme: BuiltinTheme = "dark";
if (isBuiltinTheme(nextTheme)) {
setTheme(nextTheme);
}
console.log(getTheme(), BUILTIN_THEMES, THEME_LABELS);To add an app-specific theme, scope token overrides with data-theme after importing style.css:
@import "@goblin-systems/goblin-design-system/style.css";
[data-theme="my-theme"] {
--bg: #101418;
--bg-section: #161c22;
--bg-input: #0e1318;
--bg-deep: #090d10;
--border: #27303a;
--border-focus: #4aa3ff;
--text: #d7dde5;
--text-muted: #8f98a3;
--text-heading: #ffffff;
--text-subtle: #a9d5ff;
--accent: #4aa3ff;
--accent-hover: #6bb3ff;
--success: #43c27a;
--warning: #caa64a;
--error: #dd6666;
}Public API overview
Core exports from src/lib/index.ts are grouped as follows:
- Icons:
applyIcons,createIcon,ICON_SET,IconNode - DOM helpers:
byId,byIdOptional,qs,qsAll,populateSelectOptions,setGroupDisabled - Themes:
BUILTIN_THEMES,THEME_LABELS,applyTheme,getTheme,isBuiltinTheme,isUiTheme,setTheme - Navigation and discovery:
bindTabs,bindNavigation,bindSearch,bindTooltips,bindPopover,bindContextMenu - Feedback and overlays:
mountToast,showToast,openModal,closeModal,bindModal,confirmModal,openDrawer,closeDrawer - Inputs and selection:
bindRange,bindRadial,bindSwitch,bindAccordion,bindPagination,bindStepper,bindToggleGroup,bindSelect,bindTransferList,bindRating,bindTree - Data and layout:
bindTable,bindSplitPaneResize - Platform and media:
setupWindowControls,setupContextMenuGuard,drawWaveform,createWaveProgressGradient, waveform style/color helpers
Every headless export is fully typed and keeps markup ownership with the consumer. For the full class list, markup patterns, behavior notes, and type names, see skills/SKILL.md.
Consumer guidance
- Import
style.cssexactly once. - Use the documented class names and markup structure; bindings expect specific child elements for controls like range, radial, select, accordion, tree, and transfer list.
- Call
applyIcons()after rendering icon placeholders. - Prefer token overrides and
data-themeover selector-specific restyling. - The system is intentionally square; do not add rounded corners when extending it.
Skill documentation
This repo includes the consumer-facing Skill in skills/SKILL.md.
npx skills add goblin-systems/goblin-design-systemOr from a local checkout:
npx skills add .Demo and build commands
npm install
npm run dev
npm run build
npm run build:libnpm run buildbuilds the demo app.npm run build:libtype-checks the library entry and emits the publishable package intodist/.