Styling (Tailwind v4)

Tailwind v4 is auto-loaded in every web app's Vite pipeline. The mandatory @source glob, @theme design tokens, and the two silent-failure gotchas (the framework root is .framework/, not src/; a second @theme after @layer is dropped).

Every Voltro web app's Vite pipeline auto-loads @tailwindcss/vite. Apps that don't use Tailwind pay no runtime cost (the plugin emits nothing when no @import "tailwindcss" appears in any CSS file).

To use it:

/* src/globals.css */
@import "tailwindcss";

/* IMPORTANT: the framework's Vite root is `<app>/.framework/`, not
   `<app>/src/`. Without @source, Tailwind's content scanner misses every .tsx
   file under src/ — you get an empty `@layer utilities` and zero applied
   styles. The path is relative to THIS css file. */
@source "./**/*.{tsx,ts,jsx,js}";

@theme {
  --color-background: #0a0a0a;
  --color-foreground: #fafafa;
  --radius: 0.5rem;
}
// src/pages/layout.tsx
import '../globals.css'

Tailwind v4's @theme block doubles as the framework's design-tokens surface — define your colours / radii / fonts there once and they become available as bg-background, text-foreground, etc. The shadcn convention works directly on top: copy a component's source, the classes resolve.

Gotcha: keep ALL @theme blocks ABOVE any @layer rules in the same stylesheet. A second @theme block placed AFTER @layer base is silently dropped by Tailwind v4 — none of its tokens are emitted.

Using @voltro/ui-shadcn — the kit @source is mandatory

If your app imports @voltro/ui-shadcn/tokens.css, you MUST declare a SECOND @source pointing at the kit's source — otherwise every class that exists ONLY inside a kit component (animations like motion-safe:animate-mesh-drift-a, motion-safe:animate-twinkle, kit-internal prose variants) is silently dropped from the generated CSS. The components mount and the keyframes register, but the animate-* utility classes never resolve — no warning is emitted.

/* src/globals.css — app uses kit compositions */
@import "@voltro/ui-shadcn/tokens.css";

@source "./**/*.{tsx,ts,jsx,js}";
@source "../node_modules/@voltro/ui-shadcn/src/**/*.{tsx,ts,jsx,js}";

Why: the kit's tokens.css ships its own @source "./**/*", but @source paths resolve relative to the IMPORTING css file — so once your globals.css imports the kit, the kit's ./**/* glob expands to YOUR app's src, not the kit's. The kit's own components are then never scanned. Declaring the explicit kit path closes the gap — the published package ships its src/ precisely so this glob matches (workspace link and npm install alike).

How to verify: curl -sS http://localhost:<port>/@fs/<abs>/src/globals.css | grep animate- should list every kit animation utility you use. If a class is missing, the @source is misconfigured.

Point the glob at what the package SHIPS

@voltro/ui-shadcn publishes its src/, so the glob above matches in a real install. Most packages do not. A package that publishes only its bundle has no src/ once installed, and a src/** glob then matches nothing — in your workspace, where the dependency is a symlink to the source tree, the very same line matches everything. So the stylesheet is correct locally and wrong in CI, which is the build that produces your deployed CSS. Scan the bundle instead:

@source "../node_modules/<pkg>/dist/*.js";

Tailwind extracts class names from built JavaScript exactly as it does from .tsx, so this is a complete scan, not a fallback. Scan the ONE path the package publishes — adding a src/** line beside it does not help the install and hides the mistake in your workspace, where it is the line that matches. Rebuild the dependency after editing it, since its bundle is what you scan.

voltro build warns for every @source that matches no file, and voltro doctor reports the same. An empty @source is otherwise silent — Tailwind reports neither the empty set nor the utilities it therefore did not generate.

The Dialog primitive accepts all native dialog attributes plus a React ref. Pass ref={dialogRef} with useRef<HTMLDialogElement>(null), then call dialogRef.current?.showModal() to open it modally and dialogRef.current?.close() to close it. The ref points to the native element.

Signal brand theme

The base tokens.css includes the semantic --success, --warning and --info colors in both themes, with matching Tailwind color utilities. Shared Callout variants use these tokens; consumers do not need separate local definitions.

signal.css is an optional Voltro brand layer over the kit's base tokens. It provides light and dark plum surfaces, violet actions, readable accent text, focus styles, compact controls and the Signal marketing compositions. Import it after tokens.css; importing only the base tokens keeps their neutral palette.

@import "@voltro/ui-shadcn/tokens.css";
@import "@voltro/ui-shadcn/signal.css";

@source "./**/*.{tsx,ts,jsx,js}";
@source "../node_modules/@voltro/ui-shadcn/src/**/*.{tsx,ts,jsx,js}";

SignalField renders 17 decorative contours and five light traces. It is static by default; animated enables a slow wave. Pass paused from a visible control when enabling motion. The field suspends work while offscreen or while the tab is hidden, cancels animation under reduced motion, and releases observers, listeners and animations on unmount. Browsers without SVG path interpolation retain the original contours. Keep the field in a sized .signal-stage parent; .signal-shell supplies the responsive content gutters.

Use .signal-shell signal-opener for a page opening: .signal-opener-title and .signal-opener-accent share the responsive headline scale; .signal-opener-description follows below, then .signal-opener-actions places the primary CTA and .signal-opener-secondary together on the left. These classes own typography, spacing and CTA interactions across the framework, Cloud and Docs index. Keep product-specific previews below this sequence. The sections beneath use mx-auto max-w-7xl px-6 (1280px including 24px side padding); article reading columns keep their own narrower measure.

SignalHeader accepts a brand, ordinary links, a disclosure title and links, and optional utilities such as a locale switch. It preserves visible mobile navigation, supports keyboard activation and Escape with focus return, and closes when focus or a pointer moves outside. Supply translated labels from your app catalog. It has no router or authentication dependency.

SignalHeader shares a transparent masthead, responsive gutters and the --signal-header-height token (112px, 96px, then 158px at widths up to 900px). At 900px and below, navigation moves to a second row so the brand and controls fit even with longer translated labels. Use sticky for reading or operating navigation: the header stays at the top and gains the current theme's background after scrolling. Use the same height token for sticky sidebars and anchor clearance. AppShell accepts a header node to compose this navigation above its task content.

SignalPreferences provides the same appearance/language menu on every Signal surface. Pass the current locale and an optional onLanguageChange callback (return false when routing in place). It reuses ProfileMenu for keyboard navigation, focus return, account links and optional identity. Use theme: 'system' in app.config.ts so the framework applies the saved theme before paint. The menu stores Light, Dark and System in the voltro:theme cookie; System follows the operating system, including after reloading.

Use SignalSearch with a localized label and onOpen callback for a search command. Its desktop surface matches the navigation rail; at smaller widths it becomes a labeled icon button. SignalHeaderAction is the secondary header link for actions such as sign in. Keep the filled split CTA for the page's main action. The navigationAction slot places contextual navigation, such as a section drawer button, alongside the rail instead of amongst preferences.

For Voltro-owned surfaces, VoltroWordmark from @voltro/ui-shadcn/brand accepts product for the aligned product badge and productTone="warning" for operator surfaces. SignalHeader scales the whole lockup together and puts the badge below the wordmark on narrow screens; do not resize the bolt independently or append a separate product suffix. Outside this header, use size={32} for compact sidebar branding and size={28} for footers. User apps keep their own brand in the same header slot.

import { useState } from 'react'
import { SignalField, SignalHeader } from '@voltro/ui-shadcn'

export function ProductIntro() {
  const [paused, setPaused] = useState(false)
  return (
    <section className="signal-stage">
      <SignalField animated paused={paused} />
      <SignalHeader
        brand={<a href="/">Product</a>}
        navigationLabel="Main navigation"
        menuLabel="Explore"
        menuTitle="One connected product."
        links={[{ label: 'Docs', href: '/docs' }]}
        menuLinks={[{ label: 'Features', href: '/features' }]}
      />
      <div className="signal-shell signal-opener">
        <h1 className="signal-opener-title">Your product<span className="signal-opener-accent">One connected stack.</span></h1>
        <p className="signal-opener-description">Everything you need to build your next application.</p>
        <div className="signal-opener-actions">
          <a className="signal-primary" href="/start"><span>Get started</span></a>
          <a className="signal-opener-secondary" href="/docs"><span>Read the docs</span></a>
        </div>
        <button className="signal-motion-toggle" type="button"
          aria-pressed={paused} onClick={() => setPaused(!paused)}>
          {paused ? 'Resume motion' : 'Pause motion'}
        </button>
      </div>
    </section>
  )
}

Use the expressive field on marketing introductions. Documentation and working apps can use the theme without ambient motion; .signal-operate adds restrained selection, table and form treatments. .signal-primary and .signal-arrow compose the split violet CTA, while .signal-text-link styles a secondary link. The stylesheet contains no font download: configure a self-hosted face through the font pipeline and point --font-sans at its generated variable. The first-party templates use the same palette; templates with plain CSS keep their small dependency footprint and define the equivalent local tokens.

The local Devtools settings use the same voltro:theme preference cookie as the UI-kit profile menu. Light and dark choices survive reloads; selecting System stores that preference and follows the operating-system theme. applyTheme emits THEME_CHANGE_EVENT so other appearance controls can refresh their selected state in the same document.

Documentation shell

DocsLayout accepts a header render function for a custom masthead. It receives menuButton, the layout's own mobile navigation trigger; include this in the header so the section drawer stays reachable. intro places content above the reading columns. sidebar={false} hides the desktop rail on an index while keeping mobile navigation available. Article pages normally keep the rail.

import { DocsLayout, SignalHeader } from '@voltro/ui-shadcn'

export function DocsIndex() {
  return (
    <DocsLayout brand="Product" nav={[]} sidebar={false}
      header={({ menuButton }) => (
        <SignalHeader brand={<a href="/">Product Docs</a>}
          navigationLabel="Documentation navigation" links={[]}
          menuLabel="Docs" menuTitle="Browse documentation"
          menuLinks={[{ label: 'Introduction', href: '/docs/intro' }]}
          utilities={menuButton} />
      )}
      intro={<section><h1>Product documentation</h1></section>}>
      <a href="/docs/intro">Introduction</a>
    </DocsLayout>
  )
}

The mobile drawer uses a native modal dialog: Escape closes it, focus stays inside, and closing returns focus to its trigger. Selecting a link dismisses the drawer. SearchModal also contains keyboard focus and restores it on close. Supply translated labels for both components, including TOC and pager captions. Keep article text and code still; a Docs index may use a pausable SignalField when its brand calls for it.

Styles before the first paint

Production builds put a rendered page's CSS and its static dependencies in the initial HTML, including locale mirrors and shared layouts. Static, SSR and ISR pages therefore receive their component styles before hydration. CSS from unrelated pages and dynamic-only components stays deferred. The same links respect web.assetPrefix.

HighlightedCode keeps escaped code readable immediately and loads its optional syntax highlighter when the block approaches the viewport. The light syntax palette keeps red keywords and orange parameters above the small-text contrast threshold on the kit's light surfaces.

Shared code styles preserve Shiki’s inline light-theme colors and also support CSS-variable output. Dark-theme rules override the light colors when the theme changes, so syntax coloring remains visible in both modes.