Getting started

01 Install

Already inside a SvelteKit project? The same add-on runs there too, and does this step and the next one in one go:

bunx sv add @urbicon-ui

By hand it is one package with zero runtime dependencies: compiled Svelte plus a CSS token file. Only what you import ends up in your bundle, and any package manager works.

bun add @urbicon-ui/blocks

02 Import the tokens

On the add-on path this is already done — read it to know what is in your project. The design system arrives as CSS, and Tailwind 4 does the plumbing, so if Tailwind isn’t part of your project yet, add the Vite plugin first (already there? skip ahead):

// vite.config.js
import { sveltekit } from '@sveltejs/kit/vite';
// no SvelteKit? swap it for svelte()
// from '@sveltejs/vite-plugin-svelte'
import tailwindcss from '@tailwindcss/vite';

export default {
  plugins: [tailwindcss(), sveltekit()]
};

Then two imports: Tailwind, and the token sheet — OKLCH color ramps, semantic tokens, typography, spacing, and dark mode via light-dark(). The blocks stylesheet brings its own @source directives, so Tailwind finds the components’ classes without extra config. Load the file once, wherever your app loads CSS: import './app.css' in +layout.svelte for SvelteKit, in your entry module src/main.js for plain Vite + Svelte:

/* app.css */
@import 'tailwindcss';
@import '@urbicon-ui/blocks/style/index.css';

03 Your first component

Import and render — no provider, no context setup. This is the booking widget from Fermata, the quiet hotel group every demo on this site runs on, and it’s three components speaking one grammar: label, bind:value and intent mean the same thing everywhere. The exact same code runs live in the “Your app so far” preview — book yourself a night.

<script>
  import { Badge, Button, Input, Select } from '@urbicon-ui/blocks';

  let name = $state('');
  let room = $state('garden');
  let booked = $state(false);
</script>

<Input label="Your name" bind:value={name} placeholder="Ada" />

<Select
  label="Room"
  options={[
    { label: 'Garden Room — €300', value: 'garden' },
    { label: 'Corner Room — €360', value: 'corner' }
  ]}
  bind:value={room}
/>

<Button intent="primary" onclick={() => (booked = true)} disabled={!name}>
  Reserve
</Button>

{#if booked && name}
  <Badge intent="success">Booked — see you in September, {name}.</Badge>
{/if}

04 Make it yours

Every component reads semantic tokens, so theming means overriding custom properties in Tailwind’s @theme — no component needs to know. The preview’s four paints are this site’s own room colours, one per component family; flip one and watch every component follow. In your codebase it is a declaration in your own stylesheet:

/* app.css */
@import 'tailwindcss';
@import '@urbicon-ui/blocks/style/index.css';

@theme {
  /* Override the primary ramp — every component follows it */
  --color-primary-500: oklch(0.64 0.16 40); /* warm terracotta */
}