@nexus-cross/crossx-design-system 1.3.0

package/README.md

@@ -0,0 +1,63 @@
+# @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 | `2032-6584` | `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`.
+
+## 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).

package/dist/index.d.ts

@@ -0,0 +1,273 @@
+/**
+ * The `DesignSystem` contract.
+ *
+ * This is the **swap seam**: a DApp can implement this interface with its own
+ * values and pass it to `createCrossxConfig({ designSystem })` instead of using
+ * `defaultDesignSystem`. The interface is structural, so a conforming object
+ * works even without importing these types.
+ *
+ * Names mirror the CROSSx Figma design system (Embeded v1.0.0):
+ *   - color  : `2032-6584` (embeded-color)
+ *   - type   : `2019-2351`
+ *   - layout : `2060-1755` (responsive-padding)
+ *
+ * No env types leak through — every value is a plain CSS string or number.
+ */
+/**
+ * A semantic color ramp shared by `accent.*` and every `system.*` color.
+ * `on` / `onInverted` are the readable foreground placed on top of the color.
+ */
+interface ColorRamp {
+    /** Foreground on top of `default` (e.g. text on a filled button). */
+    on: string;
+    /** The base color. */
+    default: string;
+    /** Stronger / hover variant. */
+    high: string;
+    /** Tinted surface (subtle filled background). */
+    low: string;
+    /** Faintest tinted surface. */
+    lowest: string;
+    /** Foreground for the inverted (dark-on-light / light-on-dark) context. */
+    onInverted: string;
+}
+/**
+ * A full set of color roles for one theme mode. The `light` and `dark`
+ * `ColorScale`s are parallel structures — same keys, mode-specific values.
+ */
+interface ColorScale {
+    /** Page / app root background. */
+    bg: {
+        default: string;
+        dim: string;
+    };
+    /** Raised surfaces (cards, sheets, hover fills). */
+    surface: {
+        default: string;
+        medium: string;
+        high: string;
+        dim: string;
+        inverted: string;
+    };
+    /** Text & icon colors. Note: no `default` step — `highest` is the strongest. */
+    content: {
+        highest: string;
+        high: string;
+        medium: string;
+        low: string;
+        lowest: string;
+        inverted: string;
+    };
+    /** Borders / dividers. Note: steps are `default`/`medium`/`high` (no `low`). */
+    border: {
+        default: string;
+        medium: string;
+        high: string;
+    };
+    /** Brand accent. */
+    accent: {
+        primary: ColorRamp;
+    };
+    /** Semantic status colors. */
+    system: {
+        red: ColorRamp;
+        blue: ColorRamp;
+        orange: ColorRamp;
+        purple: ColorRamp;
+        green: ColorRamp;
+    };
+    /** Scrim behind modals / drawers. */
+    overlay: {
+        dim: string;
+        subtle: string;
+    };
+    /** Mode-independent absolutes. */
+    static: {
+        white: string;
+        black: string;
+    };
+}
+/**
+ * One text style. `fontSize` is px, `lineHeight` is a unitless multiplier,
+ * `letterSpacing` is a percentage (Figma convention; `-1` → `-0.01em`).
+ */
+interface TypeStyle {
+    fontFamily: string;
+    fontSize: number;
+    fontWeight: number;
+    lineHeight: number;
+    letterSpacing: number;
+}
+type TextSize = '2xs' | 'xs' | 'sm' | 'base' | 'lg' | 'xl';
+/** `text-semibold` has no `2xs`. */
+type TextSemiboldSize = 'xs' | 'sm' | 'base' | 'lg' | 'xl';
+type LabelSize = 'xs' | 'sm' | 'md' | 'lg';
+type LabelSemiboldSize = 'sm' | 'md' | 'lg';
+type HeadingSize = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'h7';
+type DisplaySize = 'sm' | 'md' | 'lg';
+interface DesignSystemTypography {
+    text: Record<TextSize, TypeStyle>;
+    textMedium: Record<TextSize, TypeStyle>;
+    textSemibold: Record<TextSemiboldSize, TypeStyle>;
+    label: Record<LabelSize, TypeStyle>;
+    labelSemibold: Record<LabelSemiboldSize, TypeStyle>;
+    heading: Record<HeadingSize, TypeStyle>;
+    display: Record<DisplaySize, TypeStyle>;
+}
+/**
+ * Layout scales. Values are px.
+ *
+ * `responsivePadding` is the container side-padding per breakpoint bucket
+ * (`sm`/`md`/`lg`). Breakpoint wiring (which bucket applies when) is a
+ * consumer concern — the tokens only define the values.
+ */
+interface DesignSystemLayout {
+    responsivePadding: {
+        sm: number;
+        md: number;
+        lg: number;
+    };
+}
+/**
+ * Shadow / blur effects. Values are ready-to-use CSS:
+ * `shadowModal.*` are `box-shadow` values, `bgBlur7` is a `filter`/
+ * `backdrop-filter` value.
+ */
+interface DesignSystemEffects {
+    /** Modal / popover drop shadow, per theme mode. */
+    shadowModal: {
+        light: string;
+        dark: string;
+    };
+    /** Background blur (Figma `BG_blur7`, 7px radius). */
+    bgBlur7: string;
+}
+interface DesignSystem {
+    /** Identifier (e.g. `'crossx'`). Surfaced for debugging / theme switching. */
+    name: string;
+    colors: {
+        light: ColorScale;
+        dark: ColorScale;
+    };
+    typography: DesignSystemTypography;
+    layout: DesignSystemLayout;
+    effects: DesignSystemEffects;
+}
+type ThemeMode = 'light' | 'dark';
+
+/**
+ * Default color palette — transcribed verbatim from CROSSx Figma
+ * `embeded-color` (node `2032-6584`), light + dark modes.
+ *
+ * Black/white alpha steps (content, border, overlay) are emitted as `rgba()`.
+ * Note: `accent.primary` and `system.green` share the same brand-teal ramp.
+ */
+
+declare const lightColors: ColorScale;
+declare const darkColors: ColorScale;
+
+/**
+ * Default typography scale — transcribed from CROSSx Figma type styles
+ * (node `2019-2351`). All Inter. `letterSpacing` is a percentage:
+ * the `text*` families use -1 (-0.01em); label / heading / display use 0.
+ */
+
+declare const typography: DesignSystemTypography;
+
+/**
+ * Default layout tokens — transcribed from CROSSx Figma `layout`
+ * (node `2060-1755`, `responsive-padding`). Values are px.
+ */
+
+declare const layout: DesignSystemLayout;
+
+/**
+ * Default effect tokens — transcribed from CROSSx Figma `Effects` collection.
+ *
+ * - `shadow-modal-light`: drop shadow, color #0000 @ 15%, offset (0,4), blur 30, spread -1
+ * - `shadow-modal-dark` : drop shadow, color #0000 @ 70%, offset (0,4), blur 30, spread -1
+ * - `BG_blur7`          : background blur, Figma radius 7 → CSS blur(3.5px)
+ *                         (Figma's background-blur radius ≈ 2× the CSS blur,
+ *                         per Dev Mode codegen)
+ */
+
+declare const effects: DesignSystemEffects;
+
+/**
+ * The default CROSSx design system — assembled from the Figma-transcribed
+ * color, typography and layout tokens. Passed to `createCrossxConfig` when a
+ * DApp does not supply its own `designSystem`.
+ */
+
+declare const defaultDesignSystem: DesignSystem;
+
+/**
+ * Turn a {@link DesignSystem} into CSS.
+ *
+ * - **Colors** flatten deterministically to `--ds-*` custom properties under
+ *   per-mode selectors (dark is the `:root` default; light is overlaid via
+ *   `[data-ds-theme="light"]`).
+ * - **Layout** tokens emit as mode-independent `--ds-*` properties.
+ * - **Typography** emits as utility classes (`.ds-text-medium-sm` …) carrying
+ *   the full font shorthand — applied via `className`, not CSS variables.
+ *
+ * The walk is generic, so any conforming `DesignSystem` (incl. a DApp's own)
+ * produces predictable names.
+ */
+
+/** `--ds-*` declarations for one mode's color scale (no selector wrapper). */
+declare function buildColorVars(scale: ColorScale): string;
+/** `--ds-*` declarations for layout tokens (px). */
+declare function buildLayoutVars(layout: DesignSystemLayout): string;
+/** `.ds-<group>-<size>` utility classes for every type style. */
+declare function buildTypographyClasses(typography: DesignSystemTypography): string;
+interface BuildCssOptions {
+    /** Selector that receives the default (dark) palette. Defaults to `:root`. */
+    scope?: string;
+}
+/**
+ * Full stylesheet: color vars (both modes) + layout vars + typography classes.
+ * Attach the returned string to a `<style>` once; flip palettes by setting
+ * `data-ds-theme="light" | "dark"` on any ancestor.
+ */
+declare function buildDesignSystemCss(ds: DesignSystem, opts?: BuildCssOptions): string;
+
+/**
+ * Project a {@link DesignSystem} down to the 12-key color contract that
+ * crossy-sdk's embedded modal requires (`SDKColorOverrides`).
+ *
+ * This is **not** the rejected `--cck-*` alias table — it is the unavoidable
+ * adapter for handing colors to a third-party SDK whose theming API is fixed.
+ * `@nexus-cross/connect-kit-wagmi` calls this at connector-creation time.
+ *
+ * The local shape is kept structural so this package does not harden on
+ * crossy-sdk internals.
+ */
+
+interface SdkColorOverrides {
+    primary?: string;
+    secondary?: string;
+    onPrimary?: string;
+    borderDefault?: string;
+    borderSubtle?: string;
+    textIconPrimary?: string;
+    textIconSecondary?: string;
+    textIconTertiary?: string;
+    surfaceDefault?: string;
+    surfaceSubtle?: string;
+    bg?: string;
+    error?: string;
+}
+declare function toSdkColorOverrides(ds: DesignSystem, mode: ThemeMode): SdkColorOverrides;
+
+/**
+ * `@nexus-cross/crossx-design-system`
+ *
+ * The CROSSx design system: a swappable `DesignSystem` contract, the default
+ * Figma-derived token set, and helpers to emit CSS / project to crossy-sdk.
+ */
+
+/** Convenience: the default design system's full stylesheet. */
+declare function getDefaultDesignSystemCss(): string;
+
+export { type BuildCssOptions, type ColorRamp, type ColorScale, type DesignSystem, type DesignSystemEffects, type DesignSystemLayout, type DesignSystemTypography, type DisplaySize, type HeadingSize, type LabelSemiboldSize, type LabelSize, type SdkColorOverrides, type TextSemiboldSize, type TextSize, type ThemeMode, type TypeStyle, buildColorVars, buildDesignSystemCss, buildLayoutVars, buildTypographyClasses, darkColors, defaultDesignSystem, effects, getDefaultDesignSystemCss, layout, lightColors, toSdkColorOverrides, typography };

package/dist/index.js

@@ -0,0 +1,7 @@
+var a={bg:{default:"#FFFFFF",dim:"#F5F7FA"},surface:{default:"#FFFFFF",medium:"#F5F7FA",high:"#EDF1F2",dim:"#F9FAFB",inverted:"#1E232E"},content:{highest:"#000000",high:"#000000D9",medium:"#000000A6",low:"#00000066",lowest:"#00000040",inverted:"#FFFFFF"},border:{default:"#00000012",medium:"#0000002E",high:"#000000A6"},accent:{primary:{on:"#FFFFFF",default:"#00B4B7",high:"#00A0A2",low:"#E7F9F8",lowest:"#F0FAF9",onInverted:"#00E8C9"}},system:{red:{on:"#FFFFFF",default:"#DA0B2E",high:"#D20609",low:"#FFEEEE",lowest:"#FFF6F6",onInverted:"#FF0F47"},blue:{on:"#FFFFFF",default:"#0888DE",high:"#008DCA",low:"#ECF8FC",lowest:"#F5FBFE",onInverted:"#0FC7FF"},orange:{on:"#FFFFFF",default:"#FC8B01",high:"#E56F00",low:"#FCF5E9",lowest:"#FFF9F2",onInverted:"#FF9F21"},purple:{on:"#FFFFFF",default:"#7E54F4",high:"#7346F3",low:"#F5F3FF",lowest:"#F9F8FF",onInverted:"#9B78FF"},green:{on:"#FFFFFF",default:"#00B4B7",high:"#00A0A2",low:"#E7F9F8",lowest:"#F0FAF9",onInverted:"#00E8C9"}},overlay:{dim:"#00000080",subtle:"#00000005"},static:{white:"#FFFFFF",black:"#000000"}},g={bg:{default:"#1E232E",dim:"#191D27"},surface:{default:"#1E232E",medium:"#252B39",high:"#363B4C",dim:"#161B26",inverted:"#FFFFFF"},content:{highest:"#FFFFFF",high:"#FFFFFFD9",medium:"#FFFFFFA6",low:"#FFFFFF66",lowest:"#FFFFFF40",inverted:"#000000"},border:{default:"#FFFFFF12",medium:"#FFFFFF2E",high:"#FFFFFFA6"},accent:{primary:{on:"#000000",default:"#00CEB2",high:"#00E8C9",low:"#123235",lowest:"#102E31",onInverted:"#00A0A2"}},system:{red:{on:"#FFFFFF",default:"#CD0C40",high:"#FF0F47",low:"#461420",lowest:"#39151E",onInverted:"#D20609"},blue:{on:"#FFFFFF",default:"#0888DE",high:"#0FC7FF",low:"#143446",lowest:"#162B3B",onInverted:"#008DCA"},orange:{on:"#000000",default:"#FF9F21",high:"#FF9F21",low:"#342B1E",lowest:"#2E2820",onInverted:"#E56F00"},purple:{on:"#FFFFFF",default:"#744FDC",high:"#9B78FF",low:"#2E2854",lowest:"#2A2740",onInverted:"#7346F3"},green:{on:"#000000",default:"#00CEB2",high:"#00E8C9",low:"#123235",lowest:"#102E31",onInverted:"#00A0A2"}},overlay:{dim:"#000000B3",subtle:"#00000026"},static:{white:"#FFFFFF",black:"#000000"}};var x="Inter, sans-serif",e=(t,o,r,n)=>({fontFamily:x,fontSize:t,fontWeight:o,lineHeight:r,letterSpacing:n}),d={text:{"2xs":e(10,400,1.5,-1),xs:e(12,400,1.5,-1),sm:e(14,400,1.5,-1),base:e(16,400,1.5,-1),lg:e(18,400,1.5,-1),xl:e(20,400,1.5,-1)},textMedium:{"2xs":e(10,500,1.5,-1),xs:e(12,500,1.5,-1),sm:e(14,500,1.5,-1),base:e(16,500,1.5,-1),lg:e(18,500,1.5,-1),xl:e(20,500,1.5,-1)},textSemibold:{xs:e(12,600,1.5,-1),sm:e(14,600,1.5,-1),base:e(16,600,1.5,-1),lg:e(18,600,1.5,-1),xl:e(20,600,1.5,-1)},label:{xs:e(10,500,1,0),sm:e(12,500,1,0),md:e(14,500,1,0),lg:e(16,500,1,0)},labelSemibold:{sm:e(12,600,1,0),md:e(14,600,1,0),lg:e(16,600,1,0)},heading:{h7:e(14,600,1.25,0),h6:e(16,600,1.25,0),h5:e(18,600,1.25,0),h4:e(20,600,1.25,0),h3:e(24,600,1.25,0),h2:e(30,700,1.25,0),h1:e(36,700,1.25,0)},display:{sm:e(36,700,1.25,0),md:e(48,700,1.25,0),lg:e(60,700,1.25,0)}};var m={responsivePadding:{sm:16,md:24,lg:32}};var c={shadowModal:{light:"0px 4px 30px -1px rgba(0, 0, 0, 0.15)",dark:"0px 4px 30px -1px rgba(0, 0, 0, 0.7)"},bgBlur7:"blur(3.5px)"};var u={name:"crossx",colors:{light:a,dark:g},typography:d,layout:m,effects:c};var y="--ds";function F(t){return t.replace(/([a-z0-9])([A-Z])/g,"$1-$2").toLowerCase()}function h(t,o,r){for(let[n,s]of Object.entries(t)){let i=[...o,F(n)];typeof s=="string"?r.push(`  ${y}-${i.join("-")}: ${s};`):s&&typeof s=="object"&&h(s,i,r)}}function p(t){let o=[];return h(t,[],o),o.join(`
+`)}function b(t){let o=[];for(let[r,n]of Object.entries(t)){let s=F(r);for(let[i,l]of Object.entries(n))o.push(`  ${y}-${s}-${F(i)}: ${l}px;`)}return o.join(`
+`)}function C(t){return t===0?"0":`${t/100}em`}function D(t,o){return[`.${t} {`,`  font-family: ${o.fontFamily};`,`  font-size: ${o.fontSize}px;`,`  font-weight: ${o.fontWeight};`,`  line-height: ${o.lineHeight};`,`  letter-spacing: ${C(o.letterSpacing)};`,"}"].join(`
+`)}function S(t){let o=[];for(let[r,n]of Object.entries(t)){let s=F(r);for(let[i,l]of Object.entries(n))o.push(D(`ds-${s}-${i}`,l))}return o.join(`
+
+`)}function f(t,o={}){return[`${o.scope??":root"}, [data-ds-theme="dark"] {`,p(t.colors.dark),b(t.layout),`  --ds-shadow-modal: ${t.effects.shadowModal.dark};`,`  --ds-bg-blur-7: ${t.effects.bgBlur7};`,"}","",'[data-ds-theme="light"] {',p(t.colors.light),`  --ds-shadow-modal: ${t.effects.shadowModal.light};`,"}","",S(t.typography),""].join(`
+`)}function w(t,o){let r=t.colors[o];return{primary:r.accent.primary.default,secondary:r.system.red.default,onPrimary:r.accent.primary.on,error:r.system.red.default,bg:r.bg.default,surfaceDefault:r.surface.medium,surfaceSubtle:r.surface.high,borderDefault:r.border.default,borderSubtle:r.border.medium,textIconPrimary:r.content.highest,textIconSecondary:r.content.medium,textIconTertiary:r.content.low}}function R(){return f(u)}export{p as buildColorVars,f as buildDesignSystemCss,b as buildLayoutVars,S as buildTypographyClasses,g as darkColors,u as defaultDesignSystem,c as effects,R as getDefaultDesignSystemCss,m as layout,a as lightColors,w as toSdkColorOverrides,d as typography};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@nexus-cross/crossx-design-system",
+  "version": "1.3.0",
+  "description": "CROSSx design system — color, typography and layout tokens with a swappable DesignSystem contract",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}