Getting Started

Include the built assets, set root theme attributes, and begin from patterns instead of guessing from isolated primitives.

1. Include the package files

The smallest correct setup includes the main CSS and JS bundles. Add the icon CSS only if you want class-based icon usage with <i class="wb-icon wb-icon-*">. The docs and playground in this repo load the same built files from the local published dist path so the examples stay aligned with the shipped package output.

<link rel="stylesheet" href="/packages/webblocks/dist/webblocks-ui.css">
<link rel="stylesheet" href="/packages/webblocks/dist/webblocks-icons.css">
<script src="/packages/webblocks/dist/webblocks-ui.js" defer></script>

No extra layer required

You do not need framework wrappers, a custom starter stylesheet, or a separate component runtime to use the package correctly.

Mask-image icon path

This guide uses the shipped class-based icon path with webblocks-icons.css and <i class="wb-icon wb-icon-...">. Keep that stylesheet included if you want the same icon behavior.

2. Set root theme attributes

Theme axes live on the html element. The package theme module reads and updates these attributes for you.

<html data-mode="auto"
      data-accent="royal"
      data-preset="corporate"
      data-radius="soft"
      data-density="compact">
Mode

light, dark, or auto

Accent and preset

Accent changes the color system. Preset applies a named bundle of axis values.

3. Start from a pattern

The fastest correct path is not to browse every primitive first. Start from the page job, then inspect the surfaces and primitives that the pattern uses.

Dashboard shell Admin and data-heavy screens
Use this when the page needs sidebar navigation, a topbar, and structured main content.
Content shell Docs, onboarding, long-form content
Use this when prose, hierarchy, and reading width matter more than dense application chrome.

4. Copy the nearest shipped example

The pattern example pages already combine shell choice, hierarchy, surfaces, primitives, and behavior hooks in one place without leaving the docs navigation.

Admin dashboard Topbar, sidebar, stats, tables
Good first copy when the page is an application surface with navigation and dense operational content.
Admin settings Settings sections and destructive flows
Good first copy when the page is a slower settings workflow with grouped fields and secondary descriptions.
Auth login Narrow, single-task entry screens
Good first copy when the page needs visual quiet and should stay centered around one form task.
Public home Hero, promo, calmer page rhythm
Good first copy when the page is marketing-led, editorial, or public-facing rather than application-heavy.
Playground Test HTML before you integrate
Use this when you already have markup, want to try AI-generated snippets, or need to preview real WebBlocks assets without wiring a full page first.

5. Keep responsibilities clear

CSS and JS should keep their own jobs

Layout is CSS-driven. Overlays, tooltips, tabs, drawers, theme switching, and command palette behavior are JavaScript-driven through shipped hooks. Do not add JS to fake layout, and do not add CSS to fake missing behavior.

Markup

<button class="wb-btn wb-btn-primary">Save</button>
<div class="wb-card">...</div>
<table class="wb-table wb-table-hover">...</table>

Theme

<button data-wb-mode-set="dark">Dark</button>
<button data-wb-accent-set="forest">Forest</button>
<button data-wb-preset-set="minimal">Minimal</button>

Behavior

<button data-wb-toggle="modal" data-wb-target="#demoModal">Open dialog</button>
<button data-wb-toggle="modal" data-wb-target="#mediaViewer">Open viewer modal</button>
<button data-wb-toggle="drawer" data-wb-target="#demoDrawer">Filters</button>
<button data-wb-toggle="cmd" data-wb-target="#siteCmd">Search</button>