shd.build/docs/DESIGN_SYSTEM.md

SHD.build Design System

This document defines the visual language for SHD.build. New pages should feel like part of the same tactical data network as the admin dashboard, while public pages may use more space and larger editorial typography.

Design principles

1. Tactical, not military cosplay. Use operational language, compact information density, restrained status indicators, and precise alignment. Avoid camouflage, distressed textures, or decorative weapon imagery in utility interfaces.
2. Data first. Hierarchy comes from grouping, typography, borders, and spacing. Admin tools should resemble a dependable control surface rather than a collection of marketing cards.
3. Orange means action. SHD orange identifies primary actions, active navigation, focus, and important values. It should not cover large areas.
4. State is always visible. Loading, disabled, active, archived, configured, error, and success states need both visual and textual indicators.
5. Square and engineered. Panels and controls use square corners, fine borders, tight spacing, and deliberate grid alignment.

Tokens

The canonical tokens live in src/app.css under :root.

Purpose	Token	Value
Page background	--shd-bg	#0a0c0d
Base surface	--shd-surface	#111415
Raised surface	--shd-surface-raised	#141718
Primary border	--shd-border	#303536
Main text	--shd-text	#ecebe5
Muted text	--shd-text-muted	#858b8d
SHD action orange	--shd-orange	#f6a821
Success	--shd-success	#75c08c
Destructive/error	--shd-danger	#df8069
Informational/defensive	--shd-info	#70b9d6

Use the spacing tokens for new components. Prefer 8px, 12px, and 20px gaps. Dashboard controls use the shared 40px height when practical.

Typography

• The current UI stack is Arial, Helvetica, sans-serif.
• Page and module headings are uppercase, heavy, and tightly spaced.
• Eyebrows and table labels use 7–10px text with 1–2px letter spacing.
• Body and form text should normally remain between 9–12px in dashboards.
• Public/editorial copy may use Georgia for a restrained field-manual character.
• Never use low-contrast tiny text for information required to complete a task.

Layout patterns

Public pages

• Maximum content width: approximately 1400–1640px.
• Larger headings and more generous vertical rhythm are appropriate.
• Preserve the grid background and orange accents.

Admin dashboard

• Use admin-page, admin-command, admin-dashboard, admin-sidebar, and admin-content.
• Each module starts with module-toolbar, followed by module-kpis.
• Editors use dashboard-editor and appear before the affected table.
• Data collections use dashboard-table, dashboard-row, and table-heading.
• Keep tables dense and horizontally scrollable rather than wrapping columns unpredictably.

Forms

• Labels are uppercase and letter-spaced.
• Inputs use dark surfaces, one-pixel borders, and clear disabled styling.
• Related min/max fields remain visually paired.
• Primary save actions sit at the lower right. Cancel is secondary.
• Destructive/archive actions are visually separated from save actions.

Interaction rules

• Every interactive element needs a pointer cursor unless disabled.
• Buttons have hover, pressed, focus-visible, pending, and disabled states.
• Forms that send requests should use PendingForm.svelte or equivalent enhancement to prevent duplicate submissions.
• Pending buttons use aria-busy="true" and remain disabled until the request completes.
• Respect prefers-reduced-motion.

Color semantics

• Orange: primary action, current location, selected operational value.
• Green: online, active, configured, or successful.
• Red: destructive action, error, or offensive classification when context requires it.
• Blue: defensive or informational classification.
• Gray: inactive, archived, unavailable, or supporting metadata.

Do not communicate state by color alone; include a label, icon, or pattern.

Responsive behavior

• Collapse the dashboard sidebar into a two-column module grid below 900px.
• KPI tiles become two columns on small screens.
• Tier editors stack vertically on tablets.
• Tables retain a useful minimum width and scroll horizontally.
• Primary and secondary toolbar actions may expand equally on narrow screens.

Adding a new admin module

1. Add the route beneath src/routes/admin.
2. Register it in the admin layout navigation.
3. Start with the module toolbar and KPI row.
4. Reuse dashboard editor and table classes.
5. Use the shared tokens instead of introducing near-duplicate colors.
6. Verify keyboard focus, pending behavior, empty states, mobile layout, and archived data behavior.

If a new interface needs a genuinely new pattern, document it here when introducing it.