website refactor

docs/architecture/website/DISPLAY_OBJECTS.md

@@ -1,10 +1,10 @@
-# Display Objects
+# Displays
 
 ## Definition
 
-A **Display Object** encapsulates **reusable, UI-only display logic**.
+A **Display** encapsulates **reusable, UI-only display logic**.
 
-In this codebase, a Display Object is a **Frontend Value Object**:
+In this codebase, a Display is a **Frontend Value Object**:
 
 - class-based
 - immutable
@@ -15,14 +15,20 @@ It answers the question:
 
 > “How should this specific piece of information be shown?”
 
-Display Objects are **not screen-specific**.
+Displays are **not screen-specific**.
 They exist to avoid duplicating presentation logic across View Models.
 
+**Naming Convention:**
+- Displays MUST end with `Display` suffix
+- Displays MUST be reusable across multiple screens
+- Valid examples: `PriceDisplay`, `EmailDisplay`, `RatingDisplay`
+- Invalid examples: `DashboardRatingDisplay`, `UserProfileDisplay`
+
 ---
 
 ## Responsibilities
 
-A Display Object MAY:
+A Display MAY:
 
 - format values (money, dates, durations)
 - handle localization only when localization inputs are deterministic (for example: mapping stable codes to stable labels)
@@ -30,18 +36,18 @@ A Display Object MAY:
 - encapsulate UI display conventions
 - be reused across multiple View Models
 
-In addition, a Display Object MAY:
+In addition, a Display MAY:
 
 - normalize presentation inputs (for example trimming/casing)
 - expose multiple explicit display variants (for example `shortLabel`, `longLabel`)
 
-A Display Object MUST:
+A Display MUST:
 
 - be deterministic
 - be side-effect free
 - operate only on presentation data
 
-A Display Object MUST:
+A Display MUST:
 
 - be implemented as a **class** with a small, explicit API
 - accept only primitives/plain data in its constructor (or static factory)
@@ -51,7 +57,7 @@ A Display Object MUST:
 
 ## Restrictions
 
-A Display Object MUST NOT:
+A Display MUST NOT:
 
 - contain business logic
 - enforce domain invariants
@@ -60,7 +66,7 @@ A Display Object MUST NOT:
 - be sent back to the server
 - depend on backend or infrastructure concerns
 
-In this repository, a Display Object MUST NOT:
+In this repository, a Display MUST NOT:
 
 - call `Intl.*`
 - call `Date.toLocaleString()` / `Date.toLocaleDateString()` / `Date.toLocaleTimeString()`
@@ -82,41 +88,42 @@ Forbidden approaches:
 - any usage of `toLocale*`
 
 If a rule affects system correctness or persistence,
-it does not belong in a Display Object.
+it does not belong in a Display.
 
 ---
 
 ## Ownership & Placement
 
-- Display Objects belong to the **presentation layer**
+- Displays belong to the **presentation layer**
 - They are frontend-only
 - They are not shared with the backend or core
 
 Placement rule (strict):
 
-- Display Objects live under `apps/website/lib/display-objects/*`.
+- Displays live under `apps/website/lib/display-objects/*`.
+- Filenames MUST match the class name with `.tsx` extension (e.g., `RatingDisplay.tsx` contains `class RatingDisplay`)
 
 ---
 
 ## Relationship to View Models
 
-- View Models MAY use Display Objects
-- Display Objects MUST NOT depend on View Models
-- Display Objects represent **parts**
+- View Models MAY use Displays
+- Displays MUST NOT depend on View Models
+- Displays represent **parts**
 - View Models represent **screens**
 
 Additional strict rules:
 
-- View Models SHOULD compose Display Objects.
-- Display Objects MUST NOT be serialized or passed across boundaries.
+- View Models SHOULD compose Displays.
+- Displays MUST NOT be serialized or passed across boundaries.
   - They must not appear in server-to-client DTOs.
-  - Templates should receive primitive display outputs, not Display Object instances.
+  - Templates should receive primitive display outputs, not Display instances.
 
 ---
 
 ## Testing
 
-Display Objects SHOULD be tested because they often contain:
+Displays SHOULD be tested because they often contain:
 
 - locale-specific behavior
 - formatting rules
@@ -131,9 +138,9 @@ Additionally:
 
 ## Summary
 
-- Display Objects encapsulate **how something looks**
+- Displays encapsulate **how something looks**
 - View Models encapsulate **what a screen needs**
 - Both are presentation concerns
 - Neither contains business truth
 
-In one sentence: Display Objects are **Value Objects for UI display**, not utility functions.
+In one sentence: Displays are **Value Objects for UI display**, not utility functions.