mrarm-ui/WEB_DESIGN_STYLE.md

Web Design Style Guide

Use this guide when designing or implementing web user interfaces that should feel compact, practical, durable, and optimized for repeated operational use. The preferred style is a restrained control-panel aesthetic: dense but readable, strongly structured, low-decoration, and built around clear data, direct actions, and predictable navigation.

This is not a landing-page style. It is not a marketing style. It is a working-interface style for tools, dashboards, admin areas, review queues, editors, monitoring pages, configuration screens, and other interfaces where users need to scan, compare, decide, and act efficiently.

Design Intent

The interface should feel like dependable system software: plain, precise, and information-forward. Visual choices should support speed, legibility, and confidence rather than brand expression or emotional effect.

Favor:

• Compact layouts with clear grouping.
• Dense tables, forms, status rows, and action bars.
• Muted neutral surfaces.
• Strong borders and obvious boundaries.
• Small, consistent typography.
• Direct labels and command text.
• Minimal motion.
• Semantic color used sparingly.
• Interfaces that remain useful with large amounts of data.

Avoid:

• Marketing pages, hero sections, oversized feature copy, or decorative storytelling.
• Large soft cards, glassmorphism, frosted panels, floating layouts, or excessive elevation.
• Gradient backgrounds, decorative blobs, large illustration panels, and atmospheric imagery.
• Big rounded corners, pill-heavy layouts, and oversized touch-target styling unless the product context requires it.
• Spacious SaaS dashboard styling that sacrifices density.
• One-note color themes where the entire screen is a variation of a single hue.
• Animations that call attention to themselves.

Overall Aesthetic

Use a restrained, old-school administrative console look. The screen should read as a serious work surface, not a consumer product.

The primary visual language is:

• Flat grey panels.
• Square or nearly square corners.
• Visible 1px or 2px borders.
• Simple top bars and navigation strips.
• Small controls.
• Full-width data tables.
• Monospace text for machine-oriented values.
• Clear status badges with minimal decoration.

The design should be easy to inspect at a glance. A user should immediately understand which region is navigation, which region is content, which items are actionable, and which values are status indicators.

Layout Principles

Use a fixed, practical page structure:

1. A compact top bar with product/page identity and optional account or global actions.
2. A main wrapper with modest padding.
3. A bordered main panel or unframed content area depending on the application shell.
4. A compact navigation bar near the top of the working area.
5. Page content arranged as dense sections with headings, tables, forms, and action rows.

Recommended spacing:

• Page padding: 10px to 14px.
• Panel padding: 8px to 12px.
• Section gap: 10px to 16px.
• Table cell padding: 6px to 8px.
• Form row gap: 6px to 10px.
• Button padding: 6px 10px.

Use grid layouts only where they improve scanning. Two-column grids are useful for summary/detail layouts. Avoid decorative card grids unless each card is a true repeated data item.

Do not create nested cards. If a page needs multiple regions, use sections, tables, fieldsets, bordered panels, or full-width bands. Keep hierarchy clear through headings, borders, and spacing rather than shadows or depth effects.

Density

The preferred density is high. Users should be able to see many controls or rows without excessive scrolling.

Keep:

• Headings small.
• Controls compact.
• Labels concise.
• Tables full-width.
• Actions close to the data they affect.
• Repeated metadata in small text.

Do not use:

• Oversized page titles.
• Tall cards for simple metrics.
• Large icon-only empty states.
• Wide blank gutters.
• Large vertical gaps between related controls.

The layout should remain comfortable, but it should never feel like a marketing dashboard.

Typography

Use system-adjacent, utilitarian fonts. Preferred font stack:

font-family: Tahoma, Verdana, Arial, sans-serif;

Recommended type scale:

• Body: 13px.
• Small text: 12px.
• Headings: 14px, bold.
• Table headers: 12px, bold.
• Code, IDs, timestamps, URLs, logs: 12px monospace.

Recommended monospace stack:

font-family: "Courier New", Courier, monospace;

Rules:

• Keep line-height compact, around 1.25 to 1.35.
• Do not use negative letter spacing.
• Do not scale type with viewport width.
• Do not use display-scale typography inside tool surfaces.
• Use bold for hierarchy and active states, not for decoration.
• Use muted small text for secondary metadata.

Headings should be practical section labels, not editorial copy. Examples:

• Details
• Actions
• Recent Runs
• Configuration
• Import
• Queue
• Status
• Logs

Color Palette

Use a neutral grey base with restrained semantic colors.

Recommended tokens:

:root {
  --bg: #b9bcc0;
  --panel: #d6d8db;
  --panel-2: #cfd2d6;
  --panel-3: #e7e9ec;
  --surface: #ffffff;
  --surface-alt: #f6f7f8;
  --border: #5c6268;
  --border-2: #8a9199;
  --line: #c0c4c9;
  --text: #101214;
  --muted: #2f343a;
  --accent: #0b5fa5;
  --ok: #1f7a3a;
  --warn: #b66b00;
  --bad: #a32828;
}

Use color roles consistently:

• Grey for layout, panels, controls, and table structure.
• Blue for primary actions, links, active navigation accents, and selected states.
• Green only for successful, enabled, healthy, accepted, or complete states.
• Orange only for warning, pending, degraded, or attention-needed states.
• Red only for destructive, failed, rejected, blocked, or dangerous states.

Do not make the whole UI blue, purple, green, beige, black, or any other single dominant hue. The screen should read as neutral grey with small semantic highlights.

Borders And Corners

Borders are a primary design tool in this style.

Use:

• 1px borders for tables, fields, buttons, dropdowns, badges, and small panels.
• 2px borders for the main application panel or important structural containers.
• Medium grey border colors with enough contrast to define regions.
• Border-only separation before using background changes.

Corners:

• Prefer 0px border radius.
• If radius is needed, keep it at 2px to 4px.
• Avoid rounded cards.
• Avoid pill shapes except for rare compact tags or indicators where the pattern is already established.

Shadows:

• Avoid soft shadows.
• If a menu needs separation, use a simple hard shadow such as 2px 2px 0 #8a9199.
• Do not use layered elevation systems.

Navigation

Navigation should be compact, obvious, and operational.

Preferred patterns:

• Horizontal tab-like navigation near the top of the panel.
• Dropdown groups for related sections.
• Active item shown with white or lighter background, bold text, and a blue inset border/accent.
• Simple text labels.
• Small status chips embedded only when useful.

Navigation controls should look like rectangular system buttons, not marketing nav links.

Recommended behavior:

• Active top-level section remains visually distinct.
• Dropdown menus align directly below their trigger.
• Menus have a bordered, flat panel background.
• Menu items are full-width rows with hover/focus states.
• On narrow screens, navigation items stack full-width.

Avoid:

• Large sidebars unless the application has many persistent sections.
• Icon-heavy navigation without text.
• Animated mega menus.
• Floating glass nav bars.
• Breadcrumb-heavy layouts unless depth is genuinely complex.

Panels And Containers

Use panels to define working regions, not to decorate.

Main panels:

• Light grey background.
• 2px dark grey border.
• 8px to 12px padding.
• No shadow.
• No rounded corners.

Secondary containers:

• White or very light grey background.
• 1px medium grey border.
• 8px padding.
• Used for code boxes, markdown previews, log entries, and compact detail blocks.

Do not wrap every section in a card. Many sections can simply be headings followed by tables or forms.

Tables

Tables are central to this style. They should be dense, legible, and full-width.

Table rules:

• Use border-collapse: collapse.
• Use white table background.
• Use 1px borders between all cells.
• Use light grey headers.
• Use subtle alternating row backgrounds.
• Align text left.
• Keep numeric or machine values in monospace when helpful.
• Keep row actions in the last column.
• Use badges for status cells.

Recommended CSS:

table {
  width: 100%;
  border-collapse: collapse;
  background: #ffffff;
  border: 1px solid var(--border-2);
}

th,
td {
  border: 1px solid var(--line);
  padding: 6px 7px;
  vertical-align: top;
}

th {
  background: #e9ecef;
  text-align: left;
  font-weight: 700;
  font-size: 12px;
}

tr:nth-child(even) td {
  background: var(--surface-alt);
}

Table content guidance:

• Use links for primary identifiers or names.
• Use small muted text for metadata.
• Use monospace for IDs, timestamps, paths, URLs, and machine values.
• Use compact buttons for row actions.
• Do not place large multiline content directly into a table unless it is preformatted operational output.
• For long values, allow wrapping or provide a code box/detail row.

Forms

Forms should be structured, compact, and predictable.

Preferred pattern:

• Two-column rows.
• Fixed-width labels on the left.
• Inputs on the right.
• Small label text in muted color.
• Actions in a compact row below the fields.

Recommended CSS:

.row {
  display: grid;
  grid-template-columns: 180px 1fr;
  gap: 8px;
  align-items: start;
  margin: 8px 0;
}

.row .label {
  font-size: 12px;
  color: var(--muted);
  padding-top: 6px;
}

Inputs:

• Full-width by default.
• White background.
• 1px medium grey border.
• 6px to 7px padding.
• Same font as body.
• Textareas use monospace when the expected content is prompts, logs, code, markdown, JSON, or configuration.

Avoid:

• Floating labels.
• Large rounded inputs.
• Oversized validation messages.
• Multi-column forms with unclear reading order.
• Placeholder text as the only label.

Buttons And Actions

Buttons should be small, rectangular, and direct.

Base button:

• Light grey background.
• 1px medium grey border.
• 6px 10px padding.
• 13px font.
• No radius or minimal radius.
• Pointer cursor.

Primary button:

• Pale blue background.
• Blue-grey border.
• Dark blue text.
• Bold label.

Danger button:

• Pale red background.
• Red border.
• Dark red text.

Recommended CSS:

button,
.btn {
  padding: 6px 10px;
  border: 1px solid var(--border-2);
  background: #f2f4f6;
  cursor: pointer;
  font-family: Tahoma, Verdana, Arial, sans-serif;
  font-size: 13px;
  text-decoration: none;
  color: var(--text);
}

button.primary,
.btn.primary {
  background: #e9f2fb;
  border-color: #6f99c2;
  color: #0a4778;
  font-weight: 700;
}

button.danger,
.btn.danger {
  background: #fdeaea;
  border-color: #c26969;
  color: #7a0f0f;
}

Action placement:

• Keep page-level actions near the top of a page.
• Keep row-level actions in the relevant table row.
• Keep destructive actions visually distinct but not oversized.
• Use confirmation for irreversible destructive actions.
• Use action groups with 8px gaps.

Button labels should be short commands:

• Save
• Import
• Refresh
• Review
• Cancel
• Delete
• Export
• Open
• Apply
• Retry

Links

Links should be straightforward and recognizable.

Use:

• Blue text for inline links.
• Underline only if the broader environment requires it or readability suffers.
• Links inside tables for primary record navigation.
• Buttons for command-like actions.

Do not style command links as decorative text when they mutate state. Use a button or button-like form control.

Badges And Status Indicators

Use badges for status, state, and small categorical labels.

Base badge:

• Inline-block.
• 1px border.
• Light grey background.
• 12px font.
• 1px 6px padding.
• No icon unless required for accessibility or scanning.

Semantic variants:

• Success: green border and green text.
• Warning: orange border and orange text.
• Error: red border and red text.
• Neutral: grey border and dark text.

Recommended CSS:

.badge {
  display: inline-block;
  padding: 1px 6px;
  border: 1px solid var(--border-2);
  background: #f4f6f8;
  font-size: 12px;
}

.badge.ok {
  border-color: #2b8b47;
  color: var(--ok);
}

.badge.warn {
  border-color: #c9891b;
  color: var(--warn);
}

.badge.bad {
  border-color: #b94b4b;
  color: var(--bad);
}

Badges should not become the dominant visual element on the page. They are scanning aids.

Code, Logs, And Preformatted Content

Machine-oriented text should be set apart clearly.

Use code boxes for:

• Logs.
• JSON.
• Configuration snippets.
• Generated output.
• URLs or endpoint summaries.
• Error messages.
• Technical descriptions that benefit from preserved whitespace.

Recommended CSS:

.mono {
  font-family: "Courier New", Courier, monospace;
  font-size: 12px;
}

.small {
  font-size: 12px;
  color: var(--muted);
}

.codebox {
  background: #ffffff;
  border: 1px solid var(--border-2);
  padding: 8px;
  overflow: auto;
  max-height: 280px;
}

For transcript or log streams:

• Use stacked code boxes.
• Include a bold title and small timestamp.
• Keep metadata compact.
• Use white-space: pre-wrap for long output.
• Avoid syntax highlighting unless it genuinely improves readability.

Markdown Content

Rendered markdown should still match the utilitarian interface.

Use:

• White background.
• 1px border.
• 12px to 13px body size.
• Compact margins.
• Monospace code.
• Light grey code backgrounds.
• Simple blockquote left borders.

Avoid:

• Blog-style typography.
• Large prose widths with oversized line-height.
• Decorative heading scales.
• Rich article styling that clashes with the application shell.

Modals And Overlays

Use modals sparingly. Prefer inline controls and detail rows when possible.

When a modal is needed:

• Use a simple dark translucent backdrop.
• Use a bordered rectangular panel.
• Keep content constrained with scrolling.
• Keep headings small.
• Put actions in a compact row.
• Avoid large rounded cards.
• Avoid animated entrance effects.

Modals should feel like utility dialogs, not product-tour surfaces.

Alerts And Flash Messages

Alerts should be plain and close to the relevant area.

Use:

• Small text.
• Border and background changes.
• Semantic color only when needed.
• Clear, direct copy.

Do not use large banners unless the issue blocks the entire page.

Progress And Live State

Progress indicators should be simple and compact.

Preferred patterns:

• Small status text.
• Thin progress bars with borders.
• Inline live indicators.
• Badges for connection or queue state.

Avoid:

• Full-page loaders for local actions.
• Large animated spinners.
• Excessive real-time motion.

If something updates live, preserve layout stability. Row height, columns, and action placement should not shift unexpectedly.

Responsive Behavior

The style should remain practical on small screens without becoming a different design.

Rules:

• Stack navigation items full-width on narrow screens.
• Make dropdown menus static and full-width on narrow screens.
• Collapse two-column grids into one column below tablet width.
• Keep tables horizontally scrollable if necessary.
• Preserve table structure for data-heavy views instead of converting everything into cards.
• Form rows may collapse to one column on very narrow screens.

Do not create a separate mobile marketing layout. The mobile version is still a compact tool interface.

Accessibility

The compact style must remain accessible.

Requirements:

• Use semantic HTML controls.
• Preserve visible focus states.
• Ensure text contrast is sufficient.
• Use labels for form inputs.
• Keep destructive actions explicit.
• Provide accessible names for icon-only controls if any are used.
• Do not rely on color alone for critical state.
• Respect prefers-reduced-motion.

Dense does not mean ambiguous. Every control should be understandable and reachable by keyboard.

Motion

Use minimal motion.

Acceptable:

• Short expand/collapse transitions for utility panels.
• Simple hover/focus background changes.
• Subtle progress updates.

Avoid:

• Page transitions.
• Scroll-triggered animation.
• Decorative animated backgrounds.
• Springy controls.
• Motion that distracts from reading data.

If an animation is not helping the user understand state, remove it.

Icons

Text labels are usually preferred. Use icons only where they improve scanning or match a familiar tool action.

If using icons:

• Keep them small.
• Pair unfamiliar icons with text.
• Use tooltips or accessible labels.
• Match stroke weight and size consistently.
• Do not use icons as decoration.

Avoid illustration-style icons, large empty-state graphics, and decorative icon clusters.

Empty States

Empty states should be short and functional.

Use:

• A single muted line such as No entries yet.
• A compact primary action if there is an obvious next step.
• Optional small explanation when the absence of data might be confusing.

Avoid:

• Large illustrations.
• Inspirational copy.
• Oversized centered panels.
• Marketing-style onboarding.

Copy Style

Use direct, operational language.

Good labels:

• Status
• Updated
• Server URL
• Import
• Search
• Delete selected
• Review
• Export
• Run
• Cancel

Avoid:

• Playful copy.
• Marketing claims.
• Long explanations in the UI.
• Feature descriptions that belong in documentation.
• Ambiguous verbs like Go, Do it, or Manage when a specific action exists.

The user interface should speak in short labels and commands.

Page Patterns

Dashboard

Dashboards should emphasize current operational state and recent activity.

Use:

• Compact summary tables.
• Small metric blocks only when they are styled consistently.
• Recent activity tables.
• Direct action buttons.
• Endpoint or configuration summaries in code boxes.

Avoid oversized KPI cards. If metrics are shown as blocks, keep them compact and bordered.

List Page

List pages should make filtering and row actions easy.

Use:

• Top action row.
• Filter form.
• Full-width table.
• Status badges.
• Row-level action buttons.
• Compact empty row when no records exist.

Detail Page

Detail pages should make metadata, actions, and history easy to inspect.

Use:

• Two-column grid for details and actions.
• Tables for fixed metadata.
• Code boxes for long text or output.
• Action row near the top.
• Subsequent sections for notes, logs, attempts, history, or related items.

Configuration Page

Configuration pages should be clear and conservative.

Use:

• Two-column form rows.
• Plain section headings.
• Required fields marked through native validation or concise labels.
• Save/apply actions close to the form.
• Existing settings shown in tables or code boxes.

Review Queue

Review pages should help users make decisions quickly.

Use:

• Dense rows.
• Clear status badges.
• Primary and danger actions.
• Context in code boxes.
• Links to related records.
• Optional live refresh indicators.

Implementation Checklist

Before considering a UI complete, verify:

• The page uses compact typography and spacing.
• The main structure is obvious without decorative effects.
• Tables are readable and dense.
• Forms use consistent label/value rows.
• Buttons are small, rectangular, and semantically styled.
• Status color is sparse and meaningful.
• Long machine text uses monospace/code boxes.
• Navigation active states are visible.
• Mobile layout preserves usability.
• Text does not overflow buttons or controls.
• There are no decorative gradients, blobs, glass effects, or large rounded cards.
• The interface still works with realistic amounts of data.

Agent Instructions

When implementing a web UI in this style:

1. Start with the working task, not a landing page.
2. Build the primary tool surface as the first screen.
3. Use compact neutral panels, tables, forms, and action rows.
4. Apply semantic color only for state and action priority.
5. Prefer standard HTML controls before custom widgets.
6. Keep all spacing, typography, and borders consistent.
7. Avoid decorative layout patterns.
8. Check the interface at desktop and mobile widths.
9. Revise any area that looks like a modern marketing dashboard.
10. Optimize for repeated use by a knowledgeable operator.

The final result should feel plain in the best sense: fast to parse, hard to misread, and built for doing work.