# @nexus-cross/crossx-design-system

The CROSSx design system — **color**, **typography** and **layout** tokens with
a swappable `DesignSystem` contract. Pure TypeScript, **no runtime dependencies**.

It is the single source of design tokens for `@nexus-cross/dapp-ui` and
`@nexus-cross/connect-kit-*`. A DApp can replace it wholesale by passing its own
`DesignSystem`-shaped object — see [Swapping](#swapping).

## Install

```sh
pnpm add @nexus-cross/crossx-design-system
```

## Tokens

Transcribed from the CROSSx Figma design system (Embeded v1.0.0):

| Axis | Figma node | Shape |
|---|---|---|
| color | `2151-1073` (file `Bta3fMnTynXtOtyZqI05fu`) | `bg`, `surface`, `content`, `border`, `accent.primary`, `system.{red,blue,orange,purple,green}`, `overlay`, `static` — light + dark |
| typography | `2019-2351` | `text`, `textMedium`, `textSemibold`, `label`, `labelSemibold`, `heading` (h1–h7), `display` |
| layout | `2060-1755` | `responsivePadding` (`sm`/`md`/`lg`) |

## CSS output

```ts
import { buildDesignSystemCss, defaultDesignSystem } from '@nexus-cross/crossx-design-system';

const css = buildDesignSystemCss(defaultDesignSystem);
// inject `css` into a <style>, then set data-ds-theme="light" | "dark"
```

- **Colors / layout** → `--ds-*` custom properties.
  `content.highest` → `var(--ds-content-highest)`,
  `accent.primary.default` → `var(--ds-accent-primary-default)`,
  `responsivePadding.md` → `var(--ds-responsive-padding-md)`.
  Dark is the `:root` default; light overlays via `[data-ds-theme="light"]`.
- **Typography** → utility classes, applied with `className`:
  `.ds-text-medium-sm`, `.ds-label-md`, `.ds-heading-h6`, `.ds-display-lg`.

## Picking a ramp

`accent.primary` is the **brand orange** (`#FF8438` / `#F0640D`).
`system.orange` is a separate **warning amber** (`#FC8B01` / `#E56F00`), and
`system.green` is the teal success ramp. The two oranges look similar but are
not interchangeable — choose by meaning:

| Intent | Ramp |
|---|---|
| Primary CTA, focus ring, active tab, brand highlight | `accent.primary` |
| Warning / caution copy and chips | `system.orange` |
| Success, completion, positive delta | `system.green` |

`ColorRamp.medium` is **optional** — only `system.orange` and `system.green`
define it, so `--ds-<ramp>-medium` is emitted for those two ramps alone.

## crossy-sdk bridge

```ts
import { toSdkColorOverrides, defaultDesignSystem } from '@nexus-cross/crossx-design-system';

const overrides = toSdkColorOverrides(defaultDesignSystem, 'dark'); // 12-key SDKColorOverrides
```

## Swapping

```ts
import type { DesignSystem } from '@nexus-cross/crossx-design-system';

const myDesignSystem: DesignSystem = { name: 'acme', colors: { light, dark }, typography, layout };
createCrossxConfig({ /* ... */, designSystem: myDesignSystem });
```

The contract is structural — a conforming object works even without importing
the type.

See [`docs/design-system/01-architecture.md`](../../docs/design-system/01-architecture.md).