Build UI

Build UI - visual design system for TouchDesigner panels

Load BEFORE building or restyling any TD panel UI (dialogs, wizards, HUDs, control surfaces). This is the design layer; td-ui-mechanics.md (in this skill directory) is the mechanics (which COMP to use, single-window, etc.). A panel is not done until a captured frame / live window proves it reads cleanly.

The failure this prevents: font sizes all over the place, giant buttons, no padding, no alignment, no hierarchy, low contrast - "novice" UI. The cure is a small set of tokens applied consistently. Never pick a size, color, or gap ad hoc; pull it from the scales below.

1. Design tokens (dark theme - TD colors are 0..1 floats)

Color - a restrained palette. More colors != better; use opacity/size for hierarchy, accent only for the primary action.

Rule: exactly one accent element per screen (the primary action). Everything else is surface/text. Match the host project's existing palette when it has one (e.g. Embody's tagger dark) instead of inventing.

Type scale - 3-4 sizes, never more. fontsizex on a Text COMP:

If two things are the same role, they are the same size. Establish hierarchy with size + color, not five random sizes.

Spacing - a 4px grid. Every gap, pad, and size is one of these: 4, 8, 12, 16, 24, 32. No arbitrary values.

2. Layout rules

• Padding first. Content never touches the panel edge. Inset all content by pad-edge (24). In TD: put content in an inner container smaller than the outer by 2xpad on each axis, or use align margins - the outer bg showing around it IS the padding.
• Left-align body text and lists. Center ONLY short titles and button captions. Never center a multi-line sentence - it looks broken.
• Constrain width + wrap. A Text COMP must have a width and wordwrap on so text wraps inside the panel instead of running off the edge. Long line length hurts readability - keep body under ~60 chars per line.
• Align to a single left edge. Title, body, and controls share one left margin. Ragged left edges read as broken.
• Buttons are modest. btn-h = 32, width = content + 2xbtn-pad-x, or equal columns with a gap-item between. A button must NEVER fill a whole row's height - that's the #1 tell of novice TD UI.
• Explicit vertical order. With a verttb container, children stack in panel order; confirm the title ends up on TOP, not the bottom. Verify, don't assume.

3. Hierarchy, contrast, rhythm

• Hierarchy: one clear focal point (the title or the primary action), then supporting text, then hints. Drive it with size + color, not boxes everywhere.
• Contrast: text on bg for anything readable; text-muted only for genuinely secondary info. The primary/recommended button uses accent; the alternative uses surface. This makes the recommended path obvious at a glance.
• Rhythm: consistent gaps. Equal spacing between peers; a larger gap (gap-section) separates groups. Inconsistent spacing looks accidental.
• Restraint: flat surfaces, one accent, generous space. Do not add borders, gradients, or colors "to fill space" - space IS the design.

4. Component recipes

• Dialog / wizard step: outer bg container -> inner content container inset by pad-edge -> [Title 20] - gap-section - [Body 12, left-aligned, wrapped] - gap-section - [action row]. Action row = right-aligned buttons, gap-item apart, btn-h tall; primary = accent, secondary = surface.
• Button: Button COMP (surface or accent bg) + a Text COMP child caption (size 12, centered, text/accent-text). Height btn-h. Never a bare Button (shows "Button") and never a Text TOP (see td-ui-mechanics.md).
• One decision per screen (wizards): a short title, one question, 2-3 clear options; the recommended one is the accent button. Don't crowd a screen.

5. Process (do this, don't eyeball it)

1. Pick tokens up front - the exact sizes/colors/gaps you'll use, from section 1.
2. Lay out on the grid - compute positions/sizes from the spacing scale; put content inside the pad-edge inset.
3. Clone, don't reinvent - copy a working widget from the host project (Embody's tagger) so styling/caption/callback come for free.
4. Verify visually with a temporary OP Viewer TOP - never build panel UI blind. You CANNOT capture_top a panel COMP directly, but you CAN point a temporary OP Viewer TOP (opviewerTOP, set .par.op = the panel COMP) at it and capture_top THAT to see exactly how the panel renders. Do this after EVERY change and CHECK: type scale consistent? one accent? padding on every edge? left edges aligned? nothing overflowing or cropped? title on top? If you find yourself guessing from the user's screenshots instead of your own captures, you have skipped this step - stop and add the OP Viewer.
5. Iterate against the checklist, not vibes - re-capture the OP Viewer after each tweak until it passes.
6. Remove the probe when done. Once the UI is right and the user approves, delete the temporary OP Viewer TOP. It is a build-time verification tool, not part of the shipped UI.

Anti-patterns (the exact mistakes to never ship)

• Text running off the panel edge (no width / no wordwrap).
• Buttons that fill a whole row's height, or differ in height from each other.
• More than ~4 font sizes; the same role at different sizes.
• Centered multi-line body text; ragged left edges.
• Zero padding - content flush to the window frame.
• No visual difference between the primary and secondary action.
• Using a Text TOP for panel text (renders scaled/blurry - use a Text COMP).