Presentation Tiers¶

Document: docs/product/presentation-tiers.md
Status: Canonical — all UI component briefs must conform to this document
Last updated: 2026-04-06
Authority: Tim Rignold, UCCA Inc

Purpose¶

This document defines the canonical presentation tiers for all five RTOpacks primitive objects, the data contract at each tier, the KN integration pattern, the print primitive, and the mobile posture. Every component brief is measured against these definitions.

Package¶

All shared presentation components live in:

packages/training-ui/src/
  unit/
  qualification/
  skill-set/
  rto/
  general-ed/

Package name: @rtopacks/training-ui

This package replaced the previously proposed @rtopacks/qual-ui. The scope covers all five primitive objects, not just qualification/unit.

Turbopack constraint: Due to Turbopack's file: resolution issue in Cloudflare builds, @rtopacks/training-ui cannot be natively imported by consumer apps. The resolved pattern is a prebuild sync script (established in SHARED-01). The sync script copies from packages/training-ui/src/ to apps/[surface]/components/training/ before each build. This script runs as a pre-commit hook and a CI gate. Source of truth always lives in packages/training-ui/src/.

The Four Tiers¶

Every object has four presentation tiers. The tiers are data contracts, not just visual sizes.

Tier 1 — Chip¶

Purpose: Inline reference. Non-interactive or minimally interactive. Used where an object needs to be named and identified but not explored.

Minimum data contract: - Code (e.g. BSBWHS411) - Title (short form where available, full title otherwise) - Status badge (current / superseded / deleted)

Where it appears: - Breadcrumbs - Tag lists and scope lists - Admin compliance references - Workspace Studio scope selectors - Related object references within Drawer and Page tiers

KN: Not applicable at Chip tier. KN content never appears in a Chip.

Mobile: Chip is always responsive — it is a small inline element by nature.

Print: Chips render as plain text in print context — code + title, status badge omitted or rendered as text.

Tier 2 — Card¶

Purpose: Scannable list item. The primary unit of search results, browse grids, and list views. Contains enough information to evaluate relevance without drilling in.

Minimum data contract (all objects): - Code - Title - Status badge - Object type indicator (unit / qual / skill set / rto / gen-ed)

Extended data contract by object:

Object	Additional Card fields
Unit of Competency	Field of education, training package, KN indicator (boolean only), currency
Qualification	AQF level, field of education, unit count, RTO delivery count, KN indicator
Skill Set	Unit count, associated licence/requirement (if known)
RTO	State/territory, delivery mode (classroom/online/workplace), active status
General Education Unit	Skill domain (literacy/numeracy/digital/social), UCCA-assigned

Variant prop — Workspace Studio:

<QualCard
  variant="workspace"
  selected={isSelected}
  onSelect={handleSelect}
/>

The variant="workspace" prop adds selection state chrome and drag handle. The base component has no knowledge of workspace state — the variant prop unlocks surface-specific behaviour. One component, not two.

KN at Card tier: Boolean indicator only. A visual signal that KN enrichment exists for this object. Not a preview, not a snippet. The user must go to Drawer or Page tier to access KN content.

Mobile: Cards are fully responsive. Single-column stacking below 640px.

Print: Cards do not have a meaningful print context — they exist in list/grid views that do not translate to print. If a list of cards is printed, it renders as a simple text list with code and title only.

Tier 3 — Drawer¶

Purpose: Expanded detail without navigation. The user stays on their current surface; the drawer opens over or alongside the current view. Contains the substantive content of the object. This is where the user decides whether to go deeper.

Minimum data contract (all objects): - All Card fields - Full description / overview text - Related objects (linked chips) - Metadata (dates, package, version)

Extended data contract by object:

Object	Additional Drawer fields
Unit of Competency	Elements of competency, performance criteria, required skills and knowledge, range of conditions, evidence guide, skill set memberships, qualification memberships, KN payload (if available)
Qualification	Full unit list (core + elective groups), packaging rules, entry requirements, skill sets within this qual, RTO delivery count, KN payload (if available)
Skill Set	Unit list, licensing/regulatory context, parent qualification references
RTO	Full contact details, delivery footprint, registration status, scope summary, Radar profile (if available)
General Education Unit	Learning outcomes, assessment approach, skill domain detail, contextualisation notes

KN at Drawer tier: Full kn_criteria_reasoning payload rendered in its own section within the Drawer. KN section is conditionally rendered — if kn prop is absent, the section either shows a locked/upgrade state or is omitted entirely depending on the user's access tier.

KN prop pattern:

interface DrawerProps {
  object: UnitOfCompetency | Qualification // etc
  kn?: KNPayload  // optional — absent = no KN for this object or user not entitled
}

The Drawer component never fetches KN data itself. Data is passed down from the surface's data layer. This preserves the sacred count rule — no component in @rtopacks/training-ui has direct access to kn_criteria_reasoning.

Mobile: Drawer renders as a full-screen bottom sheet on mobile. All content remains accessible, scroll-within-drawer behaviour. Close button prominent.

Print: Drawer content is printable via the print primitive (see Print section below). Print output includes the universal print footer.

Tier 4 — Page¶

Purpose: Full canonical view. Owns its own URL. Contains everything including live data, maps, and surface-specific interactive features. The most fully realised implementation.

Current state: The public site /qual/[code] page is the most realised Page implementation. It serves as the reference point.

Minimum data contract (all objects): - All Drawer fields - Tabbed or sectioned navigation for content areas - Live data where applicable (market data, delivery counts)

Extended data contract by object:

Object	Page-specific features
Unit of Competency	Full competency detail tabs, KN deep view, related quals/skill sets map, RTO delivery, gauge animations
Qualification	4-tab layout (Detail / Units / Market / RTOs), gauge animations, VideoDissolve background, FindRTOsMap, cycle timers, labour market data
Skill Set	Unit list with detail, licensing context, RTO delivery
RTO	Full RTO profile, scope of registration (quals and units), delivery footprint map, Radar intelligence panel, contact and governance
General Education Unit	Learning outcomes in full, assessment detail, contextualisation guide, UCCA delivery notes

KN at Page tier: Full KN section as per Drawer, plus any Page-specific KN features (e.g. interactive competency explorer if built).

Mobile: Page tier renders responsively for content sections. Map components (FindRTOsMap) degrade gracefully on mobile — simplified view or static fallback. Complex interactive features (gauge animations, cycle timers) may be simplified on mobile. See routing-structure.md for Workspace Studio designer mobile posture.

Print: Page tier is fully printable via the print primitive. Print output is a clean single-column document with all content sections. Maps and interactive elements are replaced with static summaries or omitted in print context. Universal print footer applied.

KN Integration — Canonical Pattern¶

Knowledge Navigator (KN) is a conditional layer, not baked into components. The rules are absolute:

Chip tier: KN never appears. Not even an indicator.
Card tier: Boolean indicator only — a visual signal that KN data exists. No content, no preview.
Drawer tier and above: Full kn_criteria_reasoning payload, passed as optional prop. Component never fetches KN itself.
The component is never the gatekeeper. Access tier gatekeeping happens at the data layer, not in the component. If the kn prop is present, the component renders it. If absent, the component renders the absent state. The surface decides whether to pass it.
KN sacred count: 15,128 units. Never modified without Tim sign-off. See object-model.md.

KN rendering standard: See docs/ops/kn-personality-standard.md for full KN character and rendering rules. KN components in @rtopacks/training-ui must conform to that standard.

Print Primitive¶

Print is a universal primitive across all surfaces and all tiers from Drawer upward. It is not a compliance-mode-only feature. It is a shared component called by any surface that needs to produce a printed or PDF output.

Print Component Location¶

packages/training-ui/src/print/
  PrintWrapper.tsx       — universal print wrapper
  PrintFooter.tsx        — universal print footer
  PrintHeader.tsx        — configurable print header (L4 customisable)
  usePrint.ts            — print trigger hook

Every printed document, regardless of object type, surface, or user tier, includes the following footer:

Field	Source
RTO name and number	L4 org record (if applicable)
Printed by	Authenticated user full name
Date and time printed	Server timestamp at print trigger — not client time
Document reference	Object type + code + version
Uncontrolled document notice	Fixed text: "Once printed, this document becomes uncontrolled. Verify currency at source before use."

If the user is not at L4 (e.g. a UCCA staff member printing), the RTO field shows the UCCA entity instead.

Print Logging¶

Every print event is logged to ops-db regardless of surface or tier:

print_log {
  id
  user_id
  org_id          // L4 org if applicable
  object_type     // unit | qual | skill-set | rto | gen-ed
  object_code
  surface         // site | workspace | admin | ops
  format          // print | pdf
  timestamp       // server time
  session_id
}

L4 org owners can view the full print log for their organisation via /settings/activity in Workspace Studio. This is a governance tool — RTO principals have a legitimate need to see who is printing compliance documentation.

Print Trigger¶

The print primitive is invoked by a print button on any Drawer or Page tier component. In compliance mode, the print button is always visible and prominent. In other modes, it may be in a secondary actions menu.

L4 Print Header Customisation¶

RTO clients at L4 can configure their print header — logo, org name presentation, contact details. This is part of the L4 customisation layer (see l4-customisation.md). The footer is not customisable — it is a compliance element and must remain consistent.

Print Output Format¶

Default print output renders to browser print dialog. PDF generation uses the same print template rendered to PDF via Worker. Format options by tier — see security-posture.md for export format policy.

Mobile Posture¶

Component tier	Mobile behaviour
Chip	Always responsive — inline element
Card	Fully responsive — single column below 640px
Drawer	Full-screen bottom sheet on mobile
Page	Responsive content sections — map and complex interactive components degrade gracefully

Minimum screen widths:

Surface	Minimum width	Below threshold
Public site	None — fully responsive	N/A
Workspace Studio — browse/view	640px	Degraded but functional
Workspace Studio — designer/builder	1280px	Graceful message, view mode only
Admin panel	1024px	Graceful message
Ops console	1280px	Desktop only

Graceful degradation: When a surface is accessed below its minimum width, the product does not break or present an unusable interface. It renders a clear, friendly message explaining what is available on the current device and what requires a larger screen. The user remains authenticated and can access what is available.

Component Naming Conventions¶

Object	Chip	Card	Drawer	Page
Unit of Competency	`UnitChip`	`UnitCard`	`UnitDrawer`	`UnitPage`
Qualification	`QualChip`	`QualCard`	`QualDrawer`	`QualPage`
Skill Set	`SkillSetChip`	`SkillSetCard`	`SkillSetDrawer`	`SkillSetPage`
RTO	`RTOChip`	`RTOCard`	`RTODrawer`	`RTOPage`
General Education Unit	`GenEdChip`	`GenEdCard`	`GenEdDrawer`	`GenEdPage`

All components are exported from their object subdirectory and re-exported from the package root.

Design System¶

All components in @rtopacks/training-ui conform to Design Foundation (see design-foundation.md). The Foundation overrides all defaults. No Claude-default palettes, no generic component library styling unless explicitly wrapped in Foundation tokens. Every brief that produces a component must reference the Design Foundation document.

Amendment Log¶

Date	Change	Authority
2026-04-06	Initial document created — first formal expression of presentation tiers	Tim Rignold

Presentation Tiers¶

Purpose¶

Package¶

The Four Tiers¶

Tier 1 — Chip¶

Tier 2 — Card¶

Tier 3 — Drawer¶

Tier 4 — Page¶

KN Integration — Canonical Pattern¶

Print Primitive¶

Print Component Location¶

Universal Print Footer¶

Print Logging¶

Print Trigger¶

L4 Print Header Customisation¶

Print Output Format¶

Mobile Posture¶

Component Naming Conventions¶

Design System¶

Amendment Log¶