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
@themeblocks ABOVE any@layerrules in the same stylesheet. A second@themeblock placed AFTER@layer baseis 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.