@voltro/ui-shadcn 0.1.0

package/dist/tokens.css

@@ -0,0 +1,532 @@
+/* @voltro/ui-shadcn design tokens — Tailwind v4 + tw-animate-css + the full
+ * shadcn palette (light AND dark values) + the kit's ambient animations.
+ *
+ * Wiring, in your app's src/globals.css (see the styling docs,
+ * `routing/styling`):
+ *
+ *   @import "@voltro/ui-shadcn/tokens.css";
+ *   @source "./";                                       (your app's src)
+ *   @source "../node_modules/@voltro/ui-shadcn/src";    (the kit sources)
+ *
+ * (Directory form shown — the equivalent glob form ending in
+ * "…src/**/*.{tsx,ts,jsx,js}" works too; it just can't be spelled
+ * inside this CSS comment.)
+ *
+ * The SECOND @source (the kit path) is MANDATORY when you render kit
+ * components: @source paths resolve relative to the IMPORTING css file, so
+ * the kit's own @source below expands to YOUR app's src once imported —
+ * kit-only classes are silently dropped without the explicit kit path. The
+ * published package ships src/ precisely so this path matches.
+ *
+ * Keep every @theme block ABOVE any @layer rules in the same stylesheet —
+ * a later @theme is silently dropped. */
+
+@import "tailwindcss";
+@import "tw-animate-css";
+
+/* Tailwind v4 derives content from the Vite module graph; the framework's
+   Vite root is `<app>/.framework/`, not the app src — this glob (rebased to
+   the importing stylesheet, see the header) points the scanner at the
+   consuming app's src/. */
+@source "./**/*.{tsx,ts,jsx,js}";
+
+/* Canonical shadcn-style dark-mode trigger: any descendant of an
+   element with class `dark` inherits the dark token set. */
+@custom-variant dark (&:is(.dark *));
+
+:root {
+  --background: oklch(0.99 0 0);
+  --foreground: oklch(0 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0 0 0);
+  --popover: oklch(0.99 0 0);
+  --popover-foreground: oklch(0 0 0);
+  --primary: oklch(0 0 0);
+  --primary-foreground: oklch(1 0 0);
+  --secondary: oklch(0.94 0 0);
+  --secondary-foreground: oklch(0 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.44 0 0);
+  --accent: oklch(0.94 0 0);
+  --accent-foreground: oklch(0 0 0);
+  --destructive: oklch(0.63 0.19 23.03);
+  --destructive-foreground: oklch(1 0 0);
+  --border: oklch(0.92 0 0);
+  --input: oklch(0.94 0 0);
+  --ring: oklch(0 0 0);
+  --chart-1: oklch(0.81 0.17 75.35);
+  --chart-2: oklch(0.55 0.22 264.53);
+  --chart-3: oklch(0.72 0 0);
+  --chart-4: oklch(0.92 0 0);
+  --chart-5: oklch(0.56 0 0);
+  --sidebar: oklch(0.99 0 0);
+  --sidebar-foreground: oklch(0 0 0);
+  --sidebar-primary: oklch(0 0 0);
+  --sidebar-primary-foreground: oklch(1 0 0);
+  --sidebar-accent: oklch(0.94 0 0);
+  --sidebar-accent-foreground: oklch(0 0 0);
+  --sidebar-border: oklch(0.94 0 0);
+  --sidebar-ring: oklch(0 0 0);
+  --font-sans: Geist, sans-serif;
+  --font-serif: Georgia, serif;
+  --font-mono: Geist Mono, monospace;
+  --radius: 0.5rem;
+  --shadow-x: 0px;
+  --shadow-y: 1px;
+  --shadow-blur: 2px;
+  --shadow-spread: 0px;
+  --shadow-opacity: 0.18;
+  --shadow-color: hsl(0 0% 0%);
+  --shadow-2xs: 0px 1px 2px 0px hsl(0 0% 0% / 0.09);
+  --shadow-xs: 0px 1px 2px 0px hsl(0 0% 0% / 0.09);
+  --shadow-sm:
+    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 1px 2px -1px hsl(0 0% 0% / 0.18);
+  --shadow:
+    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 1px 2px -1px hsl(0 0% 0% / 0.18);
+  --shadow-md:
+    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 2px 4px -1px hsl(0 0% 0% / 0.18);
+  --shadow-lg:
+    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 4px 6px -1px hsl(0 0% 0% / 0.18);
+  --shadow-xl:
+    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 8px 10px -1px hsl(0 0% 0% / 0.18);
+  --shadow-2xl: 0px 1px 2px 0px hsl(0 0% 0% / 0.45);
+  --tracking-normal: 0em;
+  --spacing: 0.25rem;
+}
+
+.dark {
+  --background: oklch(0 0 0);
+  --foreground: oklch(1 0 0);
+  --card: oklch(0.14 0 0);
+  --card-foreground: oklch(1 0 0);
+  --popover: oklch(0.18 0 0);
+  --popover-foreground: oklch(1 0 0);
+  --primary: oklch(1 0 0);
+  --primary-foreground: oklch(0 0 0);
+  --secondary: oklch(0.25 0 0);
+  --secondary-foreground: oklch(1 0 0);
+  --muted: oklch(0.23 0 0);
+  --muted-foreground: oklch(0.72 0 0);
+  --accent: oklch(0.32 0 0);
+  --accent-foreground: oklch(1 0 0);
+  --destructive: oklch(0.69 0.2 23.91);
+  --destructive-foreground: oklch(0 0 0);
+  --border: oklch(0.26 0 0);
+  --input: oklch(0.32 0 0);
+  --ring: oklch(0.72 0 0);
+  --chart-1: oklch(0.81 0.17 75.35);
+  --chart-2: oklch(0.58 0.21 260.84);
+  --chart-3: oklch(0.56 0 0);
+  --chart-4: oklch(0.44 0 0);
+  --chart-5: oklch(0.92 0 0);
+  --sidebar: oklch(0.18 0 0);
+  --sidebar-foreground: oklch(1 0 0);
+  --sidebar-primary: oklch(1 0 0);
+  --sidebar-primary-foreground: oklch(0 0 0);
+  --sidebar-accent: oklch(0.32 0 0);
+  --sidebar-accent-foreground: oklch(1 0 0);
+  --sidebar-border: oklch(0.32 0 0);
+  --sidebar-ring: oklch(0.72 0 0);
+  --font-sans: Geist, sans-serif;
+  --font-serif: Georgia, serif;
+  --font-mono: Geist Mono, monospace;
+  --radius: 0.5rem;
+  --shadow-x: 0px;
+  --shadow-y: 1px;
+  --shadow-blur: 2px;
+  --shadow-spread: 0px;
+  --shadow-opacity: 0.18;
+  --shadow-color: hsl(0 0% 0%);
+  --shadow-2xs: 0px 1px 2px 0px hsl(0 0% 0% / 0.09);
+  --shadow-xs: 0px 1px 2px 0px hsl(0 0% 0% / 0.09);
+  --shadow-sm:
+    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 1px 2px -1px hsl(0 0% 0% / 0.18);
+  --shadow:
+    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 1px 2px -1px hsl(0 0% 0% / 0.18);
+  --shadow-md:
+    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 2px 4px -1px hsl(0 0% 0% / 0.18);
+  --shadow-lg:
+    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 4px 6px -1px hsl(0 0% 0% / 0.18);
+  --shadow-xl:
+    0px 1px 2px 0px hsl(0 0% 0% / 0.18), 0px 8px 10px -1px hsl(0 0% 0% / 0.18);
+  --shadow-2xl: 0px 1px 2px 0px hsl(0 0% 0% / 0.45);
+}
+
+/* ---- Map the tokens above into Tailwind v4's @theme so utility
+   classes like `bg-background`, `text-muted-foreground`, etc.
+   resolve correctly. The `inline` keyword means the values are
+   used verbatim — no @media (prefers-color-scheme) inversion. ---- */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+  --font-serif: var(--font-serif);
+
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+
+  --shadow-2xs: var(--shadow-2xs);
+  --shadow-xs: var(--shadow-xs);
+  --shadow-sm: var(--shadow-sm);
+  --shadow: var(--shadow);
+  --shadow-md: var(--shadow-md);
+  --shadow-lg: var(--shadow-lg);
+  --shadow-xl: var(--shadow-xl);
+  --shadow-2xl: var(--shadow-2xl);
+
+  /* Animation utilities — Tailwind v4 generates `animate-<name>`
+   * utilities from `--animate-<name>` registrations here. Keyframe
+   * definitions live further down (CSS doesn't care about order between
+   * @keyframes and the rule that references them, so the @theme block
+   * stays consolidated at the top to avoid the multi-@theme merge bug
+   * where blocks after @layer get silently dropped). */
+  --animate-mesh-drift-a: ui-mesh-drift-a 70s ease-in-out infinite;
+  --animate-mesh-drift-b: ui-mesh-drift-b 90s ease-in-out infinite;
+  --animate-mesh-drift-c: ui-mesh-drift-c 60s ease-in-out infinite;
+  --animate-caret-blink: ui-caret-blink 1s steps(2) infinite;
+  --animate-gradient-pan: ui-gradient-pan 8s ease-in-out infinite;
+  --animate-pulse-ring: ui-pulse-ring 2s ease-out infinite;
+  --animate-shimmer: ui-shimmer 2.5s linear infinite;
+  --animate-twinkle: ui-twinkle 6s ease-in-out infinite;
+}
+
+/* Border-color reset in @layer components (NOT @layer base). Under Vite the
+ * consuming app's entry `@import "tailwindcss"` AND this kit's own
+ * `@import "tailwindcss"` inject Tailwind preflight TWICE; the duplicate
+ * `* { border: 0 solid }` (→ currentColor) lands AFTER a reset inside
+ * @layer base and wins, so every plain `border` renders as the text color
+ * (white in dark mode). @layer components beats @layer base (preflight) yet
+ * loses to @layer utilities, so `border-red-500` / `border-destructive` still
+ * override. (Bundler-dedup'd builds like Turbopack only ever see one
+ * preflight, so this is harmless there.) */
+@layer components {
+  *,
+  ::before,
+  ::after {
+    border-color: var(--border);
+  }
+}
+
+@layer base {
+  html,
+  body {
+    background: var(--background);
+    color: var(--foreground);
+    font-family: var(--font-sans);
+    min-height: 100vh;
+    font-feature-settings:
+      "rlig" 1,
+      "calt" 1;
+  }
+  /* Reserve scrollbar gutter unconditionally. Without this, short
+   * pages have no vertical scrollbar and long pages do — the resulting
+   * ~15px viewport-width difference shifts every `mx-auto max-w-7xl`
+   * container by ~7-8px between page navigations. Centered brand
+   * marks and nav rows visibly jump on route change. `stable` reserves
+   * the gutter even when no scrollbar is rendered, so layout is
+   * page-length-independent. */
+  html {
+    scrollbar-gutter: stable;
+  }
+
+  /* Pointer cursor on every actionable element. Tailwind v4 dropped
+   * the Preflight rule that gave `<button>` `cursor: pointer`,
+   * matching macOS/Windows native button behaviour. Most apps in this
+   * repo expect web-style pointer affordance on anything clickable
+   * (buttons, role="button" divs, summary, label[for]). Re-enable
+   * here so every plain `<button>` in a consumer app picks it up
+   * without per-component opt-in. `:not(:disabled)` keeps disabled
+   * buttons at default (paired with shadcn's `disabled:pointer-events-none`). */
+  button:not(:disabled),
+  [role="button"]:not([aria-disabled="true"]),
+  [role="menuitem"]:not([aria-disabled="true"]),
+  summary,
+  label[for] {
+    cursor: pointer;
+  }
+  body {
+    margin: 0;
+  }
+
+  /* Cross-browser custom scrollbars. Thin, theme-aware, the thumb
+   * brightens on hover. Same visual outcome as a Radix ScrollArea
+   * but with zero JS + no extra DOM. Applies to every scrollable
+   * element (sidebars, code blocks, the page itself); add
+   * `.scrollbar-default` on any element to opt out. */
+  * {
+    /* Firefox */
+    scrollbar-width: thin;
+    scrollbar-color: var(--border) transparent;
+  }
+  *::-webkit-scrollbar {
+    width: 10px;
+    height: 10px;
+  }
+  *::-webkit-scrollbar-track {
+    background: transparent;
+  }
+  *::-webkit-scrollbar-thumb {
+    background: var(--border);
+    border-radius: 999px;
+    border: 2px solid transparent;
+    background-clip: padding-box;
+    transition: background-color 120ms ease;
+  }
+  *::-webkit-scrollbar-thumb:hover {
+    background-color: var(--muted-foreground);
+    background-clip: padding-box;
+  }
+  *::-webkit-scrollbar-corner {
+    background: transparent;
+  }
+  .scrollbar-default {
+    scrollbar-width: auto;
+    scrollbar-color: auto;
+  }
+  .scrollbar-default::-webkit-scrollbar {
+    width: revert;
+    height: revert;
+  }
+  .scrollbar-default::-webkit-scrollbar-thumb {
+    background: revert;
+    border: revert;
+    border-radius: revert;
+  }
+}
+
+.font-tabular {
+  font-variant-numeric: tabular-nums;
+}
+
+/* ---- Cinematic ambient animations ----
+ * Slow drifting blobs, blinking caret, gradient pan. All transform-
+ * only (GPU-composited), all motion-safe via the `motion-safe:`
+ * Tailwind variant on the consumer. Durations are deliberately long
+ * (45–90s) so motion feels ambient, not "loud". */
+
+@keyframes ui-mesh-drift-a {
+  0%,
+  100% {
+    transform: translate3d(0, 0, 0) scale(1);
+  }
+  33% {
+    transform: translate3d(8vw, 4vh, 0) scale(1.05);
+  }
+  66% {
+    transform: translate3d(-4vw, 8vh, 0) scale(0.95);
+  }
+}
+@keyframes ui-mesh-drift-b {
+  0%,
+  100% {
+    transform: translate3d(0, 0, 0) scale(1);
+  }
+  33% {
+    transform: translate3d(-6vw, -5vh, 0) scale(1.08);
+  }
+  66% {
+    transform: translate3d(4vw, -8vh, 0) scale(0.92);
+  }
+}
+@keyframes ui-mesh-drift-c {
+  0%,
+  100% {
+    transform: translate(-50%, 0) scale(1);
+  }
+  50% {
+    transform: translate(-50%, -8vh) scale(1.1);
+  }
+}
+@keyframes ui-caret-blink {
+  0%,
+  50% {
+    opacity: 1;
+  }
+  51%,
+  100% {
+    opacity: 0;
+  }
+}
+@keyframes ui-gradient-pan {
+  0%,
+  100% {
+    background-position: 0% 50%;
+  }
+  50% {
+    background-position: 100% 50%;
+  }
+}
+@keyframes ui-pulse-ring {
+  0% {
+    transform: scale(0.6);
+    opacity: 0;
+  }
+  20% {
+    transform: scale(0.7);
+    opacity: 0.4;
+  }
+  100% {
+    transform: scale(1.3);
+    opacity: 0;
+  }
+}
+@keyframes ui-shimmer {
+  0% {
+    transform: translateX(-100%);
+  }
+  100% {
+    transform: translateX(200%);
+  }
+}
+@keyframes ui-twinkle {
+  /* Twinkle = restrained opacity ramp + a hint of scale. Caps at
+   * opacity 0.7 so the dot never fully solidifies (would read as a
+   * UI element, not ambient sparkle). Stays at 0 for 30% of the
+   * cycle so different dots feel arrhythmic. */
+  0%,
+  30%,
+  100% {
+    opacity: 0;
+    transform: scale(0.6);
+  }
+  55% {
+    opacity: 0.7;
+    transform: scale(1);
+  }
+  75% {
+    opacity: 0.3;
+    transform: scale(0.85);
+  }
+}
+
+/* ---- Shiki dual-theme switch ----
+ * `HighlightedCode` (and any direct codeToHtml caller using
+ * `themes: { light, dark }` + `defaultColor: false`) emits inline
+ * styles like `--shiki-light:#xxx; --shiki-dark:#yyy` on every
+ * token span. The rules below resolve those CSS vars to the actual
+ * color/bg, picking the LIGHT set by default and DARK under `.dark`.
+ *
+ * Background goes ONLY on the <pre> — putting it on inner spans too
+ * paints the per-line `<span class="line">` elements with the theme
+ * bg, which then visibly banded against the surrounding wrapper
+ * (CodeBlock figure / CodeWindow chrome) because the colours are
+ * close-but-not-identical. Spans keep the color rule so per-token
+ * syntax highlighting still works. */
+pre.shiki {
+  background-color: var(--shiki-light-bg) !important;
+  color: var(--shiki-light) !important;
+}
+pre.shiki span {
+  color: var(--shiki-light) !important;
+}
+.dark pre.shiki {
+  background-color: var(--shiki-dark-bg) !important;
+  color: var(--shiki-dark) !important;
+}
+.dark pre.shiki span {
+  color: var(--shiki-dark) !important;
+}
+
+/* Heading with hand-painted gradient text. Use on display-size <h1>
+ * elements: `<h1 className="text-gradient">…</h1>`. Combines well
+ * with motion-safe animate-gradient-pan for the cinematic pan effect. */
+.text-gradient {
+  background-image: linear-gradient(
+    100deg,
+    var(--foreground) 0%,
+    oklch(0.75 0.18 290) 50%,
+    var(--foreground) 100%
+  );
+  background-size: 200% auto;
+  -webkit-background-clip: text;
+  background-clip: text;
+  -webkit-text-fill-color: transparent;
+  color: transparent;
+}
+
+/* ---- Stagger entrance for grids ----
+ * `.stagger-in > *` fades + slides up with a 40ms delay between
+ * children. Used by DocCards (and reusable for any grid). Respects
+ * prefers-reduced-motion. */
+@keyframes ui-stagger-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+.stagger-in > * {
+  animation: ui-stagger-in 320ms cubic-bezier(0.2, 0.8, 0.2, 1) backwards;
+}
+.stagger-in > *:nth-child(1) {
+  animation-delay: 0ms;
+}
+.stagger-in > *:nth-child(2) {
+  animation-delay: 40ms;
+}
+.stagger-in > *:nth-child(3) {
+  animation-delay: 80ms;
+}
+.stagger-in > *:nth-child(4) {
+  animation-delay: 120ms;
+}
+.stagger-in > *:nth-child(5) {
+  animation-delay: 160ms;
+}
+.stagger-in > *:nth-child(6) {
+  animation-delay: 200ms;
+}
+.stagger-in > *:nth-child(7) {
+  animation-delay: 240ms;
+}
+.stagger-in > *:nth-child(8) {
+  animation-delay: 280ms;
+}
+.stagger-in > *:nth-child(9) {
+  animation-delay: 320ms;
+}
+.stagger-in > *:nth-child(n + 10) {
+  animation-delay: 360ms;
+}
+@media (prefers-reduced-motion: reduce) {
+  .stagger-in > * {
+    animation: none;
+  }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@voltro/ui-shadcn",
+  "version": "0.1.0",
+  "description": "Voltro's first-party shadcn/ui kit: Tailwind v4 design tokens (light + dark), 30+ primitives, layout compositions, styled widgets for the @voltro/ui seam, and the canonical theme/language preference-cookie helpers.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./cn": {
+      "types": "./dist/cn.d.ts",
+      "import": "./dist/cn.js",
+      "default": "./dist/cn.js"
+    },
+    "./brand": {
+      "types": "./dist/brand.d.ts",
+      "import": "./dist/brand.js",
+      "default": "./dist/brand.js"
+    },
+    "./tokens.css": "./dist/tokens.css"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "*.css"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@radix-ui/react-dropdown-menu": "^2.1.20",
+    "@radix-ui/react-toggle": "^1.1.14",
+    "@radix-ui/react-toggle-group": "^1.1.15",
+    "@voltro/ui": "0.1.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "shiki": "^4.3.1",
+    "tailwind-merge": "^3.6.0",
+    "tw-animate-css": "^1.2.5"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/brand/README.md

@@ -0,0 +1,60 @@
+# Voltro brand mark
+
+The company + framework logo: a faceted lightning bolt ("volt") that
+also reads as the **V** of Voltro. On-brand violet
+(`oklch(0.55 0.25 290)` ≈ `#7C3AED` — the same hue as the text-gradient
+and mesh backdrop). One source, every app.
+
+## React (the usual path)
+
+```tsx
+import { VoltroMark, VoltroIcon, VoltroWordmark } from '@voltro/ui-shadcn'
+
+// Header lock-up — text uses the app's font + currentColor (light/dark safe)
+<VoltroWordmark size={28} />
+
+// The bolt alone
+<VoltroMark size={32} />                       // gradient (default)
+<VoltroMark size={20} variant="mono" />        // currentColor — inherits text colour
+<VoltroMark size={20} variant="white" />       // on a coloured surface
+
+// App / advertising icon (bolt on a rounded squircle, own background)
+<VoltroIcon size={40} />                        // brand: violet squircle + white bolt
+<VoltroIcon size={40} tone="dark" />            // near-black squircle + glowing bolt
+```
+
+`variant="mono"` paints in `currentColor`, so it's automatically correct
+in light **and** dark mode — no theme branching. The `gradient` and
+`icon` variants carry their own colour and sit on any background.
+
+## Static assets (favicons, OG images, app-store / ad icons)
+
+Plain `.svg` in [`./assets`](./assets) for non-React use:
+
+| File | Use |
+|---|---|
+| `voltro-favicon.svg` | **Favicon** — light/dark **adaptive** (`prefers-color-scheme`): the two-tone violet bolt on a squircle that's light in light mode, dark in dark mode |
+| `voltro-mark.svg` | Gradient bolt, transparent — inline / marketing |
+| `voltro-mark-mono.svg` | `currentColor` bolt — set `color`/`fill` to theme it |
+| `voltro-icon.svg` | **App-store / ad icon** — two-tone bolt on the solid violet squircle (fixed brand colour, not adaptive) |
+| `voltro-icon-dark.svg` | Dark squircle + glowing bolt — dark-only OG / placements |
+
+```html
+<!-- Adaptive favicon — follows the browser/OS theme (the framework's web
+     head auto-links /favicon.svg, so just drop voltro-favicon.svg there). -->
+<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+```
+
+Use the **adaptive `voltro-favicon.svg`** as the favicon (it stays readable
+in both light and dark browser chrome). Use the **fixed `voltro-icon.svg`**
+where the icon needs one consistent colour regardless of theme — app-store
+listings, ads, OG images. For PNG app-store sizes (1024², 512², 192², 180², …)
+rasterise `voltro-icon.svg` at the target resolution — it's
+resolution-independent, so one source covers every size.
+
+## Colour
+
+Primary violet `#7C3AED` (`VOLTRO_VIOLET`). The faceted variants run a
+hue-292 family: lit facet `#A874FF → #7C3AED`, shaded facet
+`#6D28D9 → #4C1D95`. Need the raw geometry? `VOLTRO_BOLT_PATH`
+(`{ full, front, back }`) exposes the path data to compose your own SVG.

package/src/brand/assets/voltro-favicon.svg

@@ -0,0 +1,30 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" fill="none" role="img" aria-label="Voltro">
+  <!-- Adaptive favicon. The two-tone VIOLET Voltro bolt is the star; the
+       squircle behind it follows the browser/OS light–dark preference
+       (prefers-color-scheme) so the brand bolt stays visible in both modes —
+       light squircle in light mode, dark squircle (+ glow) in dark mode.
+       Browsers honour @media inside an SVG favicon. For a non-adaptive,
+       always-violet app/store icon use voltro-icon.svg instead. -->
+  <style>
+    .sq   { fill: #F2F0FB; }   /* light squircle */
+    .glow { opacity: 0; }
+    .lit  { fill: #7C3AED; }   /* violet front facet */
+    .shad { fill: #5B21B6; }   /* deep violet back facet */
+    @media (prefers-color-scheme: dark) {
+      .sq   { fill: #18141F; } /* dark squircle */
+      .glow { opacity: 1; }
+      .lit  { fill: #C4A6FF; }
+      .shad { fill: #9D5BFF; }
+    }
+  </style>
+  <defs>
+    <radialGradient id="voltroFaviconGlow" cx="0.5" cy="0.46" r="0.5">
+      <stop stop-color="#7C3AED" stop-opacity="0.5"/>
+      <stop offset="1" stop-color="#7C3AED" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+  <rect class="sq" width="64" height="64" rx="14.5"/>
+  <ellipse class="glow" cx="32" cy="30" rx="26" ry="26" fill="url(#voltroFaviconGlow)"/>
+  <path class="lit"  transform="translate(8 8)" d="M28 5 13 27 22 26 20 43Z"/>
+  <path class="shad" transform="translate(8 8)" d="M28 5 20 43 35 21 26 22Z"/>
+</svg>