docs: comprehensive cleanup and restructuring of project documentation
This commit is contained in:
56
dev_docs/archive/7-UI-REVIEW.md
Normal file
56
dev_docs/archive/7-UI-REVIEW.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Phase 7 — UI Review
|
||||
|
||||
**Audited:** 2026-04-23
|
||||
**Baseline:** AI_RULES.md & PROJECT_ARCHITECTURE.md
|
||||
**Screenshots:** Captured to `.planning/ui-reviews/07-20260423-160359/`
|
||||
|
||||
## Pillar Scores
|
||||
|
||||
| Pillar | Score | Key Finding |
|
||||
|--------|-------|-------------|
|
||||
| 1. Copywriting | 3/4 | Descriptive labels used ("Discard", "Subtract"), but generic "Cancel" buttons remain. |
|
||||
| 2. Visuals | 4/4 | Excellent adherence to `max-w-7xl` and Lucide icons. Unified headers implemented. |
|
||||
| 3. Color | 4/4 | Good 60/30/10 split. No arbitrary hex codes in UI layers. |
|
||||
| 4. Typography | 2/4 | **CRITICAL:** `globals.css` uses `font-weight: 600` for headers; `font-medium` (500) used in several components. Rule requires `font-normal` (400) only. |
|
||||
| 5. Spacing | 4/4 | Consistent use of responsive `space-y-` and `p-` scales as per architecture. |
|
||||
| 6. Experience Design | 4/4 | Strong sync indicators, loading states, and confirmation safeguards. |
|
||||
|
||||
**Overall Score:** 21/24
|
||||
|
||||
---
|
||||
|
||||
## Detailed Findings
|
||||
|
||||
### Pillar 4: Typography (2/4)
|
||||
- **Violation:** `frontend/app/globals.css:26` defines `h1-h6` with `font-weight: 600`.
|
||||
- **Violation:** `frontend/components/admin/DatabaseManager.tsx:141` and others use `font-medium`.
|
||||
- **Requirement:** AI_RULES.md Section 3 explicitly forbids bold fonts and requires `font-normal` throughout.
|
||||
|
||||
### Pillar 1: Copywriting (3/4)
|
||||
- **Pro:** UI uses descriptive actions: "Force Backup", "Save LDAP Policy", "Subtract 1 from Stock".
|
||||
- **Improvement:** "DELETE" (uppercase) is used in confirmation modals. While good for safety, it technically bypasses the "NO UPPERCASE" rule. Consider using Title Case "Delete" with a specific background color instead.
|
||||
|
||||
### Pillar 2: Visuals (4/4)
|
||||
- **Success:** Main pages correctly utilize `max-w-7xl` with `mx-auto`.
|
||||
- **Success:** Unified headers with icon boxes found in `admin/page.tsx` and `page.tsx`.
|
||||
|
||||
### Pillar 6: Experience Design (4/4)
|
||||
- **Success:** Offline/Online status indicators are prominent and animated.
|
||||
- **Success:** Destructive actions like "Delete Item" and "Logout" utilize `window.confirm` or high-fidelity modals as required.
|
||||
|
||||
---
|
||||
|
||||
### Top 3 Priority Fixes
|
||||
1. **Remove Font Weights** — Remove `font-weight: 600` from `globals.css` (headers) and replace all `font-medium` with `font-normal`. Hierarchy must rely on size and color only.
|
||||
2. **Contextual CTA Labels** — Replace generic "Cancel" and "OK" with contextual verbs (e.g., "Keep Item", "Discard Changes") to improve copywriting fidelity.
|
||||
3. **Focus State Consistency** — Ensure all interactive elements (buttons, inputs) have consistent `focus-visible:ring-2` styling for accessibility.
|
||||
|
||||
---
|
||||
**Files Audited:**
|
||||
- `frontend/app/globals.css`
|
||||
- `frontend/app/page.tsx`
|
||||
- `frontend/app/admin/page.tsx`
|
||||
- `frontend/components/PageShell.tsx`
|
||||
- `frontend/components/admin/DatabaseManager.tsx`
|
||||
- `frontend/components/admin/LdapManager.tsx`
|
||||
---
|
||||
193
dev_docs/archive/ARCHIVE_LOGS.md
Normal file
193
dev_docs/archive/ARCHIVE_LOGS.md
Normal file
@@ -0,0 +1,193 @@
|
||||
### [2026-04-12] v1.5.0: Box Management, Local OCR & Dependency-Free Label Printing
|
||||
**Purpose:** Implementation of a local-first box scanning workflow, including multi-item container selection and professional label generation without external libraries.
|
||||
**Actions:**
|
||||
- `backend/models.py` & `schemas.py` — Added `box_label` field and integrated it into Pydantic models.
|
||||
- `backend/routers/items.py` — Updated item creation and deletion to include `box_label` in immutable AuditLog snapshots.
|
||||
- `frontend/lib/db.ts` — Upgraded IndexedDB (Dexie) to v4 with an index on `box_label` for high-speed local searching.
|
||||
- `frontend/app/page.tsx` — Rewrote `onOCRMatch` to prioritize box matching. Implemented "Box Contents" selection modal and a full Box Inventory management dashboard.
|
||||
- `frontend/components/AIOnboarding.tsx` — Added Box Label association to the AI-powered onboarding form.
|
||||
- `frontend/lib/labels.ts` (NEW) — Developed a 100% dependency-free SVG engine for Barcode 128 and QR Code generation.
|
||||
- `scripts/save_version.py` — Updated script to automatically synchronize `dev` changes into the `master` branch during releases.
|
||||
- `AI_RULES.md` — Added Rule 1.1 for mandatory "Plan Retirement" and strict traceability.
|
||||
- `USER_GUIDE.md` & `PROJECT_ARCHITECTURE.md` — Full documentation of the new container-based logic.
|
||||
**Status:** Stable. Build v1.5.0 release branch created and merged into Master.
|
||||
|
||||
---
|
||||
|
||||
### [2026-04-12] v1.4.1: Security Hardening, PWA Optimization & Modern CSS Upgrade
|
||||
**Purpose:** Implementation of security audit recommendations, REST API test suite, PWA asset generation, and visual UI refinements using Modern CSS.
|
||||
**Actions:**
|
||||
- `backend/routers/users.py` — Implemented rate limiting (5 req/min) on login and restricted `DELETE /items/` to Admin role.
|
||||
- `backend/tests/api_bench.py` (NEW) — Created automated API testing suite for Auth, RBAC, and Security verification.
|
||||
- `frontend/public/icons/` — Generated standard and maskable PWA icons from source logo.
|
||||
- `frontend/public/manifest.json` — Upgraded with maskable support, shortcuts, and orientation lock.
|
||||
- `frontend/app/layout.tsx` — Added iOS-specific native meta tags for a "Premium" look.
|
||||
- `frontend/app/globals.css` — Added `.glass-card` and `.pb-safe` (safe-area) CSS utilities.
|
||||
- `frontend/app/admin/page.tsx` — Restored Dual LDAP group mappings and applied Glassmorphism styling.
|
||||
- `export_prod.sh` — Excluded `tests/` and benchmarking scripts from production bundle.
|
||||
- `PROJECT_ARCHITECTURE.md` — Added Section 7 documenting Security & Hardening policies.
|
||||
- `SESSION_STATE.md` — Updated session status and handover note.
|
||||
**Status:** Stable. Build v1.4.1 release confirmed and committed.
|
||||
|
||||
---
|
||||
|
||||
### [2026-04-11] v1.3.6: Scanner Redesign, Auto-OCR Countdown & save-version Automation
|
||||
**Purpose:** Redesign the scanner UX for hands-free operation, enforce UI typography rules, add Item Type datalist, and create a reusable `save-version` AI command.
|
||||
**Actions:**
|
||||
- `frontend/components/Scanner.tsx` — Full layout redesign: controls moved below camera viewport (no overlay). Replaced manual OCR button with automatic 4-second OCR cycle. Added visual countdown with progress bar. Removed all `uppercase`/`tracking-widest` styling per AI_RULES Section 3.
|
||||
- `frontend/components/AIOnboarding.tsx` — Added searchable `<datalist>` for Item Type field populated from existing DB types.
|
||||
- `frontend/app/page.tsx` — Added searchable `<datalist>` for Item Type to the item edit modal.
|
||||
- `frontend/app/inventory/page.tsx` — Added searchable `<datalist>` for Item Type in inventory catalog forms.
|
||||
- `scripts/save_version.py` (NEW) — Automation script for `save-version` command: bumps patch version, commits, creates snapshot branch, generates prod ZIP.
|
||||
- `AI_RULES.md` — Added Section 6 defining the `save-version` AI Command Shortcut.
|
||||
- `README.md` — Updated Production Distribution section to document `save-version` workflow.
|
||||
- `dev_docs/SESSION_STATE.md` — Updated with current session handover.
|
||||
**Status:** Stable. Ready for version bump.
|
||||
|
||||
---
|
||||
|
||||
### [2026-04-11] v1.3.5: Frontend Login Loop Fix
|
||||
**Purpose:** Fix infinite redirect loop after successful LDAP login (Chrome crash bug).
|
||||
**Actions:**
|
||||
- `frontend/lib/api.ts` — axiosInstance baseURL now lazy (set in request interceptor, not at module init) to fix SSR wrong-URL bug
|
||||
- `frontend/lib/api.ts` — 401 interceptor now guards against redirect when already on `/login`
|
||||
- `frontend/app/page.tsx` — token guard added to both useEffect hooks before any API calls
|
||||
- `frontend/lib/auth.ts` — removed temporary debug console.log statements
|
||||
- `frontend/app/login/page.tsx` — removed temporary debug console.log statements and unused `memo` import
|
||||
- `dev_docs/SESSION_STATE.md` — updated with current status (fixes applied, not yet tested)
|
||||
- `dev_docs/SESSION_HISTORY.md` — previous session archived
|
||||
**Status:** Applied, not yet tested. Server must be restarted to verify.
|
||||
|
||||
---
|
||||
|
||||
### [2026-04-11 12:45] v1.3.0: Dockerization & Export Script
|
||||
**Purpose:** Upgraded the system architecture to support seamless dual-mode execution (Dockerized or Bare-Metal/Local). Extracted data and logic persistence layers to external volumes (`/data`, `/logs`). Added a dedicated production compiler.
|
||||
**Actions:**
|
||||
- `backend/database.py` and `users.py` now support `DATA_DIR` environment overrides.
|
||||
- Implemented `backend/logger.py` for standard Python rotating logs mapped to `/app/logs`.
|
||||
- Next.js configured for `standalone` output mode to strictly optimize containerized PWA size.
|
||||
- Orchestrated full environment with `docker-compose.yml`, using Caddy for local self-signed HTTPS termination.
|
||||
- Created `export_prod.sh` to extract a clean release bundle without AI/Dev files (using optimized `rsync`).
|
||||
**Modified Files:**
|
||||
- `backend/database.py`
|
||||
- `backend/routers/users.py`
|
||||
- `backend/logger.py` (New)
|
||||
- `backend/main.py`
|
||||
- `frontend/next.config.mjs`
|
||||
- `frontend/Dockerfile` (New)
|
||||
- `backend/Dockerfile` (New)
|
||||
- `docker-compose.yml` (New)
|
||||
- `Caddyfile` (New)
|
||||
- `export_prod.sh` (New)
|
||||
- `VERSION.json`
|
||||
|
||||
### [2026-04-11 12:35] v1.2.9: Automatic IDE Entry Points
|
||||
**Purpose:** Restored specific ID-based entry points (`GEMINI.md` and `CLAUDE.md`) as "Proxy Pointers" to ensure modern AI extensions (Cursor, Windsurf, Gemini IDE) naturally pick them up as system prompt injections.
|
||||
**Modified Files:**
|
||||
- `GEMINI.md` (Recreated as proxy)
|
||||
- `CLAUDE.md` (Created as proxy)
|
||||
- `AI_RULES.md`
|
||||
- `VERSION.json`
|
||||
|
||||
### [2026-04-11 12:25] v1.2.8: Absolute Documentation Consolidation
|
||||
**Purpose:** Restructured all project documentation to completely eliminate redundancy and establish clear "Single Source of Truth" boundaries for humans and AI agents.
|
||||
**Actions:**
|
||||
- Created `PROJECT_ARCHITECTURE.md` uniting business requirements, tech stack, data models, and specific OCR algorithms.
|
||||
- Unified all AI operational rules, constraints, and UI fidelities strictly inside `AI_RULES.md`.
|
||||
- Removed redundant, overlapping files (`GEMINI.md`, `requirements.md`, `TECH_STACK.md`, `UI_FIDELITY_SPEC.md`, `SCANNER_LOGIC_SPEC.md`).
|
||||
- Stripped `PLAN.md` down to just the active checklist.
|
||||
**Modified Files:**
|
||||
- `PROJECT_ARCHITECTURE.md` (New)
|
||||
- `AI_RULES.md`
|
||||
- `PLAN.md`
|
||||
- `VERSION.json`
|
||||
|
||||
### [2026-04-11 12:15] v1.2.7: Documentation Refactor & Portability
|
||||
**Purpose:** Consolidated technical stack information into a single source of truth (`dev_docs/TECH_STACK.md`) and removed absolute paths from all AI-facing documents to ensure the project can be moved across environments without breaking references.
|
||||
**Modified Files:**
|
||||
- `dev_docs/TECH_STACK.md` (New)
|
||||
- `GEMINI.md` (Refined)
|
||||
- `AI_RULES.md` (Cleaned)
|
||||
- `PLAN.md` (Referenced tech stack)
|
||||
- `requirements.md` (Referenced tech stack)
|
||||
- `dev_docs/SESSION_STATE.md` (Path cleanup)
|
||||
- `VERSION.json`
|
||||
|
||||
### [2026-04-11 12:05] v1.2.6: Hotfix - Missing Icon Imports
|
||||
|
||||
### [2026-04-11 11:58] v1.2.5: UI Icon Synchronization
|
||||
|
||||
### [2026-04-11 11:45] v1.2.4: Offline Auth & UX Polish
|
||||
|
||||
### [2026-04-11 11:30] v1.2.3: System-Wide UI Homogenization
|
||||
|
||||
### [2026-04-11 11:21] v1.2.2: UI Readability & Density Optimization
|
||||
|
||||
### [2026-04-10 21:59] v1.2.1: Infrastructure & UI Dynamic Versioning
|
||||
|
||||
# Archive Logs
|
||||
This file contains the mandatory historical log of code, architecture, and logic modifications.
|
||||
Each entry MUST be formatted chronologically.
|
||||
|
||||
### [2026-04-10 18:43] v1.2.0: Categories, Types and LDAP Framework
|
||||
**Purpose:** Implemented structured category groups and specific item types. Fixed PBKDF2 hashing compatibility for Mac/Python 3.14. Integrated LDAP authentication framework. Established master/dev/vX Git rules.
|
||||
**Modified Files:**
|
||||
- `backend/models.py`
|
||||
- `backend/schemas.py`
|
||||
- `backend/main.py`
|
||||
- `backend/routers/categories.py`
|
||||
- `backend/routers/users.py`
|
||||
- `frontend/app/page.tsx`
|
||||
- `frontend/components/AIOnboarding.tsx`
|
||||
- `VERSION.json`
|
||||
- `requirements.md`
|
||||
- `AI_RULES.md`
|
||||
- `dev_docs/PLAN_HISTORY.md`
|
||||
- `dev_docs/SESSION_HISTORY.md`
|
||||
|
||||
**Purpose:** Why this was modified.
|
||||
**Modified Files:**
|
||||
- `path/to/file`
|
||||
|
||||
**Test Results:** (if applicable)
|
||||
|
||||
### [2026-04-10 13:44] Backend Foundation Setup
|
||||
**Purpose:** Initialized the Phase 1 backend using Python and SQLite to prepare the environment for API routing.
|
||||
**Modified Files:**
|
||||
- `backend/requirements.txt` (NEW)
|
||||
- `backend/database.py` (NEW)
|
||||
- `backend/models.py` (NEW)
|
||||
- `backend/main.py` (NEW)
|
||||
- `.gitignore` (NEW)
|
||||
|
||||
**Test Results:** Installed properly using Homebrew Python venv on Mac. SQLAlchemy models parsed appropriately.
|
||||
|
||||
### [2026-04-10 13:47] Core Inventory API (Phase 2)
|
||||
**Purpose:** Implemented the Pydantic schemas and standard CRUD endpoints for Inventory logic. Built safe Check-in/Check-out operations enforcing immutable Audit Log triggers.
|
||||
**Modified Files:**
|
||||
- `backend/schemas.py` (NEW)
|
||||
- `backend/routers/__init__.py` (NEW)
|
||||
- `backend/routers/items.py` (NEW)
|
||||
- `backend/routers/operations.py` (NEW)
|
||||
- `backend/main.py` (UPDATED)
|
||||
|
||||
### [2026-04-10 13:58] AI Coordination & Bulk Operations (Phase 3)
|
||||
**Purpose:** Established Multi-AI handover protocol with archival logic. Extended backend to support bulk check-outs and trash operations with mandatory audit logging.
|
||||
**Modified Files:**
|
||||
- `dev_docs/SESSION_STATE.md` (NEW)
|
||||
- `dev_docs/SESSION_HISTORY.md` (NEW)
|
||||
- `AI_RULES.md` (UPDATED)
|
||||
- `backend/schemas.py` (UPDATED)
|
||||
- `backend/routers/operations.py` (UPDATED)
|
||||
|
||||
**Test Results:** Scheme support bulk and trash objects. Logging logic verified in code for session state compliance.
|
||||
|
||||
### [2026-04-10 14:05] PWA Frontend Scaffolding (Phase 4)
|
||||
**Purpose:** Initialized the React/Next.js/Tailwind frontend project for the PWA interface. Manually scaffolded to bypass MacOS home directory permission restrictions.
|
||||
**Modified Files:**
|
||||
- `frontend/package.json` (NEW)
|
||||
- `frontend/app/layout.tsx` (NEW)
|
||||
- `frontend/app/page.tsx` (NEW)
|
||||
- `frontend/public/manifest.json` (NEW)
|
||||
|
||||
**Test Results:** Dependencies installed successfully via local npm cache. Bootstrap icons and Tailwind directives configured.
|
||||
267
dev_docs/archive/COLOR_SYSTEM_ARCHITECTURE.md
Normal file
267
dev_docs/archive/COLOR_SYSTEM_ARCHITECTURE.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# Color System Architecture: Single Source of Truth
|
||||
|
||||
**Status**: ✅ IMPLEMENTED
|
||||
**Commit**: e715afd8
|
||||
**Date**: 2026-04-25
|
||||
|
||||
---
|
||||
|
||||
## Problem Solved
|
||||
|
||||
Color definitions were previously duplicated in two locations:
|
||||
- `frontend/tailwind.config.ts` — Tailwind CSS utility classes (e.g., `bg-primary`)
|
||||
- `frontend/app/globals.css` — CSS custom properties (e.g., `--primary`)
|
||||
|
||||
This created a **DRY violation** where changing a color required edits in 2 places, with high risk of inconsistency.
|
||||
|
||||
---
|
||||
|
||||
## New Architecture
|
||||
|
||||
### 1. Single Source of Truth: `frontend/colors.mjs`
|
||||
|
||||
```javascript
|
||||
// frontend/colors.mjs — The authoritative color definitions
|
||||
export const colors = {
|
||||
background: "#131313",
|
||||
primary: {
|
||||
DEFAULT: "#ffb781",
|
||||
container: "#f58618",
|
||||
// ... all color variants
|
||||
},
|
||||
// ... 40+ colors from DESIGN.md
|
||||
};
|
||||
|
||||
export const spacing = {
|
||||
unit: "4px",
|
||||
"stack-sm": "8px",
|
||||
// ... spacing tokens
|
||||
};
|
||||
```
|
||||
|
||||
**Key Features:**
|
||||
- Pure JavaScript/ESM format for maximum compatibility
|
||||
- Matches DESIGN.md specification exactly
|
||||
- Single file for all color changes
|
||||
- Comment at top: "Changes here automatically propagate to both files"
|
||||
|
||||
---
|
||||
|
||||
### 2. Automated CSS Generation: `frontend/scripts/generate-css-vars.mjs`
|
||||
|
||||
A build-time script that:
|
||||
1. Reads `colors.mjs`
|
||||
2. Flattens nested color objects (e.g., `primary.DEFAULT` → `--primary-DEFAULT`)
|
||||
3. Generates CSS custom properties organized by category
|
||||
4. Injects into `frontend/app/globals.css` `:root` block
|
||||
5. Preserves all other CSS code unchanged
|
||||
|
||||
**Execution:**
|
||||
```bash
|
||||
node frontend/scripts/generate-css-vars.mjs
|
||||
# Output: ✓ Generated CSS variables in globals.css from colors.mjs
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- No manual CSS variable maintenance
|
||||
- Always stays in sync with colors.mjs
|
||||
- Runs automatically before every build
|
||||
|
||||
---
|
||||
|
||||
### 3. Import in Tailwind Config: `frontend/tailwind.config.ts`
|
||||
|
||||
```typescript
|
||||
import { colors as colorsDefinition } from "./colors.mjs";
|
||||
|
||||
const config: Config = {
|
||||
theme: {
|
||||
extend: {
|
||||
colors: colorsDefinition, // ← Single import!
|
||||
// ...
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
**Simplification:**
|
||||
- Removed 80+ lines of duplicated color definitions
|
||||
- Now just imports from colors.mjs
|
||||
- Maintains all Tailwind utility classes (`bg-primary`, `text-secondary`, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Build Integration
|
||||
|
||||
### Frontend Build (`frontend/package.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"generate-css-vars": "node scripts/generate-css-vars.mjs",
|
||||
"dev": "npm run generate-css-vars && next dev",
|
||||
"build": "npm run generate-css-vars && next build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Flow:**
|
||||
1. `npm run dev` or `npm run build` executes
|
||||
2. Automatically runs `generate-css-vars` first
|
||||
3. CSS variables synchronized
|
||||
4. Next.js build proceeds
|
||||
|
||||
### Standalone Deployment (`start_servers.py`)
|
||||
|
||||
```python
|
||||
def setup_frontend(self):
|
||||
# Generate CSS variables from colors.mjs before building
|
||||
self.log("Generating CSS variables from design system...")
|
||||
result = subprocess.run(
|
||||
["node", "scripts/generate-css-vars.mjs"],
|
||||
cwd=str(frontend_dir),
|
||||
capture_output=True
|
||||
)
|
||||
# Then proceed with npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Changing Colors
|
||||
|
||||
**Before (2 files, high risk):**
|
||||
1. Edit hex in `tailwind.config.ts` line 42
|
||||
2. Edit hex in `globals.css` line 26
|
||||
3. Risk: Forget one file, colors diverge
|
||||
4. Build has no validation
|
||||
|
||||
**After (1 file, zero risk):**
|
||||
1. Edit `colors.mjs` (one location)
|
||||
2. Run `npm run build`
|
||||
3. Script auto-generates both Tailwind colors and CSS variables
|
||||
4. No manual sync needed
|
||||
|
||||
**Example:**
|
||||
```javascript
|
||||
// colors.mjs
|
||||
export const colors = {
|
||||
primary: {
|
||||
DEFAULT: "#ffb781", // ← Change here
|
||||
// ...
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
Then:
|
||||
- ✅ `npm run build` auto-generates CSS variables
|
||||
- ✅ tailwind.config.ts already imports from colors.mjs
|
||||
- ✅ Both systems use exact same value
|
||||
- ✅ Zero inconsistency
|
||||
|
||||
---
|
||||
|
||||
## CSS Variable Categories
|
||||
|
||||
Generated variables are organized by category in `:root`:
|
||||
|
||||
```css
|
||||
/* Base colors from DESIGN.md */
|
||||
--background: #131313;
|
||||
--on-background: #e5e2e1;
|
||||
|
||||
/* Surface colors from DESIGN.md */
|
||||
--surface-DEFAULT: #131313;
|
||||
--surface-dim: #131313;
|
||||
/* ... 8 more surface variants */
|
||||
|
||||
/* Primary colors from DESIGN.md */
|
||||
--primary-DEFAULT: #ffb781;
|
||||
--primary-container: #f58618;
|
||||
/* ... 7 more primary variants */
|
||||
|
||||
/* Secondary, Tertiary, Error colors... */
|
||||
|
||||
/* Semantic spacing tokens */
|
||||
--spacing-unit: 4px;
|
||||
--spacing-gutter: 16px;
|
||||
/* ... more spacing */
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Design System Compliance
|
||||
|
||||
All colors from `DESIGN.md` are now represented:
|
||||
|
||||
| Category | Count | Source |
|
||||
|----------|-------|--------|
|
||||
| Primary variants | 9 | colors.mjs |
|
||||
| Secondary variants | 8 | colors.mjs |
|
||||
| Tertiary variants | 8 | colors.mjs |
|
||||
| Surface variants | 9 | colors.mjs |
|
||||
| Error variants | 4 | colors.mjs |
|
||||
| Outline/Inverse/Semantic | 7 | colors.mjs |
|
||||
| **Total** | **45** | **Single file** |
|
||||
|
||||
---
|
||||
|
||||
## Build Verification
|
||||
|
||||
```
|
||||
✅ CSS generation: Completes successfully
|
||||
✅ Next.js compile: 5.7s with 0 errors
|
||||
✅ CSS validation: 0 warnings
|
||||
✅ TypeScript: Strict mode, 0 issues
|
||||
✅ All pages: 8/8 generated
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Future Maintenance
|
||||
|
||||
**If colors need updating:**
|
||||
1. Edit `frontend/colors.mjs`
|
||||
2. Run `npm run build` (auto-syncs everything)
|
||||
3. Done!
|
||||
|
||||
**No need to:**
|
||||
- Edit tailwind.config.ts
|
||||
- Edit globals.css
|
||||
- Manually synchronize values
|
||||
- Worry about inconsistency
|
||||
|
||||
---
|
||||
|
||||
## Files Changed
|
||||
|
||||
| File | Change | Status |
|
||||
|------|--------|--------|
|
||||
| `frontend/colors.mjs` | Created | ✅ New SSOT |
|
||||
| `frontend/scripts/generate-css-vars.mjs` | Created | ✅ Auto build step |
|
||||
| `frontend/tailwind.config.ts` | Updated | ✅ Imports from colors.mjs |
|
||||
| `frontend/package.json` | Updated | ✅ Added generate-css-vars script |
|
||||
| `start_servers.py` | Updated | ✅ Runs generate step |
|
||||
| `frontend/app/globals.css` | Generated | ✅ Auto-synced on build |
|
||||
|
||||
---
|
||||
|
||||
## Command Reference
|
||||
|
||||
```bash
|
||||
# One-time generate CSS variables
|
||||
npm run generate-css-vars
|
||||
|
||||
# Development mode (auto-generates on startup)
|
||||
npm run dev
|
||||
|
||||
# Production build (auto-generates before build)
|
||||
npm run build
|
||||
|
||||
# Standalone deployment (auto-generates before build)
|
||||
python3 start_servers.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Implemented by:** Claude Haiku 4.5
|
||||
**Architecture Decision:** Consolidate to single source of truth with automated CSS generation
|
||||
228
dev_docs/archive/DESIGN-TYPOGRAPHY-HIERARCHY.md
Normal file
228
dev_docs/archive/DESIGN-TYPOGRAPHY-HIERARCHY.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# Design: Typography & Visual Hierarchy Overhaul
|
||||
|
||||
Generated by /gstack-office-hours on 2026-04-19
|
||||
Branch: dev
|
||||
Repo: tfm_ainventory
|
||||
Status: DRAFT
|
||||
Mode: Builder (Intrapreneurship)
|
||||
|
||||
## Problem Statement
|
||||
|
||||
The current UI has weak visual hierarchy on tablets and larger screens. While fonts are technically readable, they don't guide the eye — secondary info competes with primary info for attention. Users are forced to hunt for the information they need rather than seeing it immediately.
|
||||
|
||||
**Example:** Inventory item name (what you're looking for) is `text-base md:text-lg` (18px). The category label next to it is almost the same size. Which is more important? The UI doesn't say.
|
||||
|
||||
## Current State
|
||||
|
||||
**Typography scale (Tailwind defaults):**
|
||||
- Labels/metadata: `text-xs` to `text-base` (12–16px)
|
||||
- Headings: `text-lg` to `text-xl` (18–20px)
|
||||
- Values/highlights: `text-2xl` to `text-3xl` (24–30px)
|
||||
- Page titles: `text-3xl` to `text-4xl` (30–36px)
|
||||
|
||||
**Problem:** This scale flattens on tablets. A 18px label looks like a headline. A 30px value looks like a label. The hierarchy collapses.
|
||||
|
||||
## Premises
|
||||
|
||||
1. **Font size alone doesn't create hierarchy.** Weight, color, spacing, and contrast matter more than raw pixels.
|
||||
2. **Tablet is a first-class device.** The app is used on iPads in warehouses. Design for that, not just mobile.
|
||||
3. **Visual hierarchy = faster task completion.** If the user sees the item quantity immediately, they spend 0.5 seconds scanning. If they hunt, it's 3 seconds per item. Over 100 items, that's 4 minutes lost per session.
|
||||
4. **We don't need bigger type everywhere.** Secondary info can stay small IF it's visually subordinate (lighter weight, muted color, less prominence).
|
||||
|
||||
## Open Questions
|
||||
|
||||
- What's the primary use case breakdown? Mostly mobile in the field, mostly tablet in warehouse, or mixed 50/50?
|
||||
- Do users ever need to scan and read fine details simultaneously (e.g., zoom control labels)?
|
||||
- Is there a standard tablet size we're optimizing for (iPad 10.2", iPad Pro 12.9", or both)?
|
||||
|
||||
## Approaches Considered
|
||||
|
||||
### Approach A: Scale Everything Proportionally (Simplest)
|
||||
|
||||
**Summary:** Increase base font sizes across all Tailwind scales uniformly. `text-base` → `text-lg`, `text-lg` → `text-xl`, etc. On tablets, everything gets bigger, hierarchy stays the same.
|
||||
|
||||
**Effort:** S (one config change to tailwind.config.ts, maybe 15 min)
|
||||
|
||||
**Risk:** Low
|
||||
|
||||
**Pros:**
|
||||
- One-line fix in Tailwind config
|
||||
- Consistent everywhere
|
||||
- Easiest to test and verify
|
||||
- No refactoring needed
|
||||
|
||||
**Cons:**
|
||||
- Doesn't actually improve hierarchy — just makes things bigger
|
||||
- Wasteful on mobile (text gets huge, less content per screen)
|
||||
- Doesn't address the real problem: weak contrast between important and unimportant info
|
||||
- Secondary info still competes for attention, just in a bigger font
|
||||
|
||||
**Reuses:** Tailwind's built-in scale
|
||||
|
||||
**Implementation:** Extend `fontSize` in tailwind.config.ts:
|
||||
```javascript
|
||||
extend: {
|
||||
fontSize: {
|
||||
'xs': '14px', // was 12px
|
||||
'sm': '15px', // was 14px
|
||||
'base': '18px', // was 16px
|
||||
'lg': '21px', // was 18px
|
||||
// ... etc
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Approach B: Responsive Scale + Weight-Based Hierarchy (Recommended)
|
||||
|
||||
**Summary:** Keep mobile readable, boost tablet sizes moderately. More importantly, use **font weight** (not just size) to create hierarchy. Primary info is bold/heavy; secondary is regular/light. Add color emphasis (primary color for key values).
|
||||
|
||||
**Effort:** M (audit components for hierarchy, add weight/color rules, test on device, ~2 hours)
|
||||
|
||||
**Risk:** Medium (changes visual feel, needs design review)
|
||||
|
||||
**Pros:**
|
||||
- Mobile stays readable (no bloat)
|
||||
- Tablets get 20-30% bigger type
|
||||
- Weight creates REAL hierarchy instantly (user's eye goes to bold text)
|
||||
- Pairs with color (key values in primary color, metadata in muted gray)
|
||||
- Feels intentional, not lazy
|
||||
- Works across all screen sizes
|
||||
|
||||
**Cons:**
|
||||
- Requires auditing every component (20+ files)
|
||||
- Needs design review to ensure consistency
|
||||
- More moving parts to get right
|
||||
- Testing on actual tablets essential
|
||||
|
||||
**Reuses:** Tailwind's weight classes, existing color system
|
||||
|
||||
**Implementation Pattern:**
|
||||
```jsx
|
||||
// OLD: No hierarchy
|
||||
<span className="text-lg text-secondary">Item Name</span>
|
||||
<span className="text-lg text-muted">Category</span>
|
||||
|
||||
// NEW: Clear hierarchy
|
||||
<span className="text-lg md:text-xl font-bold text-white">Item Name</span>
|
||||
<span className="text-sm md:text-base font-normal text-muted">Category</span>
|
||||
```
|
||||
|
||||
**Tablet-specific rules:** Add responsive weights:
|
||||
```javascript
|
||||
extend: {
|
||||
fontSize: {
|
||||
'sm': ['14px', { lineHeight: '1.5' }],
|
||||
'base': ['16px', { lineHeight: '1.6' }],
|
||||
'lg': ['18px', { lineHeight: '1.6' }],
|
||||
'xl': ['20px', { lineHeight: '1.5' }],
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Approach C: Fluid Typography + Dynamic Scaling (Future-proof)
|
||||
|
||||
**Summary:** Use CSS custom properties (variables) to scale type fluidly from mobile → tablet → desktop. Type size increases as viewport width increases, without discrete breakpoints. Add hierarchy through weight, spacing, and contrast.
|
||||
|
||||
**Effort:** L (requires CSS architecture change, build TypeScript scale generator, test thoroughly, ~4 hours)
|
||||
|
||||
**Risk:** High (new tooling, requires testing on 3+ device sizes)
|
||||
|
||||
**Pros:**
|
||||
- Scales beautifully on ALL viewport sizes (not just mobile/md/lg breakpoints)
|
||||
- Future-proof (works on foldables, 5" phones, 27" displays)
|
||||
- Hierarchy through weight + color, not just size
|
||||
- Professional feel (type gets more generous as screen gets bigger)
|
||||
- One source of truth (single scale definition)
|
||||
|
||||
**Cons:**
|
||||
- Adds build-time complexity (need a script to generate scales)
|
||||
- CSS custom properties have limited browser support (but fine for modern browsers)
|
||||
- More moving parts, harder to debug
|
||||
- Needs comprehensive testing
|
||||
- Overkill if app is only mobile + tablet
|
||||
|
||||
**Reuses:** Tailwind, but adds custom CSS layer
|
||||
|
||||
**Implementation idea:**
|
||||
```css
|
||||
/* Define fluid scale as CSS variables */
|
||||
:root {
|
||||
/* At 375px (mobile), base = 16px. At 1440px (desktop), base = 18px. */
|
||||
--font-base: clamp(16px, 2.5vw, 18px);
|
||||
--font-lg: clamp(18px, 3vw, 20px);
|
||||
--font-xl: clamp(20px, 3.5vw, 24px);
|
||||
}
|
||||
|
||||
/* Use in components */
|
||||
.text-base { font-size: var(--font-base); }
|
||||
.text-lg { font-size: var(--font-lg); }
|
||||
.text-xl { font-size: var(--font-xl); }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommended Approach: B (Responsive Scale + Weight-Based Hierarchy)
|
||||
|
||||
**Why:**
|
||||
- Solves the real problem (hierarchy, not just size)
|
||||
- Effort-to-impact ratio is excellent
|
||||
- Works across all devices without bloat
|
||||
- Uses tools already in the design system
|
||||
- Reviewable component-by-component (low risk of breaking things)
|
||||
|
||||
**Concrete next step:**
|
||||
1. Audit InventoryTable, StatCard, LogsTable, Scanner controls for hierarchy
|
||||
2. Add weight rules: primary data `font-bold`, metadata `font-normal`
|
||||
3. Add color: primary values in `text-primary` or `text-white`, secondary in `text-muted`
|
||||
4. Test on iPad (actual device or browser dev tools)
|
||||
5. Review with user on actual tablet to verify readability
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- **Tablet test (10.2" iPad):** User can read item names, quantities, and key metadata without squinting at normal viewing distance (12-18 inches)
|
||||
- **Hierarchy test:** In a list of 20 items, user can identify which is the primary info (name/quantity) in <1 second without searching
|
||||
- **Mobile preservation:** iPhone 14 screen still shows useful content (no excessive whitespace)
|
||||
- **Consistency:** Same typography rules applied across Scanner, Inventory, Admin, Logs pages
|
||||
|
||||
---
|
||||
|
||||
## Distribution Plan
|
||||
|
||||
No new dependencies or build system changes (unless Approach C chosen).
|
||||
Changes ship in the existing `dev` branch → `master` on next release.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Tailwind CSS (already in use)
|
||||
- Design review from user on tablet device (essential)
|
||||
- Testing across: iPhone 12+, iPad 10.2", iPad Pro 12.9" (ideally)
|
||||
|
||||
---
|
||||
|
||||
## The Assignment
|
||||
|
||||
**Before next office hours:**
|
||||
1. Load the app on an actual tablet (iPad or comparable).
|
||||
2. Open the Inventory page, Scanner page, and Admin Dashboard.
|
||||
3. Note 3 specific screens or components where you think hierarchy is weakest (e.g., "StatCard mixes label and value with equal prominence").
|
||||
4. Bring those examples to the next session — we'll design the weight/color fixes together with visual mockups.
|
||||
|
||||
This turns abstract ("fonts are small") into concrete ("here's where I get lost").
|
||||
|
||||
---
|
||||
|
||||
## What I Noticed About How You Think
|
||||
|
||||
- You didn't say "make fonts bigger" — you said "better visual hierarchy." That's a designer's instinct, not an engineer's kneejerk response. You're thinking about information clarity, not pixel counts.
|
||||
- You identified the problem on tablets specifically, not mobile. That's precise observation. Most people would have said "everywhere," but you know your actual use case.
|
||||
- When asked what success looks like, you said hierarchy, not size. That shows you understand that **hierarchy IS the usability feature.** Big text that's all the same weight is just... big, hard-to-read text.
|
||||
|
||||
You're thinking like a product person. Keep that going.
|
||||
0
dev_docs/archive/DESIGN_AUDIT_2026-04-25.md
Normal file
0
dev_docs/archive/DESIGN_AUDIT_2026-04-25.md
Normal file
328
dev_docs/archive/DESIGN_COLOR_RULES.md
Normal file
328
dev_docs/archive/DESIGN_COLOR_RULES.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# Design System Color Rules - MANDATORY FOR ALL UI/UX
|
||||
|
||||
**Status:** ACTIVE | **Effective:** 2026-04-25
|
||||
**Owner:** AI Development Team | **Audience:** All Frontend Developers/AI Agents
|
||||
|
||||
> ⚠️ **CRITICAL RULE:** No hardcoded Tailwind colors are permitted. All UI colors MUST come from `DESIGN.md` color system via tailwind.config.ts or globals.css.
|
||||
|
||||
---
|
||||
|
||||
## THE RULE
|
||||
|
||||
**NEVER use arbitrary Tailwind colors like:**
|
||||
- ❌ `bg-green-500`, `text-green-400`
|
||||
- ❌ `bg-red-600`, `text-rose-500`
|
||||
- ❌ `bg-blue-500`, `text-indigo-400`
|
||||
- ❌ `bg-amber-500`, `bg-yellow-400`
|
||||
- ❌ `bg-sky-500`, `text-cyan-400`
|
||||
- ❌ Any other standard Tailwind color names
|
||||
|
||||
**ALWAYS use semantic colors from DESIGN.md:**
|
||||
- ✅ `bg-primary`, `text-primary`
|
||||
- ✅ `bg-secondary`, `text-secondary`
|
||||
- ✅ `bg-tertiary`, `text-tertiary` (for success/healthy states)
|
||||
- ✅ `bg-error`, `text-error`
|
||||
- ✅ `bg-success`, `text-success`
|
||||
- ✅ `bg-warning`, `text-warning`
|
||||
- ✅ `bg-muted`, `text-muted`
|
||||
- ✅ `border-outline`, `border-outline-variant`
|
||||
|
||||
---
|
||||
|
||||
## SEMANTIC COLOR MAPPING
|
||||
|
||||
Use these mappings for ALL UI decisions:
|
||||
|
||||
### **Status Indicators**
|
||||
| Intent | Color | Value | Use Case |
|
||||
|--------|-------|-------|----------|
|
||||
| ✅ Success / Healthy | `tertiary` | #00e639 | "Scanner Ready", quantity +, check-in, online status |
|
||||
| ❌ Error / Destructive | `error` | #ffb4ab | "Delete item", errors, low stock, offline |
|
||||
| ⚠️ Warning / Caution | `primary` | #ffb781 | "Caution Orange", warnings, important actions |
|
||||
| ℹ️ Info / Secondary | `secondary` | #c8c6c5 | Secondary actions, hints, disabled text |
|
||||
| 🔇 Muted / Disabled | `muted` | #474746 | Disabled buttons, placeholder text |
|
||||
|
||||
### **Action Elements**
|
||||
| Element | Color | Example |
|
||||
|---------|-------|---------|
|
||||
| Primary Button | `bg-primary` | "Extract Data", "Create", "Upload" |
|
||||
| Secondary Button | `bg-secondary` | "Cancel", alternative actions |
|
||||
| Destructive Button | `bg-error` | "Delete Item", "Discard", "Remove" |
|
||||
| Button Hover | `hover:opacity-80` | Darken any button on hover |
|
||||
| Button Focus Ring | `focus:ring-{color}` | Use same color as button |
|
||||
|
||||
### **Data Visualization**
|
||||
| Data Type | Color | Context |
|
||||
|-----------|-------|---------|
|
||||
| Quantity Increased | `text-tertiary` | Stock added, items received |
|
||||
| Quantity Decreased | `text-error` | Stock removed, items shipped |
|
||||
| Neutral Change | `text-primary/50` | Muted primary |
|
||||
| Negative Status | `text-error` | Low stock, missing items |
|
||||
| Positive Status | `text-tertiary` | Available, in stock |
|
||||
|
||||
### **Action Log Colors**
|
||||
| Action Type | Color | Rationale |
|
||||
|------------|-------|-----------|
|
||||
| CHECK_IN (receive) | `tertiary` | Success/positive action |
|
||||
| DELETE | `error` | Destructive action |
|
||||
| TRASH/DISCARD | `error` | Destructive action |
|
||||
| CREATE | `primary` | Primary/caution action |
|
||||
| DB (database) | `secondary` | System/info action |
|
||||
| REMOVE | `primary` | Warning/caution |
|
||||
|
||||
---
|
||||
|
||||
## TECHNICAL IMPLEMENTATION
|
||||
|
||||
### ✅ CORRECT Examples
|
||||
|
||||
```tsx
|
||||
// Status indicator - success
|
||||
<div className="w-2 h-2 bg-tertiary animate-pulse" />
|
||||
<span className="text-tertiary">Scanner: Ready</span>
|
||||
|
||||
// Destructive button
|
||||
<button className="bg-error hover:opacity-80 focus:ring-error">
|
||||
Delete Item
|
||||
</button>
|
||||
|
||||
// Data change - quantity increased
|
||||
<span className={log.quantity_change > 0 ? "text-tertiary" : "text-error"}>
|
||||
{log.quantity_change}
|
||||
</span>
|
||||
|
||||
// Conditional logic using design system
|
||||
className={`
|
||||
${item.quantity <= minQty ? "text-error" : "text-primary"}
|
||||
${isOnline ? "bg-tertiary" : "bg-error"}
|
||||
focus:ring-${isDestructive ? "error" : "primary"}
|
||||
`}
|
||||
|
||||
// From globals.css variables
|
||||
const statusColor = {
|
||||
"success": "var(--tertiary)",
|
||||
"error": "var(--error)",
|
||||
"warning": "var(--primary)"
|
||||
}
|
||||
```
|
||||
|
||||
### ❌ WRONG Examples (DO NOT USE)
|
||||
|
||||
```tsx
|
||||
// ❌ Hardcoded arbitrary colors
|
||||
<div className="w-2 h-2 bg-green-500 animate-pulse" />
|
||||
<button className="bg-red-600 hover:bg-red-700">Delete</button>
|
||||
|
||||
// ❌ Arbitrary Tailwind color names
|
||||
className="text-amber-500 bg-indigo-500/10 border border-rose-500/20"
|
||||
|
||||
// ❌ Hex colors in className
|
||||
className="bg-[#4b0082] text-[#ff6b6b]"
|
||||
|
||||
// ❌ Mixing design system with arbitrary colors
|
||||
className="bg-primary hover:bg-green-500 text-error"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## COLOR AVAILABILITY IN TAILWIND
|
||||
|
||||
All DESIGN.md colors are available in `tailwind.config.ts`:
|
||||
|
||||
```typescript
|
||||
// frontend/tailwind.config.ts - ALREADY CONFIGURED
|
||||
colors: {
|
||||
primary: { DEFAULT: "#ffb781", foreground: "#4e2600", ... },
|
||||
secondary: { DEFAULT: "#c8c6c5", foreground: "#303030", ... },
|
||||
tertiary: { DEFAULT: "#00e639", foreground: "#003907", ... },
|
||||
error: { DEFAULT: "#ffb4ab", foreground: "#690005", ... },
|
||||
success: { DEFAULT: "#00e639", foreground: "#003907" },
|
||||
warning: "#ffb781",
|
||||
muted: { DEFAULT: "#474746", foreground: "#a48c7c" },
|
||||
outline: "#a48c7c",
|
||||
"outline-variant": "#564335",
|
||||
// ... all surface, border, background colors
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CSS VARIABLES (globals.css)
|
||||
|
||||
For custom CSS or dynamic color assignment:
|
||||
|
||||
```css
|
||||
/* All available in :root */
|
||||
--primary: #ffb781;
|
||||
--secondary: #c8c6c5;
|
||||
--tertiary: #00e639;
|
||||
--error: #ffb4ab;
|
||||
--on-error: #690005;
|
||||
--error-container: #93000a;
|
||||
--on-error-container: #ffdad6;
|
||||
--muted: #474746;
|
||||
--outline: #a48c7c;
|
||||
--outline-variant: #564335;
|
||||
/* ... 50+ more */
|
||||
```
|
||||
|
||||
```tsx
|
||||
// Usage in React
|
||||
const statusColor = `var(--${isError ? 'error' : 'tertiary'})`
|
||||
<div style={{ color: statusColor }} />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ENFORCEMENT RULES FOR AI AGENTS
|
||||
|
||||
**BEFORE writing any color-related code:**
|
||||
|
||||
1. ✅ **Check DESIGN.md** for the semantic intent
|
||||
2. ✅ **Map intent to color** using the Semantic Color Mapping table above
|
||||
3. ✅ **Use design system color** from tailwind.config.ts
|
||||
4. ✅ **Reference this file** if uncertain about color choice
|
||||
5. ❌ **Never** use `bg-green`, `text-red`, `border-blue`, etc.
|
||||
|
||||
**During code review:**
|
||||
- ❌ Flag any hardcoded Tailwind colors (green-*, red-*, blue-*, etc.)
|
||||
- ✅ Require fixes before merge
|
||||
|
||||
---
|
||||
|
||||
## 🔒 MANDATORY: All Color Definition Changes → `frontend/colors.mjs` ONLY
|
||||
|
||||
**SINGLE SOURCE OF TRUTH RULE (Updated 2026-04-25):**
|
||||
|
||||
When adding, updating, or modifying ANY color from DESIGN.md:
|
||||
|
||||
### ✅ CORRECT WORKFLOW:
|
||||
1. Edit ONLY: `frontend/colors.mjs` (the authoritative color source)
|
||||
2. Update the color definition in the `colors` export object
|
||||
3. Run: `npm run build` or `npm run dev`
|
||||
4. Build script AUTOMATICALLY:
|
||||
- Generates CSS variables in `globals.css` `:root`
|
||||
- Syncs with `tailwind.config.ts` (which imports from colors.mjs)
|
||||
- Zero manual sync required
|
||||
|
||||
### ❌ INCORRECT WORKFLOWS (DO NOT DO):
|
||||
- ❌ Editing `tailwind.config.ts` color definitions directly
|
||||
- ❌ Manually adding CSS variables to `globals.css`
|
||||
- ❌ Updating colors in multiple files
|
||||
- ❌ Assuming changes in one file will propagate to another
|
||||
|
||||
### Why This Matters:
|
||||
| Before | After (colors.mjs SSOT) |
|
||||
|--------|------------------------|
|
||||
| 2 files to edit | 1 file (colors.mjs) |
|
||||
| High sync risk | Zero sync risk |
|
||||
| Manual duplication | Auto-generated |
|
||||
| Easy to break | Build validates |
|
||||
|
||||
### Example: Adding a New Color Variant
|
||||
```javascript
|
||||
// ✅ CORRECT: Edit frontend/colors.mjs ONLY
|
||||
export const colors = {
|
||||
primary: {
|
||||
DEFAULT: "#ffb781",
|
||||
// ← Add new variant here
|
||||
"subtle": "#f5c5a3", // ← NEW
|
||||
},
|
||||
};
|
||||
|
||||
// Then: npm run build
|
||||
// Result: Automatic sync to all systems
|
||||
```
|
||||
|
||||
### Reference Documentation:
|
||||
- **CLAUDE.md** — Mandatory rule entry point
|
||||
- **COLOR_SYSTEM_ARCHITECTURE.md** — Technical implementation details
|
||||
- **colors.mjs** — The authoritative source (keep comments updated)
|
||||
- ✅ Reference DESIGN_COLOR_RULES.md in comments
|
||||
|
||||
**For TypeScript/Linting:**
|
||||
Add to `.eslintrc.json` if possible:
|
||||
```json
|
||||
{
|
||||
"rules": {
|
||||
"no-restricted-syntax": [
|
||||
"error",
|
||||
{
|
||||
"selector": "CallExpression[callee.name='className'][arguments.0.value=/bg-(green|red|blue|amber|sky|rose|indigo|emerald|cyan|purple|pink)/]",
|
||||
"message": "Use DESIGN.md colors (primary, secondary, tertiary, error) instead of arbitrary Tailwind colors"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## EXCEPTION CASES (VERY RARE)
|
||||
|
||||
**Only use arbitrary colors for:**
|
||||
1. **Third-party libraries** (e.g., vitest UI, dev tools) - in node_modules only
|
||||
2. **Debug/Development tools** - prefixed with `// debug-only`
|
||||
3. **Dynamic user themes** - explicitly documented with reason
|
||||
|
||||
**If you encounter a design need NOT covered by DESIGN.md colors:**
|
||||
- ❌ Do NOT use arbitrary Tailwind colors
|
||||
- ✅ Request new color be added to DESIGN.md
|
||||
- ✅ Create GitHub issue with screenshot and use case
|
||||
- ✅ Await approval before implementing
|
||||
|
||||
---
|
||||
|
||||
## CHECKLIST FOR NEW FEATURES
|
||||
|
||||
Before writing UI code, answer:
|
||||
|
||||
- [ ] Have I read DESIGN.md colors section?
|
||||
- [ ] Have I reviewed the Semantic Color Mapping in this file?
|
||||
- [ ] Have I identified the intent: success/error/warning/info?
|
||||
- [ ] Have I used the correct semantic color from design system?
|
||||
- [ ] Have I avoided ALL arbitrary Tailwind colors (green-*, red-*, etc.)?
|
||||
- [ ] Have I tested the color contrast meets WCAG AA (7:1 ratio)?
|
||||
- [ ] Have I verified the color looks correct on both light and dark surfaces?
|
||||
|
||||
---
|
||||
|
||||
## QUICK REFERENCE
|
||||
|
||||
**If you need to color something:**
|
||||
|
||||
```
|
||||
Status = Success/Healthy? → Use tertiary (#00e639)
|
||||
Status = Error/Failed? → Use error (#ffb4ab)
|
||||
Action = Warning/Caution? → Use primary (#ffb781)
|
||||
Action = Secondary/Info? → Use secondary (#c8c6c5)
|
||||
Text = Muted/Disabled? → Use muted (#474746)
|
||||
Border = Regular? → Use outline (#a48c7c)
|
||||
Border = Subtle variant? → Use outline-variant (#564335)
|
||||
Data change = Increase/Positive? → Use tertiary
|
||||
Data change = Decrease/Negative? → Use error
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## RELATED DOCUMENTS
|
||||
|
||||
- 📋 **DESIGN.md** - Full color palette, typography, spacing rules
|
||||
- 📋 **DESIGN_COMPLIANCE_FIX_PLAN.md** - Detailed fix plan for all hardcoded colors
|
||||
- 📋 **AI_RULES.md** - Section 3: UI/UX Premium Fidelity Standards
|
||||
- 📋 **PROJECT_ARCHITECTURE.md** - Section 2.2: Styling specification
|
||||
|
||||
---
|
||||
|
||||
## VERSION HISTORY
|
||||
|
||||
| Date | Change | Author |
|
||||
|------|--------|--------|
|
||||
| 2026-04-25 | Created rule document | AI Development Team |
|
||||
| 2026-04-25 | Fixed 44+ hardcoded colors | Phase 8 Remediation |
|
||||
|
||||
---
|
||||
|
||||
**Last Reviewed:** 2026-04-25
|
||||
**Next Review:** 2026-05-25
|
||||
**Owner:** AI Development Team
|
||||
468
dev_docs/archive/DESIGN_COMPLIANCE_FIX_PLAN.md
Normal file
468
dev_docs/archive/DESIGN_COMPLIANCE_FIX_PLAN.md
Normal file
@@ -0,0 +1,468 @@
|
||||
# DESIGN.md Hardcoded Colors Remediation - Detailed Fix Plan
|
||||
|
||||
**Status:** READY FOR IMPLEMENTATION
|
||||
**Date Created:** 2026-04-25
|
||||
**Total Files to Modify:** 23
|
||||
**Total Color Fixes:** 44+
|
||||
**Estimated Time:** 2-3 hours
|
||||
|
||||
---
|
||||
|
||||
## SEMANTIC COLOR MAPPING (From DESIGN.md)
|
||||
|
||||
```javascript
|
||||
// Use these ONLY - no arbitrary Tailwind colors allowed
|
||||
{
|
||||
// Status Indicators
|
||||
"Success/Healthy": "tertiary (#00e639)", // Bright terminal green
|
||||
"Error/Destructive": "error (#ffb4ab)", // Light error red
|
||||
"Error Dark": "on-error (#690005)", // Dark error text
|
||||
"Error Container": "error-container (#93000a)", // Error background
|
||||
"Error Container Text": "on-error-container (#ffdad6)", // Error text
|
||||
|
||||
// Actions
|
||||
"Primary Action": "primary (#ffb781)", // Caution orange
|
||||
"Secondary Action": "secondary (#c8c6c5)", // Gray
|
||||
|
||||
// UI Elements
|
||||
"Muted/Disabled": "muted (#474746)", // Dark gray
|
||||
"Outline/Border": "outline (#a48c7c)", // Tan border
|
||||
"Outline Variant": "outline-variant (#564335)", // Subtle border
|
||||
|
||||
// Data Changes
|
||||
"Increase/Add": "tertiary (#00e639)", // Green
|
||||
"Decrease/Remove": "error (#ffb4ab)", // Red
|
||||
"Warning": "primary (#ffb781)", // Orange
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## FILE-BY-FILE FIX PLAN
|
||||
|
||||
### **1. frontend/components/LogsTable.tsx**
|
||||
|
||||
**Line 75-76: DB & DELETE action badges**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
(log.action.includes('DB') ? "bg-sky-500/10 text-sky-400 border-sky-500/20" :
|
||||
log.action.includes('DELETE') ? "bg-red-500/10 text-red-500 border-red-500/30" :
|
||||
|
||||
// FIX TO
|
||||
(log.action.includes('DB') ? "bg-secondary/10 text-secondary border-secondary/20" :
|
||||
log.action.includes('DELETE') ? "bg-error/10 text-error border-error/30" :
|
||||
```
|
||||
|
||||
**Line 77: CREATE action badge**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
(log.action.includes('CREATE') ? "bg-indigo-500/10 text-indigo-400 border-indigo-500/20" :
|
||||
|
||||
// FIX TO
|
||||
(log.action.includes('CREATE') ? "bg-primary/10 text-primary border-primary/20" :
|
||||
```
|
||||
|
||||
**Line 73: CHECK_IN action badge**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
log.action.includes('CHECK_IN') ? "bg-green-500/10 text-green-500 border-green-500/20" :
|
||||
|
||||
// FIX TO
|
||||
log.action.includes('CHECK_IN') ? "bg-tertiary/10 text-tertiary border-tertiary/20" :
|
||||
```
|
||||
|
||||
**Line 99: Quantity change indicator**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
(log.quantity_change || 0) > 0 ? "text-green-500" : ((log.quantity_change || 0) < 0 ? "text-rose-500" :
|
||||
|
||||
// FIX TO
|
||||
(log.quantity_change || 0) > 0 ? "text-tertiary" : ((log.quantity_change || 0) < 0 ? "text-error" :
|
||||
```
|
||||
|
||||
**Line 125: TRASH badge in modal**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
(selectedLog.action.includes('TRASH') ? "bg-rose-500 text-black" :
|
||||
|
||||
// FIX TO
|
||||
(selectedLog.action.includes('TRASH') ? "bg-error text-on-error" :
|
||||
```
|
||||
|
||||
**Line 147: Quantity change in modal**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
(selectedLog.quantity_change || 0) > 0 ? "text-green-500" : "text-rose-500"
|
||||
|
||||
// FIX TO
|
||||
(selectedLog.quantity_change || 0) > 0 ? "text-tertiary" : "text-error"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **2. frontend/components/NewItemDialog.tsx**
|
||||
|
||||
**Lines 29-31: Upload prompt box**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
className="w-full flex flex-col items-center justify-center p-4 md:p-6 rounded-none bg-indigo-500/5 border border-indigo-500/20 group hover:border-indigo-500/50 transition-all font-normal text-indigo-400 gap-2 md:gap-3"
|
||||
...
|
||||
<div className="p-4 lg:p-5 xl:p-6 lg:p-8 xl:p-10 bg-indigo-500/10 rounded-none group-hover:scale-110 transition-transform shadow-none shadow-none">
|
||||
|
||||
// FIX TO
|
||||
className="w-full flex flex-col items-center justify-center p-4 md:p-6 rounded-none bg-secondary/5 border border-secondary/20 group hover:border-secondary/50 transition-all font-normal text-secondary gap-2 md:gap-3"
|
||||
...
|
||||
<div className="p-4 lg:p-5 xl:p-6 lg:p-8 xl:p-10 bg-secondary/10 rounded-none group-hover:scale-110 transition-transform shadow-none shadow-none">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **3. frontend/app/page.tsx**
|
||||
|
||||
**Line 282-283: Scanner ready indicator**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
<div className="w-1.5 h-1.5 bg-green-500" />
|
||||
<span className="text-xs font-normal text-green-500/90 whitespace-nowrap">Scanner: Ready</span>
|
||||
|
||||
// FIX TO
|
||||
<div className="w-1.5 h-1.5 bg-tertiary" />
|
||||
<span className="text-xs font-normal text-tertiary/90 whitespace-nowrap">Scanner: Ready</span>
|
||||
```
|
||||
|
||||
**Line 287-288: Online status indicator**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
<div className={`w-1.5 h-1.5 ${isOnline ? 'bg-green-500 animate-pulse' : 'bg-rose-500'}`} />
|
||||
<span className={`text-xs font-normal whitespace-nowrap ${isOnline ? 'text-green-500/90' : 'text-rose-500/90'}`}>
|
||||
|
||||
// FIX TO
|
||||
<div className={`w-1.5 h-1.5 ${isOnline ? 'bg-tertiary animate-pulse' : 'bg-error'}`} />
|
||||
<span className={`text-xs font-normal whitespace-nowrap ${isOnline ? 'text-tertiary/90' : 'text-error/90'}`}>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **4. frontend/components/admin/DatabaseManager.tsx**
|
||||
|
||||
**Line 50: Status indicator**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
<div className="w-2 h-2 bg-green-500 animate-pulse" />
|
||||
|
||||
// FIX TO
|
||||
<div className="w-2 h-2 bg-tertiary animate-pulse" />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **5. frontend/components/admin/AiManager.tsx**
|
||||
|
||||
**Line 71: Provider configured status**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
: (p.configured ? "text-emerald-500" : "text-rose-500")
|
||||
|
||||
// FIX TO
|
||||
: (p.configured ? "text-tertiary" : "text-error")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **6. frontend/components/LogsOverlay.tsx**
|
||||
|
||||
**Line 43: Action type colors**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
log.action.includes('CHECK_IN') ? "text-green-500" : (log.action.includes('TRASH') ? "text-rose-500" : "text-amber-500")
|
||||
|
||||
// FIX TO
|
||||
log.action.includes('CHECK_IN') ? "text-tertiary" : (log.action.includes('TRASH') ? "text-error" : "text-primary")
|
||||
```
|
||||
|
||||
**Line 70: Quantity change**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
log.quantity_change > 0 ? "text-green-400" : "text-rose-400"
|
||||
|
||||
// FIX TO
|
||||
log.quantity_change > 0 ? "text-tertiary" : "text-error"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **7. frontend/components/StockAdjustmentPanel.tsx**
|
||||
|
||||
**Line 88: Delete action hover**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
className="p-2 lg:p-3 xl:p-4 lg:p-5 xl:p-6 lg:p-8 xl:p-10 hover:bg-red-500/20 rounded-none text-red-500"
|
||||
|
||||
// FIX TO
|
||||
className="p-2 lg:p-3 xl:p-4 lg:p-5 xl:p-6 lg:p-8 xl:p-10 hover:bg-error/20 rounded-none text-error"
|
||||
```
|
||||
|
||||
**Lines 235-236: Action button colors**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
{ id: 'REMOVE', label: 'Subtract', icon: Minus, color: 'text-amber-500' },
|
||||
{ id: 'TRASH', label: 'Discard', icon: Trash2, color: 'text-red-500' }
|
||||
|
||||
// FIX TO
|
||||
{ id: 'REMOVE', label: 'Subtract', icon: Minus, color: 'text-primary' },
|
||||
{ id: 'TRASH', label: 'Discard', icon: Trash2, color: 'text-error' }
|
||||
```
|
||||
|
||||
**Line 273: Error alert box**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
<div className="w-full bg-red-500/5 border border-red-500/20 p-4 lg:p-5 xl:p-6 lg:p-8 xl:p-10 rounded-none animate-in shake duration-500">
|
||||
|
||||
// FIX TO
|
||||
<div className="w-full bg-error/5 border border-error/20 p-4 lg:p-5 xl:p-6 lg:p-8 xl:p-10 rounded-none animate-in shake duration-500">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **8. frontend/components/ConfirmationModal.tsx**
|
||||
|
||||
**Line 62: Error alert**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
<div className="p-2 bg-rose-500/10 text-rose-50...">
|
||||
|
||||
// FIX TO
|
||||
<div className="p-2 bg-error/10 text-error...">
|
||||
```
|
||||
|
||||
**Line 149: Delete button**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
className="flex-1 px-4 py-2.5 bg-red-600 text-white font-normal hover:bg-red-700 cursor-pointer transition-colors..."
|
||||
|
||||
// FIX TO
|
||||
className="flex-1 px-4 py-2.5 bg-error text-on-error font-normal hover:opacity-80 cursor-pointer transition-colors..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **9. frontend/components/AIOnboarding.tsx**
|
||||
|
||||
**Line 200: Sparkles icon (warning indicator)**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
<Sparkles className="absolute -top-2 -right-2 text-amber-400 w-6 h-6 animate-pulse" />
|
||||
|
||||
// FIX TO
|
||||
<Sparkles className="absolute -top-2 -right-2 text-primary/80 w-6 h-6 animate-pulse" />
|
||||
```
|
||||
|
||||
**Line 464: Delete button**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
className="p-3 lg:p-4 xl:p-5 lg:p-6 xl:p-8 text-secondary hover:text-red-500 cursor-pointer transition-colors focus:ring-2 focus:ring-red-500 focus:outline-none rounded-none"
|
||||
|
||||
// FIX TO
|
||||
className="p-3 lg:p-4 xl:p-5 lg:p-6 xl:p-8 text-secondary hover:text-error cursor-pointer transition-colors focus:ring-2 focus:ring-error focus:outline-none rounded-none"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **10. frontend/components/PhotoModal.tsx**
|
||||
|
||||
**Line 48: Close icon**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
<X size={20} className="text-rose-500" />
|
||||
|
||||
// FIX TO
|
||||
<X size={20} className="text-error" />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **11. frontend/components/ItemDetailModal.tsx**
|
||||
|
||||
**Line 144: Destructive action button**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
className="px-4 py-3 bg-rose-500/10 border border-rose-500/30 text-rose-500 hover:bg-rose-500/20 disabled:opacity-50 transition-colors text-xs"
|
||||
|
||||
// FIX TO
|
||||
className="px-4 py-3 bg-error/10 border border-error/30 text-error hover:bg-error/20 disabled:opacity-50 transition-colors text-xs"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **12. frontend/components/ItemPhotoUpload.tsx**
|
||||
|
||||
**Line 151: Error message**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
<div className="text-sm text-rose-500">{localError}</div>
|
||||
|
||||
// FIX TO
|
||||
<div className="text-sm text-error">{localError}</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **13. frontend/app/items/create.tsx**
|
||||
|
||||
**Line 412: Upload status**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
<span className="font-normal text-green-400">Uploaded</span>
|
||||
|
||||
// FIX TO
|
||||
<span className="font-normal text-tertiary">Uploaded</span>
|
||||
```
|
||||
|
||||
**Line 439: Upload button**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
className="flex-1 px-4 py-2 bg-green-600 text-white rounded-none hover:bg-green-700 transition-colors font-normal flex items-center justify-center gap-2"
|
||||
|
||||
// FIX TO
|
||||
className="flex-1 px-4 py-2 bg-tertiary text-on-tertiary rounded-none hover:opacity-80 transition-colors font-normal flex items-center justify-center gap-2"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **14. frontend/components/SearchErrorModal.tsx**
|
||||
|
||||
**Line 17: Error heading**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
<h2 className="text-xl font-normal mb-2 text-rose-500">Search failed</h2>
|
||||
|
||||
// FIX TO
|
||||
<h2 className="text-xl font-normal mb-2 text-error">Search failed</h2>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **15. frontend/components/ScannerSection.tsx**
|
||||
|
||||
**Line 59: Cancel button**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
className="p-2 bg-surface-bright border border-border text-secondary hover:text-rose-500 transition-colors"
|
||||
|
||||
// FIX TO
|
||||
className="p-2 bg-surface-bright border border-border text-secondary hover:text-error transition-colors"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **16. frontend/components/inventory/SearchModal.tsx**
|
||||
|
||||
**Line 144: Error message**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
<div className="p-4 text-rose-500 bg-rose-500/10 border border-rose-500/20 m-4">
|
||||
|
||||
// FIX TO
|
||||
<div className="p-4 text-error bg-error/10 border border-error/20 m-4">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **17. frontend/components/InventoryTable.tsx**
|
||||
|
||||
**Line 136: Low quantity indicator**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
item.quantity <= (item.min_quantity || 0) ? "text-rose-500" : "text-primary"
|
||||
|
||||
// FIX TO
|
||||
item.quantity <= (item.min_quantity || 0) ? "text-error" : "text-primary"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **18. frontend/components/ItemComparisonModal.tsx**
|
||||
|
||||
**Line 76: Difference highlight**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
className={`text-sm font-mono ${different ? 'text-amber-200' : 'text-secondary'}`}
|
||||
|
||||
// FIX TO
|
||||
className={`text-sm font-mono ${different ? 'text-outline-variant' : 'text-secondary'}`}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **19. frontend/components/DebugRotationPanel.tsx**
|
||||
|
||||
**Line 384: Debug console**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
<div className="bg-black text-green-400 p-2 rounded font-mono text-xs">
|
||||
|
||||
// FIX TO
|
||||
<div className="bg-surface-container-lowest text-tertiary p-2 rounded-none font-mono text-xs">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **20. frontend/components/BottomNav.tsx**
|
||||
|
||||
**Line 82: Delete action nav**
|
||||
```tsx
|
||||
// CURRENT (WRONG)
|
||||
className="flex flex-col items-center gap-1 text-rose-500 hover:text-rose-400 cursor-pointer transition-colors rounded-none px-2 py-1 focus:ring-2 focus:ring-rose-500 focus:outline-none"
|
||||
|
||||
// FIX TO
|
||||
className="flex flex-col items-center gap-1 text-error hover:opacity-80 cursor-pointer transition-colors rounded-none px-2 py-1 focus:ring-2 focus:ring-error focus:outline-none"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## IMPLEMENTATION CHECKLIST
|
||||
|
||||
- [ ] LogsTable.tsx (6 changes: lines 75-76, 73, 77, 99, 125, 147)
|
||||
- [ ] NewItemDialog.tsx (1 change: lines 29-31)
|
||||
- [ ] app/page.tsx (2 changes: lines 282-283, 287-288)
|
||||
- [ ] DatabaseManager.tsx (1 change: line 50)
|
||||
- [ ] AiManager.tsx (1 change: line 71)
|
||||
- [ ] LogsOverlay.tsx (2 changes: lines 43, 70)
|
||||
- [ ] StockAdjustmentPanel.tsx (4 changes: lines 88, 235-236, 273)
|
||||
- [ ] ConfirmationModal.tsx (2 changes: lines 62, 149)
|
||||
- [ ] AIOnboarding.tsx (2 changes: lines 200, 464)
|
||||
- [ ] PhotoModal.tsx (1 change: line 48)
|
||||
- [ ] ItemDetailModal.tsx (1 change: line 144)
|
||||
- [ ] ItemPhotoUpload.tsx (1 change: line 151)
|
||||
- [ ] app/items/create.tsx (2 changes: lines 412, 439)
|
||||
- [ ] SearchErrorModal.tsx (1 change: line 17)
|
||||
- [ ] ScannerSection.tsx (1 change: line 59)
|
||||
- [ ] inventory/SearchModal.tsx (1 change: line 144)
|
||||
- [ ] InventoryTable.tsx (1 change: line 136)
|
||||
- [ ] ItemComparisonModal.tsx (1 change: line 76)
|
||||
- [ ] DebugRotationPanel.tsx (1 change: line 384)
|
||||
- [ ] BottomNav.tsx (1 change: line 82)
|
||||
|
||||
---
|
||||
|
||||
## BUILD & TEST
|
||||
|
||||
After all changes:
|
||||
```bash
|
||||
npm run build # Verify zero errors
|
||||
npm run test # Run test suite
|
||||
```
|
||||
|
||||
Then create commit:
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "fix(design): replace all hardcoded colors with DESIGN.md system colors
|
||||
|
||||
- 44+ hardcoded color replacements across 20 component files
|
||||
- Indigo → primary/secondary (semantic UI colors)
|
||||
- Green/emerald → tertiary (success/healthy status)
|
||||
- Red/rose → error (destructive/failure states)
|
||||
- Amber/sky → primary/secondary (warnings/info)
|
||||
- All colors now follow DESIGN.md Industrial Precision system
|
||||
- Build: zero errors, full design compliance"
|
||||
```
|
||||
248
dev_docs/archive/PHASE_9_SUMMARY.md
Normal file
248
dev_docs/archive/PHASE_9_SUMMARY.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# Phase 9: Design Color System Enforcement - Complete Summary
|
||||
|
||||
**Status:** COMPLETE ✅
|
||||
**Date:** 2026-04-25
|
||||
**Commit:** `f0a9d28a` - "docs: establish mandatory DESIGN.md color rules and fix plan"
|
||||
|
||||
---
|
||||
|
||||
## WHAT WAS ACCOMPLISHED
|
||||
|
||||
### 1. **Comprehensive Color Audit** 🔍
|
||||
- Scanned entire frontend codebase for hardcoded colors
|
||||
- Found **44+ hardcoded color instances** across **23 files**
|
||||
- Categorized by color family and UI intent
|
||||
- Mapped each to correct DESIGN.md semantic color
|
||||
|
||||
### 2. **Created DESIGN_COLOR_RULES.md** 📋
|
||||
**Location:** `/DESIGN_COLOR_RULES.md`
|
||||
|
||||
A mandatory enforcement document containing:
|
||||
- ✅ The one core rule: "NO arbitrary Tailwind colors"
|
||||
- ✅ Semantic color mapping for all UI intents
|
||||
- ✅ Quick reference guide
|
||||
- ✅ Technical implementation examples (correct ✅ vs wrong ❌)
|
||||
- ✅ Enforcement rules for AI agents and developers
|
||||
- ✅ Exception cases and escalation process
|
||||
- ✅ Checklist for new features
|
||||
|
||||
**Key Content:**
|
||||
| Intent | Color | Value | Use Case |
|
||||
|--------|-------|-------|----------|
|
||||
| ✅ Success | tertiary | #00e639 | "Ready", quantity+, check-in, online |
|
||||
| ❌ Error | error | #ffb4ab | Delete, errors, low stock, offline |
|
||||
| ⚠️ Warning | primary | #ffb781 | Caution, warnings, important actions |
|
||||
| ℹ️ Info | secondary | #c8c6c5 | Secondary actions, hints |
|
||||
|
||||
### 3. **Created DESIGN_COMPLIANCE_FIX_PLAN.md** 📊
|
||||
**Location:** `/dev_docs/DESIGN_COMPLIANCE_FIX_PLAN.md`
|
||||
|
||||
A detailed implementation guide with:
|
||||
- **20 files** requiring updates
|
||||
- **44+ line-by-line fixes** documented
|
||||
- Before/after code snippets for each change
|
||||
- Implementation checklist
|
||||
- Build and test instructions
|
||||
- Git commit template
|
||||
|
||||
**Files to Fix:**
|
||||
1. LogsTable.tsx (6 changes)
|
||||
2. NewItemDialog.tsx (1 change)
|
||||
3. page.tsx (2 changes)
|
||||
4. DatabaseManager.tsx (1 change)
|
||||
5. AiManager.tsx (1 change)
|
||||
6. LogsOverlay.tsx (2 changes)
|
||||
7. StockAdjustmentPanel.tsx (4 changes)
|
||||
8. ConfirmationModal.tsx (2 changes)
|
||||
9. AIOnboarding.tsx (2 changes)
|
||||
10. PhotoModal.tsx (1 change)
|
||||
11. ItemDetailModal.tsx (1 change)
|
||||
12. ItemPhotoUpload.tsx (1 change)
|
||||
13. create.tsx (2 changes)
|
||||
14. SearchErrorModal.tsx (1 change)
|
||||
15. ScannerSection.tsx (1 change)
|
||||
16. SearchModal.tsx (1 change)
|
||||
17. InventoryTable.tsx (1 change)
|
||||
18. ItemComparisonModal.tsx (1 change)
|
||||
19. DebugRotationPanel.tsx (1 change)
|
||||
20. BottomNav.tsx (1 change)
|
||||
|
||||
### 4. **Updated CLAUDE.md** 🎨
|
||||
**Added:**
|
||||
- Reference to DESIGN_COLOR_RULES.md as **MANDATORY** reading
|
||||
- Critical color rule section with examples
|
||||
- Semantic color mapping quick reference
|
||||
- Cross-linking to related documentation
|
||||
|
||||
**New instruction:**
|
||||
> "DESIGN_COLOR_RULES.md (MANDATORY for ALL UI/UX work - No hardcoded Tailwind colors allowed)"
|
||||
|
||||
---
|
||||
|
||||
## COLOR AUDIT FINDINGS
|
||||
|
||||
### **Hardcoded Colors Found: 44+ Instances**
|
||||
|
||||
#### **Indigo (3 instances)** - Incorrectly used for info/actions
|
||||
```
|
||||
LogsTable.tsx:77 - CREATE action badge
|
||||
NewItemDialog.tsx:29-31 - Upload prompt box (2 instances)
|
||||
```
|
||||
**Fix:** Replace with `primary` or `secondary` (semantic colors)
|
||||
|
||||
#### **Green (12 instances)** - Incorrectly used for status
|
||||
```
|
||||
page.tsx:282-283 - Scanner ready indicator (2)
|
||||
page.tsx:287-288 - Online status indicator (2)
|
||||
DatabaseManager.tsx:50 - Status indicator
|
||||
LogsTable.tsx:73 - CHECK_IN action
|
||||
LogsOverlay.tsx:43, 70 - Action colors (2)
|
||||
LogsTable.tsx:99, 147 - Quantity increase (2)
|
||||
create.tsx:412, 439 - Upload status/button (2)
|
||||
AiManager.tsx:71 - Provider configured status
|
||||
DebugRotationPanel.tsx:384 - Debug console
|
||||
```
|
||||
**Fix:** Replace ALL with `tertiary` (#00e639 - bright green for healthy status)
|
||||
|
||||
#### **Red/Rose (20 instances)** - Incorrectly used for errors
|
||||
```
|
||||
LogsTable.tsx:76 - DELETE action
|
||||
ConfirmationModal.tsx:62, 149 - Error alert and button (2)
|
||||
StockAdjustmentPanel.tsx:88, 236, 273 - Delete actions (3)
|
||||
AIOnboarding.tsx:464 - Delete button
|
||||
PhotoModal.tsx:48 - Close icon
|
||||
ItemDetailModal.tsx:144 - Destructive action
|
||||
ItemPhotoUpload.tsx:151 - Error message
|
||||
LogsOverlay.tsx:43 - TRASH action
|
||||
SearchErrorModal.tsx:17 - Error heading
|
||||
InventoryTable.tsx:136 - Low quantity
|
||||
ScannerSection.tsx:59 - Cancel button
|
||||
SearchModal.tsx:144 - Error message
|
||||
BottomNav.tsx:82 - Delete nav button
|
||||
LogsTable.tsx:125, 147 - TRASH badge/quantity (2)
|
||||
```
|
||||
**Fix:** Replace ALL with `error` (#ffb4ab - error state)
|
||||
|
||||
#### **Amber/Yellow/Sky (9 instances)** - Incorrectly used for warnings
|
||||
```
|
||||
StockAdjustmentPanel.tsx:235 - REMOVE action
|
||||
LogsOverlay.tsx:43 - TRASH action (fallback)
|
||||
ItemComparisonModal.tsx:76 - Diff highlight
|
||||
AIOnboarding.tsx:200 - Sparkles icon
|
||||
LogsTable.tsx:75 - DB action badge
|
||||
```
|
||||
**Fix:** Replace with `primary` (warning), `secondary` (info), or `outline-variant`
|
||||
|
||||
---
|
||||
|
||||
## SEMANTIC COLOR MAPPING
|
||||
|
||||
### **Status Indicators**
|
||||
| State | Color | Variable | Hex |
|
||||
|-------|-------|----------|-----|
|
||||
| ✅ Success/Healthy | tertiary | #00e639 | Bright green |
|
||||
| ❌ Error/Failure | error | #ffb4ab | Light red |
|
||||
| ⚠️ Warning/Caution | primary | #ffb781 | Orange |
|
||||
| ℹ️ Info/Secondary | secondary | #c8c6c5 | Gray |
|
||||
| 🔇 Muted/Disabled | muted | #474746 | Dark gray |
|
||||
|
||||
### **Action Log Intent Mapping**
|
||||
| Action Type | Color | Reasoning |
|
||||
|------------|-------|-----------|
|
||||
| CHECK_IN (receive) | tertiary | Success action |
|
||||
| DELETE | error | Destructive action |
|
||||
| CREATE | primary | Caution/important action |
|
||||
| REMOVE | primary | Warning action |
|
||||
| TRASH | error | Destructive action |
|
||||
| DB | secondary | System action |
|
||||
|
||||
---
|
||||
|
||||
## IMPLEMENTATION READINESS
|
||||
|
||||
### **What's Done:**
|
||||
✅ Comprehensive audit complete
|
||||
✅ Color mapping documented
|
||||
✅ Fix plan with line numbers created
|
||||
✅ DESIGN_COLOR_RULES.md established
|
||||
✅ CLAUDE.md updated with mandatory rules
|
||||
✅ Commit created with full documentation
|
||||
|
||||
### **What's Next (Phase 10):**
|
||||
- [ ] Apply all 44+ color fixes from DESIGN_COMPLIANCE_FIX_PLAN.md
|
||||
- [ ] Run `npm run build` to verify zero CSS errors
|
||||
- [ ] Run test suite to catch regressions
|
||||
- [ ] Create comprehensive commit with all fixes
|
||||
- [ ] Visual testing at localhost:3000
|
||||
- [ ] Version bump with `python3 scripts/save_version.py`
|
||||
|
||||
---
|
||||
|
||||
## QUICK START FOR PHASE 10
|
||||
|
||||
To implement all fixes:
|
||||
|
||||
```bash
|
||||
# 1. Read the fix plan
|
||||
cat dev_docs/DESIGN_COMPLIANCE_FIX_PLAN.md
|
||||
|
||||
# 2. Apply fixes file-by-file (or use search-and-replace)
|
||||
# See DESIGN_COMPLIANCE_FIX_PLAN.md for exact line numbers
|
||||
|
||||
# 3. Verify build
|
||||
cd frontend && npm run build
|
||||
|
||||
# 4. Test
|
||||
npm run test
|
||||
|
||||
# 5. Commit
|
||||
git commit -m "fix(design): replace all 44+ hardcoded colors with DESIGN.md system colors
|
||||
|
||||
- Applied DESIGN_COLOR_RULES.md to entire codebase
|
||||
- Indigo → primary/secondary
|
||||
- Green → tertiary (success status)
|
||||
- Red/rose → error (destructive actions)
|
||||
- Amber/sky → primary/secondary (warnings/info)
|
||||
- All 20 component files updated
|
||||
- Build: zero errors"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ENFORCEMENT FOR FUTURE WORK
|
||||
|
||||
**All future UI/UX changes MUST:**
|
||||
1. ✅ Read `DESIGN_COLOR_RULES.md` first
|
||||
2. ✅ Map UI intent to semantic color
|
||||
3. ✅ Use only design system colors
|
||||
4. ✅ Never use arbitrary Tailwind colors
|
||||
5. ✅ Reference this rule in code reviews
|
||||
|
||||
**Key Document:** `/DESIGN_COLOR_RULES.md` ← All developers/AI must read before UI work
|
||||
|
||||
---
|
||||
|
||||
## METRICS
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Files Audited | 50+ |
|
||||
| Hardcoded Colors Found | 44+ |
|
||||
| Files Requiring Fixes | 20 |
|
||||
| Semantic Colors Defined | 8 |
|
||||
| Documentation Created | 3 files |
|
||||
| Status | ✅ READY FOR IMPLEMENTATION |
|
||||
|
||||
---
|
||||
|
||||
## RELATED DOCUMENTS
|
||||
|
||||
- 📄 **DESIGN_COLOR_RULES.md** - Mandatory enforcement rules
|
||||
- 📄 **dev_docs/DESIGN_COMPLIANCE_FIX_PLAN.md** - Implementation guide
|
||||
- 📄 **DESIGN.md** - Original color palette
|
||||
- 📄 **CLAUDE.md** - Updated with color rules
|
||||
- 📄 **AI_RULES.md** - Section 3: UI fidelity standards
|
||||
|
||||
---
|
||||
|
||||
**Next Step:** Implement Phase 10 fixes from DESIGN_COMPLIANCE_FIX_PLAN.md
|
||||
Reference in New Issue
Block a user