# Getting started

Binary UIKit provides Svelte 5 components and theme tokens for product interfaces. Configure the private package source, install the library with its date peer dependency, and place `Provider` near the root of your app.

<h2 id="purpose">Purpose</h2>

Use the package when an application needs the Binary Dreams token system and its Svelte 5 components. The published library contains no locale state, so your application keeps control of translated labels and route language.

<h2 id="install">Install</h2>

Binary Dreams publishes Binary UIKit to a private OneDev registry. Add the scope mapping to the project `.npmrc`:

```ini
@binarydreams:registry=https://git.binarydreams.io/BinaryDreams/~npm/
```

Keep credentials out of the project. Add a OneDev access token that can read packages to your user-level `~/.npmrc`, replacing the placeholder with the token value:

```ini
//git.binarydreams.io/BinaryDreams/~npm/:_authToken=<ONEDEV_ACCESS_TOKEN>
```

Install the library and its date peer dependency:

```sh
npm install @binarydreams/uikit @internationalized/date
```

<h2 id="provider">Add Provider</h2>

`Provider` installs the default variables and utility styles. Keep document mode for an app shell. Use scoped mode when the kit lives inside a widget or shadow root.

```svelte
<script lang="ts">
	import { Button, Provider } from '@binarydreams/uikit';
</script>

<Provider>
	<Button>Save changes</Button>
</Provider>
```

<h2 id="anatomy">Application structure</h2>

`Provider` establishes the theme boundary. Components sit below it and import from the package root. Overlays use the same boundary, including inside a scoped widget or shadow root.

<h2 id="usage">First component</h2>

Start with one action and keep its label in your application translation layer. Pass component state through props or bindings. Use snippets for visible content and custom cells.

<h2 id="variants">Configuration</h2>

A bare `Provider` installs Graphite Light with the Graphite accent, Compact density, and Ledger radii. The supported 2x2 model pairs Graphite and Blueprint styles with Light and Dark modes. Apply Graphite Dark, Blueprint Light, or Blueprint Dark with `BD_PRESET_GRAPHITE_DARK`, `BD_PRESET_BLUEPRINT`, or `BD_PRESET_BLUEPRINT_DARK`. Marketing Buttons use the pill shape as a contextual exception. Use `scoped={true}` only when the kit must stay inside an embedded boundary.

<h2 id="typescript">TypeScript and SvelteKit</h2>

Import public components and types from `@binarydreams/uikit`. The package supports Svelte 5 and exposes declarations for component props, snippets, callbacks, and bindable values.

<h2 id="accessibility">Accessibility</h2>

Many interactive components use Bits UI, which provides strong keyboard, focus, and ARIA behavior by default. Applications remain responsible for task-specific labels, status messages, and contrast, including after theme overrides.

<h2 id="tokens">Tokens and style hooks</h2>

Use the exported token objects when application code needs token values. Component styles read `--bd-*` variables. Apply visual changes through `Provider` overrides instead of private component classes.

<h2 id="related">Next steps</h2>

Read [Colors](/docs/foundations/colors) before changing theme values. Open the [Button reference](/docs/components/button) for a compact component example.