style props

Summary#

A component's appearance lives in its variants block. Each leaf assignment there — Bg = Surface;, P = 4;, BorderW = 1; — is a style prop: a name from a fixed vocabulary that the renderer maps to one or more CSS properties. The vocabulary is closed and checked at compile time, so a misspelled prop (Backgroud = …) is an error, not a declaration that silently styles nothing.

component Card() {
  variants {
    base {
      Bg = Surface;         // paint
      P = 4;                // spacing (a step on the 0.25rem scale)
      Rounded = Card;       // a theme radius token
      BorderW = 1;          // a 1px border...
      Border = Border;      // ...painted with the theme's Border color
      Shadow = "0 1px 3px rgba(0,0,0,0.08)";   // a CSS box-shadow, or a theme Shadow token by name
    }
  }
  render { Stack { Slot; } }
}

Which token names do I actually have? osy kit tokens prints every token the starter theme ships — by group, with its value. (osy model --json reports the tokens your own theme blocks declare.) This page answers which style props exist; those answer which values they may take, and the two are different questions.

A style prop's value is one of four things: a number (lowered to the prop's unit — a spacing step, a pixel length, or a raw number), a keyword from that prop's closed set (Display = Display.Flex), a theme tokens token referenced by name (Bg = Surface), or a literal CSS string for a prop whose value is passed through verbatim (Shadow, Cols, …) — the per-prop tables below give each prop's value forms. A theme group is never a prerequisite: an app with no Shadow { } group can still write Shadow = "0 1px 3px rgba(0,0,0,0.08)". Reach for a token when the value is part of the app's design language and should change with the theme; reach for a literal for a one-off. Layout arguments (align, justify, gap) are separate — see layout primitives.

Signature#

variants {
  base {
    <StyleProp> = <number | keyword | tokenName>;
    ...
  }
}

Description#

The style-prop vocabulary is grouped by what it controls. Values are a number, a keyword (closed set), or a theme token name.

Which element a variants block styles — every top-level one#

A variants block styles the component's render root, and a component whose render has several top-level elements has several roots. All of them wear the styling — whichever is on screen:

component Divider(bool vertical = false) {
  variants { base { Bg = Border; } }        // ← applies to whichever Box renders
  render {
    if (vertical)  { Box(w: "1px",  h: "100%"); }
    if (!vertical) { Box(w: "100%", h: "1px");  }
  }
}

That is the rule for every way an element can reach the top level: written there directly, inside an if arm, or one per row of a top-level foreach. It is not inherited downward — anything nested inside a root is ordinary content, and styles itself.

A component whose render root is another component passes the styling on: the child's own roots wear it, on top of whatever the child's own variants block declares.

Two roots on screen at once — warning VARIANTS_ON_SEVERAL_ROOTS

Exclusive arms are what the rule is for. Two roots that can be on screen together almost never are: an overlay or click-catcher drawn beside a page-sized root takes the root's MinH = Length.Screen; Bg = … and becomes an opaque sheet over the whole window. So the compiler warns — osy validate prints it — naming the component, its styling, and each element that would wear it (with its line, the component it is drawn in, and its condition):

component Shell() {
  bool menuOpen = false;
  action Close() { menuOpen = false; }
  variants { base { MinH = Length.Screen; Bg = Colors.Bg; } }
  render { Frame(menuOpen, Close); }       // the frame's roots are the shell's roots
}
component Frame(bool menuOpen, Action onClose) {
  render {
    Stack(gap: 0) { Slot; }
    if (menuOpen) { Box(onClick: onClose); }   // ⚠ beside the root: a second root, while the menu is open
  }
}

The fix is always the same: put them inside one root element, so the styling lands once. A fixed-position overlay is unaffected by where in the tree it is drawn.

theme App {
  Colors { Surface = "#ffffff"; }
}

component Shell() {
  bool menuOpen = false;
  action Close() { menuOpen = false; }
  variants { base { MinH = Length.Screen; Bg = Colors.Surface; } }
  render { Frame(menuOpen, Close); }
}
component Frame(bool menuOpen, Action onClose) {
  render {
    Stack(gap: 0) {
      Slot;
      if (menuOpen) { Box(onClick: onClose); }
    }
  }
}

Two arms the compiler can see are exclusive are not warned: one if … else if … else chain, or bare ifs whose conditions contradict (c / !c, x == A / x == B, n > 0 / n <= 0). If two roots are never on screen together for a reason it cannot see, write them as one if … else.

What color is it — background, text, shadow, opacity#

Every row below that says color token takes one of these — the starter theme's Colors, in scope wherever using Osysharp.Ui; is:

Colors.Bg · OnBg · Surface · OnSurface · Border · BorderDanger · Muted · TextMuted · TextSecondary · Primary · OnPrimary · Danger · Success · Warning · Scrim · Transparent

Primary, Danger, Success and Warning are built with Palette.From(...), so each is a whole RAMP rather than one colour. A step is reached by a semantic alias — Subtle · Muted · Default · Hover · Active · Strong (Bg = Colors.Primary.Hover) — or by number: 50 · 100 · 200 · 300 · 400 · 500 · 600 · 700 · 800 · 900 · 950 (Colors.Primary[600]). The plain name is the base.

An app that declares its own theme adds to this set rather than replacing it, so osy model --json reports the tokens THIS app actually has, light and dark separately — the answer whenever the list above is not the whole of it.

Drawing a border, a divider, or a focus ring#

Border (above) sets only the color — a border becomes visible once it has width. BorderW turns a solid, theme-colored hairline on; Border recolors it. Per-edge widths draw a single rule — a rail's right edge, a table row's bottom edge — without a full box.

A hairline is BorderW = 1; (the style defaults to solid); recolor it with Border = <token>. A divider under a list row is BorderBW = 1; on the row.

An outline is drawn outside the box and takes no layout space, which is what makes it the right tool for a focus ring: showing one must not move the page.

A custom focus ring is those four inside a Focus { … } block. Only replace the default one, never remove it: Outline* with no visible result is a keyboard user losing their place on the page.

Padding, margin, and the gap between children#

⚑ The whole spacing and sizing vocabulary, stated compactly. Measured on eval run 261: the model wanted a full-viewport page, could not find minH in the style guide, wrote "safer to skip it", and shipped a worse layout for a prop that has always worked.

⚑ Why a FENCE and not a paragraph. osy docs ui-styling prints every code fence in full and replaces the prose with a line saying how much there is — so a prop named only in a sentence is absent from the answer the command actually gives, while a prop named in a fence is always in it. These props were prose, and that is why a run could look them up and not find them.

// SPACING — a number is a step on the 0.25rem scale (`p: 4` is 1rem); a string passes through (`mx: "auto"`).
Box(p: 4, px: 6, py: 2, pt: 1, pr: 1, pb: 1, pl: 1);      // padding
Box(m: 4, mx: "auto", my: 2, mt: 1, mr: 1, mb: 1, ml: 1); // margin
Stack(gap: 3);                                            // flex/grid gap — same scale, or a Space token

// SIZE — a number is px, a string passes through, or a Length token.
Stack(w: "100%", h: "4rem");
Stack(minW: "20rem", minH: Length.Screen);   // Length.Screen is how a page fills the viewport (100dvh)
Stack(maxW: "34rem", maxH: "40rem");   // maxW is how a column stops growing on a wide screen
Stack(w: Length.Measure);              // …or a Length token the kit ships — `osy kit tokens` lists every one
// ⚠ THERE IS NO `Length.Column`. A page-column width is YOURS to name — declare it in your own theme first:
//      theme Default { Length { Column = "820px"; } }      // …then `Stack(maxW: Length.Column)` resolves
//   Without that declaration `Length.Column` is a compile error, not a fallback.

Every horizontal side is a START or END side. Pl/Ml/BorderLW/Left name the side a line starts on and Pr/Mr/BorderRW/Right the side it ends on — the left and right of an English page, mirrored in an Arabic one, with nothing in the app written for it (Right to left — an app that reads in Arabic with no change to the app). They lower to CSS's logical properties (padding-inline-start, margin-inline-end, inset-inline-start …); Px/Mx to padding-inline/margin-inline. | Gap | gap | the flex/grid gap, same 0.25rem scale, or a Space token |

How big is it — W/H, min/max, and flex grow#

…and the flex sizing trio:

A size you state is a size you get

A definite size on the main axis holds. W on a child of a Row, or H on a child of a Stack, is not a suggestion that the layout may overrule: a child written H = 2000 is 2000 tall, and a Row whose children total more than its width overflows rather than squeezing them.

Stack(h: 150, overflowY: Overflow.Auto) {
  Box(h: 2000) { Text("tall"); }     // 2000 tall — so the Stack scrolls
}

⚠ THIS IS A DELIBERATE DEVIATION FROM CSS, and the one place in the style vocabulary where a prop does not mean exactly what its CSS twin means. In CSS flex-shrink: 1 is the initial value, so an explicit height is only a starting point and a flex child shrinks past it to fit. That default is right for a language where you write flex-basis and think in flex terms; it is wrong for one where you write h: 2000, because writing a number is the statement that you want that number.

"Definite" means a plain length — 150, 12.5rem, 50vh. It does not include a percentage (which resolves against the container, and is exactly where shrinking is the point), the content-driven keywords (auto, fit-content, min-content, max-content), or anything computed or referenced (calc(…), min(…), clamp(…), a size token) — those could hold any of the above, so they keep the CSS default.

To opt back in, say so: Shrink = 1 makes a child shrink again, and being an inline style it beats the rule, so nothing is unreachable. Reach for it in the case it is meant for — a responsive toolbar whose items may compress. Though the more usual answer there is not to state a width at all, and use Grow or MinW = 0 instead.

⚑ The cross axis is untouched. H on a child of a Row never shrank, and still does not — flex-shrink only governs the main axis.

Styling text — font, weight, alignment, truncation#

WhiteSpace = WhiteSpace.Nowrap keeps a tab, a table cell, or a button on one line (the row's own OverflowX handles the excess). A tracked-out uppercase section label is TextTransform = TextTransform.Uppercase; LetterSpacing = "0.06em";; a numeric table column right-aligns with TextAlign = TextAlign.Right;. FontVariant = FontVariant.TabularNums gives every digit the same width so a column of numbers — a metric, a price, a count — lines up vertically instead of jittering as the digits change.

A truncated line is three props, not one: TextOverflow = TextOverflow.Ellipsis needs WhiteSpace = WhiteSpace.Nowrap and Overflow = Overflow.Hidden beside it, or there is nothing to truncate. WordBreak = WordBreak.BreakWord is the other answer — for a long URL or an unspaced identifier that would otherwise widen its container and push the whole layout sideways.

Pinning, layering, scrolling and transforms#

These are what let an app build a drawer, a sticky header, or a modal out of ordinary style props — the platform widens this vocabulary rather than shipping the component.

Motion is four props with a page of its own — animation — keyframe motion, on entry, on exit, in a loop, or as it scrolls into view is where the

All four are ordinary style props — usable inline or in a variants block — and animation — keyframe motion, on entry, on exit, in a loop, or as it scrolls into view is where the declaration, the timing vocabulary and the staggering example live.

Transforms move, turn and resize a box without re-running layout, so they composite on the GPU and cost nothing per frame. That is why a drawer slides with TranslateX rather than by animating Left.

TranslateX and TranslateY both write the single transform property, so the compiler merges them into one declaration — setting both is transform: translateX(a) translateY(b), not one silently overwriting the other. Rotate/Scale are CSS's own individual properties and compose on their own.

Cursor, click-through, selection, hiding#

What a box does to the pointer, the caret and the selection — the props that make a decorative overlay click-through, or a label un-selectable so a double-click selects the row instead of the word.

⚠ Order changes only the PAINTED order. Tab order and screen-reader order still follow the source, so a visual order that disagrees with the document order is an accessibility bug, not a layout trick.

Lining columns up across rows — grid#

With Display = Display.Grid, these define a grid — the way to align columns across rows (a data table) without a shipped Table component. Children flow into the tracks in order.

A table header + rows all using the same Cols line up automatically; Gap (see spacing) sets the grid gap. The GridAuto* props take over when the data outruns the declared tracks, which is the usual case for a list of unknown length: declare Cols and let the rows generate themselves.

Styling hover, focus, disabled, and one screen width#

A nested Hover { … } / Focus { … } / Active { … } / Disabled { … } block styles that interaction state; a nested breakpoint block (Tablet { … } — one of the kit's Base/Phone/Tablet/Laptop/Desktop/Widescreen, or a name your theme's Breakpoints declares) applies its props only at that width and up (mobile-first). Both nest inside any variant value.

Styling one atom without minting a component#

The style props above are usually set in a component's variants recipe, but an atom can also carry them inline as call arguments — the C#-natural way to style a one-off without minting a component for it:

Text("osyrin", fontSize: 17, fontWeight: FontWeight.Medium, color: Colors.TextPrimary)
Box(bg: Colors.Surface, p: 4, rounded: Radius.Card)
Icon(Icons.Chev, size: 18, color: Colors.TextMuted)

Argument names are the camelCase of the prop (fontSize, bg, p, rounded); values are the same forms as in a variant (a theme token, a number, a string, a keyword) — or a conditional that picks between them (below). A hover style still belongs in variants (it is a pseudo-state, not a value choice). A responsive value can be either: a breakpoint block in variants, or a conditional on the live width right at the call — cols: Layout.AtLeast(Tablet) ? "2fr 1fr 1fr" : "1fr" (layout primitives) — which is the short form for one value.

⚠ Inline, a name value is written QUALIFIED — bg: Colors.Surface, not bg: Surface. An argument slot accepts every kind of value, so a bare capitalised name there could be a theme token, an enum member or a style keyword, and all three are spelled alike; the group name is what says which vocabulary you meant. Each prop's group is the one its values come from — Colors for bg/color/border, Radius for rounded, Shadow for shadow, FontSize / FontWeight / Font for the type props, and the keyword props take their own name (Display.Flex, Position.Fixed, Overflow.Auto, Cursor.Pointer). A bare name is refused, and the refusal names the exact spelling to write.

⚑ A variants block follows the same rule — Bg = Colors.Surface;, Rounded = Radius.Card;, Display = Display.Flex;. There is no position where a value is written bare. The prop on the left does not decide the vocabulary, which is the thing that makes the rule uniform rather than arbitrary: any group's token is accepted for any prop, so Bg = Radius.Card; is a legal (if odd) thing to write and the group is genuinely carrying information.

The one sentence is: a value names the vocabulary it comes from. Not "when it is ambiguous" — always, so you never have to work out which case you are in.

An inline value may be a conditional (cond ? A : B) whose branches are each an ordinary style value — so one property can depend on one piece of component state without minting an enum + a variants dimension for it:

theme App {
  Colors { Surface2 = "#eef1f5"; TextPrimary = "#111827"; TextMuted = "#6b7280"; }
  Radius { Control = "8px"; }
}

[Composable] component Tab(string label, bool active, Action onClick) {
  render {
    Row(bg: active ? Colors.Surface2 : "transparent", color: active ? Colors.TextPrimary : Colors.TextMuted, rounded: Radius.Control) {
      Text(label);
    }
  }
}

The condition is a Boolean read from component state; the value re-evaluates and the element re-renders whenever that state changes. Branches may mix a token and a string and may nest (bg: a ? (b ? "#fee" : Colors.Border) : Colors.Bg). For a whole set of properties that changes together across several states, an enum-typed state variant is still the better fit — a conditional value is for the common "one property, one condition" case.

Giving an element a NAME — not a style prop#

A style prop says how an element looks. Three other ambient vocabularies say what it is, what state it is in, and what it is called — and the last one is the one people miss, because the obvious-looking candidate is a style prop's neighbour in the same argument list:

Input(value: email, placeholder: "[email protected]")            // ✗ has NO name
Text("Email", labelFor: field); Input(value: email, id: field) // ✓ named, and the words are clickable

A placeholder: is not a name: it disappears the moment you type, is not announced as the field's name, and nothing can address the field by it. The naming props (labelFor:/id:, labelledBy:, describedBy:, label:) are ambient — legal on every element, so they appear in no atom's signature. osy kit atoms lists them under Ambient; accessibility is the full reference.

Styling a child when an ANCESTOR is hovered — inside#

A nested inside <Component>.<State> { … } block styles this element when it sits inside an ancestor component that is in a given interaction state — the reveal-on-hover pattern (a row's actions, a card's menu, a tab's close):

theme App {
  Motion { Fade = "opacity 0.12s ease"; }
}

[Composable] component RowActions() {
  variants {
    base {
      Opacity = 0; Transition = Motion.Fade;          // hidden by default…
      inside DataRow.Hover { Opacity = 1; }    // …shown when its DataRow is hovered
    }
  }
  render { Row { Text("⋯"); } }
}

[Composable] component DataRow() {
  render { Row { Slot; } }
}

The child names the ancestor, so it stays reusable in any matching container and the container needs to know nothing about it. <State> is one of the universal interaction states (Hover / Active / Focus) — a declared state like "selected" is data the child can see, so it rides an ordinary state variant fed by a prop, not inside. The block nests inside a value block (usually base), like a pseudo-state.

Examples#

A flat, hairline-bordered card with a hover lift — the whole look from the vocabulary, no shipped component:

theme App {
  Colors { Surface = "#ffffff"; Border = "#e5e7eb"; }
  Radius { Card = "12px"; }
}

[Composable] component Card() {
  variants {
    base {
      Bg = Colors.Surface; BorderW = 1; Border = Colors.Border; Rounded = Radius.Card; P = 4;
      Hover { BorderW = 1; Shadow = "0 1px 3px rgba(0,0,0,0.08)"; }
    }
  }
  render { Stack(gap: 2) { Slot; } }
}

A list row with a bottom divider, the last row suppressing it via a passed-in state:

theme App {
  Colors { Border = "#e5e7eb"; }
}

enum RowEdge { Divided, Last }

[Composable] component ListRow(RowEdge edge) {
  variants {
    base { Px = 3; Py = 2; }
    edge {
      Divided { BorderBW = 1; Border = Colors.Border; }
      Last { }
    }
  }
  render { Row(justify: Justify.Between) { Slot; } }
}

See also#

• theme tokens — the design tokens a style prop's value references by name
• layout primitives — Stack/Row/Box and the align/justify/gap layout arguments
• component — where a variants block lives and how a component is authored
• Placing and naming a component — m:, w:, grow:, alignSelf:, animation:, label: on a component call — the placement, spacing and motion props a caller may write on a component call
• accessibility — the other ambient argument vocabularies: what an element IS, what STATE it is in, and what it is CALLED