# 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`.
