Design Foundation¶
Document: docs/product/design-foundation.md
Status: Canonical — all UI briefs must conform to this document. Foundation overrides all defaults.
Last updated: 2026-04-06
Version: v1.22
Authority: Tim Rignold, UCCA Inc
Purpose¶
This document defines the RTOpacks Design Foundation — the visual and interaction language of the product. Every component, surface, and UI brief is measured against this document. The Foundation is not a suggestion — it overrides all defaults, all component library defaults, and all AI-generated UI defaults. Nothing ships that contradicts the Foundation without explicit Tim sign-off and a recorded amendment.
The Foundation Rule¶
The Foundation overrides everything. No Claude-default palettes. No generic component library styling unless explicitly wrapped in Foundation tokens. No AI-generated UI that hasn't been evaluated against this document. When a brief produces a component and that component is reviewed against the Foundation and found non-conforming, the component is rebuilt — not patched.
This rule exists because the cumulative effect of small visual inconsistencies compounds into a product that feels generic, untrustworthy, and inconsistent with the premium intelligence positioning that RTOpacks requires.
Visual Language¶
Aesthetic¶
RTOpacks is a professional intelligence product for a regulated industry. The visual language reflects:
- Precision — information is presented clearly, without visual noise
- Authority — the product conveys that it knows its domain deeply
- Calm — the interface does not excite or alarm; it informs
- Contemporary — not corporate legacy, not startup casual — a serious modern product
The Workspace Studio surface uses the Liquid Glass aesthetic established in the AppGrid — glass icons, layered transparency, depth. Other surfaces (admin, ops) are more direct and utilitarian while remaining within the Foundation.
Typography¶
- Primary font: Anthropic Sans (or the platform-resolved equivalent)
- Weights: 400 (regular) and 500 (medium) only. Never 600 or 700 — they read heavy against the host UI.
- Sizes: 22px (h1), 18px (h2), 16px (h3/body), 14px (secondary/label), 12px (caption/meta)
- Line height: 1.7 for body, 1.3 for headings
- Case: Sentence case always. Never Title Case. Never ALL CAPS in UI elements.
Colour¶
Foundation colours are defined by token, not by hex value, so that they adapt correctly to light and dark mode. The following are the canonical colour categories:
Backgrounds:
- Primary: --color-background-primary (white / near-black)
- Secondary: --color-background-secondary (surfaces, cards)
- Tertiary: --color-background-tertiary (page background)
- Semantic: info, danger, success, warning variants
Text:
- Primary: --color-text-primary (black / white)
- Secondary: --color-text-secondary (muted)
- Tertiary: --color-text-tertiary (hints, meta)
- Semantic: info, danger, success, warning variants
Borders:
- Tertiary: --color-border-tertiary (default — 0.15 alpha)
- Secondary: --color-border-secondary (hover — 0.3 alpha)
- Primary: --color-border-primary (active — 0.4 alpha)
No custom hex values in component code. All colour references use CSS variables. This ensures dark mode works correctly across all surfaces without separate dark mode stylesheets.
No Claude-default palettes. This means: no default blue-on-white component library aesthetics, no generic purple/blue accent schemes, no default Tailwind colour utilities used as the design intent. Foundation tokens are the design intent.
Spacing and Layout¶
- Border radius:
--border-radius-md(8px) for interactive elements,--border-radius-lg(12px) for cards,--border-radius-xl(16px) for modals and drawers - No gradients on interactive elements
- No drop shadows on UI components (reserved for elevated surfaces like modals)
- No blur effects as primary UI treatment
- Stroke width: 0.5px for borders and diagram edges — thin strokes feel refined
Mode Visual Treatment¶
The mode system (see mode-system.md) has visual indicators that must be consistent across all surfaces:
| Mode | Visual treatment |
|---|---|
| LIVE | Neutral / default — no accent, standard Foundation UI |
| GUIDED | Warm accent colour — approachable, instructional |
| COMPLIANCE | Formal accent colour — authoritative, regulatory |
Specific token values for mode accents to be defined when mode indicator component is built.
Compliance Mode Colours¶
Compliance mode uses a deliberately distinct visual language — formal, document-styled, regulatory in character. These tokens define the compliance annotation card palette:
| Token | Value | Usage |
|---|---|---|
--rp-compliance-bg-primary |
#FFF8E7 |
Card background |
--rp-compliance-bg-secondary |
#F0D9A0 |
Card border |
--rp-compliance-text-dark |
#01497C |
Heading text, left accent border |
--rp-compliance-text-secondary |
#2C3E50 |
Body text |
--rp-compliance-text-muted |
#7F8C8D |
Clause text, italic references |
--rp-compliance-warning |
#7F6000 |
Unmapped element warning |
These are intentionally light-mode values — compliance annotation cards are always rendered in a formal light style regardless of the surface's dark/light mode setting.
Component Standards¶
Hierarchy¶
@rtopacks/ui— Foundation primitives: Button, Badge, Tab, Input, Modal, Drawer shell, etc.@rtopacks/training-ui— Domain components: all five object tiers (Chip/Card/Drawer/Page per object)- Surface components — app-specific compositions that consume the above packages
Turbopack Constraint¶
Both packages use the sync script pattern (established in SHARED-01) due to Turbopack's file: resolution issue in Cloudflare builds. Sync script is a pre-commit hook and CI gate. Source of truth always in packages/.
Component Rules¶
- Every component is dark-mode compliant by default — tested in both modes before merging
- No hardcoded colour values in component code — CSS variables only
- No component imports platform-specific data or makes API calls — data is always passed as props
- Print styles are included in every Drawer and Page tier component — not added later
- Mobile responsive behaviour is defined and tested for every component — not retrofitted
KN Components¶
All KN rendering within @rtopacks/training-ui conforms to docs/ops/kn-personality-standard.md. The KN rendering standard is a separate canonical document — this Foundation document does not duplicate it. The key rules:
- KN text: white TGA text, green KN label stacked below — never side by side
- KN is a character, not a tool — "care given, no responsibility taken"
- KN section is visually distinct from platform content and RTO annotation
Asset Standards¶
EXT-ASSET rule: All assets used in core UI are self-hosted. No CDN dependencies for core UI assets. This applies to fonts, icons, images, and any other static asset that affects the rendered appearance of the product.
Exceptions: - CDN-hosted libraries (cdnjs, esm.sh, jsdelivr, unpkg) are permitted for JS libraries only — not for visual assets - Third-party map tiles (Mapbox) are permitted for map surfaces — this is a defined external dependency
Asset hosting: All self-hosted assets are served via Cloudflare R2 or Workers. No third-party image CDNs for product UI assets.
Print Design Standards¶
Print output must be clean, professional, and ASQA-presentable. It is not a screen capture — it is a designed document.
Print layout principles: - Single column — print is not a responsive grid - All decorative UI elements stripped in print context — no gradients, no glass effects, no background colours on containers - Typography carries the document — headings, body text, clear hierarchy - Tables render with clear borders — screen hairlines are invisible on print - Maps and interactive elements replaced with static summaries or omitted
Print header: Configurable at L4 (see l4-customisation.md)
Print footer: Universal, non-configurable (see presentation-tiers.md)
Page setup: - A4 portrait as default - 20mm margins all sides - Page numbers in footer alongside universal footer content - Document title and object code in running header
Responsive Design Standards¶
Breakpoints:
| Name | Width | Notes |
|---|---|---|
| Mobile | < 640px | Single column, bottom sheet drawers |
| Tablet | 640px – 1024px | Two column where appropriate |
| Desktop | 1024px – 1280px | Standard desktop layout |
| Wide | > 1280px | Designer/builder minimum width |
Mobile-first: All components are built mobile-first and enhanced for larger screens. The exception is the Workspace Studio designer which is desktop-only by design — it is built for wide screens and degrades gracefully below 1280px with a message rather than a broken layout.
Amendment Log¶
| Date | Change | Authority |
|---|---|---|
| 2026-04-06 | Initial document created — formalising Foundation v1.22 as standalone canonical doc | Tim Rignold |