reformatted skill

2026-06-16 23:51:59 -05:00
parent 35a3a8dbed
commit 57da7e001e
4 changed files with 307 additions and 298 deletions
@@ -0,0 +1,76 @@
+# Architecture and Styling Reference
+
+## Project Boundaries
+
+Use this dependency direction:
+
+- pages import components and services
+- components contain presentation logic only
+- services contain business logic and do not import UI
+- static assets are mounted and loaded once at bootstrap
+
+Suggested module split:
+
+```text
+src/app/
+  ui/pages/
+  ui/components/
+  ui/static/
+  services/
+  api/
+  bootstrap.py
+```
+
+## Component Extraction Rules
+
+Extract to ui/components when a pattern appears in two or more pages.
+
+Keep in-page if the layout is specific to a single route.
+
+```python
+def card_section(title: str, content: str) -> ui.card:
+    with ui.card().classes("w-full max-w-md") as card:
+        ui.label(title).classes("text-lg font-bold")
+        ui.label(content).classes("text-gray-600")
+    return card
+```
+
+## Tailwind-First Layout Pattern
+
+Use Tailwind utility classes for structure and spacing.
+Use breakpoint classes for responsive behavior.
+Use .style() only for values that must be computed dynamically.
+
+```python
+with ui.column().classes("w-full"):
+    with ui.row().classes("w-full gap-4 flex-wrap sm:flex-nowrap"):
+        ui.card().classes("flex-1 min-w-64")
+        ui.card().classes("flex-1 min-w-64")
+```
+
+## Styling Decision Order
+
+1. Tailwind utility classes
+2. Quasar props
+3. Reusable styled component functions
+4. Minimal custom CSS loaded once at bootstrap (only when needed)
+
+```python
+from fastapi.staticfiles import StaticFiles
+
+app.mount("/static", StaticFiles(directory="src/app/static"), name="static")
+ui.add_css(open("src/app/static/css/base.css").read())
+```
+
+## Static Asset Rules
+
+- Keep custom CSS small and tokenized with variables.
+- Avoid per-page CSS injection.
+- Verify static mount paths and reverse proxy rewrites.
+
+## Links
+
+- NiceGUI elements: https://nicegui.io/documentation/element
+- NiceGUI binding: https://nicegui.io/documentation/section_binding_properties
+- Tailwind: https://tailwindcss.com/docs/utility-first
+- Quasar components: https://quasar.dev/vue-components
@@ -0,0 +1,109 @@
+# Interaction Patterns Reference
+
+## Reactive State
+
+Use bindable dataclasses for local page state.
+
+```python
+from dataclasses import field
+from nicegui import binding, ui
+
+@binding.bindable_dataclass
+class PageState:
+    selected_id: int | None = None
+    items: list = field(default_factory=list)
+
+state = PageState()
+ui.label().bind_text_from(state, "selected_id")
+```
+
+## File Upload Pattern
+
+- Validate extension and size before storing.
+- Delegate storage to a service method.
+- Notify success and failure explicitly.
+
+```python
+async def handle_upload(e: ui.events.UploadEventArguments):
+    try:
+        if e.size > 10 * 1024 * 1024:
+            raise ValueError("File too large")
+        if not e.name.endswith(".pdf"):
+            raise ValueError("Only PDF allowed")
+        await file_service.store(e.content.read(), e.name)
+        ui.notify(f"Uploaded: {e.name}", type="positive")
+    except ValueError as err:
+        ui.notify(str(err), type="negative")
+
+ui.upload(on_upload=handle_upload, auto_upload=True)
+```
+
+## Form Submission Pattern
+
+- Bind UI inputs to dataclass fields.
+- Perform validation in the service layer.
+- Clear form state on success.
+
+```python
+@binding.bindable_dataclass
+class FormData:
+    name: str = ""
+    email: str = ""
+
+data = FormData()
+ui.input("Name").bind_value(data, "name")
+ui.input("Email").bind_value(data, "email")
+
+async def on_submit():
+    try:
+        await user_service.create_user(name=data.name, email=data.email)
+        ui.notify("User created", type="positive")
+        data.name = data.email = ""
+    except ValueError as err:
+        ui.notify(str(err), type="negative")
+
+ui.button("Submit").on_click(on_submit)
+```
+
+## Real-Time Updates Decision
+
+Use SSE for one-way status streaming.
+Use WebSocket for bidirectional messaging.
+
+SSE endpoint example:
+
+```python
+@app.get("/events/status")
+async def status_stream():
+    async def gen():
+        while True:
+            yield f"data: {await get_status()}\\n\\n"
+            await asyncio.sleep(1)
+    return StreamingResponse(gen(), media_type="text/event-stream")
+```
+
+## Background Work Pattern
+
+- Start long jobs in FastAPI background tasks.
+- Expose status via endpoint or streaming channel.
+- Guard buttons against duplicate submissions during in-flight tasks.
+
+## Explicit Refresh Pattern
+
+Use @ui.refreshable and call refresh intentionally instead of polling unrelated state.
+
+```python
+@ui.refreshable
+async def item_list():
+    items = await service.list()
+    for item in items:
+        ui.label(item.name)
+
+ui.button("Refresh").on_click(lambda: item_list.refresh())
+```
+
+## Links
+
+- NiceGUI action events: https://nicegui.io/documentation/section_action_events
+- FastAPI SSE: https://fastapi.tiangolo.com/advanced/server-sent-events/
+- FastAPI WebSockets: https://fastapi.tiangolo.com/advanced/websockets/
@@ -0,0 +1,39 @@
+# Troubleshooting and Quality Gates
+
+## Troubleshooting
+
+### Upload Errors
+
+- Validate extension and size before storage.
+- Catch expected exceptions and return negative notifications.
+- Log unexpected exceptions with request context.
+
+### UI Race Conditions
+
+- Disable triggering controls during async work.
+- Remove duplicate timers and listeners targeting the same state.
+- Ensure service call ordering is deterministic before render updates.
+
+### Asset Caching
+
+- Confirm static mount and proxy rewrite correctness.
+- Add cache-busting query strings for changed assets.
+- Avoid per-page CSS injection.
+
+### Navigation and State Drift
+
+- Avoid global mutable UI state.
+- Keep state request-scoped or service-managed.
+- Rehydrate page data during route load.
+
+## Production Readiness Gate
+
+Pass all checks before shipping:
+
+- Structure: one-way dependencies between pages, components, and services.
+- Responsiveness: UI validated at both small and large viewport widths.
+- Accessibility: labels and actions are clear and readable.
+- Reliability: validation and exception paths surface user feedback.
+- Maintainability: repeated UI patterns are extracted; business logic remains in services.
+
+If any check fails, return to the workflow step that owns that concern.