CSS & Styling

Style your UI with CSS, the same way you’d style a web page. Cuttlefish understands a practical subset of CSS — the box model, flexbox, colors, typography, and selectors. All of it is resolved when you build (no CSS engine runs on the device): flexbox is laid out with Yoga (a layout library), styles are resolved, and the resulting draw commands are what the firmware runs.

Box model

Length units

px, bare numbers, and rem/em (multiplied by 16, the root font size — so 0.625rem = 10px). Percentages are honored where applicable. calc() evaluates + - * / on lengths after var() substitution, with operator precedence.

Flexbox (via Yoga)

display: none removes the element subtree from layout, drawing, and hit-testing while preserving generated node indices.

Colors

All standard CSS formats: #rrggbb, #rgb, #rrggbbaa (alpha ignored), rgb(r,g,b), rgba(r,g,b,a) (alpha ignored), hsl(...), hsla(...). Both comma and CSS4 space syntaxes work. The 147 CSS named colors (red, dodgerblue, transparent, …) are supported.

Typography

Fonts (@font-face)

Declare variants with @font-face. When you build, Cuttlefish keeps only the font characters you actually use:

@font-face {
  font-family: "DeviceSans";
  src: url("./assets/DeviceSans-Bold.ttf");
  font-weight: bold;
}

• font-subset: exact — include only the exact glyphs used (smallest binary).
• font-subset: fallback — include fallback glyphs for dynamic text that may contain unanticipated characters.
• font-smoothing: antialiased — enables per-pixel alpha for the matched text.

Visual properties

Transitions, animations, and :pressed

transition: background 300ms;
transition: color 120ms;

Smoothly transitions the property over the duration. The :pressed pseudo-class applies while a button’s .value is 1:

#ok { background: #2563eb; transition: background 120ms; }
#ok:pressed { background: #1e40af; transform: translateY(2px); }

:pressed rules may include top/left/right/bottom or transform: translate(...) as draw-time offsets (outset shadows stay anchored).

@keyframes animations

Define keyframe sets and attach them with the animation property (or its long forms animation-name, -duration, -iteration-count, -delay, -timing-function):

@keyframes pulse {
  from { opacity: 1; }
  to   { opacity: 0.4; }
}

#indicator { animation: pulse 1.2s infinite ease-in-out; }

Animatable properties are background, color, opacity, transform, and size (width/height). The shorthand accepts name duration iterations delay timing in any order; infinite loops forever, and linear/ease/ease-in/ease-out/ease-in-out shape the interpolation. direction (normal, reverse, alternate, alternate-reverse), fill-mode, and running/paused tokens are parsed for compatibility. Animations advance in ui_tick() alongside transitions.

Selectors

Pseudo-states: :pressed (button held; :active is an alias), :disabled, :checked (check/radio .value is 1), :focus.

Inline style="…" attributes and <style> blocks are both supported.

CSS variables and theming

Define variables in :root and reference with var():

:root {
  --bg: #111;
  --fg: #eee;
}
screen { background: var(--bg); color: var(--fg); }

Class-scoped themes select a variant at build time via themeClass in your cuttlefish.config.ts:

:root { --bg: #fff; --fg: #000; }
.dark { --bg: #111; --fg: #eee; }

display: { themeClass: 'dark', /* … */ }

The built-in component kit

A shadcn-style component kit is built into @typecad/ui and always included — its tokens and class recipes are prepended ahead of your stylesheets, so anything you write overrides them by normal cascade order. No imports or scaffolding: put the classes on native elements and they work.

<button class="btn btn-primary">Save</button>
<view class="card">
  <view class="card-header">
    <text class="card-title">Title</text>
    <text class="card-description">Subtitle</text>
  </view>
  <view class="card-content"> ... </view>
  <view class="card-footer"> ... </view>
</view>

The kit covers btn (variants -secondary -outline -ghost -destructive, sizes .btn-sm/.btn-lg, .btn-block), badge, card, input, form-label, row, separator/vseparator, alert, skeleton, spinner, dialog and toast recipes (dialog-scrim, dialog-card, dialog-footer, toast, toast-title, toast-description), progress, avatar, switch (a styled <check>), tabs, and accordion. Validation states (.input-error, .field-error) are runtime-driven — bind borderColor/visible to a signal.

The kit’s design tokens are ordinary CSS variables (--primary, --background, --card, --muted, --destructive, --border, --radius, …), themed through the checked pseudo-state as well: :checked rules resolve a --primary/--primary-foreground pair, so switches, checkboxes, radios, and select option rows recolor automatically per theme.

Themes

A theme is any CSS file. Pre-packaged ones ship with @typecad/ui — @import one by bare specifier from a <style> block (or the sidecar .ui.css file):

@import "@typecad/ui/themes/blue.css";

Available themes: zinc, slate, stone, gray, neutral, blue, green, red. Dark mode activates with themeClass: 'dark' in the config’s display block. To use your own, save a ui.shadcn.com / tweakcn export into the project and @import it by path — its :root/.dark token blocks override the kit defaults (later definitions win). Both dialects parse: classic HSL channel triplets and Tailwind-v4 oklch(). Alpha in colors is ignored (no blending on bare metal). Redefine any kit class in your own stylesheet and your definition wins.

@media performs compile-time variant selection (no runtime resizing). Supported conditions: min-width, max-width, min-height, max-height (in px), exact-match (width: N)/(height: N), and the feature queries (e-ink), (update: slow|fast), (monochrome) / (monochrome: N), and (color-gamut: srgb|p3). orientation is unsupported (warned and skipped).

@media (max-width: 200px) {
  screen { flex-direction: column; }
}

Unsupported (and why)

These are intentionally out of scope for microcontroller rendering:

• display: grid — use flexbox
• background-image / CSS sprites — use <img> instead, or a two-stop linear-gradient() on background
• position: fixed
• ::before / ::after pseudo-elements
• Per-corner border-radius (uniform only)
• Runtime theme switching (themes are resolved at transpile time)
• @supports (@import is supported for theme files — see Themes)

Inline rich text (mixed bold/italic/underline spans via <b>/<i>/<u>/<a>, line breaks with <br>) and text-shadow are supported — see Elements.

Next: Display Configuration for wiring a physical display.