Zinc UI styling system: coverage against CSS, Tailwind and React Native, and a plan for the gaps

Date 2026-10-07. Scope: audit and design, no code and no backlog change. Sources read: RULES.md, ARCHITECTURE.md, docs/ui.md, lib/std/ui.ts (2856 lines; the working tree holds another developer’s uncommitted StyleSheet/Style work, read only, line numbers below are of that tree and will move), lib/std/kit/*, compiler/src/{ui-style,css}.ts, docs/reports/ui-rendering-architecture.md (cited as “RA”, sections 4 and 7), lib/gfx.d.ts, runtime/zrt_raster.h, runtime/raster.cpp, backlog ZN-044, ZN-077, ZN-170..206, ZN-227, ZN-228, tools/proto-capture and tests/golden/examples/proto (41 files, every manifest row at tol 0). Statuses: supported (works as in CSS for the common case), partial (works with a stated restriction or deviation), missing. “Task” points to the proposed backlog entries ST-nn of section 5 (placeholders, not created).

1. Summary

Coverage: 110 features audited, 26 supported, 29 partial, 55 missing (section 2). The 30 proposed tasks ST-01..ST-30 are in section 6; the five most valuable gaps are min/max sizes with the rest of flexbox (ST-04, ST-05), theme variables with dark mode and any-property state variants (ST-22, ST-24), full box-shadow and borders (ST-08, ST-10), 2D transforms with transitions and keyframes (ST-14, ST-25, ST-26), and text overflow control (ellipsis, line-clamp, decoration, italic: ST-18..ST-20).

What the engine is today, in one paragraph. Every style source (class tokens, .css rules compiled to tokens, style={{...}} objects, StyleSheet.create entries, array layers) ends in the same flat UiNode (ui.ts:130-193, about 95 fields, roughly 600 B per node by the measurement in the comment at ui.ts:207) through two string-keyed entry points: applyToken (ui.ts:560-685, an if chain over strings) and applyNumber (ui.ts:429-487, a second chain). Style keys are strings looked up with indexOf per node (ui.ts:425, 744). The layout is a single-pass flexbox (measure 817-877, place 878-948), the painter emits ten raster command kinds (rrect, gradient, border, shadow, drawText, drawImage, clip, stroke, polygon, path; lib/gfx.d.ts), and hover/focus/active exist only as colour fields on the node (ui.ts:174, 185, 191). That is a good core and a long tail of missing properties; none of the missing ones needs a new architecture, but three structural points decide the cost of everything else: string keys, a fat node, and a raster command set with one radius, one border width and one gradient angle per box.

2. Coverage table

Cost and tier columns are in section 3, parity risk in section 4. File:line is lib/std/ui.ts unless a path is given.

2.1 Style model

2.2 Box model and layout

2.3 Visual effects

2.4 Typography

2.5 Images

2.6 Accessibility-related

3. Cost and rendering-tier constraints

Tiers as in RA 4.13: T0 ESP32 class, software band raster to RGB565, 160 KiB heap, 160-256 commands, f32; T1 PS1 (fx12, 256 KiB heap, 512 commands) and PS2; T2 GLES2 / WebGL1 (Pi 1-3, VideoCore IV: no derivatives, no sampler arrays, one render pass per frame); T3/T4 GLES3 / WebGL2 / native. The SW raster is the oracle on every tier (RA 4.1 invariant 1); GPU backends must match it within a tolerance file (ZN-172). A “free” cost means no raster change and no extra command on the SW path.

Two raster-level facts shape the plan. First, the command is 48 bytes with one radius (r), one border width and one gradient direction; everything that needs per-side or per-corner data must wait for the Scene v2 Quad of RA 4.2 (ZN-174) or be decomposed into several commands. Second, a command past the list limit is dropped silently (gfx.cpp per RA 1), so every decomposition must check a remaining-budget counter and fall back to the plain form; the budget check is part of the design below, not an option.

4. Prototype parity impact

Goal: every examples/* entry stays pixel-identical (tests/golden/examples/proto, 41 PNGs, all rows tol 0, some known rows that “may not grow”, e.g. ZN-223; gate tools/proto-capture compare). The prototype and the new engine share lib/std/ui.ts, so a style change is a change of both oracles at once: a regression would not show against the prototype, only against the committed PNGs. Hence:

1. Additive only. A new key, token or variant must be inert when absent. No default changes: shrink stays 0, flex-1 keeps grow over content size, border stays paint-only, opacity stays per-primitive, gap-x/gap-y fix is the only change of an existing token and no example uses gap-x- or gap-y- (grep of examples/: 0 files). CSS-faithful behaviour is opt-in (basis-0, box-border-layout, isolate, shrink).
2. Neutrality gate. Before and after each task: tools/proto-capture compare over the whole manifest (tol 0, known rows unchanged), tests/t1/ui.sh (frames 1 and 40 of tests/visual/ui.tsx), tests/t0/jsx_style.sh. A task that needs a manifest row changed is wrong by construction.
3. New goldens are ours. The prototype cannot render rotate or dashed, so new scenes get goldens under tests/golden/ui-style/ captured from the SW f32 backend of the new engine, cross-checked by the AOT and --engine quickjs, and compared on other backends with per-tier tolerance files (ZN-172). The prototype’s compiler/ is not changed except for fixes (ARCHITECTURE.md); the style-lowering rules of compiler/src/ui-style.ts that ZN-077 ported to src/frontend are extended on the Next side only, and the key tables are generated into docs so the two cannot drift silently.
4. Sequencing. lib/std/ui.ts carries uncommitted work of another developer. Nothing in section 5 starts before that work is committed (ZN-077 closes) or the task uses the partial-staging method recorded in ZN-228’s notes.
5. Highest risk per area. Layout tasks (ST-04, ST-05, ST-06) touch measure/place that every example uses: keep the legacy loop as the path when no child of the line has a side record, and add the differential layout test of ZN-189 to their gate. Painter tasks (ST-08, ST-10, ST-12) must reproduce today’s preset shadows, borders and gradients bit-for-bit through the new code path (presets are expressed as the new parameters and compared to the old output). Text tasks (ST-18..ST-21) change what wrapText returns only when a new property is set.

5. Design for the missing parts

5.1 Parsing: three entry points, one property table

Today applyToken, applyNumber and sheetNumber each re-implement the same properties with string comparisons (about 60 string compares per key in the applyNumber chain). Proposal:

• A PROP table of small integer ids, one row per property: {id, kind (length | int | colour | enum | flag), min, max, side-record field, dirty class}. The dirty class is the invalidation class of RA 4.8: layout, paint, slot (transform, opacity, colour lerp). applyProp(n, id, value) is the only writer of node style.
• StyleSheet and inline objects: the compiler lowers each key to (id, number) pairs. Style becomes {ids: i32[], values: number[]} (today keys: string[], ui.ts:114). Non-numeric values are encoded at build time the way ui-style.ts already does for enums (ui-style.ts:17-23) and colours (@key:hex, ui.ts:709-715, kept because 24-bit colours overflow fx12 number): enums to ints, colours to i32 RGBA, lists to fixed slots (boxShadow to shadow0X, shadow0Y, shadow0Blur, shadow0Spread, shadow0Color, shadow0Inset, same for shadow1; gradient to bgGradAngle, bgGradStopN, bgGradPos0.., bgGradCol0..; transform: [{rotate:'45deg'}, {scale:2}] to rotate, scaleX, scaleY when the order is the canonical one, otherwise a build error because the affine product is not commutative). Unsupported on the build’s profile: warning plus drop (section 5.6), never silent.
• Class tokens: a prefix table (rotate-, -mt-, min-w-, ring-, shadow-[, bg-[linear-gradient(, dark:, max-lg:, group-hover:, aria-[..]:) maps to (id, value); value parsers for lengths (px, %, rem, vw, vh, fractions, negative), colours (hex, /alpha, rgb(), hsl(), var(--x)), enums. Tokens that need no runtime string work (static class strings) are tokenised at build time (css.ts already does this for .css), dynamic strings use the same table at run time.
• Variants are a prefix chain evaluated left to right into a condition set {scheme, minW, maxW, container, pointer, orientation, reducedMotion} plus one state in {none, hover, focus, active, disabled, focusVisible, within, group, peer, aria}; unconditional or statically true conditions are folded at build time.
• Order of resolution stays as in docs/ui.md:323-327: base classes, then style layers left to right, then imperative setNumber/animations. The state overlays are applied last in their own pass so that removing a state returns to the base.

5.2 Storage and the memory budget on small targets

• Core UiNode keeps the fields that every node pays for (geometry, flags, background, border colour/width, radius, size, text basics). New properties never add fields to it.
• Side records, allocated on first write, the same pattern as hs: Handlers | null and ed: Edit | null (ui.ts:188-189): lx: LayoutExt (min/max, shrink, basis, order, selfAlign, aspect, z, sticky offsets, snap, margin-auto bits, percent paddings, rowGap; about 16 fields), dx: Deco (per-corner radii, border style and per-side colours, outline, up to 2 shadow specs, gradient spec, background image spec, tint, object-fit, text shadow), fx: Fx (rotate, skew, scaleX/Y, origin, blend, filter, backdrop, clip shape), tx: TextExt (italic, transform, decoration, clamp, word spacing, white-space, family list, weight 100-900), st: States (per state: ids[], values[]), a11y (role, label, hidden). Cost when unused: five nullable pointers (20-40 B); a typical page pays for a record on 5-10% of its nodes.
• Net saving, not growth. The 12 per-state colour fields (focusBg, activeBg, focusFg, activeFg, ui.ts:174, hoverBg, hoverFg, hoverBorder, focusBorder 185, withinBg, withinFg, withinBorder 191), the transition fields (transMs, curBg, fromBg, transStart 175), the gradient fields (160) and the four side widths (163) move into st/dx. Estimate: 25 fields, about 100 B per node (roughly 17% of the 600 B figure), about 17 KiB on a 171-node page; to be measured with zinc mem/tools/resmon in ST-02 and recorded in the task notes (RULES 5, measurements beat estimates).
• Global tables: the theme variable table (i32[64] per scheme, 512 B for two) and the keyframe registry (build-time constants in flash on firmware).
• Compatibility with ZN-189 (SoA): side records become sparse parallel arrays indexed by handle; the field list above is the contract, not the object layout.
• Code size: the extended painter and parsers live in a module zinc:ui/fx that registers hooks (paintDeco, layoutExt, parseExtToken); the compiler adds the import only when a lowered style op or token needs it, so an ESP32 app that uses none of it ships none of it (ST-29 measures size before and after).

5.3 Layout

• measure: after ownW/ownH, clamp by lx.min/max and derive from lx.aspect; percent padding and margin resolve against maxW.
• place: when no child of the line has lx, run today’s loop unchanged. Otherwise run the CSS resolve-flexible-lengths loop (freeze items that hit min/max, at most 3 passes) with basis, grow (fractional), shrink (explicit only), order (stable sort of the child list in flat() 768-775, only if the parent flag hasOrder is set by a child setter), alignSelf (override of n.align at 926-929), margin auto (free-space share before justify), rowGap, reverse directions (iterate the list backwards), column wrap (symmetrical to row wrap).
• Grid: out of scope for this plan except as display: grid with a fixed-track subset in ST-05 if the flex work finishes under budget; RA 4.8 already records it as a later display mode.
• z-index: parents with a child z != 0 set hasZ; paint and hitIn (1811) iterate a z-stable order only for such parents.
• sticky: resolved at paint and hit time from the scroll parent’s sy (clamped to the parent’s content box): no relayout, no new commands.
• Scroll snap: snap-x|y, snap-start|center|end give snap points collected at release; releaseAxis (1695) targets the nearest instead of the inertia end; same spring (springStep 1703).
• Container queries: nodes with the container flag publish their laid-out width; a restyle triggered by a width change reruns layout() at most once more (2 passes total, bounded).
• Differential oracle for ST-05: a headless browser lays out generated flex trees offline; the boxes are stored as JSON fixtures (no browser dependency in the build); Yoga/Taffy stay oracles only, as RA 4.8 decides.

5.4 Painting by the software raster

• Rule: lower into existing commands first, change the raster second, because the raster and the damage hash (ZN-179) already know the ten kinds; every new command field must be part of the diff hash.
• A paintBox function replaces the inline sequence at ui.ts:1066-1086: shadows (loop over dx.shadow[]), fill (flat, gradient, image), borders (uniform border(), per-side bands, dashed bands), outline/ring, then content. Presets shadow-sm..xl and today’s uniform paths are expressed as the same parameters and must compare bit-exact to the old output (section 4).
• Gradient grad 5 for rects: a paint record in the point pool [type, x0, y0, x1, y1, n, (pos, colour) * n] (the canvas grad 4 path, raster.cpp:152, 234, 273). Axis-aligned multi-stop on T0 lowers to chained rects with no raster change.
• Transforms: the painter keeps accumulating translate/scale (paint 1057-1062) and passes a 2x3 matrix to the raster only when rotate or skew is present, so existing frames take the old path. The raster evaluates each primitive’s SDF in local coordinates (inverse map), AA at the edge as now; glyph runs under rotation use bilinear transformed quads. Hit testing inverts the same matrix (boxOf 1831 already inverts translate/scale).
• Blend, tint, alpha ramps: one byte blend in Cmd.pad and one colour for IMAGE tint; both skipped by a branch when zero.
• Blur and backdrop blur on bands: the band is rendered with r extra rows, blur applied on the composited rows below the node (three box passes, no new library), then the node’s own commands. damage grows by r around the node so the diff stays correct.
• Clip shapes: CLIP carries kind; ellipse and polygon coverage are computed per pixel in the clip stack the raster already keeps (corner_px, raster.cpp:463-512); polygon mask uses the existing polygon fill into a one-row coverage buffer.
• Text: decoration and ellipsis are layout and extra rrect commands; italic is baked when the build has the face, else a synthetic shear of glyph rows; text-transform and line-clamp rewrite lines[] in wrapText; white-space: nowrap|pre bypasses the word splitter; text-shadow is a duplicated run.
• Images: object-fit: cover = clip(box) + drawImage at the oversized rect; contain = smaller box; both zero raster change.

5.5 Painting by the GPU backend (RA roadmap R-tasks)

• All new records enter the Scene v2 (ZN-174): Quad (4 radii, 4 widths, fill paint, border paint, dashed/inset flags), Shadow (+ inset, spread), Transform, LayerPush/Pop (opacity, blend, filter, cache_key), Clip shapes, Image (+ tint, uv rect).
• Ranks (ZN-177) and batches (ZN-178) use the clipped axis-aligned bounds of the transformed primitive including shadow, outline and blur extent; features (dashed, inset, gradient type) become shader feature flags and not batch breaks (RA 4.4 rule 2).
• T2 shaders (GLES2 floor, ZN-176): no derivatives, AA from a pixel_size uniform; gradients through a 1x256 ramp texture in the atlas pages (ZN-182); rotated quads by vertex transform, edge AA by SDF in local space; blend through glBlendFunc where exact, else normal; backdrop blur through one render-to-texture pass per frame at most; clip shapes through stencil only when the renderbuffer exists (caps from ZN-183, quirks table), else bounding box.
• T3: instancing, sampler2DArray pages, dual-Kawase blur, conic gradients in the fragment shader, framebuffer-fetch blend modes when the cap bit is set.
• Property slots (ZN-191): rotate, scale, translate, opacity, colour lerps and filter amounts are slot-dirty, so transitions and keyframes on them re-record nothing and cost one uniform/instance patch on GPU.
• Every degrade is a Caps decision logged once (zinc doctor), never a crash (RA 4.13 limit-handling rule).

5.6 Degradation on tiny profiles

• targets/capabilities.json gets a ui.style level per profile (ST-29): core (today’s set plus layout and colour additions that cost no raster work), extended (borders, shadows, gradients, transforms 90 degrees, text effects), full (blur, clip shapes, conic, group opacity, backdrop). Defaults: esp32 and ps1 core+selected extended bits, ps2 and rpi1 extended, desktop and wasm full.
• The build diagnostic for a key above the level: warn and drop (default), strict for an error, off to be silent; zinc.json "ui": {"style": "strict"}. A fallback per feature is named in section 3 and implemented once, in the paintBox function, not scattered.
• The command budget guard: before emitting N decomposed commands (dashes, bands, tiles, text shadow, shadow layers) the painter asks budgetLeft(); below a profile threshold (T0: 32, PS1: 64) it emits the plain form.
• Fixed point: all new values are lengths (number), enums and i32 colours; no new transcendental in the paint path on fx12 (rotate uses a sine table lookup built at start, 91 entries; atan2 only on T3+).

6. Proposed backlog tasks

Sizes: S = 1 day, M = 2, L = 3 (as RA 7). Each task ends with the neutrality gate of section 4 (tools/proto-capture compare unchanged, tests/t1/ui.sh, tests/t0/jsx_style.sh); that line is not repeated. “Golden” means tests/golden/ui-style/<scene>.png from the SW f32 backend; “tier” means a tolerance file per backend as in ZN-172.

Suggested order: ST-01, ST-02, ST-03, ST-11 (foundations, no visible change), then ST-04..ST-06 and ST-09 (layout and focus, highest daily value), ST-08, ST-10, ST-12, ST-14 (visual parity with CSS), ST-18..ST-20 (text), ST-22..ST-25 (themes, queries, states, transitions), the rest as needed. ST-28 starts with ST-08 and grows with each task.

7. Risks and open points

• The prototype, the new engine and the kit share lib/std/ui.ts; the in-flight StyleSheet work must land first (section 4.4).
• The per-node estimate of 100 B saved is arithmetic on field counts, not a measurement; ST-02 decides whether the side-record design stays.
• Scene v2 (ZN-174) is the gate for per-corner, inset, transform and filter on the GPU path; the SW path can ship each feature earlier through command decomposition, at the price of the command budget on T0 and T1.
• CSS deviations kept for parity (flex-1 over content size, default shrink 0, paint-only borders, per-primitive opacity) will surprise authors porting CSS; the opt-in switches in ST-05, ST-08 and ST-15 plus a doc page “Differences from CSS” (in ST-30) are the mitigation.
• VideoCore IV blur and stencil behaviour is unmeasured; the one-pass-per-frame limits in section 3 are proposals to validate with the stress rules of RA 4.6 (S2).

Edit this page on GitHub ↗