Slt

SuperLightTUI (SLT) Authoring Skill — v0.20

Mental model

SLT is immediate-mode. Your app is one closure: slt::run(|ui: &mut Context| { ... }). The closure runs every frame. State lives in plain Rust variables outside the closure — no App trait, no Model/View/Update, no retained tree. SLT handles flexbox layout, ANSI diff, and stdout flush.

Response.rect reflects the previous frame because layout runs after the closure returns. Frame 1 returns a zero Rect. Guard measurement-dependent logic with if ui.tick() > 0 { ... }. See docs/PREVIOUS_FRAME_GUIDE.md.

For larger apps write components as functions: fn render_card(ui: &mut Context, data: &Card). Share read-mostly state with ui.provide(value, |ui| ...) + ui.use_context::<T>() instead of threading &theme through every helper.

The 5 API rules (predictability anchors)

These are non-negotiable in v0.20+. When generating new code, every public widget must match all 5.

1. Builder for optional config. Methods on Context return a builder when ≥1 option exists. Builders chain &mut self -> &mut Self, render on Drop, expose .show() to capture a *Response.

   ui.gauge(0.6).label("60%").width(24).color(Color::Cyan);                     // good
   let r = ui.breadcrumb(&segs).separator(" › ").show();                        // capture response

   Removed in v0.20: gauge_w, gauge_colored, line_gauge_with, breadcrumb_sep, LineGaugeOpts, HighlightRange::single, label_owned. Do not write these — AI training data may suggest them.

2. Floats are f64. Public surface never takes/returns f32. 0.5 is f64 natively, so ui.gauge(0.5) just works.

3. ≤3 positional args. When 4+ args appear, use an opts struct (<Widget>Opts) or a builder.

   GutterOpts::line_numbers(total, viewport)                                    // Opts struct
   ui.scrollable_with_gutter(&mut scroll, opts, |ui, abs| { ... });

4. Stateful widgets take &mut <Widget>State. Never &mut String, &mut Vec<T>, &mut usize. Trivial-value exceptions: slider(&mut f64), checkbox(&mut bool), toggle(&mut bool).

   ui.text_input(&mut TextInputState);   // not &mut String
   ui.tabs(&mut TabsState);              // not &mut usize

5. Responses. Single-rect widgets return Response. Compound widgets return <Widget>Response: Deref<Target = Response> with #[must_use]. Never tuples.

   if ui.button("Save").clicked { ... }                                          // Response
   if let Some(i) = ui.breadcrumb(&segs).show().clicked_segment { ... }          // BreadcrumbResponse

6. Return-type pattern. Methods on Context return one of two types — picking the wrong one is the most common AI-generated compile error.

   • &mut Self — chainable mutators of the last rendered element. Use for: text, link, styled, separator, timer_display, and the style chain (bold, dim, italic, fg, bg, wrap, truncate, align, text_center, m, mx, w, h, grow, spacer, with_if, with).
   • Response — interaction result of an independently-rendered widget. Use for every stateful interactive widget (button, checkbox, toggle, table, tabs, select, radio, multi_select, text_input, list, tree, file_picker, slider, calendar, command_palette, rich_log).
   • Container helpers split: col / row / modal → Response. line / line_wrap / screen → &mut Self (these continue an inline-text chain).

   ui.button("Save").bold();           // ❌ Response has no .bold() — compile error
   if ui.button("Save").clicked { … }  // ✅ Response field
   ui.text("Saved").bold().fg(green);  // ✅ &mut Self chain on display element

Naming categories (NAMING.md micro tier)

Method names encode their category. When picking a name, match the category shape of nearby methods.

Allowed universal abbreviations: bg fg id idx len min max pos pct w h x y r g b a. Forbidden: ctx btn lbl dbg cfg req res srv db in public API. Closure params over &mut Context are always ui, never ctx.

Layer model (5 layers, predictability anchor)

When a method belongs to two layers (ui.bordered(B) shortcut vs ui.container().border(B) explicit), prefer the explicit form in skill output.

Sibling widget shapes (memorize)

When unsure about a widget signature, find its family and match.

// Stateful interactive widgets — &mut <Widget>State, returns Response
ui.list(&mut ListState);              ui.tabs(&mut TabsState);
ui.table(&mut TableState);            ui.tree(&mut TreeState);
ui.select(&mut SelectState);          ui.radio(&mut RadioState);
ui.multi_select(&mut MultiSelectState);
ui.file_picker(&mut FilePickerState); ui.calendar(&mut CalendarState);
ui.text_input(&mut TextInputState);   ui.textarea(&mut TextareaState, rows);  // textarea takes rows
ui.rich_log(&mut RichLogState);       ui.command_palette(&mut CommandPaletteState);
ui.toast(&mut ToastState);            ui.spinner(&SpinnerState);              // spinner is &, not &mut

// Trivial-value siblings — exception to Rule 4
ui.button("Save");                    // Response
ui.checkbox("Done", &mut done);       // Response
ui.toggle("Enabled", &mut on);        // Response
ui.slider("Vol", &mut value, 0.0..=100.0);  // Response

// Builder widgets — chain optional config, render on Drop
ui.gauge(0.6).label("60%").width(24).color(Color::Cyan);
ui.line_gauge(0.6).filled('━').empty('─').width(24).label("60%");
let r = ui.breadcrumb(&segs).separator(" › ").color(Color::Cyan).show();

// Compound responses — Deref<Response> + extra fields
let r = ui.gauge(cpu).label("CPU").show();          // GaugeResponse { ratio: f64 }
let r = ui.breadcrumb(&segs).show();                // BreadcrumbResponse { clicked_segment: Option<usize> }
let r = ui.split_pane(&mut split, l, r);            // SplitPaneResponse { ratio: f64 }
let r = ui.scrollable_with_gutter(&mut scroll, opts, body);  // GutterResponse { current_highlight: Option<usize> }

Hook ordering — three variants

Hooks must be called in the same order every frame unless they are id-keyed.

// WRONG — order-based hook in conditional drifts call order between frames
if expanded { let count = ui.use_state(|| 0); }

// RIGHT — id-keyed variant is safe inside conditionals
if expanded { let count = ui.use_state_named::<i32>("sidebar.count"); }

// Per-list-item runtime keys
for i in 0..items.len() {
    let count = ui.use_state_keyed_default::<i32>(format!("counter-{i}"));
}

Context injection (provide / use_context)

Stop threading &theme, &tick, &mut toasts through every render fn. provide injects a typed value scoped to a closure; nested code reads it back with use_context.

struct AppCtx { theme: slt::Theme, tick: u64, user: &'static str }

slt::run(|ui| {
    let ctx = AppCtx { theme: *ui.theme(), tick: ui.tick(), user: "subin" };
    ui.provide(ctx, |ui| {
        render_header(ui);
        render_card(ui);
    });
});

fn render_card(ui: &mut slt::Context) {
    let ctx = ui.use_context::<AppCtx>();           // panics if missing
    // let maybe = ui.try_use_context::<AppCtx>(); // returns Option<&T>
    ui.text(format!("hi {} (tick {})", ctx.user, ctx.tick));
}

Reserve explicit parameters for writes (&mut MyDocState). Bound is T: 'static — use &'static str for literals, String for runtime values.

Conditional styling (with_if / with)

with_if(cond, modifier) and with(modifier) collapse conditional branches into a single chain. Available on text and ContainerBuilder. Beware: text uses &mut self -> &mut Self, ContainerBuilder uses consuming Self -> Self.

// text — closure receives &mut Self
ui.text("Status").with_if(is_error, |t| { t.bold().fg(Color::Red); });

// ContainerBuilder — closure receives Self by value
ui.container().with_if(is_focused, |c| c.bg(theme.surface_hover)).col(|ui| ...);

Custom widget pattern (Layer 3)

When to use which pattern:

• Function (fn render_card(ui: &mut Context, data: &CardData)): 90% of cases. Use for screens, sections, reusable layouts. Cheaper to write, no trait bounds, easier to test. Built-in widgets follow this shape internally (impl Context direct methods).
• impl Widget: when the component (a) has its own state struct that the caller owns, and (b) you want ui.widget(&mut w) ergonomics matching built-ins. Required for third-party crates that export widgets through trait-bound APIs.

struct Label<'a> { text: &'a str }

impl<'a> slt::Widget for Label<'a> {
    type Response = slt::Response;
    fn ui(&mut self, ui: &mut slt::Context) -> Self::Response {
        ui.register_focusable();
        ui.text(self.text).bold();
        slt::Response::default()
    }
}

ui.add(Label { text: "hello" });   // or call .ui(ui) directly

For mouse hit-testing use ui.interaction(rect). For keyboard use register_focusable() + available_key_presses().

Authoring workflow

1. Confirm the goal — what app? Data table? Dashboard? Form? Game?
2. Check examples/ for the closest pattern (see Reference Examples below). Start from that file if it fits.
3. Grep src/context/widgets_* and src/widgets/* for the actual signature before writing ui.foo(...). Do NOT invent APIs.
4. Keep Cargo.toml features minimal — see REFERENCES.md.
5. Run the quality gate before saying "done".