Initial commit

design/soundbox_ops/DESIGN.md

@@ -0,0 +1,201 @@
+---
+name: Soundbox Ops
+colors:
+  surface: '#faf8ff'
+  surface-dim: '#d9d9e5'
+  surface-bright: '#faf8ff'
+  surface-container-lowest: '#ffffff'
+  surface-container-low: '#f3f3fe'
+  surface-container: '#ededf9'
+  surface-container-high: '#e7e7f3'
+  surface-container-highest: '#e1e2ed'
+  on-surface: '#191b23'
+  on-surface-variant: '#434655'
+  inverse-surface: '#2e3039'
+  inverse-on-surface: '#f0f0fb'
+  outline: '#737686'
+  outline-variant: '#c3c6d7'
+  surface-tint: '#0053db'
+  primary: '#004ac6'
+  on-primary: '#ffffff'
+  primary-container: '#2563eb'
+  on-primary-container: '#eeefff'
+  inverse-primary: '#b4c5ff'
+  secondary: '#505f76'
+  on-secondary: '#ffffff'
+  secondary-container: '#d0e1fb'
+  on-secondary-container: '#54647a'
+  tertiary: '#943700'
+  on-tertiary: '#ffffff'
+  tertiary-container: '#bc4800'
+  on-tertiary-container: '#ffede6'
+  error: '#ba1a1a'
+  on-error: '#ffffff'
+  error-container: '#ffdad6'
+  on-error-container: '#93000a'
+  primary-fixed: '#dbe1ff'
+  primary-fixed-dim: '#b4c5ff'
+  on-primary-fixed: '#00174b'
+  on-primary-fixed-variant: '#003ea8'
+  secondary-fixed: '#d3e4fe'
+  secondary-fixed-dim: '#b7c8e1'
+  on-secondary-fixed: '#0b1c30'
+  on-secondary-fixed-variant: '#38485d'
+  tertiary-fixed: '#ffdbcd'
+  tertiary-fixed-dim: '#ffb596'
+  on-tertiary-fixed: '#360f00'
+  on-tertiary-fixed-variant: '#7d2d00'
+  background: '#F8FAFC'
+  on-background: '#191b23'
+  surface-variant: '#e1e2ed'
+  success: '#16A34A'
+  warning: '#F59E0B'
+  danger: '#DC2626'
+  info: '#0EA5E9'
+  slate-900: '#0F172A'
+  slate-700: '#334155'
+  slate-500: '#64748B'
+  slate-200: '#E2E8F0'
+  slate-100: '#F1F5F9'
+typography:
+  display-lg:
+    fontFamily: Plus Jakarta Sans
+    fontSize: 36px
+    fontWeight: '600'
+    lineHeight: 44px
+    letterSpacing: -0.02em
+  headline-lg:
+    fontFamily: Plus Jakarta Sans
+    fontSize: 28px
+    fontWeight: '600'
+    lineHeight: 36px
+  headline-md:
+    fontFamily: Plus Jakarta Sans
+    fontSize: 20px
+    fontWeight: '600'
+    lineHeight: 28px
+  body-lg:
+    fontFamily: Inter
+    fontSize: 16px
+    fontWeight: '400'
+    lineHeight: 24px
+  body-md:
+    fontFamily: Inter
+    fontSize: 14px
+    fontWeight: '400'
+    lineHeight: 20px
+  label-md:
+    fontFamily: Inter
+    fontSize: 12px
+    fontWeight: '500'
+    lineHeight: 16px
+    letterSpacing: 0.01em
+  metric-lg:
+    fontFamily: Inter
+    fontSize: 32px
+    fontWeight: '600'
+    lineHeight: 40px
+  metric-sm:
+    fontFamily: Inter
+    fontSize: 14px
+    fontWeight: '600'
+    lineHeight: 20px
+rounded:
+  sm: 0.125rem
+  DEFAULT: 0.25rem
+  md: 0.375rem
+  lg: 0.5rem
+  xl: 0.75rem
+  full: 9999px
+spacing:
+  topbar-height: 72px
+  page-padding: 24px
+  card-padding: 20px
+  row-height: 52px
+  gutter: 24px
+---
+
+## Brand & Style
+
+The design system is engineered for the high-stakes environment of fintech operations. The brand personality is **Precise, Reliable, and Proactive**, focusing on the seamless bridge between digital ledgers and physical IoT soundboxes. 
+
+The chosen style is **Corporate / Modern** with a heavy emphasis on **Data-Centricity**. This is achieved through a structured information hierarchy that prioritizes rapid scanning of transaction states and device health. The interface utilizes high-density layouts, subtle tonal layering to separate operational controls from data displays, and a functional aesthetic that avoids unnecessary decoration in favor of utility and speed.
+
+**Key visual principles:**
+- **Clarity over Flourish:** Every pixel must serve a functional purpose in the monitoring workflow.
+- **Immediate Feedback:** Use of distinct semantic colors to highlight system anomalies or successful settlements.
+- **Operational Efficiency:** Minimizing clicks through the use of drawers and context-aware action bars.
+
+## Colors
+
+The palette is anchored by **Primary Blue (#2563EB)** to evoke trust and established financial authority. The neutral foundation is built exclusively on the **Slate** scale, providing a cool, professional backdrop that allows semantic alerts to stand out.
+
+**Usage Guidance:**
+- **Primary:** Actionable elements, active navigation states, and primary buttons.
+- **Semantic Colors:** Reserved strictly for status indicators (Success for 'Settled', Warning for 'Degraded', Danger for 'Offline/Failed').
+- **Neutrals:** `Slate-900` for primary headings, `Slate-700` for body text, and `Slate-100/200` for borders and subtle backgrounds.
+- **Background:** The `F8FAFC` base provides a low-strain environment for long-duration operational shifts.
+
+## Typography
+
+This design system employs a dual-font strategy. **Plus Jakarta Sans** is used for headings to provide a modern, clean fintech feel, while **Inter** is used for all body and functional text for maximum legibility at small sizes.
+
+**Tabular Numbers:**
+Crucial for a platform dealing with currency (IDR) and device IDs, all metric-related typography must have `font-variant-numeric: tabular-nums` enabled. This ensures that columns of numbers align perfectly in data tables and KPI cards, facilitating easier comparison.
+
+**Scale and Hierarchy:**
+- Headlines use Semibold (`600`) to anchor page sections.
+- Body text remains Regular (`400`) for extended reading in audit logs.
+- Labels use Medium (`500`) with slight letter spacing for specialized metadata.
+
+## Layout & Spacing
+
+The system follows a **12-column fluid grid** for the main content area, allowing the platform to scale from large monitoring displays to standard laptops.
+
+**Key Layout Rules:**
+- **Fixed Infrastructure:** The topbar is locked at `72px` and the sidebar remains visible for Admin/Merchant portals to provide persistent global context.
+- **Density:** We utilize a "Comfortable-Compact" rhythm. Page margins are set to `24px`, but internal card components and data tables use tighter spacing to maximize information density without sacrificing touch/click targets.
+- **Vertical Rhythm:** A base `4px` / `8px` grid governs all spacing. Data tables utilize a consistent `52px` row height to accommodate status chips and action buttons comfortably.
+
+## Elevation & Depth
+
+To maintain a "fast and clean" feel, the system avoids heavy drop shadows. Instead, it utilizes **Tonal Layers** and **Low-Contrast Outlines**.
+
+- **Level 0 (Surface):** `#F8FAFC` (Background) - The lowest layer.
+- **Level 1 (Cards/Container):** `#FFFFFF` with a `1px` border of `Slate-200`. This is the primary surface for all data widgets.
+- **Level 2 (Interactive):** Elements that require focus (like drawers or modals) use a very soft, diffused shadow (`0 10px 15px -3px rgb(0 0 0 / 0.1)`) to lift them above the data grid.
+- **Depth via Border:** Sticky headers in tables use a `1px` bottom border in `Slate-200` rather than a shadow to indicate they are "above" the scrolling content while maintaining a flat, professional profile.
+
+## Shapes
+
+The design system adopts a **Soft** shape language. A `0.25rem` (4px) base radius is used for most UI elements, which maintains a professional, structured look while appearing modern.
+
+- **Components:** Buttons, Input fields, and KPI cards use the base `rounded` (4px) or `rounded-lg` (8px).
+- **Status Chips:** Use `rounded-full` (pill-shaped) to distinguish them from interactive buttons.
+- **Icons:** Should follow the same geometric principles—no sharp 90-degree corners, but not overly rounded or "bubbly."
+
+## Components
+
+### KPI Cards
+Standardized containers for top-level metrics. They include a `label-md` for title, a `metric-lg` for the value, and a bottom section for `metric-sm` trend indicators (e.g., +12% vs last month).
+
+### Data Tables
+- **Sticky Header:** Background remains white with a `Slate-200` bottom border during scroll.
+- **Numeric Alignment:** Amounts and percentages are right-aligned using tabular numbers.
+- **Row Hover:** Use `Slate-50` background on hover to facilitate line scanning.
+
+### Status Chips
+Pill-shaped badges with low-opacity backgrounds and high-contrast text:
+- **Active/Online/Settled:** Green (Success)
+- **Pending/Retrying:** Orange (Warning)
+- **Failed/Offline:** Red (Danger)
+- **Default/Inactive:** Slate-500 (Neutral)
+
+### Vertical Timelines
+Used for transaction history and device lifecycle. Dots represent states; solid lines represent completed paths, and dashed lines represent pending/future steps. 
+
+### Audit Blocks (Raw Payload Viewer)
+Monospaced font (`Courier Prime` or `JetBrains Mono` as an alternative), contained in a `Slate-900` box with a 'Copy' action always present in the top-right corner.
+
+### Detail Drawers
+Standardized side-panel that slides from the right. It allows for "quick inspection" of a merchant or device without losing the context of the main list.