@vegastack/design 0.1.0

package/dist/icons/index.d.ts

@@ -0,0 +1,154 @@
+import * as React from 'react';
+import { LucideIcon } from 'lucide-react';
+
+/** Functional icon size scale (px). */
+declare const SIZES$1: {
+    readonly xs: 14;
+    readonly sm: 16;
+    readonly md: 20;
+    readonly lg: 24;
+};
+type IconSize = keyof typeof SIZES$1;
+interface IconProps extends Omit<React.SVGProps<SVGSVGElement>, 'ref'> {
+    /** The lucide icon component to render. */
+    as: LucideIcon;
+    /**
+     * Size token — maps to 14/16/20/24px.
+     * @default 'md'
+     */
+    size?: IconSize;
+    /**
+     * Accessible label. When provided the icon is exposed to assistive tech;
+     * otherwise it is `aria-hidden`.
+     */
+    'aria-label'?: string;
+}
+/**
+ * `Icon` — the one sanctioned wrapper for functional UI icons (lucide-react).
+ *
+ * Color inherits `currentColor` (themes automatically); stroke width is fixed
+ * to the design-system standard. `aria-hidden` unless an `aria-label` is given.
+ *
+ * @example
+ * import { Check } from 'lucide-react';
+ * <Icon as={Check} size="sm" aria-label="Done" />
+ */
+declare function Icon({ as: Cmp, size, 'aria-label': label, ...props }: IconProps): React.JSX.Element;
+
+/** Structural shape of a `thesvg` icon module (its default export). */
+interface BrandIconModule {
+    slug: string;
+    title: string;
+    hex: string;
+    svg: string;
+    variants: Record<string, string>;
+}
+/** Brand-icon size scale → Tailwind size utilities (14/16/20/24px). */
+declare const SIZE_CLASS: {
+    readonly xs: "size-3.5";
+    readonly sm: "size-4";
+    readonly md: "size-5";
+    readonly lg: "size-6";
+};
+type BrandIconSize = keyof typeof SIZE_CLASS;
+interface BrandIconProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'children'> {
+    /** A `thesvg` icon module (default export), e.g. `import github from 'thesvg/github'`. */
+    icon: BrandIconModule;
+    /**
+     * Which `thesvg` variant to render:
+     * - `color` — the brand's official colors (the module `default` variant).
+     * - `mono` — single-color, inherits `currentColor`.
+     * - `light` / `dark` — variants tuned for light/dark surfaces.
+     * - `wordmark` — the brand's logotype/wordmark lockup.
+     *
+     * Falls back to the icon's base `svg` when a brand doesn't ship the variant.
+     * @default 'color'
+     */
+    variant?: 'color' | 'mono' | 'light' | 'dark' | 'wordmark';
+    /**
+     * Size token — maps to 14/16/20/24px.
+     * @default 'md'
+     */
+    size?: BrandIconSize;
+    /**
+     * Accessible label. Defaults to the brand title; pass `''` to hide from
+     * assistive tech (decorative).
+     */
+    'aria-label'?: string;
+}
+/**
+ * `BrandIcon` — the one sanctioned wrapper for brand/logo icons (`thesvg`).
+ *
+ * @example
+ * import github from 'thesvg/github';
+ * <BrandIcon icon={github} size="md" />          // brand colors
+ * <BrandIcon icon={github} variant="mono" />     // inherits currentColor
+ */
+declare function BrandIcon({ icon, variant, size, 'aria-label': label, className, ...props }: BrandIconProps): React.JSX.Element;
+
+/** Functional icon size scale (px) — matches `Icon`/`BrandIcon`. */
+declare const SIZES: {
+    readonly xs: 14;
+    readonly sm: 16;
+    readonly md: 20;
+    readonly lg: 24;
+};
+type AnimatedIconSize = keyof typeof SIZES;
+/**
+ * The imperative handle every `lucide-animated` icon exposes on its ref —
+ * drive the animation programmatically instead of (or in addition to) hover.
+ */
+interface AnimatedIconHandle {
+    startAnimation: () => void;
+    stopAnimation: () => void;
+}
+/**
+ * Shape of a mirrored `lucide-animated` icon component: a `forwardRef` that
+ * accepts a numeric `size`, spreads `div` props, and exposes an
+ * {@link AnimatedIconHandle}. This is what `shadcn add @vegastack/<icon>`
+ * copies in (e.g. `ActivityIcon`).
+ */
+type AnimatedIconComponent = React.ForwardRefExoticComponent<{
+    size?: number;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, 'ref'> & React.RefAttributes<AnimatedIconHandle>>;
+interface AnimatedIconProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'ref'> {
+    /** A mirrored lucide-animated icon component, e.g. `import { ActivityIcon } from '@/components/ui/activity'`. */
+    as: AnimatedIconComponent;
+    /**
+     * Size token — maps to 14/16/20/24px (overrides the icon's default 28px).
+     * @default 'md'
+     */
+    size?: AnimatedIconSize;
+    /**
+     * Accessible label. When provided the icon is exposed to assistive tech as an
+     * image; otherwise it is `aria-hidden` (decorative).
+     */
+    'aria-label'?: string;
+}
+/**
+ * `AnimatedIcon` — the one sanctioned wrapper for motion icons (`lucide-animated`,
+ * mirrored into the VegaStack registry). It standardizes the size scale + a11y and
+ * forwards the icon's {@link AnimatedIconHandle} ref, while the icon itself owns the
+ * animation (animates on hover; or call `ref.current.startAnimation()`).
+ *
+ * Deliberately imports no `motion` — the mirrored icon component carries that
+ * dependency, so the base package stays lightweight. For app-wide
+ * reduced-motion, wrap your tree once in Motion's
+ * `<MotionConfig reducedMotion="user">`.
+ *
+ * @example
+ * 'use client';
+ * import { AnimatedIcon } from '@vegastack/design/icons';
+ * import { ActivityIcon } from '@/components/ui/activity';
+ *
+ * <AnimatedIcon as={ActivityIcon} size="sm" aria-label="Activity" />
+ *
+ * @example
+ * // Programmatic control via the forwarded handle
+ * const ref = React.useRef<AnimatedIconHandle>(null);
+ * <AnimatedIcon as={ActivityIcon} ref={ref} />
+ * <button onClick={() => ref.current?.startAnimation()}>Play</button>
+ */
+declare const AnimatedIcon: React.ForwardRefExoticComponent<AnimatedIconProps & React.RefAttributes<AnimatedIconHandle>>;
+
+export { AnimatedIcon, type AnimatedIconComponent, type AnimatedIconHandle, type AnimatedIconProps, type AnimatedIconSize, BrandIcon, type BrandIconModule, type BrandIconProps, type BrandIconSize, Icon, type IconProps, type IconSize };

package/dist/icons/index.js

@@ -0,0 +1,73 @@
+import {
+  cn
+} from "../chunk-FBU37ITM.js";
+
+// src/icons/icon.tsx
+import "react";
+import { jsx } from "react/jsx-runtime";
+var SIZES = { xs: 14, sm: 16, md: 20, lg: 24 };
+function Icon({ as: Cmp, size = "md", "aria-label": label, ...props }) {
+  return /* @__PURE__ */ jsx(
+    Cmp,
+    {
+      width: SIZES[size],
+      height: SIZES[size],
+      strokeWidth: 1.75,
+      "aria-hidden": label ? void 0 : true,
+      "aria-label": label,
+      ...props
+    }
+  );
+}
+
+// src/icons/brand-icon.tsx
+import "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var SIZE_CLASS = { xs: "size-3.5", sm: "size-4", md: "size-5", lg: "size-6" };
+function BrandIcon({
+  icon,
+  variant = "color",
+  size = "md",
+  "aria-label": label,
+  className,
+  ...props
+}) {
+  const variantKey = variant === "color" ? "default" : variant;
+  const svg = icon.variants?.[variantKey] ?? icon.svg;
+  const accessibleLabel = label === void 0 ? icon.title : label;
+  return /* @__PURE__ */ jsx2(
+    "span",
+    {
+      role: accessibleLabel ? "img" : void 0,
+      "aria-label": accessibleLabel || void 0,
+      "aria-hidden": accessibleLabel ? void 0 : true,
+      className: cn("inline-flex shrink-0 [&>svg]:block [&>svg]:size-full", SIZE_CLASS[size], className),
+      dangerouslySetInnerHTML: { __html: svg },
+      ...props
+    }
+  );
+}
+
+// src/icons/animated-icon.tsx
+import * as React3 from "react";
+import { jsx as jsx3 } from "react/jsx-runtime";
+var SIZES2 = { xs: 14, sm: 16, md: 20, lg: 24 };
+var AnimatedIcon = React3.forwardRef(
+  ({ as: Cmp, size = "md", "aria-label": label, ...props }, ref) => /* @__PURE__ */ jsx3(
+    Cmp,
+    {
+      ref,
+      size: SIZES2[size],
+      role: label ? "img" : void 0,
+      "aria-hidden": label ? void 0 : true,
+      "aria-label": label,
+      ...props
+    }
+  )
+);
+AnimatedIcon.displayName = "AnimatedIcon";
+export {
+  AnimatedIcon,
+  BrandIcon,
+  Icon
+};

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { ClassValue } from 'clsx';
+export { ClassValue } from 'clsx';
+
+/**
+ * Merges Tailwind CSS class names with intelligent conflict resolution.
+ *
+ * Combines `clsx` for conditional classes and `tailwind-merge` to handle
+ * conflicting Tailwind utilities (e.g., `px-2` and `px-4` → keeps last one).
+ *
+ * @param inputs - Class names, objects, arrays, or conditional values
+ * @returns Merged and deduplicated class string
+ *
+ * @example
+ * cn('px-2 py-1', 'px-4') // 'py-1 px-4'
+ * cn('text-foreground', isError && 'text-destructive')
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * Interaction timing constants (ms) — design decisions, not magic numbers (register P2-14).
+ * Single source for every JS-driven delay in the registry; change one value and every
+ * component that expresses that role follows.
+ */
+declare const TIMINGS: {
+    /** How long transient success feedback holds before reverting (CopyButton "Copied ✓"). */
+    readonly feedbackRevertMs: 1500;
+    /** Debounce before auto-persisting a text field (AutoSaveInput). */
+    readonly autoSaveDebounceMs: 800;
+    /** Hover delay before a rich preview (HoverCard) opens — guards accidental opens. */
+    readonly hoverOpenDelayMs: 700;
+    /** Hover delay before a rich preview closes — lets the pointer travel into the card. */
+    readonly hoverCloseDelayMs: 300;
+};
+/**
+ * Floating-surface positioning constants (px) — the unified sideOffset/collisionPadding
+ * pair (register P2-14). Two offset roles, one collision padding:
+ * - `sideOffsetAttached` (4): menu-like popups that read as attached to their trigger
+ *   (dropdown, context menu, select, emoji picker).
+ * - `sideOffsetDetached` (8): floating panels that read as detached (popover, hover-card,
+ *   tooltip).
+ * Submenus deliberately use 0 (flush) and are not part of this contract.
+ */
+declare const FLOATING: {
+    readonly sideOffsetAttached: 4;
+    readonly sideOffsetDetached: 8;
+    readonly collisionPadding: 8;
+};
+
+export { FLOATING, TIMINGS, cn };

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  FLOATING,
+  TIMINGS,
+  cn
+} from "./chunk-FBU37ITM.js";
+export {
+  FLOATING,
+  TIMINGS,
+  cn
+};

package/dist/preset.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@vegastack/design/preset` — Tailwind v4 setup metadata for VegaStack.
+ *
+ * Tailwind v4 is CSS-first (no JS `presets` array), so the real "preset" is the
+ * shipped `preset.css` (`@import "@vegastack/design/preset.css"`), which
+ * wires Tailwind + tw-animate-css + the VegaStack token theme + base reset in one
+ * import. This module exposes machine-readable metadata for tooling/agents.
+ */
+declare const vegastackPreset: {
+    /** The token package this preset is bound to. */
+    readonly tokens: "@vegastack/design-tokens";
+    /** CSS entry consumers import to get the full setup. */
+    readonly css: "@vegastack/design/preset.css";
+    /** Tailwind major version this preset targets. */
+    readonly tailwind: 4;
+};
+type VegastackPreset = typeof vegastackPreset;
+
+export { type VegastackPreset, vegastackPreset };

package/dist/preset.js

@@ -0,0 +1,12 @@
+// src/preset.ts
+var vegastackPreset = {
+  /** The token package this preset is bound to. */
+  tokens: "@vegastack/design-tokens",
+  /** CSS entry consumers import to get the full setup. */
+  css: "@vegastack/design/preset.css",
+  /** Tailwind major version this preset targets. */
+  tailwind: 4
+};
+export {
+  vegastackPreset
+};

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@vegastack/design",
+  "version": "0.1.0",
+  "description": "VegaStack design system — cn utility, icon runtime, Tailwind v4 preset, and the vegastack-design CLI (tokens ship separately as @vegastack/design-tokens)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VegaStack/vegastack-design.git",
+    "directory": "packages/design"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "bin",
+    "css",
+    "preset.css"
+  ],
+  "bin": {
+    "vegastack-design": "./bin/vegastack-design.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./icons": {
+      "types": "./dist/icons/index.d.ts",
+      "import": "./dist/icons/index.js"
+    },
+    "./preset": {
+      "types": "./dist/preset.d.ts",
+      "import": "./dist/preset.js"
+    },
+    "./preset.css": "./preset.css",
+    "./theme.css": "./css/theme.css",
+    "./base.css": "./css/base.css",
+    "./utilities.css": "./css/utilities.css"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.24.0",
+    "tailwind-merge": "^3.6.0",
+    "thesvg": "^3.2.6",
+    "@vegastack/design-tokens": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.3.2",
+    "tw-animate-css": "^1.4.0"
+  },
+  "peerDependenciesMeta": {
+    "tailwindcss": {
+      "optional": true
+    },
+    "tw-animate-css": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tailwindcss/node": "4.3.1",
+    "@tailwindcss/oxide": "4.3.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "eslint": "^10.7.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tailwindcss": "^4.3.2",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^6.0.3",
+    "@vegastack/typescript-config": "0.0.0",
+    "@vegastack/eslint-config": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint . && pnpm run verify",
+    "verify": "node ../../tooling/verify-preset-source.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "node test/compare.test.mjs && node test/check-updates.test.mjs"
+  }
+}

package/preset.css

@@ -0,0 +1,39 @@
+/**
+ * @vegastack/design/preset.css
+ * One-import Tailwind v4 setup for VegaStack consumers.
+ */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@vegastack/design-tokens/theme.css";
+@import "@vegastack/design-tokens/base.css";
+@import "@vegastack/design-tokens/utilities.css"; /* shimmer / scroll-fade / scrollbar @utility helpers */
+
+/**
+ * Distribution contract — scan the classes shipped INSIDE our own packages.
+ *
+ * This package's own `dist` ships the icon runtime (`BrandIcon`'s
+ * `inline-flex shrink-0 [&>svg]:size-full`), and `@vegastack/ui` ships a compiled
+ * provider + `Toaster` whose sonner `classNames` (e.g. `group-[.toaster]:bg-popover`)
+ * live in its published `dist/*.js`, NOT in the consumer's own source — so without
+ * an explicit `@source` a real npm consumer importing ONLY this preset would get
+ * a partially-unstyled provider/Toaster + icon UI.
+ *
+ * Why `./dist` + a RELATIVE `../ui/dist` path and NOT `@source "@vegastack/ui"`:
+ *   - Tailwind v4.3.1 (the pinned version) does NOT resolve a bare package-name
+ *     `@source` through node_modules — it treats `@vegastack/ui` as a literal
+ *     glob and silently scans nothing (verified: tooling/verify-preset-source.mjs).
+ *   - Tailwind resolves `@source` relative to this file's realpath. The icon runtime
+ *     is INSIDE this package now (`./dist`). `@vegastack/ui` — when present — sits as
+ *     a sibling under the same `@vegastack` scope in node_modules, making `../ui`
+ *     resolvable from any consumer layout (flat npm OR strict pnpm). When a consumer
+ *     does NOT have ui installed, the path simply doesn't exist and Tailwind skips
+ *     it — no error, graceful degradation. (ui is deliberately NOT a peerDependency:
+ *     it is a private workspace package, and declaring it would create a
+ *     ui → design → ui cycle in the workspace graph.)
+ *
+ * Consumers need to do NOTHING extra: importing this preset self-contains the
+ * `@source`. (The packages' `dist` is what ships per their `files` field, so we
+ * point at `dist`, never `src`.)
+ */
+@source "./dist";
+@source "../ui/dist";