data-entry-app/DESIGN.MD

# Design Review

## Purpose

This document reviews the current UI design in the app as it exists today and captures the visual direction we should keep building toward.

The current design is strongest on:

- The global application shell
- The dashboard page
- The products page

The current design is weakest on:

- Raw materials
- Mixes
- Scenarios

Those pages still use older styling patterns and do not yet fully match the newer dashboard direction.

## Current Direction

The product is moving toward a modern professional operations dashboard with these core traits:

- Full-screen app layout
- Clean white panels on a pale neutral background
- Arial/Inter/IBM Plex Sans style typography
- Soft green as the primary brand/action color
- Rounded cards with subtle borders and restrained shadows
- Dense but readable information layout
- Dashboard-first composition with summary cards, charts, tables, and status pills


## What Is Working

### 1. App Shell

The shared shell in `frontend/src/routes/+layout.svelte` is the clearest part of the design system.

What works:

- Left navigation is simple and recognizably enterprise/SaaS
- Header layout is clean and easy to scan
- Sidebar, topbar, and content regions are clearly separated
- Border, radius, and spacing values are fairly consistent
- The palette is restrained enough for a data-heavy product

### 2. Typography

The shift toward IBM Plex Sans is a good move.

What works:

- Narrower letterforms help the UI feel more operational and less marketing-oriented
- Headings and labels now feel more compact
- The typography better suits dense tables and metrics

What still needs attention:

- Some older route pages still visually read as if they belong to a previous design phase
- Font sizing and spacing are not yet fully normalized across all pages

### 3. Dashboard Layout

The homepage has the most complete design language in the app right now.

What works:

- Good hierarchy from greeting to metrics to analysis to tasks
- Cards feel purposeful rather than decorative
- The dashboard uses a strong top-level grid
- Status chips and compact controls support the business-app direction
- The table redesign is much more modern than the earlier plain table styling

### 4. Products Table

The products page is now much closer to a polished admin table.

What works:

- Separated rounded rows feel modern and easier to scan
- First-column hierarchy is clearer
- Status and sale-type pills add useful structure
- Supporting metadata is visually subordinate to primary values

## Main Design Problems

### 1. The Design System Is Only Partially Applied

This is the biggest issue in the app right now.

The newer design language appears in:

- `frontend/src/routes/+layout.svelte`
- `frontend/src/routes/+page.svelte`
- `frontend/src/routes/products/+page.svelte`

But older page styles remain in:

- `frontend/src/routes/raw-materials/+page.svelte`
- `frontend/src/routes/mixes/+page.svelte`
- `frontend/src/routes/scenarios/+page.svelte`

This creates a split experience where the app shell feels professional, but some inner pages still feel like prototype screens.

### 2. Raw Materials Page Is Visually Out of Sync

The raw materials page still uses an older look and older tokens.

Current problems:

- Beige/tinted card treatment does not match the newer white panel system
- Buttons and inputs do not match the dashboard and products page controls
- Layout density feels heavier and more form-builder-like than operations-dashboard-like
- Card interiors are functional but not refined

This page matters a lot because it is one of the product's core workflows. It should be one of the strongest designed pages in the app, not one of the weakest.

### 3. Mixes And Scenarios Still Look Like MVP Scaffolding

These pages currently read as placeholders.

Current problems:

- Styling is minimal and visually detached from the newer shell
- Cards use older colors and border treatments
- Information hierarchy is too shallow
- There is little sense of table/list/system structure

### 4. Design Tokens Are Not Yet Truly Centralized

There is a good base token set in the layout, but page-level styles still define their own patterns too freely.

Symptoms:

- Different panel tones across pages
- Different table treatments across routes
- Different button personalities
- Different spacing rhythms

The app is close to needing a lightweight shared component/token layer instead of route-by-route styling.

### 5. Font Loading Strategy Should Be Revisited Later

IBM Plex Sans is the right direction, but it is currently loaded from a CSS `@import` in the route layout.

That is acceptable for now in a prototype, but longer term we should move to a more deliberate font-loading approach for performance and reliability.

## Recommended Design Principles

These should guide future UI work:

### 1. Keep The Shell Quiet

The shell should stay minimal and stable:

- White or near-white surfaces
- Very subtle borders
- Low-contrast background
- Minimal icon noise

The content should carry the visual interest, not the shell.

### 2. Prefer Information Density Over Decoration

The best parts of the current design are useful because they improve scanability rather than adding flourish.

We should keep prioritizing:

- Strong alignment
- Label/value clarity
- Good card grouping
- Useful color coding
- Structured tables

### 3. Use One Table Language Everywhere

The products table is a stronger starting point than the original table styles.

We should standardize around:

- Rounded row groups
- Soft separated rows
- Compact uppercase headers
- Badge-style statuses
- Strong first-column identity
- Muted secondary metadata

### 4. Treat Forms Like High-Value Workflow Surfaces

Raw material editing is a core task. Forms should feel as polished as dashboards.

That means:

- Cleaner sectioning
- Better spacing between fields
- More modern inputs
- Clearer primary/secondary actions
- Better use of inline metadata and supporting summaries

## Route-By-Route Assessment

### Dashboard

Status: Strong

Notes:

- Good overall hierarchy
- Good panel composition
- Good table direction
- Strongest reference page for the rest of the app

### Products

Status: Good

Notes:

- Table treatment is modern and clear
- Metrics row works well
- Could become the standard for other data-heavy pages

### Raw Materials

Status: Needs redesign pass

Notes:

- Strong functionality
- Weak visual consistency relative to the new shell
- Needs updated cards, forms, and downstream panels

### Mixes

Status: Needs redesign pass

Notes:

- Structurally too simple
- Should evolve into a more analytical operations page
- Needs stronger use of summaries, tables, and status markers

### Scenarios

Status: Needs redesign pass

Notes:

- Currently feels like raw prototype output
- JSON presentation is technically useful but visually unfinished
- Needs a proper scenario list and comparison layout

## Suggested Next Steps

### Immediate

1. Bring `raw-materials/+page.svelte` into the same visual language as the dashboard and products page.
2. Redesign the mixes page using the newer card/table tokens.
3. Redesign the scenarios page so it no longer looks like a raw debug view.

### Short Term

1. Standardize shared panel, button, input, and table styles.
2. Create one reusable status pill pattern.
3. Normalize spacing, heading sizes, and section headers across all routes.

### Medium Term

1. Move from route-local styling toward shared UI primitives.
2. Create a small written design system for color, spacing, radius, shadows, typography, and tables.
3. Revisit font loading so IBM Plex Sans is handled more deliberately.

## Final Assessment

The design is moving in the right direction.

The current shell, dashboard, and products page establish a much more credible business application style than the earlier prototype visuals. The main issue is not the direction itself, but inconsistency. Right now the app looks like two design generations living side by side.

If we bring the raw materials, mixes, and scenarios pages into the same system, the product will feel much more cohesive and substantially more production-ready.