Velaguides

Colors and surfaces

Fills, strokes, radius, shadows, blur, gradients and opacity, and the Roblox properties each one writes.

Color utilities read a key from theme.colors and write it to one Roblox property. Nothing cascades. A class sets one property on one instance.

src/client/Card.tsx
<frame className="bg-slate-800 rounded-lg border border-slate-700 shadow-lg">
<textlabel className="text-slate-100" Text="Ready" />
</frame>
A fill, a fill with a stroke, a pill radius, and a gradient — four utility families, four different targets.

Open the Lowered tab to see where each class goes. bg-* lands on the frame. border-*, rounded-* and the gradient each become a child instance.

The color families

FamilyRoblox propertyWritten on
bg-*BackgroundColor3the host instance
text-*TextColor3the host instance
image-*ImageColor3the host instance
placeholder-*PlaceholderColor3the host instance
border-{color}, ring-{color}, outline-{color}Colorthe shared UIStroke child
shadow-{color}Colora UIShadow child
inset-shadow-{color}, text-shadow-{color}Colortheir own UIShadow child
divide-{color}BackgroundColor3the separator frames
from-*, via-*, to-*color keypointsa UIGradient child

border-{color} also sets the stroke’s Transparency to 0, so you don’t need a second class to make it visible.

text-* also covers size, alignment and wrapping. See Text and fonts for how Vela tells them apart.

Arbitrary hex colors

Any color family takes a bracketed hex: bg-[#3fa8c2] or bg-[#fff]. Only three- and six-digit forms work. Anything else reports unsupported-arbitrary-value.

Use these sparingly. If a hex appears twice, give it a name in your theme.

Opacity modifiers

Add /N (an integer from 0 to 100) to set a color and its transparency in one class:

  • bg-blue-600/50 sets BackgroundColor3 and BackgroundTransparency = 0.5.
  • text-slate-100/80 shows the text at 80% opacity.
  • border-slate-500/25 fades the stroke, and divide-white/10 fades the separators.
  • from-blue-600/50 fades only that gradient stop.

placeholder-* is the exception. Roblox has no placeholder transparency, so /N there reports unsupported-opacity-modifier.

transparent

transparent sets the family’s transparency to 1 and writes no color. bg-transparent emits BackgroundTransparency = 1 and nothing else.

You rarely need bg-transparent. Preflight already starts every classed element with a clear background. Use it when a variant paints the background and the default should be clear, or when you set preflight: false.

Three keywords don’t work:

  • placeholder-transparent reports unsupported-color-key. PlaceholderColor3 has no transparency to set.
  • current and inherit report unsupported-color-key. Roblox has no cascade, so a TextLabel can’t take its color from a parent.
  • from-transparent, via-transparent and to-transparent are dropped without a warning. A two-stop gradient then renders as a flat fill.

Shades and diagnostics

Write a palette name plus a shade (bg-blue-500), a bare palette name (bg-blue), or a semantic key (bg-surface). A bare name uses the palette’s DEFAULT, which every built-in palette sets to its 500.

A suffix counts as a shade only if it is one of the eleven shade numbers. Otherwise the whole payload is one key: bg-my-color looks up my-color.

CodeFires when
color-missing-shadeyou wrote a bare palette name and that palette has no DEFAULT
color-invalid-shadeyou gave a literal a shade (bg-white-500), or asked for a shade the palette lacks
unknown-theme-keythe name isn’t in theme.colors

All three are warnings. The class is dropped and the build continues. See Theming to add your own colors.

Borders

border-* builds a UIStroke child. Roblox strokes do less than CSS borders.

src/client/Panel.tsx
<frame className="border-2 border-slate-600 border-miter" />
  • Thickness: border (1), border-0, border-1, border-2 and border-4. Other numbers report unsupported-border-value. For anything else, use a bracket: border-[3], border-[3px].
  • Color: border-{color} sets the color. border-transparent hides the stroke.
  • Corners: border-round, border-bevel and border-miter set LineJoinMode. CSS has no equivalent.

These report unsupported-border-value instead of doing nothing:

  • Styles like border-dashed or border-dotted. A stroke is always one solid line.
  • Single sides like border-t-2 or border-x. A stroke outlines the whole element. For lines between children, use divide-*.
  • border-opacity-*. Use /N instead: border-slate-500/25.

Rings and outlines

ring (thickness 3) and outline (thickness 2) exist for Tailwind habits. Roblox allows one reliable stroke per element, so border, ring and outline all write to the same UIStroke. The last class wins. You can’t stack a ring on a border.

Radius

rounded-{key} sets CornerRadius on a UICorner child. The key must exist in theme.radius. Numbers like rounded-8 report unknown-theme-key. Use a bracket for a one-off (rounded-[8px]), or name the value in your theme:

vela.config.ts
theme: { extend: { radius: { card: "new UDim(0, 10)" } } }
<frame className="rounded-card" />

Shadows

shadow and its sizes build a UIShadow child. The sizes are fixed presets:

ClassBlur radiusY offsetSpreadTransparency
shadow3100.9
shadow-sm2100.95
shadow-md64−10.9
shadow-lg1510−30.9
shadow-xl2520−50.9
shadow-2xl5025−120.75

Add shadow-{color} to change the color and keep the preset’s transparency. shadow-none disables the shadow.

<frame className="shadow-lg shadow-slate-950" />

Inset and text shadows

inset-shadow-* draws a shadow inside the element. text-shadow-* draws one behind the text.

ClassModeBlur radiusY offsetTransparency
inset-shadow-2xsInset010.95
inset-shadow-xsInset110.95
inset-shadow-smInset420.95
text-shadow-2xsText010.85
text-shadow-xsText110.8
text-shadow-smText220.8
text-shadow-mdText420.75
text-shadow-lgText840.75

shadow-inner is the same as inset-shadow-sm. Each family has a -none form and a color form, such as text-shadow-red-500/50. There is no inset-shadow-md. Vela reads it as a color and warns unknown-theme-key.

Each family is its own UIShadow, so shadow-md inset-shadow-xs text-shadow-lg gives one element all three.

Backdrop blur

backdrop-blur-* builds a UIBlur child. Roblox has three strengths, so the Tailwind sizes share them:

ClassStrength
backdrop-blur, backdrop-blur-xs, backdrop-blur-smLight
backdrop-blur-md, backdrop-blur-lgMedium
backdrop-blur-xl, backdrop-blur-2xl, backdrop-blur-3xlHeavy
backdrop-blur-noneEnabled = false

Other sizes, including brackets, warn unsupported-backdrop-blur-value. Variants work: backdrop-blur-sm hover:backdrop-blur-xl. The utilities reference lists the type requirements.

Gradients

bg-gradient-to-{dir} (or bg-linear-to-{dir}) builds a UIGradient child. Add color stops with from-*, via-* and to-*:

src/client/Header.tsx
<frame className="bg-gradient-to-br from-indigo-500 via-purple-500 to-pink-500" />
Two stops, three stops with via-*, and a vertical direction — each swatch is one UIGradient child.
Class suffixDirectionRotation
tto top270
trto top right315
rto right0
brto bottom right45
bto bottom90
blto bottom left135
lto left180
tlto top left225

Other directions report unsupported-gradient-direction.

Element opacity

opacity-N fades the whole element. N is any integer from 0 to 100, so opacity-37 works. opacity-40 emits a transparency of 0.6.

It fades everything the element draws, including its stroke, shadows and blur. It also fades every child under it, including children passed into your components.

To fade one part only, use /N instead. text-slate-100/80 fades the text and leaves the background alone. The two multiply: opacity-50 bg-blue-600/50 lands at 0.75 transparency.

A transparency you set yourself is kept. <frame BackgroundTransparency={0.2} /> stays at 0.2 under a parent’s opacity-50. On the same element, the prop wins and Vela warns explicit-prop-overrides-class.

Fading a group as one layer

Vela fades each child separately. Where siblings overlap, the overlap looks darker. Add isolate to a frame to fade the group as one layer:

<frame className="isolate opacity-50 bg-red-500">
<frame className="bg-blue-500" />
</frame>
// → <canvasgroup BackgroundColor3={…} GroupTransparency={0.5}>…</canvasgroup>

Vela builds the frame as a CanvasGroup. That has costs: it clips its children, it redraws when any child changes, and a ref or IsA check sees a CanvasGroup.

isolate must be static. Under a variant or in a dynamic class it warns isolate-not-static. On anything but a frame it warns isolate-needs-frame. Write a <canvasgroup> yourself there.

See also