CODE_GUIDELINES.md

@@ -1670,18 +1670,43 @@ Performance tests that explicitly validate performance characteristics should be
 - Use `@describetag :slow` for entire describe blocks (not `@moduletag`, as it affects all tests in the module)
 - Performance tests should include measurable assertions (query counts, timing with tolerance, etc.)
 
+**UI Tests:**
+
+UI tests that validate basic HTML rendering, Phoenix LiveView navigation, or framework functionality (Gettext translations, form elements, UI state changes) should be tagged with `@tag :ui` or `@describetag :ui` to exclude them from fast CI runs. Use `@tag :ui` for individual tests and `@describetag :ui` for describe blocks. UI tests can be consolidated when they test similar elements (e.g., multiple translation tests combined into one). Do not tag business logic tests (e.g., "can delete a user"), validation tests, or data persistence tests as `:ui`.
+
 **Running Tests:**
 
 ```bash
-# Fast tests only (default)
-mix test --exclude slow
+# Fast tests only (excludes slow and UI tests)
+mix test --exclude slow --exclude ui
+# Or use the Justfile command:
+just test-fast
+
+# UI tests only
+mix test --only ui
+# Or use the Justfile command:
+just ui
 
 # Performance tests only
 mix test --only slow
+# Or use the Justfile command:
+just slow
 
-# All tests (including slow tests)
+# All tests (including slow and UI tests)
 mix test
+# Or use the Justfile command:
+just test
+# Or use the Justfile command:
+just test-all
 ```
+
+**Test Organization Best Practices:**
+
+- **Fast Tests (Standard CI):** Business logic, validations, data persistence, edge cases
+- **UI Tests (Nightly CI):** Basic HTML rendering, navigation, translations, UI state
+- **Performance Tests (Nightly CI):** Query optimization, large datasets, timing assertions
+
+This organization ensures fast feedback in standard CI while maintaining comprehensive coverage in nightly runs.
 ---
 
 ## 5. Security Guidelines