Slt Migration

SLT Migration Skill (from ratatui / cursive / textual) — v0.20

This skill complements .claude/skills/slt/SKILL.md (authoring). Use this one to port an existing codebase. After migration switch to the slt skill for day-to-day work.

Targets SLT v0.20.0 (Cargo.toml: version = "0.20.0"). Every API name below has been verified against src/lib.rs and src/context/widgets_*.rs. The v0.20 API consistency pass removed several v0.19 names — the "v0.20 removed APIs" table below lists every one. Do not migrate to a removed name.

When to use

Trigger when:

• The user says "migrate from ratatui", "port from cursive", "ratatui equivalent in SLT", or "rewrite this TUI in SLT".
• A file in scope imports ratatui, tui, or cursive, or Cargo.toml lists them.
• The user is comparing libraries and wants concrete mappings.
• A Python textual project is being rewritten in Rust.

If starting fresh (no existing TUI), use the slt skill instead.

v0.20 removed APIs (do NOT migrate to these)

If you see these in any third-party doc, blog post, or AI training data — they are GONE in v0.20. Use the replacement.

Mental model translation

Compact side-by-side — read once before writing any code.

cursive: callback-based — siv.add_global_callback, layered views, owns its loop. SLT has no callbacks; check inputs and branch in the closure.

textual (Python): retained App+Widget classes, CSS-like styling, compose() yields widgets, on_* event handlers. SLT replaces all of that with one closure and chained method calls.

ratatui → SLT mapping

Run loop

ratatui (typical):

let mut terminal = Terminal::new(CrosstermBackend::new(io::stdout()))?;
terminal::enable_raw_mode()?;
crossterm::execute!(io::stdout(), EnterAlternateScreen, EnableMouseCapture)?;
loop {
    terminal.draw(|f| ui(f, &mut app))?;
    if let Event::Key(key) = event::read()? {
        if key.code == KeyCode::Char('q') { break; }
        // dispatch to app
    }
}
crossterm::execute!(io::stdout(), LeaveAlternateScreen, DisableMouseCapture)?;
terminal::disable_raw_mode()?;

SLT v0.20:

fn main() -> std::io::Result<()> {
    let mut app = App::default();
    slt::run(|ui| {
        if ui.key('q') || ui.key_code(KeyCode::Esc) { ui.quit(); }
        render(ui, &mut app);
    })
}

slt::run enters alternate screen, enables raw mode, installs a panic hook restoring terminal state, and tears down on exit. Variants:

• slt::run_with(RunConfig::default().mouse(true).theme(Theme::dark()), \|ui\| ...) — mouse capture, custom theme
• slt::run_inline(rows, \|ui\| ...) — render below the prompt, no alt screen
• slt::run_static(\|ui\| ...) — append-only scrollback (use with ui.static_log(...))
• slt::run_async::<Message>(\|ui, messages\| ...) — tokio integration (async feature)

Widget mapping (top ratatui widgets → v0.20 SLT)

Every SLT method below is verified against src/context/widgets_*.rs.

v0.20-only widgets (no ratatui equivalent — use these on the migration target)

These are SLT additions; if your ratatui app hand-rolled them, replace with the built-in:

Custom widgets — Layer 3

ratatui custom Widget trait impls don't translate directly. Two options:

Option A — function (preferred for one-off widgets):

fn render_my_widget(ui: &mut Context, data: &MyData) { /* method calls */ }

Option B — implement SLT's Widget trait (for reusable libraries):

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" });

Note: SLT's Widget trait is different from ratatui's. ratatui's Widget::render(self, area, buf) is a stateless paint into a Buffer. SLT's Widget::ui(&mut self, ui) is an immediate-mode call that returns a Response.

Layout mapping

ratatui:

let chunks = Layout::default()
    .direction(Direction::Vertical)
    .constraints([Constraint::Length(3), Constraint::Min(0), Constraint::Length(1)])
    .split(area);
f.render_widget(header, chunks[0]);
f.render_widget(body, chunks[1]);
f.render_widget(footer, chunks[2]);

SLT:

ui.col(|ui| {
    ui.container().h(3).col(|ui| { /* header */ });
    ui.container().fill().col(|ui| { /* body — fills remaining (v0.20 fill() == grow(1)) */ });
    ui.container().h(1).col(|ui| { /* footer */ });
});

Constraint translation:

Constraints value type also exposes the v0.20 WidthSpec set: Constraints::default().w_pct(50), .w_ratio(1, 3), .w_minmax(10, 30) — see examples/v020_widthspec.rs.

State mapping (re-exported via slt::*)

Threading state (CRITICAL for ratatui apps)

ratatui apps typically thread &mut App (or &App) through every render fn:

fn render(f: &mut Frame, app: &mut App) {
    render_header(f, app);
    render_body(f, app);
    render_footer(f, app);
}

In SLT v0.19+ replace read-only sharing with provide/use_context:

struct AppCtx { theme: slt::Theme, tick: u64, settings: Settings }

slt::run(|ui| {
    let ctx = AppCtx { theme: *ui.theme(), tick: ui.tick(), settings: app.settings.clone() };
    ui.provide(ctx, |ui| {
        render_header(ui);
        render_body(ui, &mut app.doc);   // writes still pass &mut explicitly
        render_footer(ui);
    });
});

fn render_header(ui: &mut slt::Context) {
    let ctx = ui.use_context::<AppCtx>();
    ui.text(format!("tick {}", ctx.tick));
}

Reserve explicit &mut parameters for writes (&mut MyDocState).

Event mapping

Modal-aware: ui.key(), ui.key_code(), ui.key_mod() are filtered when a modal is open. For global shortcuts that bypass modals, use ui.raw_key_code() / ui.raw_key_mod().

Consume: ui.consume_key(c) / ui.consume_key_code(code) mark events handled so child widgets don't re-process. Useful for global shortcuts taking precedence over text input.

Style mapping

Style is Copy in both libraries — no clone needed.

Color mapping

Both libraries have:

• 16 named colors: Red, Green, Blue, Yellow, Cyan, Magenta, Black, White, plus LightRed, LightGreen, etc.
• 256-color: Color::Indexed(N) ↔ Color::Indexed(N)
• 24-bit: Color::Rgb(r, g, b) ↔ Color::Rgb(r, g, b)
• Color::Reset in both

Differences:

• ratatui has Color::Gray and Color::DarkGray — SLT only has Color::DarkGray. Use Color::Indexed(8) (ANSI bright black) or Color::Rgb(128, 128, 128) for mid-gray.
• For semantic colors prefer slt::palette::tailwind::* (BLUE.c500, RED.c700) — same 11-shade scale across 22 palettes, identical to Tailwind CSS.

Border type mapping

Use via .border_sides(...): ui.bordered(Border::Single).border_sides(BorderSides::vertical()).col(...).

Theme

ratatui has no built-in theme. If you have ad-hoc Color::* constants, replace with slt::Theme and ui.color(ThemeColor::Primary) so themes can swap. v0.20 additions:

• Theme::dark() / light() (base)
• Theme::compact() / comfortable() / spacious() (density variants of dark)
• Theme::dracula() / nord() / tokyo_night() / gruvbox_dark() / one_dark() / catppuccin() / solarized_dark() / solarized_light()
• ThemeBuilder::builder_from(Theme::nord()) — extend a preset
• ContainerBuilder::theme(custom) — per-subtree override

cursive → SLT mapping

cursive is callback-driven. SLT replaces both pattern and event loop with the imperative closure model.

Mental shift: cursive callbacks fire on input. SLT's closure runs every frame. State updates are visible immediately.

textual (Python) → SLT mapping

textual is class-based with reactive state and CSS. SLT is functional with plain variables.

Common migration pitfalls

• "I have a struct that implements Widget trait." — drop ratatui's. Either rewrite as fn render_my_widget(ui: &mut Context, data: &MyData), or implement slt::Widget (different shape — see Custom widgets section).
• "My App has a draw(&mut self, frame: &mut Frame) method." — convert to fn render(ui: &mut Context, app: &mut App) and call from slt::run(\|ui\| render(ui, &mut app)).
• "ratatui ListState lives across frames." — same in SLT. let mut list = ListState::new(); outside the closure; pass &mut list to ui.list(&mut list) each frame.
• "I want raw crossterm events." — prefer ui.key() / ui.key_code() / ui.key_mod() / ui.mouse_down() / ui.scroll_up(). Raw ui.events() is for advanced cases (key release, paste handling, custom modifier matching). For modal-aware globals use ui.raw_key_code() / ui.raw_key_mod().
• "I have heavy custom layout math (.split() arithmetic on Rect)." — try ui.row / ui.col + .fill / .h / .w / .h_pct / .w_pct / .align / .justify first. Flexbox handles 95% of cases. Drop to ui.container().draw(\|buf, rect\| { ... }) only when flexbox can't express it. The draw closure must be 'static (deferred execution).
• "Constraint::Percentage(50) is everywhere." — .w_pct(50) (row child) or .h_pct(50) (col child). Both take u8.
• "I use Layout::default().margin(1).split(area)." — .p(1) on the parent container.
• "I check Response.rect immediately." — SLT layout runs after the closure. Frame 1 returns zero Rect. Guard with if ui.tick() > 0 { ... }.
• "Borders::ALL." — SLT default. ui.bordered(Border::Rounded) draws all 4 sides. Subset via .border_sides(BorderSides::vertical()).
• "I want Color::Gray." — doesn't exist. Use Color::Indexed(8) or Color::Rgb(128, 128, 128). Or pull from palette::tailwind::SLATE.c500.
• "My ratatui app calls terminal.clear() between frames." — don't. SLT diffs the buffer and only emits changed cells. Manual clear breaks the diff and causes flicker.
• "My panic hook restores raw mode." — drop it. slt::run installs one on first call.
• "I'm threading &App through every render fn." — replace read-only sharing with ui.provide(ctx, \|ui\| ...) + ui.use_context::<AppCtx>(). Keep &mut for writes.
• "My ratatui Gauge has no label." — use ui.gauge(0.75) (no label) or ui.progress(0.75) (display widget, returns &mut Self).

Migration workflow

1. Inventory ratatui widgets used.

   grep -rn "render_widget\|f\.render_widget" src/
   grep -rn "Block::\|Paragraph::\|List::\|Table::\|Tabs::\|Gauge::\|BarChart::\|Chart::\|Sparkline::" src/
   

   Map each to an SLT method via the tables above.

2. Convert the run loop. Replace Terminal::new setup + draw loop + disable_raw_mode teardown with one of slt::run, slt::run_with, slt::run_inline, or slt::run_async.

3. Move state out of the draw closure. Most ratatui apps already do this. Keep the same shape — your App struct now feeds into one SLT closure.

4. Replace layout splitters. Each Layout::default().constraints(...).split(area) becomes nested ui.row / ui.col + .fill / .h / .w / .h_pct / .w_pct / .align / .justify. .gap(n) instead of .spacing(n), .p(n) instead of .margin(n).

5. Replace each f.render_widget(...) with the SLT method. Convert widget by widget. Verify any uncertain method via the v0.20 mapping table or grep src/context/widgets_*.rs.

6. Adopt v0.20 builders. Where the old code hand-rolled gauges, breadcrumbs, scrollable-with-line-numbers, or split panes, use the v0.20 builders/opts directly. They handle hit-testing and accessibility.

7. Replace event handling. Convert raw crossterm::event::read() matches to ui.key(), ui.key_code(), ui.key_mod(), ui.mouse_down(), ui.scroll_up(). Drop manual hit-testing in favor of Response.clicked / right_clicked / hovered / gained_focus / lost_focus.

8. Replace &App threading with provide/use_context for read-only shared state.

9. Run cargo check and fix one widget at a time. Add tests with slt::TestBackend::new(80, 24).render(\|ui\| ...) once a section compiles.

After everything compiles, run the full quality gate (project CLAUDE.md): cargo fmt -- --check, cargo check --all-features, cargo clippy --all-features -- -D warnings, cargo test --all-features, cargo check --examples --all-features.

Things SLT v0.20 doesn't have a direct equivalent for

Be honest with the user — these need workarounds:

• ratatui Canvas braille drawing primitive. SLT has ui.canvas(width, height, \|cv\| { cv.line(...); cv.circle(...); }) but the API takes a CanvasContext closure, not a value-typed widget. Custom point/line drawing logic needs a small rewrite. See src/context/widgets_viz.rs:1289.
• ratatui Wrap { trim: true } exact semantics. SLT wraps via container width and .wrap() on text; trim-leading-whitespace behavior isn't identical. Test wrap-heavy text manually.
• cursive's deep view layering / multiple modal stacks. SLT supports ui.modal(...) / ui.modal_with(...) / ui.overlay_at(anchor, \|ui\| ...) but not arbitrary nested view managers. Most uses fold into if state.show_modal { ui.modal(\|ui\| ...) }.
• textual's CSS hot reload. Themes are Rust values (no hot reload). Use cargo watch -x run for fast iteration.

If a feature genuinely doesn't map, tell the user — don't fake it.

References

• .claude/skills/slt/SKILL.md — SLT authoring skill (use after migration is done).
• .claude/skills/slt/REFERENCES.md — feature flags, v0.20 surface, doc pointers.
• examples/v020_*.rs — runnable v0.20 demos (gauge, breadcrumb, scrollable_with_gutter, split_pane, etc.).
• tests/v020_*.rs — regression tests showing canonical TestBackend + sequence patterns.
• src/lib.rs — authoritative public re-exports.
• src/context/widgets_*.rs — authoritative widget signatures.
• ratatui repo: https://github.com/ratatui-org/ratatui
• cursive repo: https://github.com/gyscos/cursive
• textual repo: https://github.com/Textualize/textual

Source: subinium/SuperLightTUI — distributed by TomeVault.