From 6bbc08ef527f830c29e51df294374a5da07b2775 Mon Sep 17 00:00:00 2001
From: Junwei Zhao <wahyd4@gmail.com>
Date: Thu, 30 Jul 2026 17:03:18 +1000
Subject: [PATCH] Update md

---
 agents.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 62 insertions(+), 2 deletions(-)

diff --git a/agents.md b/agents.md
index df5c289..8aecf81 100644
--- a/agents.md
+++ b/agents.md
@@ -332,6 +332,64 @@ Before writing or modifying any feature, **check the existing contract first** t
 - **Accessibility.** Buttons/links need visible focus rings, tap targets ≥ 44 px on mobile, ARIA labels for icon-only controls, and `sr-only` labels for visually-hidden text.
 - **Tests are mandatory for API changes.** Add or update a test that pins the contract (status code, body, headers). Run `pytest` before declaring done.
 
+### UI Style Guidelines
+
+**The home page is the canonical style reference.** Every UI page in this app must align with the Apple-inspired design system defined in `links/templates/links/link_list.html`. Do not introduce ad-hoc Tailwind color palettes (e.g. `red-600`, `gray-200` buttons) or generic card styles on new pages — reuse the home page's tokens and component classes so the whole app shares one visual language.
+
+#### Canonical reference
+- **Home page template**: `links/templates/links/link_list.html` — the `{% block extra_css %}` `<style>` block defines the design system. Copy its `:root` tokens and component classes into new pages rather than inventing new ones.
+- **Files page** (`links/templates/links/files/list.html`) is an example of a non-home page that was restyled to match — use it as a secondary reference for list/card/button patterns outside the home page.
+
+#### Design tokens (CSS custom properties)
+Always declare these in the page's `{% block extra_css %}` `<style>` block:
+```css
+:root {
+  --apple-bg: #f5f5f7;            /* page canvas */
+  --apple-text: #1d1d1f;          /* primary text */
+  --apple-gray: #6e6e73;          /* secondary text */
+  --apple-blue: #0071e3;          /* primary accent / links */
+  --apple-blue-hover: #0077ed;
+  --apple-red: #ff3b30;           /* destructive */
+  --apple-green: #1e7b34;         /* success / public */
+  --apple-separator: rgba(0, 0, 0, 0.06);
+  --apple-ease: cubic-bezier(0.28, 0.11, 0.32, 1);
+  --apple-radius-lg: 28px;        /* cards */
+  --apple-radius-md: 22px;        /* modals / inner cards */
+  --apple-shadow-card: 0 4px 24px rgba(0, 0, 0, 0.05);
+  --apple-shadow-lift: 0 18px 44px rgba(0, 0, 0, 0.10);
+}
+body {
+  background-color: var(--apple-bg) !important;
+  font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
+    "Helvetica Neue", "Segoe UI", Roboto, Arial, sans-serif;
+  color: var(--apple-text);
+  -webkit-font-smoothing: antialiased;
+}
+```
+
+#### Reusable component classes (defined on the home page — copy, don't reinvent)
+- **Layout**: `.apple-wrap` (max-width 72rem, centered)
+- **Cards**: `.apple-card` (white, 28px radius, soft shadow)
+- **Section headers**: `.section-title` (clamp 1.45–1.8rem, 700 weight, -0.022em tracking), `.library-header`, `.library-count`
+- **Buttons**: `.apple-btn` base + `.apple-btn-primary` (blue pill), `.apple-btn-secondary` (gray pill), `.apple-btn-danger` (outline red). All pills: `border-radius: 980px`, `min-height: 44px`.
+- **Icon buttons**: `.icon-btn` (40px circular, hover lift) with `.blue` / `.green` / `.red` / `.amber` modifiers
+- **Badges**: `.badge` pill + `.badge-public` (green) / `.badge-private` (gray) / `.badge-link` / `.badge-template` / `.badge-custom`
+- **Links**: `.apple-link` (blue, inline-flex with chevron), `.alias-link`
+- **Tables**: `.apple-table` with uppercase tracked headers, separator borders, hover row tint
+- **Inputs**: frosted-glass pill inputs (see `.hero-search input` / `.library-filter input`) — `border-radius: 980px`, focus ring `0 0 0 4px rgba(0,113,227,0.14)`
+- **Modals**: `.apple-modal-bg` (blurred dark backdrop) + `.apple-modal` (22px radius white card)
+- **Empty state**: `.empty-state` (centered, gray, 2.6rem icon)
+- **Accessibility**: `a:focus-visible, button:focus-visible { outline: 2px solid var(--apple-blue); outline-offset: 3px; }`
+
+#### Rules
+1. **No raw Tailwind color utilities for primary UI.** Use the `--apple-*` tokens via the component classes above. Tailwind utilities are fine for layout/spacing (`flex`, `gap-4`, `hidden sm:block`), not for the brand palette.
+2. **Pill buttons, circular icon buttons, 28px-radius cards** — these shapes are the app's signature. Don't substitute `rounded-md`/`rounded-lg` for primary components.
+3. **Frosted glass for overlays.** Modals, dropdowns, and the upload HUD use `backdrop-filter: blur(20-24px) saturate(180%)` over a semi-transparent white/dark background.
+4. **Soft shadows, never harsh.** Cards use `--apple-shadow-card`; lifted/hover states use `--apple-shadow-lift`.
+5. ** SF system font stack** on `body` — never hardcoded `font-family` on individual elements.
+6. **Respect `prefers-reduced-motion`.** Disable transitions/animations under reduced motion.
+7. **When restyling an existing page**, verify computed styles match the home page's (background `rgb(245,245,247)`, card radius `28px`, primary button `rgb(0,113,227)` / radius `980px`). The Files page restyle is the reference for this check.
+
 ### Common Tasks
 
 #### Adding a New Model Field
@@ -381,8 +439,10 @@ Before writing or modifying any feature, **check the existing contract first** t
 1. Create view function in `links/views.py` or create new view file
 2. Add URL pattern to `links/urls.py` or appropriate urls file
 3. Create template in `links/templates/`
-4. Add i18n translation strings
-5. Update navigation if needed
+4. **Follow the UI Style Guidelines above** — reuse the home page's `--apple-*` tokens and component classes; don't invent new Tailwind palettes or generic card styles.
+5. Add i18n translation strings
+6. Update navigation if needed
+7. Rebuild Tailwind CSS (`npm run build:css` or `just tailwind`) if new utility classes were introduced
 
 ### Code Style Guidelines