Webui Design

Web UI Design System - AI Edit Video by noti.vn

The web UI is a monitoring and management dashboard, not a video editor. Aesthetic standard: Shopify Admin - minimal, high information density but still airy, every element has a reason to exist.

Enforcement: cd apps/web && node scripts/check-design-system.mjs. It flags off-scale type sizes, off-rhythm spacing, raw colors, and hand-rolled copies of existing primitives. Run it before you claim a UI change is done.

1. The type scale - three steps, no fourth

This is the single rule that decides whether the dashboard reads clean or noisy, so it comes first.

Plus exactly two headings - text-xl font-semibold (20px) for the page title, text-sm font-semibold (14px) for a card title - and text-[28px] font-bold for the big figure inside <StatTile>. Never more than 2 heading levels on one page.

Banned: text-[10px], text-[11px], text-[13px], text-[15px], text-base, text-lg, and every other arbitrary size. Need 13px? That is what text-meta is for - a hand-typed arbitrary size is exactly how a fourth step sneaks back in. Below 12px there is no step at all: either the text matters enough to be readable, or it should not be on screen.

text-meta is defined in globals.css via @theme { --text-meta }, so it is a real Tailwind utility, not a convention.

Why this is written down so forcefully: before the August 2026 overhaul the codebase had 416 uses of text-xs against 136 of text-sm. 12px had silently become the body size, with a long tail of 10/11/13/15px underneath. Everything looked the same, so nothing read as more important than anything else. The spec said 14px body the whole time - what was missing was a name for 13px and something that counted.

2. Spacing rhythm

Gaps and padding come from one scale: gap-1 (4px), gap-2 (8px), gap-3 (12px), gap-4 (16px), gap-6 (24px); p-2, p-3, p-4. Banned: gap-0.5, gap-2.5, gap-5, p-0.5, p-1.5, p-2.5. Icon buttons do not need their own padding - use <IconButton>.

Page shell: content gutter 20px (Shell.tsx), cards 16px inside, 16px between cards. <PageHeader> deliberately carries no bottom margin - the page's own gap-4 provides it. Adding mb-4 back doubles it to 32px and detaches the title from its page.

3. Primitives - use them, never re-derive them

Every one of these exists because the same thing had been hand-written many times over. Reaching past a primitive to raw Tailwind is the failure mode this system is built to prevent.

Nesting depth is capped at Card → Panel. Three nested borders and the eye can no longer tell what contains what - this happened for real on the translate-video page (Card → bordered box → bordered <li>).

Errors: a single field's error goes in <Field error>, right under the offending input. A card- or page-level error goes in <Banner tone="danger">. Never a bare <p className="text-[var(--danger)]">, and never swallow the raw log - pass it to detail.

4. Color tokens

Every color goes through a CSS custom property declared in :root and [data-theme="dark"]. Components never contain hex codes, and never Tailwind's palette (bg-gray-100, text-white) - map those to tokens. Do not apply alpha modifiers to tokens (bg-[var(--primary-soft)]/40) - that produces a color outside the table.

:root {
  /* Brand */
  --primary: #ed3c47;
  --primary-hover: #d62e3a;
  --primary-soft: #fdedef;
  --secondary: #ff7849;

  /* Surface */
  --bg: #ffffff;          /* page background */
  --bg-subtle: #f6f6f7;   /* sidebar, nested blocks, zebra rows */
  --surface: #ffffff;     /* card */
  --border: #e7e7ea;

  /* Text */
  --text: #101113;
  --text-muted: #5f6470;

  /* Semantic */
  --success: #16a34a;
  --success-bg: #e7f6ec;
  --danger: #e8590c;
  --danger-bg: #fbeee5;

  /* Chart series - multi-series dataviz only, validated against the dataviz checker */
  --chart-2: #2f6fed;
  --chart-3: #0d9488;

  /* Shape & motion */
  --radius: 8px;
  --radius-lg: 12px;
  --shadow-card: 0 1px 2px rgba(16, 17, 19, 0.06);
  --transition: 150ms ease;
}

[data-theme="dark"] {
  --primary: #ed3c47;          /* brand color stays the same */
  --primary-hover: #f25560;    /* in dark, hover goes LIGHTER, not darker */
  --primary-soft: #3a1d20;
  --secondary: #ff7849;

  --bg: #131417;
  --bg-subtle: #1a1b1f;
  --surface: #1e1f24;
  --border: #2c2d33;

  --text: #f2f3f5;
  --text-muted: #9a9ea9;

  --success: #2ebd6b;
  --success-bg: #17301f;
  --danger: #f0742e;
  --danger-bg: #33231a;

  --chart-2: #5b8def;
  --chart-3: #27ab92;

  --shadow-card: 0 1px 2px rgba(0, 0, 0, 0.4);
}

Dark mode rule: only change token values, NEVER add dark-only tokens. Write the component once, it runs in both themes.

The handful of legitimate exceptions (a QR code needing a real white background, an overlay on top of arbitrary video) are listed with their reasons in the ALLOW map of scripts/check-design-system.mjs. Adding an entry there requires a reason written next to it.

5. General principles

1. Light is the default, dark is opt-in. The toggle persists to localStorage and is applied via the data-theme attribute on <html>.
2. Icons are 100% inline SVG - Lucide set, stroke 1.5-2px, currentColor so they inherit text color. No icon fonts, no PNGs, no emoji as functional icons (this includes emoji inside <option> labels).
3. Inter font via the @fontsource/inter package, imported in apps/web/src/app/layout.tsx (weights 400/500/600/700). Bundled at build time, so self-hosted - never load fonts from a CDN at runtime.
4. Fixed metadata: title AI Edit Video by: noti.vn, description Edit video tự động bằng AI, favicon from public/brand/favicon.png.

6. Brand assets

The logo swaps with the theme at the same moment as the tokens (same data-theme listener).