8000
Skip to content

DESIGN.md

Latest commit

 

History

History
309 lines (272 loc) · 12.7 KB

DESIGN.md

File metadata and controls

309 lines (272 loc) · 12.7 KB
Raw
version alpha
name Docklight
description A clean, minimal admin dashboard for Dokku server management. Neutral palette with high-contrast typography, subtle depth, and purposeful color for status signals. Supports light and dark themes with responsive layouts from mobile to desktop.
colors
primary secondary tertiary neutral surface on-primary on-tertiary destructive success warning success-surface success-on-surface destructive-surface destructive-on-surface warning-surface warning-on-surface primary-dark secondary-dark neutral-dark surface-dark on-primary-dark border-dark tertiary-dark success-surface-dark success-on-surface-dark destructive-surface-dark destructive-on-surface-dark warning-surface-dark warning-on-surface-dark
#0F0F12
#52525B
#1E40AF
#FFFFFF
#F8F9FA
#FAFAFA
#FFFFFF
#B91C1C
#15803D
#B45309
#DCFCE7
#14532D
#FEE2E2
#7F1D1D
#FEF3C7
#78350F
#FAFAFA
#D4D4D8
#18181B
#09090B
#18181B
#27272A
#93C5FD
#052E16
#BBF7D0
#450A0A
#FECACA
#422006
#FDE68A
typography
font-sans font-mono h1 h2 body-md label-caps mono
fontFamily fontFeature
IBM Plex Sans
"kern", "liga", "calt"
fontFamily fontFeature
IBM Plex Mono
"kern", "liga"
fontFamily fontSize fontWeight lineHeight letterSpacing
IBM Plex Sans
1.875rem
700
1.25
-0.02em
fontFamily fontSize fontWeight lineHeight letterSpacing
IBM Plex Sans
1.25rem
600
1.4
-0.01em
fontFamily fontSize fontWeight lineHeight letterSpacing
IBM Plex Sans
1rem
400
1.6
0.01em
fontFamily fontSize fontWeight letterSpacing
IBM Plex Sans
0.75rem
600< 8000 /div>
0.06em
fontFamily fontSize lineHeight
IBM Plex Mono
0.875rem
1.6
rounded
sm md lg full
6px
8px
12px
9999px
spacing
xs sm md lg xl gutter page-padding-mobile page-padding-tablet page-padding-desktop sidebar-width content-max-width
4px
8px
16px
24px
32px
16px
16px
24px
32px
256px
1280px
breakpoints
sm md lg xl
640px
768px
1024px
1280px
components
sidebar sidebar-dark sidebar-link sidebar-link-hover sidebar-link-active page page-dark card card-dark button-primary button-primary-hover button-secondary button-secondary-hover badge-success badge-success-dark badge-error badge-error-dark badge-warning badge-warning-dark input status-indicator-success status-indicator-destructive status-indicator-warning text-muted-dark border-subtle-dark theme-toggle
backgroundColor textColor width
{colors.primary}
{colors.on-primary}
{spacing.sidebar-width}
backgroundColor textColor width
{colors.neutral-dark}
{colors.primary-dark}
{spacing.sidebar-width}
backgroundColor textColor padding rounded
transparent
{colors.on-primary}
8px 16px
{rounded.sm}
backgroundColor
rgba(255,255,255,0.08)
backgroundColor textColor
rgba(255,255,255,0.20)
{colors.on-primary}
backgroundColor textColor
{colors.surface}
{colors.primary}
backgroundColor textColor
{colors.surface-dark}
{colors.primary-dark}
backgroundColor textColor rounded padding
{colors.neutral}
{colors.primary}
{rounded.lg}
24px
backgroundColor textColor rounded padding
{colors.neutral-dark}
{colors.primary-dark}
{rounded.lg}
24px
backgroundColor textColor rounded padding
{colors.tertiary}
{colors.on-tertiary}
{rounded.sm}
8px 16px
backgroundColor
#1D4ED8
backgroundColor textColor rounded padding
{colors.neutral}
{colors.primary}
{rounded.sm}
8px 16px
backgroundColor
{colors.surface}
backgroundColor textColor rounded
{colors.success-surface}
{colors.success-on-surface}
{rounded.full}
backgroundColor textColor rounded
{colors.success-surface-dark}
{colors.success-on-surface-dark}
{rounded.full}
backgroundColor textColor rounded
{colors.destructive-surface}
{colors.destructive-on-surface}
{rounded.full}
backgroundColor textColor rounded
{colors.destructive-surface-dark}
{colors.destructive-on-surface-dark}
{rounded.full}
backgroundColor textColor rounded
{colors.warning-surface}
{colors.warning-on-surface}
{rounded.full}
backgroundColor textColor rounded
{colors.warning-surface-dark}
{colors.warning-on-surface-dark}
{rounded.full}
backgroundColor textColor rounded padding
{colors.neutral}
{colors.primary}
{rounded.sm}
8px 12px
backgroundColor textColor
{colors.success}
{colors.on-tertiary}
backgroundColor textColor
{colors.destructive}
{colors.on-tertiary}
backgroundColor textColor
{colors.warning}
{colors.on-tertiary}
textColor
{colors.secondary-dark}
backgroundColor
{colors.border-dark}
backgroundColor textColor rounded padding
transparent
{colors.on-primary}
{rounded.sm}
8px

Overview

Docklight is a minimal, self-hosted web UI for managing a single-node Dokku server. The design prioritizes clarity and operational density — administrators need to see status, act quickly, and navigate confidently. The visual language is neutral and restrained, letting data and status colors do the talking.

The tone is professional but not sterile. Think of it as a well-organized cockpit: every element has a purpose, nothing competes for attention unnecessarily.

Light and dark themes share the same semantic structure. Tertiary blue, success green, destructive red, and warning amber stay consistent across modes; only surfaces and text invert.

Colors

Light mode

  • Primary (#0F0F12): Near-black for text and the sidebar background. Tuned for WCAG AAA contrast on white surfaces.
  • Secondary (#52525B): Zinc gray for supporting text, metadata, and de-emphasized content (≥7:1 on surface).
  • Tertiary (#1E40AF): Deep blue for links and interactive text. Meets AAA on white; buttons use white on-surface text.
  • Neutral (#FFFFFF): Card backgrounds and white surfaces. The default canvas.
  • Surface (#F8F9FA): Page background. Slightly off-white to create subtle depth against cards.
  • Destructive (#B91C1C): Red for destructive actions (delete, destroy) and critical errors.
  • Success (#15803D): Green for running status and successful operations.
  • Warning (#B45309): Amber for warnings and degraded states.

Dark mode

  • Primary-dark (#FAFAFA): Near-white for primary text on dark surfaces.
  • Secondary-dark (#D4D4D8): Light zinc for supporting text and metadata (≥7:1 on dark surfaces).
  • Tertiary-dark (#93C5FD): Light blue for links on dark backgrounds.
  • Neutral-dark (#18181B): Card and elevated surface background.
  • Surface-dark (#09090B): Page background. Deep zinc for maximum contrast with cards.
  • Border-dark (#27272A): Subtle dividers and input borders.

Status badges use tinted surface tokens (success-surface, destructive-surface, warning-surface) with paired on-surface text colors tuned for WCAG AAA (7:1 normal text, 4.5:1 large text) in both themes.

Typography

IBM Plex Sans for all UI text. IBM Plex Mono for command output and code.

IBM Plex Sans was chosen over Inter for this admin UI because it offers stronger character distinction at small sizes (Il1, O0), a slightly taller x-height for dense tables, and was designed for technical interfaces. It remains neutral and professional without the over-familiar “startup dashboard” feel of Inter.

Both families are loaded via Google Fonts with display=swap and fall back to system UI fonts when offline.

Readability rules (AAA)

  • Base body size is 16px (1rem) — 14px fails AAA contrast targets for secondary text far more often.
  • Line height 1.6 on body copy for comfortable scanning of logs and tables.
  • Muted text uses secondary tokens darkened/lightened to maintain ≥7:1 against page and card surfaces.
  • Links use a darker blue (#1E40AF) in light mode and a lighter blue (#93C5FD) in dark mode — both meet AAA on their respective surfaces.
  • Table labels use 12px semibold uppercase minimum; avoid 11px for any text that carries meaning.
  • Enable kerning and ligatures via font-feature-settings.

Scale

  • H1 (1.875rem, 700): Page titles. Bold, slightly tight tracking.
  • H2 (1.25rem, 600): Section headers within cards and content areas.
  • Body (1rem, 400): Default text size. 16px base for AAA compliance.
  • Label (0.75rem, 600, uppercase tracking): Table headers and metadata labels.
  • Mono (0.875rem): Command output, log entries, technical values.

Layout

The layout is a classic admin shell: fixed sidebar (256px) with a scrollable main content area. On viewports below 768px, the sidebar collapses into an off-canvas drawer with a top bar and hamburger control.

Breakpoints

Token Width Usage
sm 640px Stack page headers; compact table padding
md 768px Sidebar becomes persistent; hide mobile top bar
lg 1024px Increase page padding; multi-column card grids
xl 1280px Cap content width at 1280px, centered

Spacing

Spacing follows a 4px baseline grid. Use md (16px) for card padding and component gaps on mobile, lg (24px) for section breaks, xl (32px) for page-level margins on desktop.

Page padding scales: 16px mobile, 24px tablet, 32px desktop. Main content is capped at 1280px and centered on wide screens.

Cards use 12px border-radius and no box-shadow — depth comes from the background color difference, not elevation.

Tables use horizontal scroll on narrow viewports. Tab navigation scrolls horizontally when labels overflow.

Elevation & Depth

Depth is achieved through tonal layers, not shadows. The page surface sits one step below card surfaces; the sidebar uses the darkest tone in light mode and matches card tone in dark mode.

  • Light: Surface (#F8F9FA) → Card (#FFFFFF) → Sidebar (#0F0F12)
  • Dark: Surface (#09090B) → Card (#18181B) → Sidebar (#18181B with border)

Interactive focus rings use tertiary blue in light mode and a lighter ring in dark mode. No box-shadows on cards or buttons.

Shapes

  • sm (6px): Buttons, inputs, badges — interactive elements.
  • md (8px): Smaller containers, inner cards.
  • lg (12px): Top-level cards and dialogs.
  • full (9999px): Avatars, status badges, pill-shaped elements.

Components

  • Sidebar: Dark background in light mode, card-tone in dark mode. Logo and app name at top. Navigation links with subtle hover/active states. Theme toggle and user info pinned to bottom.
  • Theme toggle: Icon button (sun/moon) in sidebar footer and mobile header. Persists preference to localStorage; respects prefers-color-scheme on first visit.
  • Card: Surface-colored background, 12px radius, responsive padding (16px mobile, 24px desktop). No shadow.
  • Button (primary): Blue (#1E40AF), white text, 6px radius. Hover darkens to #1D4ED8.
  • Button (secondary): Surface background, primary text, thin border. Hover lightens.
  • Status badge: Pill-shaped with tinted background tokens. Green for running, red for stopped/error, amber for warning. Uses theme-aware surface tokens.
  • Alert banner: Tinted destructive/warning/success surfaces for inline errors and health status.
  • Table: Clean rows with subtle bottom borders. Compact padding for density. Horizontal scroll on mobile.
  • Input: Card background, thin border, 6px radius. Blue ring on focus.

Do's and Don'ts

  • Do use the design token CSS variables (--background, --foreground, --success-surface, etc.) instead of hardcoded Tailwind color classes like bg-green-100.
  • Do use status colors consistently: green = healthy, red = error/stopped, amber = warning.
  • Do keep interactive elements visually distinct from static content.
  • Do test layouts at 375px, 768px, and 1280px widths.
  • Do maintain WCAG AAA contrast (7:1 normal text, 4.5:1 large text) when introducing new color pairs.
  • Do use IBM Plex Sans / IBM Plex Mono via design tokens — do not load additional display fonts.
  • Don't add decorative elements, gradients, or illustrations. The UI is functional.
    • 2F2F
  • Don't use box-shadows for depth — use background color contrast instead.
  • Don't introduce colors outside the palette. Extend the palette if a new semantic color is needed.
  • Don't nest component variants. button-primary-hover is a sibling, not a child.
  • Don't hardcode light-only colors (text-green-800, bg-red-100) — they break dark mode contrast.
0