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';

Every further @urbicon-ui/* package that ships components ships a stylesheet of its own — import it after blocks. Without it, the classes only that package uses compile to nothing, and nothing reports it. bunx urbicon init prints the import list for what is in node_modules.

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 */
}