@vllnt/ui-core 0.1.0-canary.20260917105553.sha7466647a4ba5

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to `@vllnt/ui-core` are documented in this file.
+
+## [Unreleased]
+
+### Added
+
+- Initial platform-neutral token, theme, platform metadata, and portable component contracts.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 vllnt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @vllnt/ui-core
+
+Platform-neutral design tokens and portable component contracts shared by the VLLNT UI web and React Native renderers.
+
+> Experimental and source-only. The first synchronized `canary` publication with `@vllnt/ui-native` is planned but is not available yet.
+
+The package base is **0.1.0**. Core and Native will use the same `0.1.0-canary.<run>.sha<commit>` prerelease; this base does not establish npm availability. Workflow publication is unconditionally disabled pending a separate hardening/enabling review. Stable promotion also requires a separate reviewed change after verification; see [releasing](../../docs/RELEASING.md).
+
+## Planned install
+
+After the first canary publication:
+
+```bash
+pnpm add @vllnt/ui-core@canary
+```
+
+Until then, use this package only from the repository workspace.
+
+## Use
+
+```ts
+import {
+  createNativeTheme,
+  designTokens,
+  type ButtonVariant,
+} from "@vllnt/ui-core";
+
+const theme = createNativeTheme("dark", {
+  colors: { primary: "#f5f5f5" },
+});
+```
+
+Exports include the authored token object, generated React Native-compatible themes, and renderer-neutral option unions for the pilot components. The JSON contracts are also available from `@vllnt/ui-core/tokens.json` and `@vllnt/ui-core/contracts.json`.
+
+`packages/design/tokens.json` and `packages/design/component-contracts.json` are the authored sources. Run `pnpm -F @vllnt/design-source tokens:generate` after changing either file. Generated artifacts are committed and checked for drift in CI.

package/component-contracts.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "./component-contracts.schema.json",
+  "version": "0.1.0",
+  "components": {
+    "badge": {
+      "variants": ["default", "destructive", "outline", "secondary"]
+    },
+    "button": {
+      "sizes": ["default", "icon", "lg", "sm"],
+      "variants": [
+        "default",
+        "destructive",
+        "ghost",
+        "link",
+        "outline",
+        "secondary"
+      ]
+    },
+    "card": {
+      "parts": [
+        "Card",
+        "CardHeader",
+        "CardTitle",
+        "CardDescription",
+        "CardContent",
+        "CardFooter"
+      ]
+    },
+    "heading": {
+      "levels": [1, 2, 3, 4, 5, 6]
+    },
+    "text": {
+      "sizes": ["base", "caption", "lead", "small"],
+      "tones": ["default", "muted"],
+      "weights": ["medium", "normal", "semibold"]
+    }
+  }
+}

package/component-contracts.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "VLLNT UI portable component contracts",
+  "type": "object",
+  "required": ["version", "components"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "components": {
+      "type": "object",
+      "required": ["badge", "button", "card", "heading", "text"],
+      "properties": {
+        "badge": { "$ref": "#/$defs/variants" },
+        "button": {
+          "type": "object",
+          "required": ["sizes", "variants"],
+          "properties": {
+            "sizes": { "$ref": "#/$defs/stringList" },
+            "variants": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "card": {
+          "type": "object",
+          "required": ["parts"],
+          "properties": {
+            "parts": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "heading": {
+          "type": "object",
+          "required": ["levels"],
+          "properties": {
+            "levels": {
+              "type": "array",
+              "items": { "type": "integer", "minimum": 1, "maximum": 6 },
+              "minItems": 6,
+              "maxItems": 6,
+              "uniqueItems": true
+            }
+          },
+          "additionalProperties": false
+        },
+        "text": {
+          "type": "object",
+          "required": ["sizes", "tones", "weights"],
+          "properties": {
+            "sizes": { "$ref": "#/$defs/stringList" },
+            "tones": { "$ref": "#/$defs/stringList" },
+            "weights": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$defs": {
+    "stringList": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "variants": {
+      "type": "object",
+      "required": ["variants"],
+      "properties": {
+        "variants": { "$ref": "#/$defs/stringList" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/dist/index.d.ts

@@ -0,0 +1,495 @@
+declare const designTokens: {
+    readonly $schema: "./tokens.schema.json";
+    readonly name: "VLLNT UI";
+    readonly version: "0.4.0";
+    readonly source: {
+        readonly guide: "../../DESIGN.md";
+        readonly theme: "../ui/themes/default.css";
+    };
+    readonly color: {
+        readonly format: "oklch-channel";
+        readonly semantic: {
+            readonly background: {
+                readonly cssVariable: "--background";
+                readonly light: "1 0 0";
+                readonly dark: "0 0 0";
+                readonly role: "Page and app surface";
+            };
+            readonly foreground: {
+                readonly cssVariable: "--foreground";
+                readonly light: "0.1445 0 0";
+                readonly dark: "0.9848 0 0";
+                readonly role: "Primary text and icon color";
+            };
+            readonly card: {
+                readonly cssVariable: "--card";
+                readonly light: "1 0 0";
+                readonly dark: "0.1445 0 0";
+                readonly role: "Card and contained surface";
+            };
+            readonly cardForeground: {
+                readonly cssVariable: "--card-foreground";
+                readonly light: "0.1445 0 0";
+                readonly dark: "0.9848 0 0";
+                readonly role: "Text on card surfaces";
+            };
+            readonly popover: {
+                readonly cssVariable: "--popover";
+                readonly light: "1 0 0";
+                readonly dark: "0.1445 0 0";
+                readonly role: "Popover, menu, and floating surface";
+            };
+            readonly popoverForeground: {
+                readonly cssVariable: "--popover-foreground";
+                readonly light: "0.1445 0 0";
+                readonly dark: "0.9848 0 0";
+                readonly role: "Text on popover surfaces";
+            };
+            readonly primary: {
+                readonly cssVariable: "--primary";
+                readonly light: "0.2044 0 0";
+                readonly dark: "0.9848 0 0";
+                readonly role: "Primary action surface";
+            };
+            readonly primaryForeground: {
+                readonly cssVariable: "--primary-foreground";
+                readonly light: "0.9848 0 0";
+                readonly dark: "0.2044 0 0";
+                readonly role: "Text on primary action surfaces";
+            };
+            readonly secondary: {
+                readonly cssVariable: "--secondary";
+                readonly light: "0.9703 0 0";
+                readonly dark: "0.2686 0 0";
+                readonly role: "Secondary action surface";
+            };
+            readonly secondaryForeground: {
+                readonly cssVariable: "--secondary-foreground";
+                readonly light: "0.2044 0 0";
+                readonly dark: "0.9848 0 0";
+                readonly role: "Text on secondary action surfaces";
+            };
+            readonly muted: {
+                readonly cssVariable: "--muted";
+                readonly light: "0.9703 0 0";
+                readonly dark: "0.2686 0 0";
+                readonly role: "Subtle surface";
+            };
+            readonly mutedForeground: {
+                readonly cssVariable: "--muted-foreground";
+                readonly light: "0.5555 0 0";
+                readonly dark: "0.7153 0 0";
+                readonly role: "Secondary text";
+            };
+            readonly accent: {
+                readonly cssVariable: "--accent";
+                readonly light: "0.9703 0 0";
+                readonly dark: "0.2686 0 0";
+                readonly role: "Hover and active surface";
+            };
+            readonly accentForeground: {
+                readonly cssVariable: "--accent-foreground";
+                readonly light: "0.2044 0 0";
+                readonly dark: "0.9848 0 0";
+                readonly role: "Text on accent surfaces";
+            };
+            readonly destructive: {
+                readonly cssVariable: "--destructive";
+                readonly light: "0.6368 0.2078 25.326";
+                readonly dark: "0.3959 0.1331 25.721";
+                readonly role: "Destructive action and error surface";
+            };
+            readonly destructiveForeground: {
+                readonly cssVariable: "--destructive-foreground";
+                readonly light: "0.9848 0 0";
+                readonly dark: "0.9848 0 0";
+                readonly role: "Text on destructive surfaces";
+            };
+            readonly border: {
+                readonly cssVariable: "--border";
+                readonly light: "0.9219 0 0";
+                readonly dark: "0.2686 0 0";
+                readonly role: "Hairline divider";
+            };
+            readonly input: {
+                readonly cssVariable: "--input";
+                readonly light: "0.9219 0 0";
+                readonly dark: "0.2686 0 0";
+                readonly role: "Input border";
+            };
+            readonly ring: {
+                readonly cssVariable: "--ring";
+                readonly light: "0.1445 0 0";
+                readonly dark: "0.8697 0 0";
+                readonly role: "Focus ring";
+            };
+        };
+    };
+    readonly typography: {
+        readonly fontFamily: {
+            readonly sans: {
+                readonly cssVariable: "--font-sans";
+                readonly value: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif";
+                readonly role: "Body + UI text";
+            };
+            readonly display: {
+                readonly cssVariable: "--font-display";
+                readonly value: "var(--font-sans)";
+                readonly role: "Heading + Display face — override per theme for a brand type identity (defaults to sans)";
+            };
+            readonly mono: {
+                readonly cssVariable: "--font-mono";
+                readonly value: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace";
+                readonly role: "Code + tabular";
+            };
+        };
+        readonly fontWeight: {
+            readonly heading: {
+                readonly cssVariable: "--font-weight-heading";
+                readonly value: 600;
+                readonly role: "Heading primitive weight — theme-overridable";
+            };
+            readonly display: {
+                readonly cssVariable: "--font-weight-display";
+                readonly value: 600;
+                readonly role: "Display primitive weight — theme-overridable";
+            };
+            readonly body: {
+                readonly value: 400;
+            };
+            readonly caption: {
+                readonly value: 500;
+            };
+        };
+        readonly scale: {
+            readonly display: {
+                readonly cssVariable: "--font-size-display";
+                readonly fontSize: "3.75rem";
+                readonly lineHeight: "1.05";
+                readonly lineHeightCssVariable: "--line-height-display";
+            };
+            readonly h1: {
+                readonly cssVariable: "--font-size-h1";
+                readonly fontSize: "3rem";
+                readonly lineHeight: "1.1";
+                readonly lineHeightCssVariable: "--line-height-h1";
+            };
+            readonly h2: {
+                readonly cssVariable: "--font-size-h2";
+                readonly fontSize: "2.25rem";
+                readonly lineHeight: "1.2";
+                readonly lineHeightCssVariable: "--line-height-h2";
+            };
+            readonly h3: {
+                readonly cssVariable: "--font-size-h3";
+                readonly fontSize: "1.875rem";
+                readonly lineHeight: "1.25";
+                readonly lineHeightCssVariable: "--line-height-h3";
+            };
+            readonly h4: {
+                readonly cssVariable: "--font-size-h4";
+                readonly fontSize: "1.5rem";
+                readonly lineHeight: "1.3";
+                readonly lineHeightCssVariable: "--line-height-h4";
+            };
+            readonly h5: {
+                readonly cssVariable: "--font-size-h5";
+                readonly fontSize: "1.25rem";
+                readonly lineHeight: "1.4";
+                readonly lineHeightCssVariable: "--line-height-h5";
+            };
+            readonly h6: {
+                readonly cssVariable: "--font-size-h6";
+                readonly fontSize: "1.125rem";
+                readonly lineHeight: "1.5";
+                readonly lineHeightCssVariable: "--line-height-h6";
+            };
+            readonly bodyLarge: {
+                readonly cssVariable: "--font-size-body-lg";
+                readonly fontSize: "1.125rem";
+                readonly lineHeight: "1.7";
+                readonly lineHeightCssVariable: "--line-height-body-lg";
+            };
+            readonly body: {
+                readonly cssVariable: "--font-size-body";
+                readonly fontSize: "1rem";
+                readonly lineHeight: "1.6";
+                readonly lineHeightCssVariable: "--line-height-body";
+            };
+            readonly bodySmall: {
+                readonly cssVariable: "--font-size-body-sm";
+                readonly fontSize: "0.875rem";
+                readonly lineHeight: "1.5";
+                readonly lineHeightCssVariable: "--line-height-body-sm";
+            };
+            readonly caption: {
+                readonly cssVariable: "--font-size-caption";
+                readonly fontSize: "0.75rem";
+                readonly lineHeight: "1.4";
+                readonly lineHeightCssVariable: "--line-height-caption";
+            };
+        };
+    };
+    readonly spacing: {
+        readonly unit: "4px";
+        readonly scale: {
+            readonly "1": "0.25rem";
+            readonly "2": "0.5rem";
+            readonly "3": "0.75rem";
+            readonly "4": "1rem";
+            readonly "6": "1.5rem";
+            readonly "8": "2rem";
+            readonly "12": "3rem";
+            readonly "16": "4rem";
+        };
+    };
+    readonly radius: {
+        readonly none: "0";
+        readonly sm: "0.25rem";
+        readonly md: "0.5rem";
+        readonly lg: "0.75rem";
+        readonly full: "9999px";
+    };
+    readonly elevation: {
+        readonly none: "none";
+        readonly sm: "0 1px 2px rgba(0, 0, 0, 0.05)";
+        readonly md: "0 4px 6px -1px rgba(0, 0, 0, 0.1)";
+        readonly lg: "0 10px 15px -3px rgba(0, 0, 0, 0.1)";
+    };
+    readonly motion: {
+        readonly duration: {
+            readonly fast: "100ms";
+            readonly base: "200ms";
+            readonly slow: "300ms";
+        };
+        readonly easing: {
+            readonly enter: "ease-out";
+            readonly exit: "ease-in";
+            readonly layout: "ease-in-out";
+        };
+        readonly reducedMotion: "Collapse durations to 1ms or skip non-essential motion.";
+    };
+    readonly iconography: {
+        readonly library: "lucide-react";
+        readonly size: {
+            readonly default: "1rem";
+            readonly compact: "0.875rem";
+            readonly large: "1.25rem";
+        };
+        readonly strokeWidth: 2;
+        readonly color: "currentColor";
+    };
+};
+declare const componentContracts: {
+    readonly $schema: "./component-contracts.schema.json";
+    readonly version: "0.1.0";
+    readonly components: {
+        readonly badge: {
+            readonly variants: readonly ["default", "destructive", "outline", "secondary"];
+        };
+        readonly button: {
+            readonly sizes: readonly ["default", "icon", "lg", "sm"];
+            readonly variants: readonly ["default", "destructive", "ghost", "link", "outline", "secondary"];
+        };
+        readonly card: {
+            readonly parts: readonly ["Card", "CardHeader", "CardTitle", "CardDescription", "CardContent", "CardFooter"];
+        };
+        readonly heading: {
+            readonly levels: readonly [1, 2, 3, 4, 5, 6];
+        };
+        readonly text: {
+            readonly sizes: readonly ["base", "caption", "lead", "small"];
+            readonly tones: readonly ["default", "muted"];
+            readonly weights: readonly ["medium", "normal", "semibold"];
+        };
+    };
+};
+declare const nativeTokens: {
+    readonly color: {
+        readonly dark: {
+            readonly background: "#050505";
+            readonly foreground: "#fafafa";
+            readonly card: "#0a0a0a";
+            readonly cardForeground: "#fafafa";
+            readonly popover: "#0a0a0a";
+            readonly popoverForeground: "#fafafa";
+            readonly primary: "#fafafa";
+            readonly primaryForeground: "#171717";
+            readonly secondary: "#262626";
+            readonly secondaryForeground: "#fafafa";
+            readonly muted: "#262626";
+            readonly mutedForeground: "#a3a3a3";
+            readonly accent: "#262626";
+            readonly accentForeground: "#fafafa";
+            readonly destructive: "#7f1d1d";
+            readonly destructiveForeground: "#fafafa";
+            readonly border: "#262626";
+            readonly input: "#262626";
+            readonly ring: "#d4d4d4";
+        };
+        readonly light: {
+            readonly background: "#ffffff";
+            readonly foreground: "#0a0a0a";
+            readonly card: "#ffffff";
+            readonly cardForeground: "#0a0a0a";
+            readonly popover: "#ffffff";
+            readonly popoverForeground: "#0a0a0a";
+            readonly primary: "#171717";
+            readonly primaryForeground: "#fafafa";
+            readonly secondary: "#f5f5f5";
+            readonly secondaryForeground: "#171717";
+            readonly muted: "#f5f5f5";
+            readonly mutedForeground: "#737373";
+            readonly accent: "#f5f5f5";
+            readonly accentForeground: "#171717";
+            readonly destructive: "#c92f32";
+            readonly destructiveForeground: "#fafafa";
+            readonly border: "#e5e5e5";
+            readonly input: "#e5e5e5";
+            readonly ring: "#0a0a0a";
+        };
+    };
+    readonly motion: {
+        readonly duration: {
+            readonly fast: 100;
+            readonly base: 200;
+            readonly slow: 300;
+        };
+    };
+    readonly radius: {
+        readonly none: 0;
+        readonly sm: 4;
+        readonly md: 8;
+        readonly lg: 12;
+        readonly full: 9999;
+    };
+    readonly spacing: {
+        readonly "1": 4;
+        readonly "2": 8;
+        readonly "3": 12;
+        readonly "4": 16;
+        readonly "6": 24;
+        readonly "8": 32;
+        readonly "12": 48;
+        readonly "16": 64;
+    };
+    readonly typography: {
+        readonly fontWeight: {
+            readonly heading: 600;
+            readonly display: 600;
+            readonly body: 400;
+            readonly caption: 500;
+        };
+        readonly scale: {
+            readonly display: {
+                readonly fontSize: 60;
+                readonly lineHeight: 63;
+            };
+            readonly h1: {
+                readonly fontSize: 48;
+                readonly lineHeight: 52.8;
+            };
+            readonly h2: {
+                readonly fontSize: 36;
+                readonly lineHeight: 43.2;
+            };
+            readonly h3: {
+                readonly fontSize: 30;
+                readonly lineHeight: 37.5;
+            };
+            readonly h4: {
+                readonly fontSize: 24;
+                readonly lineHeight: 31.2;
+            };
+            readonly h5: {
+                readonly fontSize: 20;
+                readonly lineHeight: 28;
+            };
+            readonly h6: {
+                readonly fontSize: 18;
+                readonly lineHeight: 27;
+            };
+            readonly bodyLarge: {
+                readonly fontSize: 18;
+                readonly lineHeight: 30.6;
+            };
+            readonly body: {
+                readonly fontSize: 16;
+                readonly lineHeight: 25.6;
+            };
+            readonly bodySmall: {
+                readonly fontSize: 14;
+                readonly lineHeight: 21;
+            };
+            readonly caption: {
+                readonly fontSize: 12;
+                readonly lineHeight: 16.8;
+            };
+        };
+    };
+};
+type BadgeVariant = (typeof componentContracts.components.badge.variants)[number];
+type ButtonSize = (typeof componentContracts.components.button.sizes)[number];
+type ButtonVariant = (typeof componentContracts.components.button.variants)[number];
+type CardPart = (typeof componentContracts.components.card.parts)[number];
+type HeadingLevel = (typeof componentContracts.components.heading.levels)[number];
+type TextSize = (typeof componentContracts.components.text.sizes)[number];
+type TextTone = (typeof componentContracts.components.text.tones)[number];
+type TextWeight = (typeof componentContracts.components.text.weights)[number];
+type SemanticColorName = keyof typeof nativeTokens.color.light;
+
+/** Renderers represented in VLLNT UI registry metadata. */
+declare const componentPlatforms: readonly ["web", "native"];
+/** A renderer target represented in VLLNT UI registry metadata. */
+type ComponentPlatform = (typeof componentPlatforms)[number];
+/** Returns whether an unknown value is a supported renderer target. */
+declare function isComponentPlatform(value: unknown): value is ComponentPlatform;
+
+/** Color modes available to renderer adapters. */
+type ThemeColorScheme = keyof typeof nativeTokens.color;
+type NumberMap<T> = {
+    readonly [Key in keyof T]: number;
+};
+type NativeFontWeight = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+/** Platform-neutral, React Native-compatible theme contract. */
+type NativeTheme = {
+    readonly colors: Readonly<Record<SemanticColorName, string>>;
+    readonly colorScheme: ThemeColorScheme;
+    readonly motion: {
+        readonly duration: NumberMap<typeof nativeTokens.motion.duration>;
+    };
+    readonly radius: NumberMap<typeof nativeTokens.radius>;
+    readonly spacing: NumberMap<typeof nativeTokens.spacing>;
+    readonly typography: {
+        readonly fontWeight: {
+            readonly [Key in keyof typeof nativeTokens.typography.fontWeight]: NativeFontWeight;
+        };
+        readonly scale: {
+            readonly [Key in keyof typeof nativeTokens.typography.scale]: {
+                readonly fontSize: number;
+                readonly lineHeight: number;
+            };
+        };
+    };
+};
+/** Supported semantic overrides for a generated native theme. */
+type NativeThemeOverride = {
+    readonly colors?: Partial<NativeTheme["colors"]>;
+    readonly motion?: {
+        readonly duration?: Partial<NativeTheme["motion"]["duration"]>;
+    };
+    readonly radius?: Partial<NativeTheme["radius"]>;
+    readonly spacing?: Partial<NativeTheme["spacing"]>;
+    readonly typography?: {
+        readonly fontWeight?: Partial<NativeTheme["typography"]["fontWeight"]>;
+        readonly scale?: Partial<NativeTheme["typography"]["scale"]>;
+    };
+};
+/** Generated light theme. Values are sRGB colors and density-independent points. */
+declare const lightTheme: NativeTheme;
+/** Generated dark theme. Values are sRGB colors and density-independent points. */
+declare const darkTheme: NativeTheme;
+/** Creates a native theme while preserving every required semantic token. */
+declare function createNativeTheme(colorScheme: ThemeColorScheme, override?: NativeThemeOverride): NativeTheme;
+
+export { type BadgeVariant, type ButtonSize, type ButtonVariant, type CardPart, type ComponentPlatform, type HeadingLevel, type NativeTheme, type NativeThemeOverride, type SemanticColorName, type TextSize, type TextTone, type TextWeight, type ThemeColorScheme, componentContracts, componentPlatforms, createNativeTheme, darkTheme, designTokens, isComponentPlatform, lightTheme, nativeTokens };