move

docs/skills/nicegui-ui-customization/references/architecture-and-styling.md

@@ -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