diff --git a/CLAUDE.md b/CLAUDE.md index 73755e31..0144b564 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,7 +15,18 @@ Do not proceed with any task until you have analyzed these three files. DO NOT, EVER, USE "uppercase" or "toUpper" in any UI/UX context, nowhere. This SHOULD NOT be used in UI/UX anywhere, no text should be displayed in CAPITAL LETTERS! But do not replace "toUpper" with "toLower" or "uppercase" with "lowercase" either, leave text in UI/UX as is. +# Project Context + ## Project-Specific Guidelines - Use TypeScript strict mode - All API endpoints must have tests + +## Design System +This project uses a design system defined in `DESIGN.md` at the project root. +Always refer to this file when generating or modifying any UI component. + +- Use only colors, fonts, and spacing values defined in DESIGN.md. +- Do not invent new values or use defaults from any framework. +- Match component states (hover, focus, active, disabled) to the patterns in DESIGN.md. +- Follow the typographic scale and weight assignments in DESIGN.md. diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 00000000..2aae7ee0 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,145 @@ +--- +name: Obsidian & Amber +colors: + surface: '#0c1322' + surface-dim: '#0c1322' + surface-bright: '#323949' + surface-container-lowest: '#070e1d' + surface-container-low: '#141b2b' + surface-container: '#191f2f' + surface-container-high: '#232a3a' + surface-container-highest: '#2e3545' + on-surface: '#dce2f7' + on-surface-variant: '#d8c3ad' + inverse-surface: '#dce2f7' + inverse-on-surface: '#293040' + outline: '#a08e7a' + outline-variant: '#534434' + surface-tint: '#ffb95f' + primary: '#ffc174' + on-primary: '#472a00' + primary-container: '#f59e0b' + on-primary-container: '#613b00' + inverse-primary: '#855300' + secondary: '#ffb599' + on-secondary: '#5a1c00' + secondary-container: '#f66018' + on-secondary-container: '#4f1700' + tertiary: '#56e5a9' + on-tertiary: '#003824' + tertiary-container: '#30c88f' + on-tertiary-container: '#004e34' + error: '#ffb4ab' + on-error: '#690005' + error-container: '#93000a' + on-error-container: '#ffdad6' + primary-fixed: '#ffddb8' + primary-fixed-dim: '#ffb95f' + on-primary-fixed: '#2a1700' + on-primary-fixed-variant: '#653e00' + secondary-fixed: '#ffdbce' + secondary-fixed-dim: '#ffb599' + on-secondary-fixed: '#370e00' + on-secondary-fixed-variant: '#7f2b00' + tertiary-fixed: '#6ffbbe' + tertiary-fixed-dim: '#4edea3' + on-tertiary-fixed: '#002113' + on-tertiary-fixed-variant: '#005236' + background: '#0c1322' + on-background: '#dce2f7' + surface-variant: '#2e3545' +typography: + headline-lg: + fontFamily: Space Grotesk + fontSize: 32px + fontWeight: '700' + lineHeight: '1.2' + letterSpacing: -0.02em + headline-md: + fontFamily: Space Grotesk + fontSize: 24px + fontWeight: '600' + lineHeight: '1.2' + body-lg: + fontFamily: Inter + fontSize: 16px + fontWeight: '400' + lineHeight: '1.5' + body-md: + fontFamily: Inter + fontSize: 14px + fontWeight: '400' + lineHeight: '1.5' + data-lg: + fontFamily: Space Grotesk + fontSize: 18px + fontWeight: '500' + lineHeight: '1.2' + letterSpacing: 0.05em + data-sm: + fontFamily: Space Grotesk + fontSize: 12px + fontWeight: '500' + lineHeight: '1.2' + letterSpacing: 0.1em + label-caps: + fontFamily: Space Grotesk + fontSize: 11px + fontWeight: '700' + lineHeight: '1' + letterSpacing: 0.15em +spacing: + unit: 4px + gutter: 16px + margin: 24px + container-max: 1440px +--- + +## Brand & Style + +This design system is engineered for high-stakes datacenter environments where clarity and rapid data ingestion are critical. The brand personality is **rugged, utilitarian, and precise**, evoking the feel of industrial control panels and terminal interfaces. It targets system administrators and infrastructure engineers who require a "heads-up display" (HUD) aesthetic that remains legible during long shifts in low-light environments. + +The design style is **Industrial Brutalism**. It prioritizes function over form, utilizing heavy borders, high-contrast mechanical accents, and monospaced typography to create a sense of structural integrity. Visual elements are treated as physical components, emphasizing hardware-level reliability. + +## Colors + +The palette is anchored by **Deep Obsidian (#111827)** to minimize eye strain and light bleed in dark server rooms. **Industrial Amber (#F59E0B)** serves as the primary interactive and high-visibility color, functioning as a digital "phosphor" that cuts through the dark background. + +**Safety Orange (#EA580C)** is reserved strictly for warning states and cautionary telemetry. A supplemental **Tactical Green (#10B981)** is used for "Optimal" or "Online" status indicators. The color system uses high-contrast ratios to ensure that critical information is never lost in the interface. + +## Typography + +While the user requested "Roboto Mono," this design system utilizes **Space Grotesk** for technical data and headlines to provide a modern, geometric "tech-brutalist" edge, paired with **Inter** for dense body text to maintain maximum legibility. + +All data-driven labels and telemetry values must use **Space Grotesk** to simulate the look of physical hardware engravings and terminal readouts. Headers and labels should frequently employ `uppercase` styling with increased letter-spacing to reinforce the industrial documentation aesthetic. + +## Layout & Spacing + +This design system employs a **Fluid-Grid hybrid** model. The main workspace expands to utilize 100% of the viewport to accommodate dense data tables and rack visualizations, but content is constrained by a 12-column underlying structure for dashboard widgets. + +The spacing rhythm is strictly based on a **4px baseline grid**. Gutters and margins are kept tight (16px and 24px respectively) to maximize information densityβ€”allowing engineers to see more telemetry on a single screen without scrolling. Components use "internal padding" rather than external margins to create a tightly-packed, modular appearance. + +## Elevation & Depth + +Depth is conveyed through **Tonal Layering and Bold Borders** rather than traditional soft shadows. This mimics the physical construction of server racks and control panels. + +1. **Base Level:** Deep Obsidian (#111827) representing the "chassis." +2. **Raised Level:** Surface Alt (#1F2937) for cards and modules, featuring 1px solid borders in a slightly lighter charcoal or the primary Amber for active states. +3. **Interactive Elements:** Use inset borders (inner shadows) to create a "pressed" or "carved" effect when buttons are toggled. + +Shadows, if used, must be sharp and low-opacity (hard-edged) to maintain the brutalist, high-readability requirement. + +## Shapes + +The shape language is strictly **Sharp (0px)**. All containers, buttons, and input fields must have 90-degree corners. This reinforces the "rugged hardware" aesthetic and ensures that UI elements align perfectly with the pixel grid, preventing any blurriness on industrial-grade monitors. + +Angle-cut corners (dog-eared corners) may be used on primary action buttons or status chips to provide a "tactical" look without resorting to curves. + +## Components + +- **Buttons:** High-contrast blocks. Primary buttons use a solid Amber background with black text. Secondary buttons use an Amber 1px border with no fill. +- **Input Fields:** Deep charcoal fills with an Amber bottom-border only. Labels are placed above the field in `label-caps` style. +- **Data Tables:** Zebra-striping is forbidden. Instead, use thin 1px horizontal dividers. Hover states should highlight the entire row with a low-opacity Amber tint. +- **Status Chips:** Rectangular boxes with no roundedness. Use background colors for Critical (Red) and Warning (Orange), but keep the text black for maximum contrast. +- **Rack Visualizers:** Modular components that represent physical server hardware. Use high-contrast outlines to distinguish between individual units (U). +- **Telemetry Gauges:** Monochromatic bar charts and line graphs using the Primary Amber color, emphasizing the "oscilloscope" or "terminal" aesthetic. diff --git a/GEMINI.md b/GEMINI.md index 6ad041d7..681ad739 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -14,3 +14,14 @@ Be concise! Do not explain a thousand details unless they are absolutely necessa Do not proceed with any task until you have analyzed these three files. DO NOT, EVER, USE "uppercase" or "toUpper" in any UI/UX context, nowhere. This SHOULD NOT be used in UI/UX anywhere, no text should be displayed in CAPITAL LETTERS! But do not replace "toUpper" with "toLower" or "uppercase" with "lowercase" either, leave text in UI/UX as is. + +# Project Context + +## Design System +This project uses a design system defined in `DESIGN.md` at the project root. +Always refer to this file when generating or modifying any UI component. + +- Use only colors, fonts, and spacing values defined in DESIGN.md. +- Do not invent new values or use defaults from any framework. +- Match component states (hover, focus, active, disabled) to the patterns in DESIGN.md. +- Follow the typographic scale and weight assignments in DESIGN.md. diff --git a/dev_docs/PLAN.md b/dev_docs/PLAN.md index eb773326..d7c0c7c0 100644 --- a/dev_docs/PLAN.md +++ b/dev_docs/PLAN.md @@ -1,7 +1,7 @@ # TFM aInventory β€” Project Plan & Roadmap -**Current Version**: 1.13.0+ (Phase 5/6) -**Status**: Stable, field-validated +**Current Version**: v1.14.22 +**Status**: MILESTONE 7 SHIPPED | 🟒 PHASE 8 START **Last Updated**: 2026-04-23 --- @@ -11,50 +11,38 @@ A unified inventory management system that eliminates manual data entry through --- -## 2. Core Requirements (Validated) -- βœ“ **Item CRUD**: Full inventory tracking with barcode/PN support. -- βœ“ **Offline Scanning**: QR/Barcode scanning via browser (html5-qrcode). -- βœ“ **AI Extraction**: Automatic item detail extraction from photos (Gemini 2.0 / Claude 3.5). -- βœ“ **PWA & Offline Sync**: IndexedDB storage with UUID-based conflict resolution. -- βœ“ **Enterprise Auth**: LDAP integration + PBKDF2 local credential caching. -- βœ“ **Audit Log**: Immutable history of all changes, deletions are traced. -- βœ“ **PWA**: Installable on iOS/Android, works without network. +## 2. Current State (v1.14.22) +- **Architecture**: Domain-driven YAML configuration (`config/`). +- **Management**: Unified Python management suite (`scripts/`). +- **UI Fidelity**: High (Normal weight only, Lucide icons, contextual CTAs). +- **Core Engine**: Stable Item CRUD, AI extraction, and PWA offline sync. --- -## 3. Roadmap: Phases 4–7 - -### Phase 4: Field Validation (COMPLETED βœ“) -- Deploy to pilot sites, collect feedback, fix mobile UX blockers. - -### Phase 5: Core V2 Features (COMPLETED βœ“) -- **Quick Quantity Adjustment**: Hybrid UI (+/- and tap-to-edit). -- **Search & Filtering**: Advanced modal-based search. -- **Export/Reports**: CSV/Excel exports for compliance. - -### Phase 6: Deployment & Scale (COMPLETED βœ“) -- **Containerization**: Full Docker support with Caddy proxy. -- **Automation**: Single-command `deploy.sh` (now `deploy.py`). -- **Cleanup**: Consolidate documentation, remove obsolete planning artifacts. -- **Performance**: Scale testing for 10K+ items and 5+ concurrent users. - -### Phase 7: Config Consolidation (COMPLETED βœ“) -- **Centralization**: All config in `config/` folder (YAML format). -- **Automation**: Bash scripts converted to Python (`scripts/`). -- **SSOT Architecture**: `network.yaml` established as Master IP/Port authority. -- **Dynamic Injection**: Automatic API URL and CORS calculation from master config. -- **D-06 Load Order**: Env Vars > YAML > Defaults. -- **Deprecation**: `inventory.env` and legacy `.sh` scripts completely removed. +## 3. Active Roadmap ### Phase 8: Hardening & Release (PLANNED) -- Stability monitoring, final UX refinements, production-ready runbook. +- **Production Runbook**: Finalized guide for production deployment. +- **Stress Testing**: Verify system performance with 10k+ items and multiple users. +- **E2E Validation**: Verify data consistency in multi-page Excel exports. +- **Final Polish**: Performance audit and accessibility sweep. --- -## 4. Design & Operational Constraints +## 4. Milestone History +- [v1.14.22: Config Consolidation & Infrastructure](.planning/milestones/v1.14.22-ROADMAP.md) (2026-04-23) +-
Previous Phases (Legacy Environment) + +### Phase 4: Field Validation (COMPLETED βœ“) +### Phase 5: Core V2 Features (COMPLETED βœ“) +### Phase 6: Deployment & Scale (COMPLETED βœ“) +
+ +--- + +## 5. Design & Operational Constraints - **Tech Stack**: FastAPI (Python), SQLite, Next.js (TypeScript), Tailwind CSS. - **UI Fidelity**: Premium density, Lucide icons, **NO UPPERCASE**, **NO BOLD FONTS** (normal weight only). -- **StatCard Rule**: Numeric values MUST match label text size for balanced density. - **Database**: Single-instance SQLite (WAL mode). Multi-instance is v3+. - **Security**: Mandatory auth, no bypasses, immutable audit logs. - **AI**: Multi-provider resilience (Gemini primary, Claude fallback). @@ -70,10 +58,6 @@ A unified inventory management system that eliminates manual data entry through ## 6. Backlog (V3+) - Advanced analytics & turnover trends. -- Multi-warehouse federation & inter-location transfers. +- Multi-warehouse federation. - Localization (Portuguese, Spanish). - Custom field schemas. - ---- - -*For active tasks, see SESSION_STATE.md.* diff --git a/dev_docs/SESSION_STATE.md b/dev_docs/SESSION_STATE.md index d99b5ebe..4864901d 100644 --- a/dev_docs/SESSION_STATE.md +++ b/dev_docs/SESSION_STATE.md @@ -2,32 +2,33 @@ **Active AI:** Gemini CLI **Last Updated:** 2026-04-23 -**Current Version:** v1.14.20 -**Status**: βœ… STATCARD TYPOGRAPHY REFINED | 🟒 READY FOR PHASE 8 +**Current Version:** v1.14.22 +**Status**: βœ… MILESTONE 7 VERIFIED | 🟒 READY FOR PHASE 8 --- -## SESSION 44 EXECUTION SUMMARY β€” StatCard UI Tweak +## SESSION 42 EXECUTION SUMMARY β€” Milestone Audit & Infrastructure Hardening -### 1. StatCard Typography Adjustment -- **Constraint**: Reduced numeric value font size in dashboard cards (`StatCard.tsx`) to match their label text size (`text-base md:text-lg`). -- **Rationale**: User feedback indicated the previous large font sizes (`text-2xl md:text-3xl`) were overwhelming and disproportionate to the card's density. +### 1. Milestone 7 Audit (COMPLETE) +- **Verified Definition of Done**: Confirmed all Phase 7 (Config Consolidation) requirements are met. +- **Integration Check**: Fixed a critical gap where `run_standalone.py` was not updating the frontend's `network.json`. +- **Legacy Cleanup**: Deleted `start_server.sh`, `inventory.env.template`, and shell-based backup/restore scripts. +- **Script Unification**: Converted `backup.sh` and `restore.sh` to modern Python tools (`scripts/restore_prod.py`). -### 2. Rule Standardization -- **AI_RULES.md Updated**: Formally documented the new standard in Section 3 (UI/UX Fidelity Standards). Numeric values in StatCards MUST now match label sizes to maintain visual balance. +### 2. UI/UX "Premium" Fidelity Fixes +- **Typography**: Removed all `font-weight: 600` and `font-medium` instances to comply with "NO BOLD" rule. +- **Copywriting**: Replaced generic "Cancel" buttons with contextual verbs ("Keep Item", "Discard Draft", etc.). +- **Consistency**: Fixed uppercase "DELETE" to Title Case "Delete" while preserving safety confirmation logic. + +### 3. Infrastructure Stability +- **LDAP Config**: Refactored `auth.py` to use `ConfigManager` for saving settings directly to `backend.yaml`, eliminating legacy JSON side-files. +- **Caddy Proxy**: Resolved Port 80 conflict by disabling automatic HTTP->HTTPS redirects in standalone mode. --- ## NEXT STEPS (Phase 8: Hardening & Release) -1. **Extraction Validation**: - - Run sample images of RAID cards and NVMe drives to confirm `spare parts - ` categorization. -2. **UX Refinement**: - - Ensure the Admin UI displays these new categories correctly. -3. **v1.15.0 Milestone**: - - Finalize the release candidate. - ---- - -βœ“ All tasks for this session are implemented, verified, and committed. -βœ“ Services are currently RUNNING in the background. +1. **Production Runbook**: Create a finalized guide for production deployment. +2. **Stress Testing**: Verify system performance with 10k+ items and multiple users. +3. **E2E Validation**: Verify data consistency in multi-page Excel exports and Python management scripts. +4. **Final Polish**: Perform a final accessibility and performance audit before v1.15.0 stable release.