open-index/open-npm huggingface dataset:
npm package: @osojicode/brand
Description: Ōsōji design tokens, CSS custom properties, and brand assets
Latest version: 0.1.0

# @osojicode/brand

Design tokens, CSS custom properties, and brand assets for the Ōsōji design system.

## Install

```bash
npm install @osojicode/brand
```

## CSS Custom Properties

```js
import '@osojicode/brand/dist/tokens.css';
```

Then reference tokens as CSS variables:

```css
body {
  font-family: var(--font-sans);
  color: var(--color-text-primary);
  background: var(--color-surface-primary);
}

h1 {
  font-family: var(--type-display-xl-family);
  font-size: var(--type-display-xl-size);
  font-weight: var(--type-display-xl-weight);
}
```

The CSS file contains three blocks:

- `:root` — all light-mode tokens (colors, typography, spacing, components, etc.)
- `[data-theme="dark"]` — dark-mode color and shadow overrides
- `@media (prefers-color-scheme: dark)` — system-preference dark mode

Set `data-theme="dark"` on `<html>` to force dark mode. Without it, the system preference applies automatically.

## JavaScript / TypeScript

```ts
import tokens from '@osojicode/brand';

// Every leaf is a var() reference for use in CSS-in-JS
tokens.color.surface.primary  // "var(--color-surface-primary)"
tokens.type.displayXl.size    // "var(--type-display-xl-size)"
tokens.spacing[4]             // "var(--spacing-4)"
```

Full TypeScript types are included via `dist/tokens.d.ts`.

## Assets

Brand assets are available at their package paths:

```
@osojicode/brand/assets/logomark-dark.svg
@osojicode/brand/assets/logomark-light.svg
@osojicode/brand/assets/logomark-full.svg
@osojicode/brand/assets/wordmark.svg
@osojicode/brand/assets/lockup-horizontal.svg
@osojicode/brand/assets/lockup-vertical.svg
@osojicode/brand/assets/favicon.ico
@osojicode/brand/assets/apple-touch-icon.png
```

## Token Categories

| Category | CSS prefix | Count |
|---|---|---|
| Colors (light + dark) | `--color-*` | 32 per mode |
| Font families | `--font-*` | 3 |
| Typography scale | `--type-*` | ~80 |
| Spacing | `--spacing-*` | 15 |
| Page layout | `--page-*` | 5 |
| Radii | `--radius-*` | 5 |
| Shadows (light + dark) | `--shadow-*` | 4 per mode |
| Motion | `--duration-*`, `--easing-*`, `--motion-*` | 9 |
| Breakpoints | `--bp-*` | 3 |
| Components | `--nav-*`, `--button-*`, `--card-*`, etc. | ~20 |

## Build

```bash
npm run build
```

Runs Style Dictionary v4 to generate `dist/tokens.css`, `dist/tokens.js`, and `dist/tokens.d.ts` from `tokens/osoji-design-tokens.json`.

## Design Principles

The token file encodes these principles (see `tokens/meta.json`):

1. Warm neutrals over cool grays — the palette is earth, not steel
2. Restraint over saturation — accents whisper, they don't shout
3. Typography carries the hierarchy — not color, not size alone
4. Generous whitespace is structural, not decorative
5. Dark mode is warm charcoal with pale ink, not inverted white