@usetheo/ui 0.4.0-next.0 → 0.5.1-next.0

package/CHANGELOG.md

@@ -7,6 +7,124 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1-next.0] - 2026-05-22
+
+Patch — RFC 0008 follow-up. The 0.5.0-next.0 release declared `tailwindcss@^4`
+as a peer dependency and shipped the `./vite-plugin` + `./preset` subpaths,
+but the actual CSS / token / preset artifacts inside the tarball were still
+Tailwind v3 internally. Result: every TheoKit consumer of 0.5.0-next.0 booted
+with unstyled UI in dev and production — `bg-primary`, `text-muted-foreground`,
+`border-border`, `text-body-sm`, etc. emitted as className strings with no
+matching CSS rule.
+
+This release rewrites the three v3-shaped artifacts to v4-native syntax and
+ships a fixture-backed real-build dogfood so the regression cannot recur.
+
+### Changed
+
+- **`dist/styles.css` is now Tailwind v4 native.** Uses `@import "tailwindcss"`
+  (replaces the v3 `@tailwind base; @tailwind components; @tailwind utilities;`
+  trio that Tailwind v4 emits as literal strings, with zero utility generation).
+  Imports `tokens.css` (runtime cascade) AND `tokens-v4.css` (`@theme` namespace)
+  so consumers' Tailwind v4 build resolves both layers correctly. Same
+  `@layer base` content (border-color, body font, focus ring, scrollbar
+  styling) as before. (#TBD)
+- **`./preset` subpath is now a CSS file.** Tailwind v4 dropped the v3 JS
+  preset format — `theme.extend.colors.{name}` declarations are a no-op for
+  v4. The new `dist/preset.css` simply chains `@import "./tokens.css"` and
+  `@import "./tokens-v4.css"` so consumers can `@import "@usetheo/ui/preset.css"`
+  from their own Tailwind v4 entry CSS. (#TBD)
+
+### Added
+
+- **`@usetheo/ui/tokens-v4.css` (NEW)** — `@theme {}` block declaring 28
+  `--color-*` aliases (full color set), 14 `--text-*` typescale tiers
+  (Violet Forge — `--text-display-2xl` through `--text-code-sm` with companion
+  `--*--line-height`, `--*--letter-spacing`, `--*--font-weight`), 3 `--font-*`
+  family tokens, 7 `--radius-*` tiers, 5 `--shadow-*` levels, 3 `--ease-*`
+  timings, and 2 `--animate-*` keyframe-bound utilities. Every color alias
+  uses `hsl(var(--*))` indirection so `<ThemeProvider>`'s runtime
+  `[data-theme]` cascade keeps working — switching themes still recolors
+  every utility. (#TBD)
+- **`@usetheo/ui/styles-v3-legacy.css` (NEW)** — the previous v3-shaped
+  `@tailwind base/components/utilities` entry. Pinned consumers on
+  `tailwindcss@^3` who still want a prebuilt stylesheet can import this
+  subpath. New code SHOULD use `@usetheo/ui/styles.css` (v4) instead.
+- **`@usetheo/ui/preset-v3-legacy` (NEW)** — the v3 JS `Partial<Config>`
+  preset that previously lived at `./preset`. Renamed so the canonical
+  `./preset` subpath can host the v4 CSS preset. v3 consumers update
+  imports from `@usetheo/ui/preset` to `@usetheo/ui/preset-v3-legacy`.
+- **Dogfood scripts** — `pnpm dogfood:v4-zero-config` (shape check, runs in
+  `quality:gates`) and `pnpm dogfood:v4-real-build` (end-to-end: packs the
+  tarball, installs in a tmp project alongside `@tailwindcss/cli@^4`, runs
+  Tailwind v4 against `tests/fixtures/v4-zero-config/`, and grep-asserts the
+  expected utility classes appear in the emitted CSS — 12 assertions). The
+  real-build dogfood is opt-in (slow, requires network) but catches any
+  future regression where v3-shaped artifacts get shipped under a v4 peer
+  declaration. (#TBD)
+
+### Notes
+
+- **Breaking for any 0.5.0-next.0 consumer.** The `./preset` subpath changed
+  from JS (`Partial<Config>` default-export) to CSS file. Code importing
+  `import preset from "@usetheo/ui/preset"` will break and must migrate to
+  `@import "@usetheo/ui/preset.css"` in an entry CSS. Blast radius: TheoKit
+  (already reverted away from 0.5.x by the time this fix shipped) plus any
+  community consumer that adopted 0.5.0-next.0 in the same day — likely zero.
+- The runtime indirection via `hsl(var(--*))` aliases keeps `<ThemeProvider>`
+  and every built-in theme (`violet-forge`, `dracula`, `vercel-mono`, etc.)
+  working with zero changes — the v4 utilities transparently follow the v3
+  cascade.
+
+## [0.5.0-next.0] - 2026-05-22
+
+Minor bump — public API gains two subpath exports (`./vite-plugin` and
+`./preset`) so the TheoKit framework's `integrateUseTheoUI()` can
+auto-wire Tailwind v4 for consumers with zero further configuration.
+Zero visual break and no runtime behavior change for existing consumers.
+
+### Added
+
+- **`@usetheo/ui/vite-plugin` (NEW, RFC 0008)** — Default-export factory
+  returning one Vite `Plugin`. The plugin's `config()` hook
+  dynamic-imports `@tailwindcss/vite` v4 and chains it into the
+  consumer's plugin array when resolvable, and degrades to `console.warn`
+  + CSS-only mode (via the pre-built `@usetheo/ui/styles.css` subpath)
+  when the peer is not installed. A virtual module
+  `virtual:@usetheo/ui/library-sources.css` provides the `@source`
+  directive covering `node_modules/@usetheo/ui/dist/**/*.{js,mjs,cjs}`
+  so Tailwind scans the library's published JS for utilities. Plugin
+  name slug: `@usetheo/ui/vite-plugin`. Options: `tailwind?: boolean`
+  (default `true`), `contentExtra?: string[]` (extra `@source` globs).
+  (#TBD)
+- **`@usetheo/ui/preset` (NEW, RFC 0008)** — Default-export Tailwind v4
+  `Partial<Config>` mirroring the design tokens in `tokens.css`
+  (colors via `hsl(var(--x) / <alpha-value>)`, font families, the
+  Violet Forge typescale, radii, shadows, animations, motion timing)
+  with `content` paths covering `./node_modules/@usetheo/ui/dist/**` and
+  the `tailwindcss-animate` plugin. Consumer usage:
+  `import preset from "@usetheo/ui/preset"; export default { presets: [preset] }`.
+  Internally delegates to the existing `src/styles/tailwind-preset.ts` —
+  the v3 shadcn-registry preset and the v4 import preset stay
+  byte-for-byte aligned and impossible to drift. (#TBD)
+- **`@tailwindcss/vite ^4`, `tailwindcss ^4`, `vite ^6 || ^7` peer-deps
+  (all optional)** — added to `peerDependenciesMeta` so consumers
+  importing `@usetheo/ui` standalone (no framework) are not forced into
+  Tailwind v4. Required only when consuming via TheoKit's auto-wire path
+  or the new `./vite-plugin` subpath. (#TBD)
+
+### Notes
+
+- Existing `tailwindcss@^3` consumers continue to work via the shadcn
+  registry preset (`registry/r/tailwind-preset.json`) and the prebuilt
+  `@usetheo/ui/styles.css`. The new subpaths are additive — they do not
+  break v3-based setups.
+- The `vite-plugin` returns ONE `Plugin` object (not `Plugin[]`) per the
+  cross-repo contract with TheoKit's `integrateUseTheoUI()`. The chain
+  to `@tailwindcss/vite` happens via the `config()` hook's `plugins`
+  field — Vite 5+ tightened the TypeScript signature, the runtime still
+  merges plugins as expected.
+
 ## [0.4.0-next.0] - 2026-05-22
 
 Minor bump — public API gains 7 new theme exports. Zero visual break for

package/dist/preset-v3-legacy.d.ts

@@ -0,0 +1,35 @@
+import { Config } from 'tailwindcss';
+
+/**
+ * `@usetheo/ui/preset-v3-legacy` — Tailwind v3 JS preset (legacy path).
+ *
+ * Default-export a `Partial<Config>` mirroring the design tokens shipped
+ * in `@usetheo/ui/tokens.css`. Adds a `content` field covering the
+ * library's published artifact tree so v3-based Tailwind builds emit
+ * the utilities used by `@usetheo/ui` components.
+ *
+ * **Tailwind v4 consumers MUST use `@usetheo/ui/preset.css`**, not this
+ * file — Tailwind v4 dropped the JS preset format entirely. This file
+ * exists for any remaining `tailwindcss@^3` consumer (notably the
+ * shadcn-style copy-paste registry path); new code should not import
+ * from this subpath.
+ *
+ * The token surface is delegated to `./styles/tailwind-preset.ts` (the
+ * existing source of truth used by the local Ladle dev surface and the
+ * shadcn registry).
+ *
+ * v3 consumer usage:
+ *
+ *   // tailwind.config.ts (Tailwind v3 only)
+ *   import preset from "@usetheo/ui/preset-v3-legacy";
+ *   export default {
+ *     presets: [preset],
+ *     content: ["./app/**\/*.{ts,tsx}"],
+ *   };
+ *
+ * See RFC 0008 follow-up.
+ */
+
+declare const preset: Partial<Config>;
+
+export { preset as default };

package/dist/preset-v3-legacy.js

@@ -0,0 +1,159 @@
+import animate from 'tailwindcss-animate';
+
+// src/styles/tailwind-preset.ts
+var hsl = (token) => `hsl(var(${token}) / <alpha-value>)`;
+var theoUIPreset = {
+  theme: {
+    container: {
+      center: true,
+      padding: "1rem",
+      screens: {
+        "2xl": "1280px"
+      }
+    },
+    extend: {
+      colors: {
+        background: hsl("--background"),
+        foreground: hsl("--foreground"),
+        card: {
+          DEFAULT: hsl("--card"),
+          foreground: hsl("--card-foreground")
+        },
+        popover: {
+          DEFAULT: hsl("--popover"),
+          foreground: hsl("--popover-foreground")
+        },
+        primary: {
+          DEFAULT: hsl("--primary"),
+          deep: hsl("--primary-deep"),
+          glow: hsl("--primary-glow"),
+          foreground: hsl("--primary-foreground")
+        },
+        secondary: {
+          DEFAULT: hsl("--secondary"),
+          foreground: hsl("--secondary-foreground")
+        },
+        accent: {
+          DEFAULT: hsl("--accent"),
+          deep: hsl("--accent-deep"),
+          foreground: hsl("--accent-foreground")
+        },
+        muted: {
+          DEFAULT: hsl("--muted"),
+          foreground: hsl("--muted-foreground")
+        },
+        success: {
+          DEFAULT: hsl("--success"),
+          foreground: hsl("--success-foreground")
+        },
+        warning: {
+          DEFAULT: hsl("--warning"),
+          foreground: hsl("--warning-foreground")
+        },
+        destructive: {
+          DEFAULT: hsl("--destructive"),
+          foreground: hsl("--destructive-foreground")
+        },
+        info: {
+          DEFAULT: hsl("--info"),
+          foreground: hsl("--info-foreground")
+        },
+        border: hsl("--border"),
+        input: hsl("--input"),
+        ring: hsl("--ring")
+      },
+      fontFamily: {
+        display: "var(--font-display)",
+        sans: "var(--font-body)",
+        mono: "var(--font-mono)"
+      },
+      /* Geist-inspired Violet Forge typescale.
+       *
+       * Three strict weights: 400 (body), 500 (UI), 600 (display/headings).
+       * Letter-spacing scales with size — aggressive negative on display.
+       * Mirrors the Vercel/Geist vocabulary while keeping Theo's identity.
+       */
+      fontSize: {
+        // Display tier — aggressive compression, content-led headlines
+        "display-2xl": ["64px", { lineHeight: "1", letterSpacing: "-0.0464em", fontWeight: "600" }],
+        "display-xl": ["48px", { lineHeight: "1.05", letterSpacing: "-0.05em", fontWeight: "600" }],
+        "display-lg": ["40px", { lineHeight: "1.1", letterSpacing: "-0.05em", fontWeight: "600" }],
+        "display-md": ["32px", { lineHeight: "1.2", letterSpacing: "-0.04em", fontWeight: "600" }],
+        headline: ["28px", { lineHeight: "1.25", letterSpacing: "-0.035em", fontWeight: "600" }],
+        // Title tier — section / card heads
+        "title-lg": ["24px", { lineHeight: "1.33", letterSpacing: "-0.04em", fontWeight: "600" }],
+        "title-md": ["20px", { lineHeight: "1.4", letterSpacing: "-0.03em", fontWeight: "600" }],
+        // Body tier — FAANG-density realignment 2026-05-22: body-md is the
+        // industry-standard 14px (shadcn / Vercel Geist / Linear / Stripe /
+        // Mantine). The previous 15px was idiosyncratic. body-sm (14px label
+        // weight) remains separate via its line-height / weight signature.
+        "body-lg": ["18px", { lineHeight: "1.56", letterSpacing: "-0.01em", fontWeight: "400" }],
+        "body-md": ["14px", { lineHeight: "1.43", letterSpacing: "0", fontWeight: "400" }],
+        "body-sm": ["13px", { lineHeight: "1.46", fontWeight: "400" }],
+        // Label tier — used on buttons, nav, secondary actions
+        label: ["14px", { lineHeight: "1.43", fontWeight: "500" }],
+        "label-caps": ["12px", { lineHeight: "1.33", letterSpacing: "0.04em", fontWeight: "500" }],
+        // Mono — code surfaces, technical labels
+        "code-md": ["14px", { lineHeight: "1.5", fontWeight: "400" }],
+        "code-sm": ["13px", { lineHeight: "1.54", fontWeight: "500" }]
+      },
+      borderRadius: {
+        none: "var(--radius-none)",
+        sm: "var(--radius-sm)",
+        md: "var(--radius-md)",
+        lg: "var(--radius-lg)",
+        xl: "var(--radius-xl)",
+        "2xl": "var(--radius-2xl)",
+        full: "var(--radius-full)"
+      },
+      boxShadow: {
+        sm: "var(--shadow-sm)",
+        md: "var(--shadow-md)",
+        lg: "var(--shadow-lg)",
+        glow: "var(--shadow-glow)",
+        "glow-strong": "var(--shadow-glow-strong)"
+      },
+      transitionTimingFunction: {
+        "out-soft": "var(--ease-out-soft)",
+        snap: "var(--ease-snap)"
+      },
+      transitionDuration: {
+        fast: "var(--duration-fast)",
+        base: "var(--duration-base)",
+        slow: "var(--duration-slow)"
+      },
+      keyframes: {
+        "fade-in-up": {
+          "0%": { opacity: "0", transform: "translateY(8px)" },
+          "100%": { opacity: "1", transform: "translateY(0)" }
+        },
+        "pulse-glow": {
+          "0%, 100%": { boxShadow: "0 0 0 0 hsl(var(--primary) / 0.5)" },
+          "50%": { boxShadow: "0 0 0 8px hsl(var(--primary) / 0)" }
+        }
+      },
+      animation: {
+        "fade-in-up": "fade-in-up var(--duration-base) var(--ease-out-soft) both",
+        "pulse-glow": "pulse-glow 1.5s var(--ease-in-out) infinite"
+      }
+    }
+  },
+  plugins: [animate]
+};
+
+// src/preset-v3-legacy.ts
+var LIBRARY_CONTENT_GLOBS = [
+  // Resolved relative to the consumer's `tailwind.config.{ts,js}`.
+  "./node_modules/@usetheo/ui/dist/**/*.{js,mjs,cjs}",
+  // Yarn PnP / pnpm hoist fallback — Tailwind's globbing tolerates both.
+  "./node_modules/@usetheo/ui/dist/**/*.{ts,tsx}"
+];
+var preset = {
+  ...theoUIPreset,
+  content: LIBRARY_CONTENT_GLOBS
+};
+var preset_v3_legacy_default = preset;
+
+export { preset_v3_legacy_default as default };
+//# sourceMappingURL=preset-v3-legacy.js.map
+//# sourceMappingURL=preset-v3-legacy.js.map

package/dist/preset-v3-legacy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/styles/tailwind-preset.ts","../src/preset-v3-legacy.ts"],"names":[],"mappings":"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","file":"preset-v3-legacy.js","sourcesContent":["/**\n * Theo UI Tailwind preset — Violet Forge identity.\n *\n * Single source of truth for the design system's utility-level tokens:\n *   - colors mapped to CSS variables (HSL split via `hsl(var(--x) / <alpha>)`)\n *   - Geist-inspired typescale (display / title / body / label / code tiers)\n *   - radii, shadows, motion timing & duration, keyframes\n *   - tailwindcss-animate plugin\n *\n * Consumed by:\n *   - `tailwind.config.ts` (this repo) via `presets: [theoUIPreset]`\n *   - registry/r/tailwind-preset.json (shipped to consumers via shadcn CLI)\n *\n * Consumers integrate as:\n *\n *   import type { Config } from \"tailwindcss\";\n *   import { theoUIPreset } from \"./styles/tailwind-preset\";\n *\n *   export default {\n *     darkMode: \"class\",\n *     content: [\"./src/**\\/*.{ts,tsx}\"],\n *     presets: [theoUIPreset],\n *   } satisfies Config;\n *\n * Note: `darkMode` and `content` are NOT in the preset — they are consumer\n * decisions. The preset only contains `theme.extend.*` and `plugins`.\n */\n\nimport type { Config } from \"tailwindcss\";\nimport animate from \"tailwindcss-animate\";\n\nconst hsl = (token: string) => `hsl(var(${token}) / <alpha-value>)`;\n\nexport const theoUIPreset: Partial<Config> = {\n  theme: {\n    container: {\n      center: true,\n      padding: \"1rem\",\n      screens: {\n        \"2xl\": \"1280px\",\n      },\n    },\n    extend: {\n      colors: {\n        background: hsl(\"--background\"),\n        foreground: hsl(\"--foreground\"),\n        card: {\n          DEFAULT: hsl(\"--card\"),\n          foreground: hsl(\"--card-foreground\"),\n        },\n        popover: {\n          DEFAULT: hsl(\"--popover\"),\n          foreground: hsl(\"--popover-foreground\"),\n        },\n        primary: {\n          DEFAULT: hsl(\"--primary\"),\n          deep: hsl(\"--primary-deep\"),\n          glow: hsl(\"--primary-glow\"),\n          foreground: hsl(\"--primary-foreground\"),\n        },\n        secondary: {\n          DEFAULT: hsl(\"--secondary\"),\n          foreground: hsl(\"--secondary-foreground\"),\n        },\n        accent: {\n          DEFAULT: hsl(\"--accent\"),\n          deep: hsl(\"--accent-deep\"),\n          foreground: hsl(\"--accent-foreground\"),\n        },\n        muted: {\n          DEFAULT: hsl(\"--muted\"),\n          foreground: hsl(\"--muted-foreground\"),\n        },\n        success: {\n          DEFAULT: hsl(\"--success\"),\n          foreground: hsl(\"--success-foreground\"),\n        },\n        warning: {\n          DEFAULT: hsl(\"--warning\"),\n          foreground: hsl(\"--warning-foreground\"),\n        },\n        destructive: {\n          DEFAULT: hsl(\"--destructive\"),\n          foreground: hsl(\"--destructive-foreground\"),\n        },\n        info: {\n          DEFAULT: hsl(\"--info\"),\n          foreground: hsl(\"--info-foreground\"),\n        },\n        border: hsl(\"--border\"),\n        input: hsl(\"--input\"),\n        ring: hsl(\"--ring\"),\n      },\n      fontFamily: {\n        display: \"var(--font-display)\",\n        sans: \"var(--font-body)\",\n        mono: \"var(--font-mono)\",\n      },\n      /* Geist-inspired Violet Forge typescale.\n       *\n       * Three strict weights: 400 (body), 500 (UI), 600 (display/headings).\n       * Letter-spacing scales with size — aggressive negative on display.\n       * Mirrors the Vercel/Geist vocabulary while keeping Theo's identity.\n       */\n      fontSize: {\n        // Display tier — aggressive compression, content-led headlines\n        \"display-2xl\": [\"64px\", { lineHeight: \"1\", letterSpacing: \"-0.0464em\", fontWeight: \"600\" }],\n        \"display-xl\": [\"48px\", { lineHeight: \"1.05\", letterSpacing: \"-0.05em\", fontWeight: \"600\" }],\n        \"display-lg\": [\"40px\", { lineHeight: \"1.1\", letterSpacing: \"-0.05em\", fontWeight: \"600\" }],\n        \"display-md\": [\"32px\", { lineHeight: \"1.2\", letterSpacing: \"-0.04em\", fontWeight: \"600\" }],\n        headline: [\"28px\", { lineHeight: \"1.25\", letterSpacing: \"-0.035em\", fontWeight: \"600\" }],\n        // Title tier — section / card heads\n        \"title-lg\": [\"24px\", { lineHeight: \"1.33\", letterSpacing: \"-0.04em\", fontWeight: \"600\" }],\n        \"title-md\": [\"20px\", { lineHeight: \"1.4\", letterSpacing: \"-0.03em\", fontWeight: \"600\" }],\n        // Body tier — FAANG-density realignment 2026-05-22: body-md is the\n        // industry-standard 14px (shadcn / Vercel Geist / Linear / Stripe /\n        // Mantine). The previous 15px was idiosyncratic. body-sm (14px label\n        // weight) remains separate via its line-height / weight signature.\n        \"body-lg\": [\"18px\", { lineHeight: \"1.56\", letterSpacing: \"-0.01em\", fontWeight: \"400\" }],\n        \"body-md\": [\"14px\", { lineHeight: \"1.43\", letterSpacing: \"0\", fontWeight: \"400\" }],\n        \"body-sm\": [\"13px\", { lineHeight: \"1.46\", fontWeight: \"400\" }],\n        // Label tier — used on buttons, nav, secondary actions\n        label: [\"14px\", { lineHeight: \"1.43\", fontWeight: \"500\" }],\n        \"label-caps\": [\"12px\", { lineHeight: \"1.33\", letterSpacing: \"0.04em\", fontWeight: \"500\" }],\n        // Mono — code surfaces, technical labels\n        \"code-md\": [\"14px\", { lineHeight: \"1.5\", fontWeight: \"400\" }],\n        \"code-sm\": [\"13px\", { lineHeight: \"1.54\", fontWeight: \"500\" }],\n      },\n      borderRadius: {\n        none: \"var(--radius-none)\",\n        sm: \"var(--radius-sm)\",\n        md: \"var(--radius-md)\",\n        lg: \"var(--radius-lg)\",\n        xl: \"var(--radius-xl)\",\n        \"2xl\": \"var(--radius-2xl)\",\n        full: \"var(--radius-full)\",\n      },\n      boxShadow: {\n        sm: \"var(--shadow-sm)\",\n        md: \"var(--shadow-md)\",\n        lg: \"var(--shadow-lg)\",\n        glow: \"var(--shadow-glow)\",\n        \"glow-strong\": \"var(--shadow-glow-strong)\",\n      },\n      transitionTimingFunction: {\n        \"out-soft\": \"var(--ease-out-soft)\",\n        snap: \"var(--ease-snap)\",\n      },\n      transitionDuration: {\n        fast: \"var(--duration-fast)\",\n        base: \"var(--duration-base)\",\n        slow: \"var(--duration-slow)\",\n      },\n      keyframes: {\n        \"fade-in-up\": {\n          \"0%\": { opacity: \"0\", transform: \"translateY(8px)\" },\n          \"100%\": { opacity: \"1\", transform: \"translateY(0)\" },\n        },\n        \"pulse-glow\": {\n          \"0%, 100%\": { boxShadow: \"0 0 0 0 hsl(var(--primary) / 0.5)\" },\n          \"50%\": { boxShadow: \"0 0 0 8px hsl(var(--primary) / 0)\" },\n        },\n      },\n      animation: {\n        \"fade-in-up\": \"fade-in-up var(--duration-base) var(--ease-out-soft) both\",\n        \"pulse-glow\": \"pulse-glow 1.5s var(--ease-in-out) infinite\",\n      },\n    },\n  },\n  plugins: [animate],\n};\n","/**\n * `@usetheo/ui/preset-v3-legacy` — Tailwind v3 JS preset (legacy path).\n *\n * Default-export a `Partial<Config>` mirroring the design tokens shipped\n * in `@usetheo/ui/tokens.css`. Adds a `content` field covering the\n * library's published artifact tree so v3-based Tailwind builds emit\n * the utilities used by `@usetheo/ui` components.\n *\n * **Tailwind v4 consumers MUST use `@usetheo/ui/preset.css`**, not this\n * file — Tailwind v4 dropped the JS preset format entirely. This file\n * exists for any remaining `tailwindcss@^3` consumer (notably the\n * shadcn-style copy-paste registry path); new code should not import\n * from this subpath.\n *\n * The token surface is delegated to `./styles/tailwind-preset.ts` (the\n * existing source of truth used by the local Ladle dev surface and the\n * shadcn registry).\n *\n * v3 consumer usage:\n *\n *   // tailwind.config.ts (Tailwind v3 only)\n *   import preset from \"@usetheo/ui/preset-v3-legacy\";\n *   export default {\n *     presets: [preset],\n *     content: [\"./app/**\\/*.{ts,tsx}\"],\n *   };\n *\n * See RFC 0008 follow-up.\n */\nimport type { Config } from \"tailwindcss\";\nimport { theoUIPreset } from \"./styles/tailwind-preset.js\";\n\nconst LIBRARY_CONTENT_GLOBS: string[] = [\n  // Resolved relative to the consumer's `tailwind.config.{ts,js}`.\n  \"./node_modules/@usetheo/ui/dist/**/*.{js,mjs,cjs}\",\n  // Yarn PnP / pnpm hoist fallback — Tailwind's globbing tolerates both.\n  \"./node_modules/@usetheo/ui/dist/**/*.{ts,tsx}\",\n];\n\nconst preset: Partial<Config> = {\n  ...theoUIPreset,\n  content: LIBRARY_CONTENT_GLOBS,\n};\n\nexport default preset;\n"]}

package/dist/preset.css

@@ -0,0 +1,27 @@
+/* Theo UI — Tailwind v4 CSS preset.
+ *
+ * For consumers running their own Tailwind v4 build (TheoKit framework
+ * path, custom Vite/Astro/Next apps with @tailwindcss/vite, etc.). The
+ * preset pulls in:
+ *   1. `tokens.css` — runtime `--*` vars `<ThemeProvider>` mutates per
+ *      theme cascade.
+ *   2. `tokens-v4.css` — the `@theme { --color-*, --font-*, --text-*,
+ *      --radius-*, --shadow-*, --ease-*, --animate-* }` namespace
+ *      Tailwind v4 actually reads to generate utilities.
+ *
+ * Consumer usage (their entry CSS):
+ *
+ *   @import "tailwindcss";
+ *   @import "@usetheo/ui/preset.css";
+ *
+ *   /* the consumer's own @theme overrides come AFTER, so they win. * /
+ *
+ * Tailwind v4 dropped the v3 JS preset format. The previous JS preset
+ * remains shipped under `@usetheo/ui/preset-v3-legacy` (which works only
+ * with `tailwindcss@^3`). New v4 consumers MUST use this CSS preset.
+ *
+ * See RFC 0008 follow-up.
+ */
+
+@import "./tokens.css";
+@import "./tokens-v4.css";

package/dist/styles-v3-legacy.css

@@ -0,0 +1,88 @@
+@import "./fonts.css";
+@import "./tokens.css";
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  * {
+    border-color: hsl(var(--border));
+  }
+
+  html {
+    font-family: var(--font-body);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    text-rendering: optimizeLegibility;
+  }
+
+  body {
+    background-color: hsl(var(--background));
+    color: hsl(var(--foreground));
+    /* OpenType ligatures globally — Geist's "liga" feature is structural
+     * and gives the Vercel-tight glyph combinations. */
+    font-feature-settings: "liga" 1, "ss01" 1;
+  }
+
+  /* Display headings inherit theme display font (Geist by default).
+   * Per-size tracking is set in tailwind.config.ts; this is the safety net. */
+  h1,
+  h2,
+  h3,
+  h4 {
+    font-family: var(--font-display);
+    font-weight: 600;
+  }
+
+  /* Code surfaces: use the mono token + tabular numerals so columns of
+   * numbers line up in tables/logs/metrics. */
+  code,
+  pre,
+  kbd,
+  samp {
+    font-family: var(--font-mono);
+    font-feature-settings: "tnum" 1, "liga" 1;
+  }
+
+  /* Focus ring — violet (signature) */
+  :focus-visible {
+    outline: 2px solid hsl(var(--ring));
+    outline-offset: 2px;
+  }
+
+  /* Selection — soft violet */
+  ::selection {
+    background-color: hsl(var(--primary) / 0.25);
+    color: hsl(var(--foreground));
+  }
+
+  /* Native scrollbar fallback (Violet Forge).
+   * Used for native browser scroll on elements that don't wrap in <ScrollArea>.
+   * Components that DO use <ScrollArea> hide the native scrollbar via Radix.
+   */
+  *::-webkit-scrollbar {
+    width: 10px;
+    height: 10px;
+  }
+  *::-webkit-scrollbar-track {
+    background: transparent;
+  }
+  *::-webkit-scrollbar-thumb {
+    background-color: hsl(var(--primary) / 0.25);
+    border: 2px solid transparent;
+    background-clip: content-box;
+    border-radius: 9999px;
+    transition: background-color var(--duration-fast) var(--ease-out-soft);
+  }
+  *::-webkit-scrollbar-thumb:hover {
+    background-color: hsl(var(--primary) / 0.5);
+  }
+  *::-webkit-scrollbar-thumb:active {
+    background-color: hsl(var(--primary) / 0.75);
+  }
+  * {
+    scrollbar-width: thin;
+    scrollbar-color: hsl(var(--primary) / 0.3) transparent;
+  }
+}

package/dist/styles.css

@@ -1,9 +1,26 @@
+/* Theo UI — Tailwind v4 prebuilt entry stylesheet.
+ *
+ * What ships at `@usetheo/ui/styles.css` since RFC 0008 follow-up
+ * (`0.5.1-next.0`). Consumer imports this once and the framework's
+ * Tailwind v4 build picks up:
+ *   - `@import "tailwindcss"` — Tailwind v4 core (preflight + utilities)
+ *   - `@import "./fonts.css"` — self-hosted Geist + Geist Mono @font-face
+ *   - `@import "./tokens.css"` — runtime `--*` vars (theme cascade target)
+ *   - `@import "./tokens-v4.css"` — `@theme { --color-*, --text-*, … }`
+ *     namespace Tailwind v4 reads to emit utilities
+ *   - `@layer base` — `border-color`, body font, focus ring, scrollbar
+ *     styling that depend on the runtime vars
+ *
+ * v3-only consumers (Tailwind 3.x + the shadcn registry preset) should
+ * load `@usetheo/ui/styles-v3-legacy.css` instead — that file is the
+ * unchanged `@tailwind base; @tailwind components; @tailwind utilities`
+ * variant. See RFC 0008 follow-up.
+ */
+
+@import "tailwindcss";
 @import "./fonts.css";
 @import "./tokens.css";
-
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+@import "./tokens-v4.css";
 
 @layer base {
   * {
@@ -26,7 +43,7 @@
   }
 
   /* Display headings inherit theme display font (Geist by default).
-   * Per-size tracking is set in tailwind.config.ts; this is the safety net. */
+   * Per-size tracking is set in tokens-v4.css; this is the safety net. */
   h1,
   h2,
   h3,

package/dist/tokens-v4.css

@@ -0,0 +1,187 @@
+/* Theo UI — Tailwind v4 theme aliases.
+ *
+ * Companion to `tokens.css`. The base file declares the v3-style runtime
+ * variables (`--primary`, `--background`, …) that `<ThemeProvider>` and
+ * `[data-theme]` cascades mutate at runtime. This file declares the
+ * Tailwind v4 `@theme` namespace (`--color-primary`, `--color-background`,
+ * …) by aliasing back to those runtime vars via `hsl(var(--*))`.
+ *
+ * Why two layers:
+ *   - `<ThemeProvider>` (and the 10 built-in themes) sets `--primary`
+ *     etc. at runtime — that's the theme switch surface.
+ *   - Tailwind v4 resolves color utilities exclusively through
+ *     `--color-*` tokens declared in `@theme`. Without these aliases
+ *     `bg-primary`, `text-muted-foreground`, `border-border`, etc. emit
+ *     a className with no matching CSS rule.
+ *
+ * The indirection (`--color-primary: hsl(var(--primary))`) preserves the
+ * runtime theme cascade — browsers resolve `var(--color-primary)` →
+ * `hsl(var(--primary))` → current `[data-theme]` value at paint time.
+ *
+ * See RFC 0008 follow-up.
+ */
+
+@theme {
+  /* Color tokens ------------------------------------------------------ */
+  --color-background: hsl(var(--background));
+  --color-foreground: hsl(var(--foreground));
+
+  --color-card: hsl(var(--card));
+  --color-card-foreground: hsl(var(--card-foreground));
+
+  --color-popover: hsl(var(--popover));
+  --color-popover-foreground: hsl(var(--popover-foreground));
+
+  --color-primary: hsl(var(--primary));
+  --color-primary-deep: hsl(var(--primary-deep));
+  --color-primary-glow: hsl(var(--primary-glow));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+
+  --color-secondary: hsl(var(--secondary));
+  --color-secondary-foreground: hsl(var(--secondary-foreground));
+
+  --color-accent: hsl(var(--accent));
+  --color-accent-deep: hsl(var(--accent-deep));
+  --color-accent-foreground: hsl(var(--accent-foreground));
+
+  --color-muted: hsl(var(--muted));
+  --color-muted-foreground: hsl(var(--muted-foreground));
+
+  --color-border: hsl(var(--border));
+  --color-input: hsl(var(--input));
+  --color-ring: hsl(var(--ring));
+
+  --color-success: hsl(var(--success));
+  --color-success-foreground: hsl(var(--success-foreground));
+  --color-warning: hsl(var(--warning));
+  --color-warning-foreground: hsl(var(--warning-foreground));
+  --color-destructive: hsl(var(--destructive));
+  --color-destructive-foreground: hsl(var(--destructive-foreground));
+  --color-info: hsl(var(--info));
+  --color-info-foreground: hsl(var(--info-foreground));
+
+  /* Fonts ------------------------------------------------------------- */
+  --font-display: var(--font-display);
+  --font-sans: var(--font-body);
+  --font-mono: var(--font-mono);
+
+  /* Violet Forge typescale -------------------------------------------- *
+   * Compound text utilities: each `--text-{name}` declares the size,
+   * with companion `--*--line-height`, `--*--letter-spacing`, and
+   * `--*--font-weight` properties Tailwind v4 picks up automatically.
+   */
+  --text-display-2xl: 64px;
+  --text-display-2xl--line-height: 1;
+  --text-display-2xl--letter-spacing: -0.0464em;
+  --text-display-2xl--font-weight: 600;
+
+  --text-display-xl: 48px;
+  --text-display-xl--line-height: 1.05;
+  --text-display-xl--letter-spacing: -0.05em;
+  --text-display-xl--font-weight: 600;
+
+  --text-display-lg: 40px;
+  --text-display-lg--line-height: 1.1;
+  --text-display-lg--letter-spacing: -0.05em;
+  --text-display-lg--font-weight: 600;
+
+  --text-display-md: 32px;
+  --text-display-md--line-height: 1.2;
+  --text-display-md--letter-spacing: -0.04em;
+  --text-display-md--font-weight: 600;
+
+  --text-headline: 28px;
+  --text-headline--line-height: 1.25;
+  --text-headline--letter-spacing: -0.035em;
+  --text-headline--font-weight: 600;
+
+  --text-title-lg: 24px;
+  --text-title-lg--line-height: 1.33;
+  --text-title-lg--letter-spacing: -0.04em;
+  --text-title-lg--font-weight: 600;
+
+  --text-title-md: 20px;
+  --text-title-md--line-height: 1.4;
+  --text-title-md--letter-spacing: -0.03em;
+  --text-title-md--font-weight: 600;
+
+  --text-body-lg: 18px;
+  --text-body-lg--line-height: 1.56;
+  --text-body-lg--letter-spacing: -0.01em;
+  --text-body-lg--font-weight: 400;
+
+  --text-body-md: 14px;
+  --text-body-md--line-height: 1.43;
+  --text-body-md--letter-spacing: 0;
+  --text-body-md--font-weight: 400;
+
+  --text-body-sm: 13px;
+  --text-body-sm--line-height: 1.46;
+  --text-body-sm--font-weight: 400;
+
+  --text-label: 14px;
+  --text-label--line-height: 1.43;
+  --text-label--font-weight: 500;
+
+  --text-label-caps: 12px;
+  --text-label-caps--line-height: 1.33;
+  --text-label-caps--letter-spacing: 0.04em;
+  --text-label-caps--font-weight: 500;
+
+  --text-code-md: 14px;
+  --text-code-md--line-height: 1.5;
+  --text-code-md--font-weight: 400;
+
+  --text-code-sm: 13px;
+  --text-code-sm--line-height: 1.54;
+  --text-code-sm--font-weight: 500;
+
+  /* Radii — Tailwind v4 reads the value directly (no var indirection). */
+  --radius-none: 0px;
+  --radius-sm: 4px;
+  --radius-md: 6px;
+  --radius-lg: 10px;
+  --radius-xl: 14px;
+  --radius-2xl: 20px;
+  --radius-full: 9999px;
+
+  /* Shadows — alias to tokens.css computed values (which already use
+     * `hsl(var(--foreground) / …)` so theme-switch keeps them in step). */
+  --shadow-sm: var(--shadow-sm);
+  --shadow-md: var(--shadow-md);
+  --shadow-lg: var(--shadow-lg);
+  --shadow-glow: var(--shadow-glow);
+  --shadow-glow-strong: var(--shadow-glow-strong);
+
+  /* Motion ------------------------------------------------------------ */
+  --ease-out-soft: var(--ease-out-soft);
+  --ease-snap: var(--ease-snap);
+
+  /* Animations — declare so `animate-fade-in-up` and `animate-pulse-glow`
+     * resolve. Keyframes are declared below (outside @theme — Tailwind v4
+     * picks them up via the @keyframes namespace).
+     */
+  --animate-fade-in-up: fade-in-up var(--duration-base) var(--ease-out-soft) both;
+  --animate-pulse-glow: pulse-glow 1.5s var(--ease-in-out) infinite;
+}
+
+@keyframes fade-in-up {
+  0% {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  100% {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes pulse-glow {
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 hsl(var(--primary) / 0.5);
+  }
+  50% {
+    box-shadow: 0 0 0 8px hsl(var(--primary) / 0);
+  }
+}

package/dist/vite-plugin.d.ts

@@ -0,0 +1,29 @@
+import { Plugin } from 'vite';
+
+/**
+ * `@usetheo/ui/vite-plugin` — auto-wire Tailwind v4 for consumers.
+ *
+ * Default export is a factory returning ONE Vite Plugin. Internally:
+ *   1. chains `@tailwindcss/vite` v4 via the `config()` hook when resolvable
+ *      and `opts.tailwind !== false`,
+ *   2. exposes a virtual module `virtual:@usetheo/ui/library-sources.css`
+ *      whose contents register `@source` directives covering the library's
+ *      published files, so consumer-side Tailwind scans `@usetheo/ui` JSX
+ *      and emits its utility classes,
+ *   3. degrades gracefully via `console.warn` (never throws) when
+ *      `@tailwindcss/vite` is not installed — the surface stays usable in
+ *      CSS-only mode via the pre-built `@usetheo/ui/styles.css` subpath.
+ *
+ * This is the cross-repo contract TheoKit's `integrateUseTheoUI()` probes
+ * for. See `docs/rfcs/0008-vite-plugin-and-preset.md`.
+ */
+
+interface UseTheoUIPluginOptions {
+    /** Disable Tailwind v4 auto-chain. Default: `true`. */
+    tailwind?: boolean;
+    /** Extra `@source` globs merged into the library defaults. */
+    contentExtra?: string[];
+}
+declare function useTheoUIVite(opts?: UseTheoUIPluginOptions): Plugin;
+
+export { type UseTheoUIPluginOptions, useTheoUIVite as default };

package/dist/vite-plugin.js

@@ -0,0 +1,72 @@
+// src/vite-plugin.ts
+var PLUGIN_NAME = "@usetheo/ui/vite-plugin";
+var VIRTUAL_ID = "virtual:@usetheo/ui/library-sources.css";
+var RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_ID}`;
+function buildLibrarySourcesCss(extra = []) {
+  const defaults = [
+    '"../node_modules/@usetheo/ui/dist/**/*.{js,mjs,cjs}"',
+    '"./node_modules/@usetheo/ui/dist/**/*.{js,mjs,cjs}"'
+  ];
+  const all = [...defaults, ...extra.map((g) => JSON.stringify(g))];
+  return `${all.map((src) => `@source ${src};`).join("\n")}
+`;
+}
+function useTheoUIVite(opts = {}) {
+  const wantsTailwind = opts.tailwind !== false;
+  const extra = opts.contentExtra ?? [];
+  let warned = false;
+  const warnMissingPeer = () => {
+    if (warned) return;
+    warned = true;
+    console.warn(
+      `[${PLUGIN_NAME}] @tailwindcss/vite was not resolvable; falling back to CSS-only mode. Install \`@tailwindcss/vite@^4\` to get the utility-driven design tokens, or import \`@usetheo/ui/styles.css\` directly for the pre-built surface.`
+    );
+  };
+  return {
+    name: PLUGIN_NAME,
+    // Vite's typing for `config()` since 5.x explicitly omits `plugins` from
+    // the allowed return shape to nudge authors toward `Plugin[]` factories.
+    // The runtime still honors `{ plugins }` merge, and the TheoKit contract
+    // requires ONE Plugin object (so we can't return `Plugin[]` here).
+    // The cast keeps the public surface honest and the type-checker quiet.
+    async config(_userConfig, _env) {
+      if (!wantsTailwind) {
+        return void 0;
+      }
+      try {
+        const specifier = "@tailwindcss/vite";
+        const mod = await import(
+          /* @vite-ignore */
+          specifier
+        );
+        const factory = mod.default;
+        if (typeof factory !== "function") {
+          warnMissingPeer();
+          return void 0;
+        }
+        const tw = factory();
+        const tailwindPlugins = Array.isArray(tw) ? tw : [tw];
+        return { plugins: tailwindPlugins };
+      } catch {
+        warnMissingPeer();
+        return void 0;
+      }
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_ID) {
+        return RESOLVED_VIRTUAL_ID;
+      }
+      return void 0;
+    },
+    load(id) {
+      if (id === RESOLVED_VIRTUAL_ID) {
+        return buildLibrarySourcesCss(extra);
+      }
+      return void 0;
+    }
+  };
+}
+
+export { useTheoUIVite as default };
+//# sourceMappingURL=vite-plugin.js.map
+//# sourceMappingURL=vite-plugin.js.map

package/dist/vite-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vite-plugin.ts"],"names":[],"mappings":";AA0BA,IAAM,WAAA,GAAc,yBAAA;AACpB,IAAM,UAAA,GAAa,yCAAA;AACnB,IAAM,mBAAA,GAAsB,KAAK,UAAU,CAAA,CAAA;AAE3C,SAAS,sBAAA,CAAuB,KAAA,GAAkB,EAAC,EAAW;AAK5D,EAAA,MAAM,QAAA,GAAW;AAAA,IACf,sDAAA;AAAA,IACA;AAAA,GACF;AACA,EAAA,MAAM,GAAA,GAAM,CAAC,GAAG,QAAA,EAAU,GAAG,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA,KAAM,IAAA,CAAK,SAAA,CAAU,CAAC,CAAC,CAAC,CAAA;AAChE,EAAA,OAAO,CAAA,EAAG,GAAA,CAAI,GAAA,CAAI,CAAC,GAAA,KAAQ,CAAA,QAAA,EAAW,GAAG,CAAA,CAAA,CAAG,CAAA,CAAE,IAAA,CAAK,IAAI,CAAC;AAAA,CAAA;AAC1D;AAEe,SAAR,aAAA,CAA+B,IAAA,GAA+B,EAAC,EAAW;AAC/E,EAAA,MAAM,aAAA,GAAgB,KAAK,QAAA,KAAa,KAAA;AACxC,EAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,YAAA,IAAgB,EAAC;AAEpC,EAAA,IAAI,MAAA,GAAS,KAAA;AACb,EAAA,MAAM,kBAAkB,MAAY;AAClC,IAAA,IAAI,MAAA,EAAQ;AACZ,IAAA,MAAA,GAAS,IAAA;AAET,IAAA,OAAA,CAAQ,IAAA;AAAA,MACN,IAAI,WAAW,CAAA,yNAAA;AAAA,KACjB;AAAA,EACF,CAAA;AAEA,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,WAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAON,MAAM,MAAA,CAAO,WAAA,EAAa,IAAA,EAAwD;AAChF,MAAA,IAAI,CAAC,aAAA,EAAe;AAClB,QAAA,OAAO,MAAA;AAAA,MACT;AAEA,MAAA,IAAI;AAKF,QAAA,MAAM,SAAA,GAAY,mBAAA;AAClB,QAAA,MAAM,MAAM,MAAM;AAAA;AAAA,UAA0B;AAAA,SAAA;AAC5C,QAAA,MAAM,UAAW,GAAA,CAA8B,OAAA;AAC/C,QAAA,IAAI,OAAO,YAAY,UAAA,EAAY;AACjC,UAAA,eAAA,EAAgB;AAChB,UAAA,OAAO,KAAA,CAAA;AAAA,QACT;AACA,QAAA,MAAM,KAAM,OAAA,EAAoC;AAChD,QAAA,MAAM,kBAAkB,KAAA,CAAM,OAAA,CAAQ,EAAE,CAAA,GAAI,EAAA,GAAK,CAAC,EAAE,CAAA;AACpD,QAAA,OAAO,EAAE,SAAS,eAAA,EAAgB;AAAA,MACpC,CAAA,CAAA,MAAQ;AACN,QAAA,eAAA,EAAgB;AAChB,QAAA,OAAO,MAAA;AAAA,MACT;AAAA,IACF,CAAA;AAAA,IAEA,UAAU,EAAA,EAAI;AACZ,MAAA,IAAI,OAAO,UAAA,EAAY;AACrB,QAAA,OAAO,mBAAA;AAAA,MACT;AACA,MAAA,OAAO,MAAA;AAAA,IACT,CAAA;AAAA,IAEA,KAAK,EAAA,EAAI;AACP,MAAA,IAAI,OAAO,mBAAA,EAAqB;AAC9B,QAAA,OAAO,uBAAuB,KAAK,CAAA;AAAA,MACrC;AACA,MAAA,OAAO,MAAA;AAAA,IACT;AAAA,GACF;AACF","file":"vite-plugin.js","sourcesContent":["/**\n * `@usetheo/ui/vite-plugin` — auto-wire Tailwind v4 for consumers.\n *\n * Default export is a factory returning ONE Vite Plugin. Internally:\n *   1. chains `@tailwindcss/vite` v4 via the `config()` hook when resolvable\n *      and `opts.tailwind !== false`,\n *   2. exposes a virtual module `virtual:@usetheo/ui/library-sources.css`\n *      whose contents register `@source` directives covering the library's\n *      published files, so consumer-side Tailwind scans `@usetheo/ui` JSX\n *      and emits its utility classes,\n *   3. degrades gracefully via `console.warn` (never throws) when\n *      `@tailwindcss/vite` is not installed — the surface stays usable in\n *      CSS-only mode via the pre-built `@usetheo/ui/styles.css` subpath.\n *\n * This is the cross-repo contract TheoKit's `integrateUseTheoUI()` probes\n * for. See `docs/rfcs/0008-vite-plugin-and-preset.md`.\n */\nimport type { Plugin, UserConfig } from \"vite\";\n\nexport interface UseTheoUIPluginOptions {\n  /** Disable Tailwind v4 auto-chain. Default: `true`. */\n  tailwind?: boolean;\n  /** Extra `@source` globs merged into the library defaults. */\n  contentExtra?: string[];\n}\n\nconst PLUGIN_NAME = \"@usetheo/ui/vite-plugin\";\nconst VIRTUAL_ID = \"virtual:@usetheo/ui/library-sources.css\";\nconst RESOLVED_VIRTUAL_ID = `\\0${VIRTUAL_ID}`;\n\nfunction buildLibrarySourcesCss(extra: string[] = []): string {\n  // `@source` paths are resolved relative to the importing CSS file in\n  // Tailwind v4. The library defaults below cover the published artifact\n  // tree under the consumer's `node_modules/@usetheo/ui/dist/`. Extra globs\n  // are appended verbatim — consumers can register additional roots.\n  const defaults = [\n    '\"../node_modules/@usetheo/ui/dist/**/*.{js,mjs,cjs}\"',\n    '\"./node_modules/@usetheo/ui/dist/**/*.{js,mjs,cjs}\"',\n  ];\n  const all = [...defaults, ...extra.map((g) => JSON.stringify(g))];\n  return `${all.map((src) => `@source ${src};`).join(\"\\n\")}\\n`;\n}\n\nexport default function useTheoUIVite(opts: UseTheoUIPluginOptions = {}): Plugin {\n  const wantsTailwind = opts.tailwind !== false;\n  const extra = opts.contentExtra ?? [];\n\n  let warned = false;\n  const warnMissingPeer = (): void => {\n    if (warned) return;\n    warned = true;\n    // biome-ignore lint/suspicious/noConsole: TheoKit cross-repo contract requires `console.warn` (not throw) when the optional `@tailwindcss/vite` peer is missing. See RFC 0008 §3 D1.\n    console.warn(\n      `[${PLUGIN_NAME}] @tailwindcss/vite was not resolvable; falling back to CSS-only mode. Install \\`@tailwindcss/vite@^4\\` to get the utility-driven design tokens, or import \\`@usetheo/ui/styles.css\\` directly for the pre-built surface.`,\n    );\n  };\n\n  return {\n    name: PLUGIN_NAME,\n\n    // Vite's typing for `config()` since 5.x explicitly omits `plugins` from\n    // the allowed return shape to nudge authors toward `Plugin[]` factories.\n    // The runtime still honors `{ plugins }` merge, and the TheoKit contract\n    // requires ONE Plugin object (so we can't return `Plugin[]` here).\n    // The cast keeps the public surface honest and the type-checker quiet.\n    async config(_userConfig, _env): Promise<Omit<UserConfig, \"plugins\"> | undefined> {\n      if (!wantsTailwind) {\n        return undefined;\n      }\n\n      try {\n        // Dynamic import keeps `@tailwindcss/vite` as an OPTIONAL peer. The\n        // specifier is held in a variable so Vite's import-analysis pass\n        // leaves it alone — at runtime the consumer's resolver does the\n        // actual resolution. Resolution failure must not crash the build.\n        const specifier = \"@tailwindcss/vite\";\n        const mod = await import(/* @vite-ignore */ specifier);\n        const factory = (mod as { default?: unknown }).default;\n        if (typeof factory !== \"function\") {\n          warnMissingPeer();\n          return undefined;\n        }\n        const tw = (factory as () => Plugin | Plugin[])();\n        const tailwindPlugins = Array.isArray(tw) ? tw : [tw];\n        return { plugins: tailwindPlugins } as unknown as Omit<UserConfig, \"plugins\">;\n      } catch {\n        warnMissingPeer();\n        return undefined;\n      }\n    },\n\n    resolveId(id) {\n      if (id === VIRTUAL_ID) {\n        return RESOLVED_VIRTUAL_ID;\n      }\n      return undefined;\n    },\n\n    load(id) {\n      if (id === RESOLVED_VIRTUAL_ID) {\n        return buildLibrarySourcesCss(extra);\n      }\n      return undefined;\n    },\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usetheo/ui",
-  "version": "0.4.0-next.0",
+  "version": "0.5.1-next.0",
   "description": "Theo UI — framework-agnostic React component library with the Violet Forge design system. Focused on AI-agent interfaces, cloud dashboards, and developer-tooling surfaces.",
   "license": "Apache-2.0",
   "type": "module",
@@ -11,7 +11,11 @@
       "import": "./dist/index.js"
     },
     "./styles.css": "./dist/styles.css",
+    "./styles-v3-legacy.css": "./dist/styles-v3-legacy.css",
     "./tokens.css": "./dist/tokens.css",
+    "./tokens-v4.css": "./dist/tokens-v4.css",
+    "./preset.css": "./dist/preset.css",
+    "./preset": "./dist/preset.css",
     "./fonts.css": "./dist/fonts.css",
     "./fonts-cdn.css": "./dist/fonts-cdn.css",
     "./slide/themes/default.css": "./dist/slide/themes/default.css",
@@ -439,6 +443,14 @@
     "./slide-deck": {
       "types": "./dist/slide-deck/index.d.ts",
       "import": "./dist/slide-deck/index.js"
+    },
+    "./vite-plugin": {
+      "types": "./dist/vite-plugin.d.ts",
+      "import": "./dist/vite-plugin.js"
+    },
+    "./preset-v3-legacy": {
+      "types": "./dist/preset-v3-legacy.d.ts",
+      "import": "./dist/preset-v3-legacy.js"
     }
   },
   "files": ["dist", "registry/r", "registry/index.json", "LICENSE", "CHANGELOG.md"],
@@ -473,10 +485,13 @@
     "dogfood:slide": "tsx scripts/dogfood-slide.ts",
     "dogfood:slide-deck": "tsx scripts/dogfood-slide-deck.ts",
     "dogfood:slide-rich": "tsx scripts/dogfood-slide-rich.ts",
-    "quality:gates": "pnpm format:check && pnpm lint:ci && pnpm typecheck && pnpm test && pnpm build && pnpm registry:build && pnpm registry:validate && pnpm quality:structure && pnpm quality:bundle && pnpm quality:a11y && pnpm ladle:build && pnpm dogfood:whiteboard && pnpm dogfood:slide && pnpm dogfood:slide-deck && pnpm dogfood:slide-rich",
+    "dogfood:v4-zero-config": "tsx scripts/dogfood-v4-zero-config.ts",
+    "dogfood:v4-real-build": "bash scripts/dogfood-v4-real-build.sh",
+    "quality:gates": "pnpm format:check && pnpm lint:ci && pnpm typecheck && pnpm test && pnpm build && pnpm registry:build && pnpm registry:validate && pnpm quality:structure && pnpm quality:bundle && pnpm quality:a11y && pnpm ladle:build && pnpm dogfood:whiteboard && pnpm dogfood:slide && pnpm dogfood:slide-deck && pnpm dogfood:slide-rich && pnpm dogfood:v4-zero-config",
     "quality:gates:fast": "pnpm format:check && pnpm lint:ci && pnpm typecheck && pnpm registry:build && pnpm registry:validate && pnpm quality:structure"
   },
   "peerDependencies": {
+    "@tailwindcss/vite": "^4.0.0",
     "hast-util-from-html": "^2.0.0",
     "hast-util-sanitize": "^5.0.0",
     "hast-util-to-jsx-runtime": "^2.0.0",
@@ -493,8 +508,10 @@
     "react-dom": ">=18.2.0 <20",
     "roughjs": "^4.6.0",
     "shiki": "^1.0.0",
+    "tailwindcss": "^4.0.0",
     "unist-util-visit": "^5.0.0",
     "unist-util-visit-parents": "^6.0.0",
+    "vite": "^6.0.0 || ^7.0.0",
     "yaml": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -548,6 +565,15 @@
     },
     "mermaid": {
       "optional": true
+    },
+    "@tailwindcss/vite": {
+      "optional": true
+    },
+    "tailwindcss": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
     }
   },
   "dependencies": {