# Riverty Design System Packages Relationship

## Overview

Three public packages form the foundation. `@riverty/web-components` depends on tokens at runtime but does **not** bundle them — the application must load them separately.

```
@riverty/design-tokens          ← source of truth for all visual values
        ↓                ↘
@riverty/css-framework    @riverty/web-components
(also bundles fonts)      (Shadow DOM components)
```

## Package Responsibilities

### `@riverty/design-tokens`

Generates CSS custom properties and SCSS variables from JSON token sources via Style Dictionary.

### `@riverty/css-framework`

A Sass-compiled CSS layer built on top of `@riverty/design-tokens`. Bundles tokens + `@riverty/fonts` — **no separate installation needed** for either when using `@riverty/css-framework`.

### `@riverty/web-components`

Stencil-compiled custom elements. Each component:

- Operates inside **Shadow DOM** — styles are fully encapsulated.
- References `var(--r-*)` CSS variables from `@riverty/design-tokens` inside its own `.scss` — tokens must be loaded globally.
- Does **not** import token values themselves — relies on CSS custom properties being available at runtime.

## Dependency Graph Summary

```
@riverty/design-tokens
  └── consumed by @riverty/css-framework (bundles it)
  └── consumed by @riverty/web-components (runtime CSS variables, not bundled)
  └── consumed by host app directly (when not using css-framework)

@riverty/fonts
  └── consumed by @riverty/css-framework (bundled)

@riverty/css-framework
  └── optional peer for apps using web-components
```