Order-Loop/DESIGN.md

# Design System — Order Loop

Order Loop is a Duolingo-inspired order management tool for teams that need to move quickly through order history, open editable order details, and create new orders with customer-driven line items and automatic pricing.

This document is the canonical description of the product design system for the current app. It covers visual direction, layout rules, components, states, responsive behavior, data model expectations, and interaction rules.

---

## 1) Product definition

### Product purpose
- Browse order history quickly.
- Open any order and edit it when the order is not closed.
- Create new orders from scratch.
- Add customers to an order and assign each item to one of those customers.
- Calculate item totals automatically from pricing rules.
- Save and persist orders locally.

### Primary workflows
1. View dashboard statistics and order history.
2. Search or filter orders by status.
3. Open an order detail view.
4. Edit customers, items, notes, and status for open orders.
5. Create a new order, add customers, add item rows, and save.
6. Return to history and see the updated order immediately.

### Core business rules
- Every order has a status: `pending`, `purchased`, `delivered`, or `closed`.
- Orders with status `closed` are read-only.
- Open orders can be edited and saved.
- New orders start as `pending`.
- Item tax ratio defaults to `16%`.
- Quantity defaults to `1`.
- Customer chips are shown as a list once added.
- Save should persist the order locally and update timestamps.

---

## 2) Brand and visual direction

### Brand personality
The interface should feel:
- bright
- friendly
- tactile
- confident
- fast to scan
- lightly gamified, but still useful and serious

The Duolingo influence is expressed through bold green accents, chunky shadows, rounded geometry, and clear hierarchy. It should never look like a generic SaaS dashboard or a muted enterprise admin panel.

### Visual tone
- White snow canvas
- Light neutral surfaces
- Strong, readable type
- Thick borders
- One primary brand accent used decisively
- Status colors that are easy to decode at a glance

### Emotional goals
- The dashboard should feel easy to start using.
- The detail page should make editing feel safe and obvious.
- The new-order form should reduce friction and make the pricing rules transparent.
- Closed orders should clearly communicate that they cannot be edited.

---

## 3) Color system

The palette is token-driven. Colors should only be used through tokens or derived `color-mix()` values.

### Core tokens
- `--bg`: page background, snow white.
- `--surface`: card and panel background.
- `--fg`: primary text.
- `--muted`: secondary text, captions, labels.
- `--meta`: placeholders and tertiary copy.
- `--border`: standard border color.
- `--accent`: primary brand green.
- `--accent-on`: text color on accent fills.
- `--accent-hover`: hover state for accent fills.
- `--accent-active`: pressed shadow tone for accent surfaces.
- `--success`: status success / delivered / correct state.
- `--warn`: warning / attention / streak-like emphasis.
- `--danger`: destructive or error states.

### Color usage rules
- The background must stay white, not beige, cream, or peach.
- Use the accent for primary CTA and a few key system moments.
- Do not flood the page with accent color.
- Use status colors only where they add meaning.
- Keep borders visible and consistent; do not replace them with soft shadows.

### Recommended semantic use
- Green: primary actions, positive confirmation, current selection.
- Orange: emphasis on totals or special summary moments when needed.
- Red: danger, deletion, invalid states.
- Blue: focus rings, form utility, interaction feedback.
- Yellow: warnings and highlighted status moments.

---

## 4) Typography

### Type families
- Display / headings / chrome: `"Feather Bold", "DIN Round Pro", "Helvetica Neue", sans-serif`
- Body: `"Mona Sans", "Helvetica Neue", system-ui, sans-serif`
- Mono: `"JetBrains Mono", ui-monospace, Menlo, Monaco, Consolas, monospace`

### Type rules
- Headings always use the display family.
- Body copy should use the body family.
- Numerical values, dates, counts, and IDs should use mono styling where helpful.
- Display size should feel bold and friendly, not delicate.
- Letterforms should remain rounded and approachable.

### Hierarchy
- H1: large hero title for dashboard, detail, and new-order screens.
- H2: section titles for dashboard modules and editors.
- H3: card titles, row labels, and panel titles.
- Lead text: short supportive summary under the main heading.
- Meta text: small, mono-styled utility labels and timestamps.

### Copy style
- Short, direct, and task-oriented.
- Avoid marketing fluff.
- Use concrete labels like “Open details”, “Add customer”, “Save order”.
- Use honest placeholders if a value is not yet known.

---

## 5) Layout system

### Page structure
Every page should follow this pattern:
1. Sticky top navigation.
2. Hero or summary block.
3. Main task area.
4. Supporting panel or sidebar.
5. Optional footnote / footer.

### Container rules
- Maximum content width: 1080px.
- Desktop gutter: 24px.
- Tablet gutter: 20px.
- Phone gutter: 16px.

### Spacing scale
Use the established 4px system:
- 4, 8, 12, 16, 20, 24, 32, 48, 64, 80

### Section rhythm
- Desktop vertical rhythm should feel generous.
- Tablet rhythm should tighten slightly.
- Mobile should keep a continuous flow without empty gaps.

### Layout primitives
- `stack`: vertical spacing between siblings.
- `row`: aligned horizontal layout with gap.
- `row-between`: space-between alignment for section headers.
- `grid-2`, `grid-3`, `grid-4`: responsive content grids.
- `grid-2-1` and `grid-1-2`: asymmetric editorial/tool splits.
- `hero-split`: primary content + secondary summary panel.
- `editor-grid`: content workspace + inspector/sidebar.

### Layout behavior by screen

#### Dashboard
- Use a split hero with summary cards.
- Show filters above the table.
- Keep the table legible and compact.
- Use a right-side preview or summary panel on larger screens.

#### Order detail
- Show the order identity, status, and save action at the top.
- Place customer list and item editor in the main column.
- Place notes and key state summary in the sidebar.
- Show a clear closed-order lock banner when read-only.

#### New order
- Show the order title, status selector, and save button first.
- Place the customer list above item rows.
- Keep the pricing summary visible and easy to scan.
- Use the sidebar for order memo and total recaps.

---

## 6) Components

### Top navigation
Purpose:
- Identify the product.
- Provide navigation to dashboard, detail, and new order.
- Keep the create action visible.

Behavior:
- Sticky at the top.
- Light blur / frosted treatment.
- Bottom border defines separation.

### Brand mark
- Green rounded square.
- White or contrasting lettermark.
- Uses inset bottom shadow for tactile feel.

### Buttons

#### Primary button
- Green fill.
- White text.
- 4px bottom shadow in a deeper green tone.
- Used for primary actions like Create order, Add customer, Save order.

#### Secondary button
- Neutral fill.
- Same border and shadow language.
- Used for navigation and secondary actions.

#### Disabled button
- Reduced opacity.
- No shadow emphasis.
- Used when order is closed or action is unavailable.

#### Interaction states
- Hover: slightly brighter or more defined.
- Active: translate downward 4px and flatten shadow.
- Focus: blue focus ring and visible outline treatment.

### Cards and panels
Purpose:
- Group summary data.
- Contain dashboards, previews, and editor blocks.

Rules:
- 2px border.
- 16px radius for primary cards.
- 20px radius for larger containers if needed.
- 4px offset shadow on raised surfaces.

### Statistic cards
- Large numeric value.
- Small explanatory label.
- Used for counts, totals, and status summaries.

### Table / history rows
- Compact row layout.
- Strong column labels.
- Right-aligned numeric columns.
- Hover highlight to support scanability.

### Status badges
Statuses must be clearly color-coded and readable:
- Pending
- Purchased
- Delivered
- Closed

Badges should communicate state quickly without requiring the user to read all row text.

### Chips / customer tags
Purpose:
- Show customers added to an order.
- Support removal unless read-only.

Rules:
- Rounded pill shape.
- 2px border.
- Small remove control when editable.
- Scroll-free wrapping list.

### Form fields
Use for:
- customer name entry
- item name
- init price
- my price
- tax ratio
- quantity
- notes
- status selection

Rules:
- 12px radius.
- 2px border.
- Clear label above each field.
- Focus ring must be visible.
- Inputs must be large enough for touch and keyboard use.

### Item row editor
Each item row must contain:
- customer selector
- item name
- init price
- my price
- tax ratio
- quantity
- net price (auto-generated)
- final price (auto-generated)
- remove action

Behavior:
- Net and final values update live.
- Auto-calculated values are read-only.
- Item rows should visually read as one grouped unit.

### Summary panel
Should include:
- total order value
- your net total
- item count
- order status
- any lock messaging for closed orders

### Lock banner
Only appears when status is closed.
It must clearly state that the order is read-only and that editing is disabled.

---

## 7) Data model

### Order shape
Each order should include:
- `id`
- `title`
- `status`
- `createdAt`
- `updatedAt`
- `customers[]`
- `notes`
- `items[]`

### Item shape
Each item should include:
- `id`
- `customer`
- `name`
- `initPrice`
- `myPrice`
- `taxRatio`
- `quantity`

### Computed values
Derived on render or save:
- `netPrice` = `(initPrice + initPrice * taxRatio) * quantity`
- `myNetPrice` = `(myPrice + myPrice * taxRatio) * quantity`
- `finalPrice` = same as net price in this product
- order `total` = sum of item final prices
- order `myTotal` = sum of item my-net prices
- item count
- customer count

### Seed data expectations
Initial data should include a mix of:
- pending
- purchased
- delivered
- closed

The seed should feel realistic, not synthetic.

---

## 8) Interaction rules

### Dashboard interactions
- Search filters should update the list in real time.
- Status filter should narrow the table instantly.
- Clicking an order should open its detail page.
- Selected order preview should reflect the current filtered result.

### Detail page interactions
- Changing status should update the working draft.
- Adding customers should append to the customer list.
- Removing customers should update item assignments if needed.
- Adding item rows should create new editable rows.
- Editing any item field should recompute totals immediately.
- Saving should persist to local storage and refresh the saved state.

### Closed-order behavior
- Inputs become disabled.
- Add actions become disabled.
- Save becomes disabled.
- The lock banner appears.
- The order remains viewable.

### New-order behavior
- Starts with one item row.
- Customers can be added before or after item creation.
- When a customer is added, the first item may inherit it if no customer exists yet.
- Save should create the new order and open the detail view for the saved order.

### Validation expectations
- Quantity should never go below 1.
- Tax ratio should default to 0.16.
- Empty item rows should remain editable but not break calculations.
- Duplicate customers should be prevented.

---

## 9) Responsive behavior

The product is responsive web, not separate native apps. The same experience must adapt across modern browser widths.

### Breakpoints to support
- 360px mobile compact
- 390–430px mobile standard
- 600–744px foldable / small tablet
- 768–834px tablet portrait
- 1024–1180px tablet landscape / large tablet
- 1280–1366px laptop
- 1440–1536px desktop
- 1920px wide

### Responsive rules
- Hero sections stack vertically on narrow screens.
- Grids collapse to one column at smaller widths.
- Table rows should remain usable and not overflow horizontally.
- Sidebars should move below the main content on mobile.
- Buttons should stay large enough for touch.
- Forms should preserve label clarity and field spacing.
- The item editor should avoid squeezing too many columns into a narrow viewport; it should reflow into a stacked or scroll-safe layout if necessary.

### Mobile priorities
- Hide nothing essential.
- Keep the primary action visible.
- Preserve readable order IDs, statuses, and totals.
- Ensure the customer list and item controls remain usable without zooming.

### Desktop priorities
- Make the table and editor feel efficient.
- Use the available space for summaries and previews.
- Keep editing controls near the data they affect.

---

## 10) Motion and feedback

### Motion principles
- Feedback should be quick and tactile.
- Motion should support confidence, not distract from task flow.

### Recommended timing
- Button press: short and immediate.
- Field change feedback: near-instant.
- Card / row updates: quick but visible.
- Status transitions: subtle.

### Motion language
- Accent buttons press down on click.
- New item rows should appear without drama.
- Summary values should change smoothly enough to be noticed.
- The product should never feel like a heavy admin suite.

---

## 11) Accessibility rules

### Contrast and readability
- Keep body text dark on white surfaces.
- Make meta text legible, not faint.
- Ensure status badges remain readable in both text and color.

### Keyboard support
- All interactive controls should be reachable via keyboard.
- Focus states must be obvious.
- Buttons, selects, and inputs need consistent tab order.

### Form usability
- Every field must have a clear label.
- Labels should not rely on placeholder text.
- Disabled state must still communicate meaning.

### Screen-reader friendliness
- Use semantic sections, headings, tables, inputs, and buttons.
- Keep status information visible and textual, not only color-based.

---

## 12) Content and tone

### Tone of voice
- Direct
- Practical
- Calm
- Clear
- Helpful

### Writing rules
- Use short labels.
- Use action verbs for buttons.
- Explain restrictions plainly.
- Avoid vague product language.

### Recommended microcopy examples
- “Add customer”
- “Add item row”
- “Save order”
- “Open details”
- “Closed order”
- “This order is read-only”

---

## 13) Do / don’t

### Do
- Use the green brand accent with confidence.
- Keep borders solid and visible.
- Make calculations explicit.
- Make closed-order locking obvious.
- Use real data-like values.
- Keep the interface friendly and fast.

### Don’t
- Don’t use beige or peach background washes.
- Don’t use emojis as UI icons.
- Don’t over-decorate cards with random gradients.
- Don’t hide the edit lock for closed orders.
- Don’t invent fake performance claims.
- Don’t turn the product into a design-spec dashboard.

---

## 14) Page-level definitions

### Dashboard
Main job:
- show overview stats
- search and filter orders
- open any order quickly

Required content:
- hero summary
- statistic cards
- filter inputs
- order table
- preview or selected-order panel

### Order detail
Main job:
- inspect and edit one order
- lock editing if the order is closed

Required content:
- order title and status
- save action
- closed-order banner when needed
- customer list
- item editor
- notes panel
- summary totals

### New order
Main job:
- create a new order from scratch
- add customers and items
- save into history

Required content:
- new order ID or title
- status selector
- customer input and chip list
- item editor rows
- pricing summary
- save button

---

## 15) Implementation notes

- Persist orders locally.
- Keep the same data model across dashboard, detail, and new-order views.
- Use computed values for totals instead of hard-coded display numbers.
- Keep page-specific HTML files separate.
- Use a launcher or index only as a gateway if needed.
- Avoid mixing design-process UI with the actual product UI.

---

## 16) Final system summary

Order Loop is a bright, tactile, responsive order tool built around three real workflows: history, detail editing, and new-order creation. The design language is Duolingo-inspired: white canvas, owl-green primary action, thick borders, chunky shadows, rounded components, and friendly but highly functional copy. The system must always make the editing lock for closed orders obvious, keep pricing rules transparent, and make the customer/item workflow feel fast and trustworthy.