@scalepad/ui 0.1.1 → 0.2.0

package/src/tokens/semantic-colors.ts

@@ -1,15 +1,27 @@
 /**
- * Semantic color tokens synced from Figma Design System (VCLfybgU3OaUUPrQdBaVmP).
+ * Semantic color tokens.
+ *
  * Values reference primitives in colors.ts; inline rgba for alpha variants.
- * Figma source of truth: Tokens collection (Light / Dark modes).
+ *
+ * NOTE: The dark-mode map and several new tokens (`background.surface.*`,
+ * `background.entity.*`, `chart.series.*`) are intentionally diverged from the
+ * Figma Design System (VCLfybgU3OaUUPrQdBaVmP) and are hand-tuned in code. The
+ * Figma source will be back-synced to match these values; until then, code is
+ * the source of truth.
+ *
+ * Original Figma source of truth: Tokens collection (Light / Dark modes).
  */
 
 import {
   black,
   dark,
+  darkAlpha,
   gray,
   grayAlpha,
   green,
+  greenAlpha,
+  grape,
+  grapeAlpha,
   indigo,
   indigoAlpha,
   red,
@@ -105,91 +117,183 @@ export const semanticColors = {
   'background.input': white,
   'background.backdrop': grayAlpha['9-60'],
   'icon.medium': gray[7],
+
+  // Elevated-surface tokens. In light mode both raised and overlay share the
+  // default white surface — depth comes from shadow, not color. In dark mode
+  // they step up the dark scale for visual elevation.
+  'background.surface.raised': white,
+  'background.surface.overlay': white,
+
+  // Entity-accent tokens (used by Spotlight Quick Create + similar surfaces).
+  // Each pair maps to one of the five semantic role families so they auto-flip
+  // with mode. The fifth slot (deliverable) borrows the grape family because
+  // there's no sixth core semantic role.
+  'background.entity.task.light': green[0],
+  'background.entity.task.icon': green[7],
+  'background.entity.initiative.light': indigoAlpha['10'],
+  'background.entity.initiative.icon': indigo[7],
+  'background.entity.goal.light': teal[0],
+  'background.entity.goal.icon': teal[7],
+  'background.entity.meeting.light': yellowAlpha['10'],
+  'background.entity.meeting.icon': yellow[7],
+  'background.entity.deliverable.light': grape[0],
+  'background.entity.deliverable.icon': grape[7],
+
+  // Chart series — deterministic, tuned-for-stacking palette consumed by
+  // budget / dashboard / trend charts. Sorted by visual weight; series 1 is
+  // the primary brand and the rest stack underneath.
+  'chart.series.1': green[7],
+  'chart.series.2': indigo[6],
+  'chart.series.3': teal[6],
+  'chart.series.4': yellow[7],
+  'chart.series.5': red[7],
+  'chart.series.6': grape[6],
 } as const;
 
 /** Dark mode semantic color values */
 export const semanticColorsDark = {
-  'text.title': dark[0],
-  'text.danger.default': red[7],
-  'text.link': green[3],
-  'background.default': dark[6],
-  'background.default-hover': dark[5],
-  'text.default': white,
-  'stroke.default': dark[4],
-  'stroke.light': dark[5],
-  'background.body': dark[7],
-  'text.disabled.default': dark[3],
+  // Foundation surfaces — distinct levels for real depth hierarchy.
+  'background.body': dark[8],
+  'background.default': dark[7],
+  'background.default-hover': dark[6],
   'background.disabled.default': dark[6],
   'background.transparent': transparent,
-  'background.primary.filled': green[5],
-  'background.primary.filled-hover': green[4],
-  'background.warning.filled': yellow[8],
-  'background.success.filled': teal[8],
-  'background.subdued.light': dark[5],
-  'background.subdued.ultralight': dark[6],
-  'background.danger.filled': red[8],
-  'background.subdued.filled': gray[7],
-  'background.warning.filled-hover': yellow[9],
-  'background.success.filled-hover': teal[9],
-  'background.danger.filled-hover': red[9],
-  'background.subdued.filled-hover': gray[8],
-  'background.danger.light': red[4],
-  'background.primary.light': green[9],
-  'background.warning.light': yellowAlpha['15'],
-  'background.success.light': tealAlpha['15'],
-  'text.subdued.default': gray[3],
-  'text.primary.default': green[3],
-  'text.primary.light': green[4],
-  'text.warning.default': yellow[3],
-  'text.success.default': teal[3],
-  'background.primary.light-hover': green[8],
+  'background.input': dark[7],
+  'background.backdrop': darkAlpha['70'],
+
+  'background.surface.raised': dark[6],
+  'background.surface.overlay': dark[5],
+
+  // Subdued (neutral) surfaces — tied to the dark scale so they keep their
+  // relationship with `background.default`. `ultralight` is intentionally a
+  // *deeper* recess in dark mode (`dark[9]`, two steps below the card) rather
+  // than the single off-white step of light mode — near-black perceptually
+  // compresses, so the wrapper needs more delta to read as a distinct frame
+  // behind cards (kanban columns, assessment blocks, drawer wells).
+  'background.subdued.light': dark[6],
+  'background.subdued.light-hover': dark[5],
+  'background.subdued.ultralight': dark[9],
+  'background.subdued.filled': dark[5],
+  'background.subdued.filled-hover': dark[4],
+
+  // Brand / role filled surfaces — keep the strong saturated hue so primary
+  // CTAs still read as primary in dark.
+  'background.primary.filled': green[7],
+  'background.primary.filled-hover': green[6],
+  'background.warning.filled': yellow[6],
+  'background.warning.filled-hover': yellow[7],
+  'background.success.filled': teal[6],
+  'background.success.filled-hover': teal[7],
+  'background.danger.filled': red[7],
+  'background.danger.filled-hover': red[8],
+  'background.information.filled': indigo[6],
+  'background.information.filled-hover': indigo[7],
+
+  // Soft / tinted role surfaces — translucent washes over the dark base, so
+  // they read as brand-tinted instead of near-black.
+  'background.primary.light': greenAlpha['12'],
+  'background.primary.light-hover': greenAlpha['20'],
+  'background.warning.light': yellowAlpha['12'],
   'background.warning.light-hover': yellowAlpha['20'],
+  'background.success.light': tealAlpha['12'],
   'background.success.light-hover': tealAlpha['20'],
-  'background.danger.light-hover': red[5],
-  'background.subdued.light-hover': dark[6],
-  'stroke.primary.default': green[6],
-  'text.danger.disabled': redAlpha['50'],
-  'stroke.success.default': teal[3],
-  'stroke.danger.default': red[7],
-  'stroke.subdued.strong': gray[3],
-  'stroke.warning.default': yellow[3],
-  'background.information.filled': indigo[8],
-  'background.information.filled-hover': indigo[9],
-  'background.information.light': indigoAlpha['15'],
+  'background.danger.light': redAlpha['12'],
+  'background.danger.light-hover': redAlpha['20'],
+  'background.information.light': indigoAlpha['12'],
   'background.information.light-hover': indigoAlpha['20'],
-  'stroke.information.default': indigo[3],
-  'text.information.default': indigo[3],
-  'stroke.focus.default': green[3],
+
+  // Inverse fills (e.g. tooltips, default-on-dark anchors) — light surface,
+  // dark text/icon.
   'background.inverse.filled': dark[0],
   'background.inverse.filled-hover': dark[1],
-  'icon.light': dark[3],
-  'icon.danger.default': red[7],
-  'icon.danger.disabled': redAlpha['50'],
-  'text.danger.strong': red[9],
-  'text.warning.strong': yellow[9],
-  'text.success.strong': teal[9],
-  'text.information.strong': indigo[9],
-  'icon.warning.default': yellow[5],
-  'icon.warning.strong': yellow[9],
-  'icon.danger.strong': red[9],
-  'icon.information.default': indigo[5],
-  'icon.information.strong': indigo[9],
-  'icon.success.default': teal[5],
-  'icon.success.strong': teal[9],
-  'text.subdued.strong': gray[6],
-  'icon.default': dark[1],
-  'stroke.inverse': dark[6],
-  'stroke.subdued.default': gray[6],
-  'text.inverse': dark[9],
+
+  // Entity accents — soft translucent role washes for the icon block,
+  // strong saturated tone for the icon foreground.
+  'background.entity.task.light': greenAlpha['12'],
+  'background.entity.task.icon': green[3],
+  'background.entity.initiative.light': indigoAlpha['15'],
+  'background.entity.initiative.icon': indigo[3],
+  'background.entity.goal.light': tealAlpha['12'],
+  'background.entity.goal.icon': teal[3],
+  'background.entity.meeting.light': yellowAlpha['15'],
+  'background.entity.meeting.icon': yellow[4],
+  'background.entity.deliverable.light': grapeAlpha['15'],
+  'background.entity.deliverable.icon': grape[3],
+
+  // Text colors — sit on the dark surface scale. AA contrast against
+  // background.body (dark[8]) verified at component-build time.
+  'text.title': dark[0],
+  'text.default': dark[1],
+  'text.subdued.default': dark[2],
+  'text.subdued.strong': dark[1],
+  'text.disabled.default': dark[3],
+  // `text.inverse` is the label color that sits on FILLED / SATURATED brand
+  // backgrounds (primary button green, danger red, avatar colour swatches,
+  // dark tooltip surfaces). Those backgrounds keep the same hue in both
+  // modes, so their contrast text must stay near-white — flipping this to a
+  // dark value produces unreadable black-on-green / black-on-red elements
+  // in dark mode. Keep this in sync with the light-mode value.
+  'text.inverse': white,
+  'text.link': green[3],
+
+  // Brand / role text — bright, readable on dark surfaces.
+  'text.primary.default': green[3],
+  'text.primary.light': green[4],
+  'text.warning.default': yellow[4],
+  'text.warning.strong': yellow[2],
+  'text.success.default': teal[3],
+  'text.success.strong': teal[2],
+  'text.danger.default': red[4],
+  'text.danger.strong': red[2],
+  'text.danger.disabled': redAlpha['50'],
+  'text.information.default': indigo[3],
+  'text.information.strong': indigo[2],
+
+  // Strokes — borders, dividers, focus rings.
+  'stroke.default': dark[4],
+  'stroke.light': dark[5],
   'stroke.strong': dark[2],
-  'icon.inverse': dark[9],
+  'stroke.subdued.default': dark[5],
+  'stroke.subdued.strong': dark[3],
+  // `stroke.inverse` is the border color used by `outline-inverse` button /
+  // icon-button variants that sit on top of saturated coloured backgrounds.
+  // Same reasoning as `text.inverse` — the host surface doesn't flip, so the
+  // border on top stays white in both modes.
+  'stroke.inverse': white,
   'stroke.icon': dark[1],
+  'stroke.focus.default': green[4],
+  'stroke.focus.strong': green[3],
+  'stroke.primary.default': green[5],
+  'stroke.success.default': teal[4],
+  'stroke.danger.default': red[5],
+  'stroke.warning.default': yellow[5],
+  'stroke.information.default': indigo[4],
+
+  // Icons.
+  'icon.default': dark[1],
+  'icon.light': dark[3],
+  'icon.medium': dark[2],
+  'icon.inverse': dark[9],
   'icon.primary.default': green[3],
-  'icon.primary.strong': green[1],
-  'stroke.focus.strong': green[1],
-  'background.input': dark[6],
-  'background.backdrop': grayAlpha['9-60'],
-  'icon.medium': dark[4],
+  'icon.primary.strong': green[2],
+  'icon.danger.default': red[4],
+  'icon.danger.strong': red[2],
+  'icon.danger.disabled': redAlpha['50'],
+  'icon.warning.default': yellow[4],
+  'icon.warning.strong': yellow[2],
+  'icon.success.default': teal[3],
+  'icon.success.strong': teal[2],
+  'icon.information.default': indigo[3],
+  'icon.information.strong': indigo[2],
+
+  // Chart series — brighter values so series read clearly against the dark
+  // surface. Order matches the light map for stable legends.
+  'chart.series.1': green[4],
+  'chart.series.2': indigo[3],
+  'chart.series.3': teal[3],
+  'chart.series.4': yellow[4],
+  'chart.series.5': red[4],
+  'chart.series.6': grape[3],
 } as const;
 
 function semanticKeyToCssVarName(key: string): string {

package/src/tokens/semantic-tokens-css.ts

@@ -1,41 +1,37 @@
 /**
  * Semantic design token CSS custom properties (radius, spacing, shadows, z-index, font).
  * Injected by ThemeProvider so components can use var(--radius-*), var(--spacing-*), etc.
+ *
+ * Shadows are emitted twice — once under the light scheme selector, once under
+ * the dark scheme selector — so `--shadow-*` flips automatically with the
+ * Mantine color scheme. All other tokens (radius, spacing, z-index, font) are
+ * mode-agnostic and live in a single shared block.
  */
 
 import { figmaRadius } from './radius';
-import { figmaShadows } from './shadows';
+import { figmaShadows, figmaShadowsDark } from './shadows';
 import { figmaSpacing } from './spacing';
 import { figmaFontFamilies } from './typography';
 import { zIndex } from './zIndex';
 
-function buildSemanticTokensCss(): string {
+function buildSharedTokensCss(): string {
   const lines: string[] = [
     ':root, [data-mantine-color-scheme="light"], [data-mantine-color-scheme="dark"] {',
   ];
 
-  // Radius
   for (const [key, value] of Object.entries(figmaRadius)) {
     lines.push(`  --radius-${key}: ${value};`);
   }
   lines.push(`  --radius-default: ${figmaRadius.lg};`);
 
-  // Spacing
   for (const [key, value] of Object.entries(figmaSpacing)) {
     lines.push(`  --spacing-${key}: ${value};`);
   }
 
-  // Shadows
-  for (const [key, value] of Object.entries(figmaShadows)) {
-    lines.push(`  --shadow-${key}: ${value};`);
-  }
-
-  // Z-index
   for (const [key, value] of Object.entries(zIndex)) {
     lines.push(`  --z-index-${key}: ${value};`);
   }
 
-  // Font families
   lines.push(
     `  --font-family-monospace: "${figmaFontFamilies['font-family-monospace']}", "Courier New", monospace;`,
   );
@@ -50,4 +46,30 @@ function buildSemanticTokensCss(): string {
   return lines.join('\n');
 }
 
-export const semanticTokensCss = buildSemanticTokensCss();
+function buildShadowCss(
+  shadowMap: Record<string, string>,
+  selector: string,
+): string {
+  const lines = [`${selector} {`];
+  for (const [key, value] of Object.entries(shadowMap)) {
+    // Emit both --shadow-* (used by vanilla-extract `tokens.shadow.*`) and
+    // --mantine-shadow-* (consumed by Mantine's Card/Paper/Modal defaults)
+    // so the entire component surface flips with the active color scheme.
+    lines.push(`  --shadow-${key}: ${value};`);
+    lines.push(`  --mantine-shadow-${key}: ${value};`);
+  }
+  lines.push('}');
+  return lines.join('\n');
+}
+
+const sharedTokensCss = buildSharedTokensCss();
+const lightShadowsCss = buildShadowCss(
+  figmaShadows,
+  ':root, [data-mantine-color-scheme="light"]',
+);
+const darkShadowsCss = buildShadowCss(
+  figmaShadowsDark,
+  '[data-mantine-color-scheme="dark"]',
+);
+
+export const semanticTokensCss = `${sharedTokensCss}\n${lightShadowsCss}\n${darkShadowsCss}`;

package/src/tokens/shadows.ts

@@ -1,11 +1,35 @@
 /**
- * AUTO-GENERATED - DO NOT EDIT
- * Generated from: packages/figma-tokens/source/shadows.json
+ * Shadow tokens.
+ *
+ * Both modes deliberately keep cards / papers / modals / drawers / headers
+ * flat: depth is carried by the body↔surface background delta plus the 1px
+ * `stroke.default` border on each surface. The original Figma export used a
+ * 10% black drop-shadow on every elevation level, which stacked up to a
+ * visually noisy "everything floats" look once cards were nested inside
+ * drawers, modals, and dashboards.
+ *
+ * `lg` is the one exception: floating overlays (popovers, picker flyouts)
+ * sit on top of scrollable canvas content where a border alone does not
+ * read as "lifted off the page". They get a single soft drop-shadow tuned
+ * per mode so they remain clearly elevated.
  */
 
 export const figmaShadows = {
-  sm: '0px 1px 3px 0px rgba(0, 0, 0, 0.10), 0px 1px 2px -1px rgba(0, 0, 0, 0.10)',
-  md: '0px 4px 6px -1px rgba(0, 0, 0, 0.10), 0px 2px 4px -2px rgba(0, 0, 0, 0.10)',
-  lg: '0px 10px 15px -3px rgba(0, 0, 0, 0.10), 0px 4px -4px 6px rgba(0, 0, 0, 0.10)',
-  xl: '0px 20px 25px -5px rgba(0, 0, 0, 0.10), 0px 8px -6px 10px rgba(0, 0, 0, 0.10)',
+  sm: 'none',
+  md: 'none',
+  lg: '0px 8px 16px -4px rgba(0, 0, 0, 0.08), 0px 2px 4px -2px rgba(0, 0, 0, 0.06)',
+  xl: 'none',
+} as const;
+
+/**
+ * Dark-mode shadow values. Same flat treatment as light mode, but `lg` uses
+ * a heavier black alpha because the underlying surfaces are already dark —
+ * a 10% black drop-shadow that reads as elevation in light mode disappears
+ * entirely against `dark[7]`/`dark[8]`.
+ */
+export const figmaShadowsDark = {
+  sm: 'none',
+  md: 'none',
+  lg: '0px 8px 16px -4px rgba(0, 0, 0, 0.25)',
+  xl: 'none',
 } as const;

package/src/vite.d.ts

@@ -0,0 +1,37 @@
+// Hand-authored type declarations for the `@scalepad/ui/vite` preset.
+// The runtime implementation lives at `./vite.js` (plain JS, not TS — see the
+// note at the top of that file for why this file isn't authored as `.ts`).
+
+import type { VanillaExtractPluginOptions } from '@vanilla-extract/vite-plugin';
+import type { Plugin } from 'vite';
+
+export interface ScalepadUiViteOptions {
+  /**
+   * Options forwarded to `@vanilla-extract/vite-plugin`. Leave undefined to
+   * use the plugin's defaults, which work for `@scalepad/ui` out of the box.
+   */
+  vanillaExtract?: VanillaExtractPluginOptions;
+  /**
+   * Extra packages to add to `optimizeDeps.include`. Use this when your app
+   * pulls in additional CommonJS deps through `@scalepad/ui` that Vite's
+   * scanner misses because the package is excluded from pre-bundling.
+   */
+  optimizeDepsInclude?: string[];
+  /**
+   * Override the default `optimizeDeps.include` list entirely. Most consumers
+   * should use `optimizeDepsInclude` to *extend* the defaults rather than
+   * replace them.
+   */
+  optimizeDepsIncludeOverride?: string[];
+}
+
+/**
+ * The default `optimizeDeps.include` list shipped with the preset. Exported
+ * so consumers can compose with it if they need full control over Vite's
+ * pre-bundling.
+ */
+export const SCALEPAD_UI_OPTIMIZE_DEPS_INCLUDE: readonly string[];
+
+export function scalepadUi(options?: ScalepadUiViteOptions): Plugin[];
+
+export default scalepadUi;

package/src/vite.js

@@ -0,0 +1,79 @@
+/**
+ * Vite preset for `@scalepad/ui`.
+ *
+ * @scalepad/ui ships as TypeScript + vanilla-extract source. Two things must
+ * be wired into a consumer's Vite config for it to load cleanly:
+ *
+ *   1. The vanilla-extract Vite plugin, so every `.css.ts` file the package
+ *      ships under `node_modules/@scalepad/ui/src/**` is compiled at build
+ *      time.
+ *   2. A pair of `optimizeDeps` overrides:
+ *        - `exclude: ['@scalepad/ui']` so Vite's esbuild pre-bundling step
+ *          doesn't try to ingest `.css.ts` files (esbuild can't handle them
+ *          on its own and the failure mode is opaque).
+ *        - `include: [...]` for the CommonJS transitive deps Vite's scanner
+ *          stops walking through once the package is excluded from
+ *          pre-bundling.
+ *
+ * This preset wraps both into a single plugin so consumers can do:
+ *
+ *     import { scalepadUi } from '@scalepad/ui/vite';
+ *
+ *     export default defineConfig({
+ *       plugins: [react(), scalepadUi()],
+ *     });
+ *
+ * The `@vanilla-extract/vite-plugin` ships as a runtime dependency of
+ * `@scalepad/ui`, so consumers don't need to install it themselves.
+ *
+ * NOTE: this file is intentionally authored as plain `.js` with a sibling
+ * `.d.ts`, NOT as `.ts`. Vite consumers import it from their `vite.config.ts`,
+ * which Vite transpiles via esbuild and then evaluates through Node's runtime.
+ * Node 22+ refuses to strip TypeScript types from files inside `node_modules`
+ * (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so the runtime artifact
+ * MUST be `.js`. Every other file in this package goes through the consumer's
+ * bundler instead of Node directly and can stay as `.ts`.
+ */
+import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';
+
+/**
+ * The default `optimizeDeps.include` list. These are the CommonJS / mixed
+ * deps that `@scalepad/ui` reaches through transitively, which Vite's
+ * scanner can't discover on its own once `@scalepad/ui` is excluded from
+ * pre-bundling.
+ *
+ * Exported so consumers can compose with it if they need full control.
+ */
+export const SCALEPAD_UI_OPTIMIZE_DEPS_INCLUDE = Object.freeze([
+  '@mantine/dates',
+  '@mantine/schedule',
+  '@tiptap/react',
+  'dayjs',
+  'fast-deep-equal',
+  'prop-types',
+]);
+
+export function scalepadUi(options = {}) {
+  const includeFromOptions =
+    options.optimizeDepsIncludeOverride ?? [
+      ...SCALEPAD_UI_OPTIMIZE_DEPS_INCLUDE,
+      ...(options.optimizeDepsInclude ?? []),
+    ];
+
+  const optimizeDepsPlugin = {
+    name: '@scalepad/ui/vite-preset',
+    config: () => ({
+      optimizeDeps: {
+        exclude: ['@scalepad/ui'],
+        include: includeFromOptions,
+      },
+    }),
+  };
+
+  const veResult = vanillaExtractPlugin(options.vanillaExtract);
+  const vePlugins = Array.isArray(veResult) ? veResult : [veResult];
+
+  return [...vePlugins, optimizeDepsPlugin];
+}
+
+export default scalepadUi;