TUI -> Kivy porting strategies

[python-processing-unit]

🏷️ Discussion Type

Question

Body

I have a Python TUI application (using Textual) that I want to port to Kivy, since the terminal has proven to constrained for my application. I have already made several failed attempts to port the UI logic, and want to know if anyone has a good strategy for this sort of problem (the biggest issue so far has been Textual's use of a CSS subset for styling)?

Guidelines

• I have read and understood this category's guidelines before making this post.

[salehablrmubeen-source]

I ran into something similar when moving from a TUI to a GUI framework. The biggest lesson was not to "port" the UI itself. Keep your core application logic untouched and rebuild the presentation layer from scratch. Textual's CSS-like styling doesn't really have a clean equivalent in Kivy, so trying to map styles one-for-one usually becomes more work than it's worth.

[python-processing-unit]

I was already trying that, but couldn't get anything to render correctly.

[vishalvivek14332-source]

If you've already separated the application logic, the next step is to stop thinking in terms of recreating the Textual layout. Kivy's widget tree and layout system (BoxLayout, GridLayout, FloatLayout, etc.) are fundamentally different from Textual's CSS-based approach.

A strategy that often works is to rebuild the interface one screen at a time:

• Start with a minimal window that displays static widgets.
• Recreate a single screen's layout using Kivy layouts instead of trying to translate CSS.
• Once the layout looks right, connect it to your existing application logic.
• Repeat for the remaining screens.

If rendering is the main blocker, it would help to know what specifically isn't rendering correctly. Are the widgets not appearing at all, are the layouts behaving unexpectedly, or are you having trouble converting specific Textual CSS rules? A small example of the original Textual layout and your Kivy code would make it much easier to suggest an equivalent approach.

[initial-d]

I would treat this as a rewrite of the presentation layer, but not a rewrite of the application.

The migration pattern that has worked best for me is:

1. Extract a UI-independent state model first

Before touching Kivy, define plain Python objects/dataclasses that describe what each screen needs to show:

@dataclass
class JobRow:
    name: str
    status: str
    progress: float

@dataclass
class DashboardState:
    title: str
    jobs: list[JobRow]
    selected_job_id: str | None

Your Textual widgets and Kivy widgets should both render from this model. That prevents the port from becoming “translate Textual widget tree into Kivy widget tree.”

2. Replace Textual messages with an app event layer

If your Textual app uses messages/events heavily, introduce your own small event API:

class AppController:
    def select_job(self, job_id: str): ...
    def refresh(self): ...
    def cancel_job(self, job_id: str): ...

Then wire Textual callbacks to that controller first. After that, Kivy button handlers call the same controller methods.

3. Do not port Textual CSS directly

Textual CSS and Kivy layout/styling are different enough that a rule-by-rule conversion usually burns time. Instead, convert CSS into a small design-token file:

COLORS = {
    "bg": "#101418",
    "panel": "#182028",
    "accent": "#4aa3ff",
}
SPACING = {
    "sm": 6,
    "md": 12,
    "lg": 20,
}

Then use those tokens from .kv files or Python widget setup. This preserves visual intent without pretending Kivy has Textual CSS.

4. Map screens, not widgets

Make a table like this:

Textual Screen          Kivy equivalent
------------------------------------------------
MainDashboard           ScreenManager screen
Header/Footer           BoxLayout sections
DataTable               RecycleView or GridLayout
Command palette         Popup / ModalView
Log panel               ScrollView + Label / RecycleView

Port one screen at a time. Keep the old Textual screen around until the Kivy version can render the same state model and pass the same controller actions.

5. Start with a read-only Kivy prototype

The first Kivy milestone should not edit anything. It should only display one realistic state snapshot. Once layout is stable, add event handlers. This avoids debugging layout, data flow, and business logic all at once.

A useful folder structure is:

app/
  core/          # business logic, state, services
  controllers/   # UI-independent actions
  textual_ui/    # current UI
  kivy_ui/       # new UI
  design.py      # shared colors/spacing/formatting tokens

The main thing I would avoid is a compatibility layer that tries to emulate Textual CSS in Kivy. It sounds attractive, but it usually creates a second framework inside your app. A thin state/controller boundary gives you a much cleaner migration path.

[lgustavopuga]

Porting from Textual to Kivy is challenging because Textual's CSS and widget model don't translate 1:1. The key to success is separating your presentation layer from your logic instead of trying to translate widgets directly.

Here is a proven strategy to get your Kivy UI rendering correctly:

• Isolate UI State: Define UI-independent state models (like standard Python dataclasses) and an event controller first. Your Kivy layouts should simply render this state.
• Use Design Tokens, Not CSS: Don't try to emulate Textual's CSS. Instead, extract colors and spacing into a simple design.py configuration file, and apply these tokens in Kivy or .kv files.
• Map Screens (Not Widgets): Rebuild one screen at a time:
• Header/Footer ➔ Kivy BoxLayout
• DataTable ➔ Kivy RecycleView
• Command Palette ➔ Kivy ModalView

Start by building a read-only Kivy prototype of your main screen using static state. Once it renders, wire up your event controller!

[blazee14]

Hi, this is an interesting case because Textual and Kivy aren't just "two different frameworks" — they're two different UI paradigms entirely (text/cell-based terminal rendering vs. graphical OpenGL rendering), so a 1:1 port of the interface logic almost never works well. Some strategies that tend to work better than trying to translate widget-by-widget:

Separate business logic from the presentation layer first (if you haven't already): Before touching Kivy, make sure all your app logic (state, validation, data calls) is fully decoupled from Textual widgets. If your current code mixes logic into on_mount, compose(), etc., the port will be much more painful. This is usually 80% of the real work.
Don't try to port Textual's CSS directly to Kivy's KV language: Even though Textual uses a CSS subset and Kivy uses its own KV language (syntactically similar to QML/CSS), the layout models are different — Textual uses a box model similar to CSS Flexbox/Grid adapted to a character grid, while Kivy has its own layout system (BoxLayout, GridLayout, FloatLayout, etc.) with real pixel coordinates and sizes. It's better to redesign the layout from scratch thinking in terms of Kivy's native layouts, rather than translating CSS rules.
Think of Textual "screens" as Kivy "Screens" (ScreenManager): Textual's screen navigation architecture (push_screen, pop_screen) has a fairly close conceptual equivalent in kivy.uix.screenmanager.ScreenManager, so that part of your app's architecture does translate reasonably well.
Consider whether you actually need Kivy, or if the issue is just "I need more graphical control": If the real limitation is things like images, custom graphics, or animations the terminal can't support, there are intermediate options before jumping to a full graphical framework:

Textual-web or exporting your Textual app as a web app (Textual already supports this) gives you more visual flexibility without abandoning your current code.
If you need 2D graphics but not the full weight of Kivy, tools like Pygame or Dear PyGui are lighter-weight.

Practical migration approach: Instead of porting the whole app at once, start by migrating a single simple screen/view as a proof of concept. This gives you a realistic sense of how much effort the rest will take before committing to a full rewrite.

How large is the app (how many screens/views), and what specifically is the terminal preventing you from doing? That would help give a more targeted recommendation on whether Kivy is really the best fit.