COAIA Sequential Thinking

# Pythonista UI Generation Guide for LLMs > A comprehensive guide for LLMs to understand, design, and generate native graphical user interfaces for Pythonista iOS applications, focusing on the `ui` module and `.pyui` file format. - **Version:** 0.1.0 - **Source:** Synthesis of Pythonista `ui` module documentation, community patterns, and analysis of existing UI examples. - **ID:** llms-ui-pythonista-guide.gemini.txt --- ### 1. Introduction & Core UI Concepts (`#ui-intro`) - **1.1. Purpose of This Guide (`#ui-intro-purpose`):** How LLMs should use this document to generate Pythonista UIs from natural language. - **1.2. Pythonista UI Philosophy (`#ui-philosophy`):** Native iOS look and feel, event-driven, separation of UI (pyui) and logic (Python). - **1.3. UI Elements Overview (`#ui-elements-overview`):** Brief introduction to `ui.View`, controls, and layout. - **1.4. UI Generation Workflow for LLMs (`#ui-llm-workflow`):** Step-by-step process for an LLM to generate UI code/pyui. ### 2. The `ui` Module: Deep Dive (`#ui-module-deep-dive`) - **2.1. `ui.View` - The Foundation (`#ui-view-deep-dive`)** - **2.1.1. Properties (`#ui-view-properties`):** `frame`, `bounds`, `background_color`, `tint_color`, `alpha`, `hidden`, `flex`, `name`, `tag`. Detailed usage and common values. - **2.1.2. Methods (`#ui-view-methods`):** `add_subview()`, `remove_from_superview()`, `present()`, `set_needs_display()`, `layout()`. - **2.1.3. View Hierarchy (`#ui-view-hierarchy`):** Understanding superviews and subviews. - **2.2. UI Controls - Interaction Points (`#ui-controls-deep-dive`)** - **2.2.1. `ui.Button` (`#ui-button`):** Properties, `action` linking, common styles. - **2.2.2. `ui.TextField` & `ui.TextView` (`#ui-text-input`):** Input types, `keyboard_type`, `delegate` for advanced handling. - **2.2.3. `ui.Slider`, `ui.Switch`, `ui.SegmentedControl` (`#ui-sliders-switches`):** Value-based controls and their `action`s. - **2.2.4. `ui.Label` & `ui.ImageView` (`#ui-display`):** Static text and image display. - **2.2.5. `ui.TableView` (`#ui-tableview`):** `datasource` and `delegate` protocols for list display. - **2.3. Layout Management (`#ui-layout`)** - **2.3.1. Absolute Positioning (`#ui-layout-absolute`):** Using `frame` directly. - **2.3.2. Flexible Layout (`#ui-layout-flex`):** Detailed explanation of `flex` strings (`'WH'`, `'LRTB'`, `'R'`, `'B'`, etc.) for responsive design. - **2.3.3. Programmatic Layout (`#ui-layout-programmatic`):** Adjusting frames in `layout()` method. - **2.4. Event Handling (`#ui-events`):** - **2.4.1. `action` Property (`#ui-events-action`):** Linking controls to Python functions/methods. - **2.4.2. `delegate` Protocol (`#ui-events-delegate`):** For more complex interactions (e.g., `TextField` editing, `TableView` selection). - **2.4.3. Touch Handling (`#ui-events-touch`):** `touch_began()`, `touch_moved()`, `touch_ended()`. - **2.5. Custom Drawing (`#ui-drawing-deep-dive`)** - **2.5.1. `draw()` Method (`#ui-draw-method`):** Overriding for custom visuals. - **2.5.2. `ui.Path` (`#ui-path`):** Creating shapes (rectangles, circles, lines, arcs). - **2.5.3. `ui.Image` (`#ui-image`)::** Loading and drawing images. - **2.5.4. Drawing Context (`#ui-draw-context`):** `ui.set_color()`, `ui.set_font()`. ### 3. The `.pyui` File Format: Structure & Generation (`#pyui-format-deep-dive`) - **3.1. JSON Schema (`#pyui-json-schema`):** Detailed breakdown of the JSON structure. - **3.2. Key Attributes for LLM Generation (`#pyui-llm-attributes`):** - `name`: Critical for Python code interaction. - `action`: Linking to Python methods. - `class`: Mapping to `ui` module classes. - `frame`, `flex`: Layout definition. - `attributes`: General properties. - `nodes`: View hierarchy. - **3.3. Best Practices for `.pyui` Generation (`#pyui-best-practices`):** - Prioritize `name` and `action` for LLM-generated UIs. - Use `flex` for responsive designs where possible. - Keep hierarchy clean. - **3.4. Loading `.pyui` in Python (`#pyui-loading`):** `ui.load_view()`. ### 4. LLM-Specific UI Generation Guidelines (`#llm-ui-guidelines`) - **4.1. Interpreting Natural Language UI Requests (`#llm-ui-interpret`):** - Translating spatial descriptions ("top left," "centered," "below") into `frame` or `flex` values. - Inferring control types from function descriptions ("input for text" -> `TextField`). - Handling responsiveness requests ("should adapt to screen size"). - **4.2. UI Generation Anti-Patterns for LLMs (`#llm-ui-antipatterns`):** - **DON'T:** Hardcode all `frame` values without considering `flex` for responsive UIs. - **DO:** Always include `name` attributes for interactive elements and elements that need to be referenced from Python. - **DON'T:** Forget to link `action` properties for buttons and other controls. - **DO:** Ensure `super().__init__(*args, **kwargs)` is called in custom `ui.View` subclasses. - **DON'T:** Create overly complex hierarchies when a simpler one suffices. - **4.3. Iterative UI Refinement (`#llm-ui-refinement`):** Guidance on how an LLM should refine generated UI based on user feedback (e.g., "move button down," "make text larger"). ### 5. UI Recipes & Common Patterns (`#ui-recipes`) - **5.1. Basic Form Layout (`#ui-recipe-form`):** Text fields, labels, buttons. - **5.2. List Display (`#ui-recipe-list`):** Using `ui.TableView`. - **5.3. Navigation Patterns (`#ui-recipe-navigation`):** `NavigationView`, tab bars. - **5.4. Custom Controls (`#ui-recipe-custom-control`):** Combining basic views to create new components. - **5.5. Responsive Layout Examples (`#ui-recipe-responsive`):** Demonstrating `flex` in action. ### 6. Appendix (`#ui-appendix`) - **6.1. Glossary of UI Terms (`#ui-glossary`):** - **6.2. External UI Resources (`#ui-external-links`):** Links to Pythonista UI tutorials, design guidelines. - **6.3. Related LLMS.txt Documents (`#ui-related-llms-docs`):** Link to `llms-pythonista-full.gemini.txt`.