Customization

Installation
Templates

Customization

5h3ll-ui customization has three layers:

  1. Choose a style pack.
  2. Override theme tokens such as colors and fonts.
  3. Add small project-level CSS overrides when tokens are not enough.

For a full visual rewrite, import the 5h3ll-ui base layer and write your own style pack instead of overriding an existing one wholesale.

Styles

5h3ll-ui ships the same style families used by the current shadcn/ui registry: Vega, Nova, Maia, Lyra, Mira, Luma, Sera, and Rhea.

Pick one complete style bundle in your app CSS:

@import "tailwindcss";
@import "5h3ll-ui/vega";

Swap the import to use another style:

@import "tailwindcss";
@import "5h3ll-ui/sera";

Each style bundle is standalone. Do not import Vega first and then load another style on top of it. Keep the selected 5h3ll-ui style after Tailwind or any other stylesheet that emits a reset/base layer.

Themes

5h3ll-ui uses shadcn/ui-compatible CSS variables. You can use a theme from TweakCN or another shadcn/ui theme generator by importing the variables after 5h3ll-ui:

@import "tailwindcss";
@import "5h3ll-ui/sera";
@import "./theme.css";

theme.css should define token values such as --background, --foreground, --primary, --muted, --border, --input, and --ring for :root and .dark when needed.

Learn more in the shadcn/ui theming docs.

Fonts

5h3ll-ui does not ship web font files by default. Its font tokens prefer Geist Sans and Geist Mono when those fonts are available, then fall back to the full Tailwind default sans and mono stacks.

Install the fonts with Fontsource:

npm install @fontsource/geist-sans @fontsource/geist-mono

Then import the font files. 5h3ll-ui’s default font tokens already reference Geist with full system fallbacks:

@import "tailwindcss";
@import "5h3ll-ui/sera";
@import "@fontsource/geist-sans/400.css";
@import "@fontsource/geist-sans/500.css";
@import "@fontsource/geist-sans/600.css";
@import "@fontsource/geist-sans/700.css";
@import "@fontsource/geist-mono/400.css";
@import "@fontsource/geist-mono/500.css";
@import "@fontsource/geist-mono/600.css";
@import "@fontsource/geist-mono/700.css";

If you use different fonts, override the font tokens after 5h3ll-ui:

@import "tailwindcss";
@import "5h3ll-ui/sera";
:root {
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
  --font-heading: "Inter", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
  --font-mono: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
}

Keep font overrides in a small CSS file imported after 5h3ll-ui. Fonts are project-level customization, not a 5h3ll-ui default.

Icons

5h3ll-ui examples use Lucide icons, but 5h3ll-ui does not require an icon package.

You can:

  • Copy SVGs from lucide.dev/icons and paste them into your HTML.
  • Install lucide and render icons from JavaScript.
  • Use a framework-specific Lucide package if your app already uses a framework.

Inline SVG is the simplest option for plain HTML, Jinja, Nunjucks, Rails, Django, Laravel, or similar stacks.

Project overrides

For small visual tweaks, add utilities or project CSS after 5h3ll-ui:

@import "tailwindcss";
@import "5h3ll-ui/sera";
@import "./app.css";
<button class="btn font-normal" data-variant="outline">Click me</button>

Prefer theme tokens for broad changes and one-off utilities for local changes. Avoid copying generated 5h3ll-ui bundles into your app unless you intend to maintain a fork.

Custom style packs

If you want a full custom style, import the styleless 5h3ll-ui base and then your own style file:

@import "tailwindcss";
@import "5h3ll-ui/base";
@import "./styles/acme.css";

5h3ll-ui/base includes 5h3ll-ui tokens, semantic utilities, and component structure, but no Vega/Nova/Maia/etc. visual style pack. Your style file owns component visuals: colors, radius, shadows, focus rings, spacing, variants, and state treatment.

The practical way to start is to copy one existing style pack from 5h3ll-ui/styles/*, rename it, and edit it:

@import "5h3ll-ui/base";
@import "./styles/acme.css";
/* ./styles/acme.css can start as a copy of 5h3ll-ui/styles/nova. */

Do not import a complete style bundle before your custom style. For example, avoid importing 5h3ll-ui/nova and then overriding it wholesale. That loads Nova visuals and forces your file to undo them. Use 5h3ll-ui/base instead.

Compatibility

5h3ll-ui 1.0 prefers data-variant and data-size over legacy variant classes. If you need old pre-1.0 aliases while migrating, import the compatibility layer after 5h3ll-ui:

@import "tailwindcss";
@import "5h3ll-ui/vega";
@import "5h3ll-ui/compat";

The compatibility layer is for migration only. New code should use the documented 1.0 API.