T
Sign in

DESIGN.md — design system (monochrome zinc, §195)

All docs GitHub source

DESIGN.md — design system (monochrome zinc, §195)

The design standard for every screen in this app, derived from the owner's UI reference github.com/skpawar1305/textile-erp-nextjs (PLANNING §52, 2026-09-04; previously gray_fabric_erp per §45-48) — layout, radii and patterns kept, hue removed in §195 (monochrome: near-black interaction, status hues only for state). UIPATTERN.md is the per-page screen-pattern guide — it implements this system; DESIGN.md is the source of truth for tokens, layout and components.

Binding constraints (unchanged): light only (Repo rule 1 — never add a theme/toggle), daisyUI for controls (Repo rule 4 — raw utility only where daisyUI has no fitting component: shell chrome, icon tiles, custom grids), append-only data (mandate 3), plain language on every screen (declutter pass §53: no stage codes, no internal refs like round 28/BOARDS-A, no → flow-speak in labels).

1. Principles

  1. Ergonomics is the most fundamental UI principle. Every other principle below — colour, layout, components, plain words, mobile-first — exists to serve the person working: fewer taps, less typing, less hunting, less re-checking. A screen that is pretty but awkward to work on is a failed screen. Judge every design decision first by how little it costs the user to do the job (see UIPATTERN.md "Design for the job" — every screen is shaped by what it serves).
  2. Calm zinc workspace, white work surfaces. The app sits on zinc-100; every work panel is a white card with a hairline border. Nothing fights for attention — the UI is monochrome; only status hues speak.
  3. Near-black = interact, zinc = read. Zinc-900 marks active, clickable, focused, linked, selected. Zinc marks surfaces, text and structure. Status colour (emerald/amber/red) is reserved for state — never decoration. Colour is never the only signal (shape + text always carry meaning too).
  4. One clear action per screen. A page has one primary CTA (top right on lists, the submit on forms, the tap target on queues). Row actions are small outline buttons; destructive/approval actions keep their daisyUI tone.
  5. Plain words only. Titles and labels say what the screen does in business language (hishob, tippan, gatepass, krill are kept — they are the owner's words); developer/process jargon is removed.
  6. Mobile-first. Tap targets stay large, tables scroll inside their cards, grids collapse to one column, the sidebar turns into a drawer with a backdrop.

2. Colour tokens

Role Reference class This app (daisyUI token)
Workspace bg-zinc-100 · body #f4f4f5 --color-base-200: #f4f4f5
Surface (cards) bg-white --color-base-100: #ffffff
Hairline border border-zinc-200 #e4e4e7 --color-base-300: #e4e4e7
Body text text-zinc-900 --color-base-content: #18181b (muted = /60)
Brand / interaction near-black --color-primary: #18181b (content #fff)
Muted partner zinc-600 #52525b --color-accent: #52525b (outline next-steps, chart 2nd series)
Neutral CTA flavour bg-black (zinc-900) btn-neutral (#18181b)
Status emerald / amber / red success #047857 · warning #b45309 · error #b91c1c · info #1d4ed8 (content #fff)
Table header strip bg-gray-50 global thead th { background: #f4f4f5 }
Row hover — zinc-100 wash + 3px inset zinc-900 bar (app.css)

Brand block: bg-gradient-to-br from-zinc-900 to-zinc-500 (logo tile, avatar). Alerts/banners: tint at 5%, border at 20%, text at 700 tone, plus a 4px left accent bar (reference alert pattern).

Contrast floor (C288). The colour code is judged by what a worker can read on a bright shop-floor screen: body text ≥ 7:1, the /60 muted tier ≥ 4.5:1, every status tone ≥ 4.5:1 both as text on a card and as white text on its filled chip, and the table header strip distinguishable from the white rows. The status tokens are the 700 tones precisely because daisyUI's light defaults (76–82% lightness) read at 1.8–2.9:1. Guarded non-UI by bun scripts/color-contrast.ts (passes, exits 1 on a regression) — never by eyeballing a screen.

3. Typography

  • Inter everywhere (loaded in app.html, maps to --font-sans in app.css; falls back to system-ui offline). No other font.
  • Scale (--text-* tuned in app.css): group headers 10px bold uppercase tracking-wider zinc-500 · field labels 13px (xs) font-medium · body 15px (sm) · panel/section titles 18px (lg) font-bold · page titles 24px (2xl) font-bold tracking-tight · dashboard hero 30px extrabold (reference text-3xl font-extrabold tracking-tight).
  • Figures are tabular-nums everywhere; right-aligned in tables.
  • Primary cells font-medium; nulls render —.

4. Layout

  • App shell (src/routes/+layout.svelte): white sidebar w-72 (collapses to a w-20 icon rail), sticky glassy header h-16 (bg-white/80 backdrop-blur-xl border-b border-zinc-200) with menu toggle + user chip; main = zinc workspace with content capped at max-w-7xl, padding p-4 sm:p-8; mobile = off-canvas drawer + bg-black/40 backdrop; work nav only in the sidebar (dev utilities live in the footer "Utility" links).
  • Page wrapper: min-h-screen bg-base-200 p-4 sm:p-6 + inner mx-auto max-w-4xl/5xl/6xl (pick by content width).
  • Page header: title + one-line subtitle (≤90 chars, plain words) and the primary CTA top-right. No page-level navbar/back chrome — the shell owns navigation (a ← Main crumb is allowed on drill pages).

5. Components (reference inventory → daisyUI implementation)

  • Sidebar item — rounded-xl, gap-3, icon 18px; active = bg-zinc-200 text-zinc-900 with a 4px left indicator bar (w-1 h-5 bg-zinc-900 rounded-r-full); inactive = text-zinc-500 hover:bg-zinc-100 hover:text-zinc-900; labels hidden on the collapsed rail (with title tooltips).
  • Brand block — 36px rounded-xl zinc-gradient tile holding the brand letter + Trading in zinc gradient (from-zinc-900 to-zinc-500).
  • Buttons — main CTAs (Save, New X, Check…, Confirm, Picked, Post…) are btn btn-neutral (near-black #18181b — PLANNING §133). btn-primary renders the same near-black (primary token = zinc-900) and is reserved for selection states (join toggles, grade/term pickers, chosen rows), auth CTAs, and xs toolbar utilities (Search/Apply/Filter); pills: rounded-lg text-xs font-semibold, selected = bg-zinc-900 text-white; row actions: btn btn-outline btn-<tone> btn-xs; auth CTA: full-width, rounded-2xl py-4 font-semibold text-lg.
  • Charts — monochrome bars (graded dark zinc gradient, dispatched light zinc gradient); legend dots via bg-primary/bg-accent tokens.
  • Cards — white border-zinc-200 rounded-2xl (radius-box 20px); KPI/stat card = icon tile (p-2.5 bg-zinc-100 rounded-xl border), trend chip (emerald/red 10% pill), big number text-xl/2xl font-bold, title text-xs font-semibold uppercase, optional desc; hover gets a top zinc-900 gradient hairline.
  • Tables — white bordered card, table table-sm; thead zinc-50 strip; th px-4 py-2 whitespace-nowrap text-left; rows border-t; status in daisyUI badges; row hover = zinc wash + zinc-900 inset bar; totals footer font-semibold tabular-nums.
  • Forms — daisyUI form-control + input/select/textarea input-bordered; label = text-xs font-medium; section headings = uppercase tracking-wider; focus ring/border follows --color-primary (zinc-900) automatically.
  • Alerts/banners — tinted 5% bg, 20% border, 700 text + left accent bar (daisyUI alert + tone adjustments).
  • Empty states — centred: icon tile (h-16 w-16 rounded-full bg-base-200), title (text-lg font-bold), one hint line, outline action button.
  • Progress bars — h-2 rounded-full bg-zinc-100, fill rounded-full in tone colour.
  • Motion — transition-all duration-200/300 on hovers/toggles; brightness bump on hover; fade-in on the dashboard; tooltips on chart hover.
  • Resolution — responsive: sm:/lg: grid columns, drawer under md:, table scroll inside overflow-x-auto cards.

6. Auth screen (login / sign-up)

Reference pattern (login/register pages) — this is the entry card users see: zinc-100 full-height centred; brand block (large 80px gradient rounded-3xl tile + wordmark) centred above; a white rounded-3xl card with shadow-xl holding the form; inputs bg-white rounded-2xl px-6 py-4 focus:border-zinc-500 focus:ring-zinc-500/30; the CTA is a full-width near-black rounded-2xl button. In this repo the auth lives on /signin (better-auth client calls) — its sign-in section follows this pattern.

7. Implementation map (how the reference lands in this repo)

  • src/app.css — token layer from §2/§3 (monochrome §195): zinc/base surfaces, zinc-900 primary, zinc-600 accent, radii (selector/field/box 0.5/0.5/1.25rem, so cards get the reference 20px), Inter, zinc-50 thead, zinc-900 row-hover bar. daisyUI light --default pin untouched.
  • src/routes/+layout.svelte — the §4 shell (§52) with the decluttered work nav (§53).
  • src/app.html — Inter font links.
  • Screens — per UIPATTERN.md (lists, forms, queues, dashboards), with plain-language wording (declutter §53 pass across all pages).
  • Known deviations (deliberate): the home dashboard keeps the BOARDS-A card-grid pattern (owner-frozen spec) rather than the reference's chart-heavy dashboard; daisyUI components substitute Tailwind-only classes with the same visual result.

8. Conformance checklist (every new or edited screen)

  • Page wrapper + page header (title, ≤90-char plain subtitle, one CTA).
  • No own navbar / ← Home chrome (shell navigates).
  • daisyUI components for all controls; raw utilities only for shell chrome/icon tiles/grids.
  • Light only — no data-theme, no dark classes, no prefersdark.
  • Plain language — no stage codes, internal refs, arrows in labels, →/@/(OCR later) suffixes.
  • Mobile-first — columns collapse, tables scroll in cards, taps stay large on queue screens.
  • Append-only respects mandates — no edit/delete UI, corrections are amendment events.