# UI System

Status: v0.7 (2026-10-22) — Phases 0-4 implemented with visual modernization; the verified shared six-column outer grid and independent Presentation content layout are documented in [Presentation Grid Architecture Baseline](PRESENTATION-GRID-ARCHITECTURE-BASELINE.md). Focused implementation verification is complete; protected STAGING release and browser acceptance remain release evidence.

## Scope and Evidence

Status: reusable visual/interaction baseline and target acceptance guidance, 2026-09-11; not a claim that every existing control works.
This document owns tokens, layout and reusable interaction patterns. [Views and content](../architecture/views-and-content.md) owns model-driven presentation, content and rendering contracts.
[Identity and governance](../architecture/identity-and-governance.md) owns permission/approval semantics; [objects and types](../architecture/objects-and-types.md) owns definition validity.
Business composition follows [composition and extensibility](../product/definition.md#composition-and-extensibility), not a separate UI specification or renderer for any domain label.
Documentation authority and lineage belong to [documentation governance](../governance/documentation.md) and the [source map](../governance/source-map.md).
The existing fixed marketing navigation, module-mirrored sitemap and "Marketing OS" subtitle are superseded as platform requirements.

## Approved dashboard design-to-Presentation mapping

The approved Pastel SaaS Business Dashboard reference is the acceptance
target for the authenticated workspace composition. It is implemented through
the generic Presentation graph rather than a dashboard template:

| Reference region | Persisted Presentation expression | Delivery responsibility |
|---|---|---|
| Welcome heading and date range | A `page_header` container with explicit `heading`, `subheading` and `date_range` children | Semantic HTML, spacing and responsive header alignment |
| KPI row | Three `kpi_card` containers with `metric` children and charts only where an authorized numeric source exists | Aggregate formatting, empty-state text and compact chart accessibility |
| Capability grid | Eight `dashboard_card` containers with data-defined child order and explicit navigation targets | Six-column packing, surface treatment and responsive reflow |
| People and record summaries | `avatar_group` and `record_list` declarations selecting authorized fields | Text/initial delivery, truncation and accessible labels |
| Project progress | `progress` declaration with an explicit authorized status field and completed values | Bounded progress bar and unavailable/empty state |
| Contextual AI panel | `callout` declaration with explicit title, description and governed action state | Informational panel and disabled/unavailable action treatment |

Dashboard capability cards and standalone capability pages are separate
persisted Presentation Objects. A dashboard card may expose an exact
`navigation.target` reference to its page root, while retaining its own
compact `dashboard_card` composition for the dashboard. The page root uses the
same generic display vocabulary and authorized sources, but owns the
capability's page-level hierarchy and content density. Neither distinction
requires a capability-specific renderer or CSS branch.

The graph supplies composition, semantic labels, source declarations and
navigation. It does not turn the reference image's sample numbers, trend
percentages, thumbnails or imagery into business facts. Where the Business
has no authoritative measurement history or authorized media reference, the
runtime shows an honest unavailable state. This preserves the analytics
contract and prevents visual completion from fabricating data.

The approved Pastel SaaS Capability Pages reference is expressed the same way.
Each capability root (Products & Services, Projects, Finance & Accounts and
the other capabilities) composes, in order, a `page_header` (icon, heading,
description, actions), three metric or progress surfaces with declared
captions, and one `record_list` with `presentation: "table"` that carries the
search box, status tabs, badge, currency and date columns and row links. The
shared CSS provides the table, badge, tab and toolbar treatments for any
`record_list` that declares them; the capability names exist only in the
profile. The grid uses `grid-auto-rows: auto` so a short header or KPI row is
not stretched to a minimum surface height, and surfaces in a row stretch to a
common height. There is no system minimum card height: a surface's
`min-height` is emitted only when a Presentation Object or a saved user
preference declares `preferred_height` (any integer of 1 rem or more), and
content always grows the surface so nothing is clipped. Width is the
documented enum of 2, 3, 4 or 6 of six columns, so the narrowest surface is
one third. The page header is not an editable surface and is excluded
from layout preferences and drag handling. Search and tab filtering is
delivered by `presentation-lists.js` from the data attributes the renderer
emits.

All eight capability pages follow that composition, extended with grouped
`chart` surfaces (inline SVG bar, hbar, line and donut, drawn from
`group_field` aggregation of authorized records) and further tables. Collection
pages (`/objects?type_id=...`) render a single table from the record template's
`display.collection`, and record detail pages render a header, labelled
`dl` sections and related collections from `display.detail`. Charts keep
their data meaning on small screens: every point is present in the SVG and in
an accessible text summary, and no bars are hidden responsively.

Shared interaction contract (2026-10-28, generic CSS/JS only):

- Compact controls (list filter tabs, sortable column headers, chart
  granularity options, calendar navigation) share one state model: neutral by
  default, an accent-soft background with accent-strong text on hover (so the
  text keeps contrast), a solid accent with white text when selected
  (`aria-pressed="true"`), a visible `:focus-visible` outline, and no global
  button shadow or teal hover leaking in.
- Compound search inputs (`.topbar-search`, `.presentation-list-search`) own
  their border, hover and `:focus-within` ring on the wrapper; the inner input
  draws no outline, so there is a single focus indication. Disabled and invalid
  states are handled at the wrapper.
- Collection title, toolbar and table header spacing come from the
  `--list-title-gap`, `--list-block-gap` and `--list-head-pad` tokens.
- Calendar events use a restrained translucent tone fill, a 1px translucent
  border and a solid left accent; dashed borders mark an event that continues
  from or past the visible week. Grid lines remain visible beneath the fill.
- Chart marks and legend items are keyboard-focusable (`tabindex="0"`, with an
  `aria-label`), use `cursor: help`, and show the same tooltip on hover or
  focus; legend hover/focus highlights the matching mark and vice versa;
  Escape dismisses the tooltip.
- Chart naming: a chart's `label` names the measure only (it becomes the
  tooltip heading and accessible name); `title` is the visible heading. Neither
  may bake in a time grain, because `granularities` lets the reader switch
  between periods (a label such as "Responses by month" would be wrong under
  Quarter). Use "Responses" and "Responses over time".
- KPI card with history: a `kpi_card` container composes an `icon`, a `metric`
  and a time-series `chart` using the existing contract (`group_field`,
  `group_bucket`, `granularities`, `trend: true`). The chart's `filters` must
  equal the metric's, so the line and the headline value measure the same
  records. Set `trend` only for records dated in the past; forward-dated
  records (forecasts) are a schedule and omit it. Records without a declared
  date field must not be used as history (see PRR-051).
- KPI card layout (shared CSS, no per-capability rules): row 1 is a compact
  icon beside the stacked label, figure and caption; row 2 is the granularity
  control; row 3 is the full-width chart and trend text. A card containing a
  chart aligns to the top so a row of cards with and without a trend line stays
  level; a metric-only card keeps its content centred.
- Metric-only KPI cards (temporary decision, PRR-055): a `metric` or `progress`
  surface with no chart declares `preferred_height` 6 so it is as tall as its
  content (the Marketing precedent), not the 12 reserved for chart-enabled
  cards. `preferred_height` is a minimum; content always wins; saved layout
  preferences (PRR-053) still override the authored value. KPI history inventory
  and per-KPI rationale for staying metric-only: PRR-051.
- Time axis and trend semantics (temporary decision, PRR-054). The projector
  emits a contiguous axis for time buckets: a period with no records is `0`,
  not omitted, and every point carries `complete` (its end date is before the
  server's current date). The trend compares the latest complete period with
  the complete period immediately before it, states both periods, and names any
  later periods it excluded as incomplete. A previous value of 0 reads "No
  comparison: no recorded activity in the previous <period>."; fewer than two
  complete periods reads "Not enough complete periods to compare.". Incomplete
  periods have a hollow dot and "(period not ended)" in the tooltip.
- Granularity gating: a line chart offers only the granularities that yield at
  least two periods from its data (so Year appears only when the records span
  two calendar years); with fewer than two periods at every grain the chart
  shows the generic "Not enough history to show a trend yet." state instead of
  a degenerate line.

Display metadata is renderer-neutral and shared by Dashboard, capability and
ordinary object contexts. Capability names are profile content, not renderer
conditionals. The generic renderer owns only HTML, CSS, accessibility,
responsive behavior, and serialization of already-authorized targets.

## Owner-provided visual reference

The [Pastel SaaS Business Dashboard reference](reference-assets/pastel-saas-business-dashboard.png)
is the standing visual reference for future UI work. Use it when evaluating or
designing dashboard, navigation, capability-card, metric-summary and related
authenticated workspace surfaces.

This reference establishes visual direction, not an alternative presentation
model or hard-coded dashboard content. The persisted Presentation Definition,
generic renderer, authorization and exact Object references remain
authoritative. Future UI changes should preserve the reference's light
workspace, generous spacing, rounded surfaces, restrained shadows, compact
navigation, clear metric hierarchy and purple/teal accent balance unless a
new owner-approved reference supersedes it.

Reference palette:

| Role | Token value |
|---|---|
| Primary purple | `#A056B0` |
| Secondary teal | `#4DAD98` |
| Tertiary blue | `#4263A5` |
| Tertiary coral | `#DB5C6B` |
| Tertiary gold | `#D4A72C` |

When implementing UI work, consult this reference and palette first, then
reconcile the result with the canonical Presentation contract and the
responsive/accessibility rules below.

## Renderer Boundary for Model-Driven Presentation

The UI layer is a delivery mechanism for the Presentation Definition and persisted Presentation Object contract owned by [Views and Content](../architecture/views-and-content.md). Persisted Presentation Objects and authorized projection own presentation content, semantic roles, recursive structure, ordering, behavior references and targets.

HTML delivery may own tags, escaping, CSS classes, accessibility attributes, browser interaction mechanics and conversion of semantic targets into delivery URLs. It must not decide that a field is a heading, label, badge, button, card, navigation item or action, and it must not invent application content or relationships.

Capability, Dashboard and ordinary Object paths converge on `RenderablePresentation` and the single generic `presentation.php` renderer. There are no domain-specific Dashboard, Capability, Project, card or CapabilityCard renderers in the target architecture; the former Dashboard/Capability templates remain deleted. Capability-specific template vocabulary and PHP-shaped conventions are not part of the target UI contract. The persisted recursive Presentation Object path is the only rendered and inspectable UI path; legacy collections/items/fields compatibility data is not authoritative and is not delivered by the generic renderer.

The generic renderer is required to provide platform-level delivery
capabilities including a shared six-column outer body grid, Presentation
Object surfaces, independent recursive content layout, positioning, resizing,
drag/drop, layout editing and persistence, generic inspection, accessibility
and responsive HTML delivery. The authenticated page surface uses the
six-column grid to arrange grid-level Presentation Objects; each such Object
renders inside its own generic surface. The surface's recursive content must
not be placed into the parent six-column grid. At narrow viewports, outer
surfaces collapse to one column and internal content reflows to the available
width. Layout editing exposes only direct manipulation affordances: a drag
handle at the top-right and a resize handle at the bottom-right. These are
renderer/platform capabilities, not Dashboard- or Capability-specific
presentation semantics. Renderer authorization is not permitted; authorization
and exact revision resolution occur before `RenderablePresentation` is
produced.

Outer authenticated main-body delivery uses six `minmax(0, 1fr)` columns at
wider viewports and preserves each persisted preferred span (`2`, `3`, `4` or
`6`) with governed packing. Delivery positions are one-based column starts;
narrow viewports collapse outer surfaces to one visual column. Internal PO
content is independent delivery metadata: span 2 is Regular/two columns, and
spans 3, 4 and 6 are Expanded/three columns.
Responsive CSS may reduce the effective internal count without changing the
persisted outer preference. There is no separately persisted internal-column
preference or user-facing mode selector.

### Current implementation boundary

The implementation establishes outer six-column packing only for the current
page-surface list, outer span/order/height persistence and generic recursive
rendering. Recursive content is delivered through an independent
`presentation-content-grid`; descendants do not receive outer row, position or
span metadata. The governed generic preference Type remains revision 2 and
persists only outer layout. Presentation mode and internal content columns are
derived from the effective outer span. No capability-specific renderer or
parallel preference mechanism is used.

The generic Presentation Object inspector is a development/admin delivery capability. It consumes the same authorized recursive `RenderablePresentation.elements` tree as the renderer, uses `data-presentation-object-id` only as delivery metadata, and does not reconstruct presentation structure from collections, items, fields or final HTML. Its toggle is inert when disabled; enabled hover inspection may expose only identity, structure, bindings, targets and layout already present in the authorized projection.

Repeated collection records use a neutral nested summary wrapper when they
appear below another Presentation surface. The wrapper does not acquire the
standalone surface padding, outer-grid span, resize affordances or card
navigation of its parent. A container-level record target is delivered as an
explicit accessible link; it never wraps recursively rendered fields. Field
values remain text unless their own projected target is explicit. This is a
generic delivery rule for all object Types and capabilities, not a
capability-specific visual branch. A nested collection also owns a
full-width internal record list; its items do not inherit the containing
surface's internal grid columns.

Presentation behavior does not create a parallel action model. Presentation Objects may reference governed behavior, while Event, Command and Action mechanisms remain authoritative for execution, authorization and evidence.

## Implemented Visual System (Phases 0-4 + Contemporary Redesign)

**Phase 0: Icon System**
- SVG icon sprite created at `target/assets/icons/icons.svg` (served as `/assets/icons/icons.svg` over HTTP)
- Stroke-based design: 2px stroke-width, round line caps/joins, fill="none", `stroke="currentColor"` for inheritance
- 12 icons defined: icon-overview, icon-menu, icon-x, icon-chevron-right, icon-check, icon-alert, icon-info, icon-globe, icon-settings, icon-user, icon-history, icon-link
- CSS sizing utilities: `.icon-sm` (1rem), `.icon-md` (1.25rem), `.icon-lg` (1.5rem), `.icon-xl` (2rem)
- Usage pattern: `<svg class="icon icon-md"><use href="/assets/icons/icons.svg#icon-name"></use></svg>`
- Navigation items updated to use SVG icons; legacy `.nav-icon` letter-box styling preserved
- **Implemented**: ✓ File exists and is accessible; ✓ SVG syntax valid; ✓ All reference icons present; ✓ Proper currentColor inheritance

**Phase 1: Visual Hierarchy and Spacing Grammar**
- Spacing rules: `.content > .stack { gap: 2rem; }` for page-level section separation; `.stack { gap: 1rem; }` default
- Section pattern: `.section` (styled card container), `.section-header` (flex title/context/status/controls), `.section-title`, `.section-context`, `.section-status`, `.section-content`, `.section-actions`
- Section headers compose flexibly: title required, context/status/actions optional
- Panel pattern: `.panel` for nested/legacy card components (identical styling to `.section` but for secondary uses)
- Convention: `.section` for primary structural containers; `.panel` for nested cards and empty states
- **Implemented**: ✓ All views use `<div class="stack">` (semantic fix); ✓ `.section` elements with structured headers; ✓ PHP syntax valid; ✓ Separation between primary (.section) and nested (.panel) components clear

**Phase 2: Interaction Ownership**
- Page-level actions: `.page-actions` container with flex separation (identity/title group | controls group)
- Section-level controls: positioned in `.section-header` (flex layout allows responsive positioning)
- Object-level actions: Grouped by semantic operation type (navigation/inspection vs. mutation)
- Ownership rule: controls positioned visually near their target content
- **Implemented**: ✓ Page-level actions at view top; ✓ Section structure supports header positioning; ✓ Object actions logically grouped

**Phase 3: Component Refinement**
- **Button states**: primary (filled accent, 2px shadow, `:focus-visible` outline offset 2px), secondary (outline, filled on hover), danger (red variant)
- **Input/select states**: 1.5px border (increased from 1px for touch targets), hover darkens, focus adds accent + 3px shadow, `:focus-visible` adds outline
- **Global focus visibility**: `:focus-visible { outline: 2px solid var(--focus); outline-offset: 3px; }` visible on all interactive elements
- **Preserved tokens**: All color/spacing/radius tokens from original design system used unchanged
- **Implemented**: ✓ Button/input styling complete; ✓ No breaking changes; ✓ Focus visible on all controls

**Phase 4: Contemporary Layout Composition**

*Redesign Principles:* Composition before decoration. Material spatial reorganization of content using desktop space intelligently. Section ownership visually obvious. Controls obviously attached to what they control. Reduce orphan UI elements. Panels not the default answer.

**Dashboard (.layout-dashboard)**
- Desktop (1400px+): Two-column composition (grid-template-columns: 1.2fr 1fr)
  - Primary column: Business Records (wider) — collections/views available in business
  - Secondary column: Operations — available business-level operations
  - Both using `.section` card styling with clear headers and content organization
- Tablet (900px): Stack with preserved visual hierarchy
- Mobile (400px): Single column, records prominent
- Result: Dashboard feels like a workspace with primary content (records) and secondary context (operations), not just a vertical list

**Object List (collection-table-section)**
- Header: Type/label prominently displayed with descriptive context
- Table: Full-width dominant content area inside `.collection-table-section` card
- Controls: Navigation (Back to Overview) positioned top-right in `.page-actions`
- Pagination: Centered, separate from table (between-content separation)
- Empty state: Centered, spacious, clearly readable
- Result: Collection identity and table are visually dominant; controls clearly own their relationships

**Object Detail (.object-detail-layout, .object-identity, .actions-column)**
- Identity area (spans full width): Prominent display of object type and current state
  - Object type shown as context label
  - State displayed as status badge if available
  - Strong visual anchor for "what object am I looking at"
- Desktop (1200px+): Two-column split (40% properties, 60% actions)
  - Properties (left): Definition list of object fields in organized two-column layout
  - Actions (right): Grouped operation buttons organized by semantic category
    - "Inspect" group: History, Relationships, Graph (navigation/analysis operations)
    - "Actions" group: Declared operation, Configured operations (mutations)
- Tablet/Mobile: Stack with preserved logical hierarchy (identity → properties → actions)
- Result: Strong object identity immediately obvious. Property/action relationship clear through spatial arrangement. Control ownership explicit through grouping.

**New Layout Utilities (CSS)**
- `.layout-dashboard`: Two-column split at 1400px, stacks at smaller sizes
- `.object-detail-layout`: Two-column split at 1200px (grid-template-columns: 40% 1fr), spans object-identity across columns
- `.object-identity`: Prominent object header block (background, border, shadow, padding)
- `.action-group`: Vertical grouped actions with label and items
- `.action-group-label`: Label for action group (uppercase, muted)
- `.action-group-items`: Grid container for action buttons (gap: 0.6rem)
- `.properties-column`, `.actions-column`: Semantic column containers in detail layout
- `.collection-header`, `.collection-table-section`: Semantic containers for list view composition

**Responsive Behavior**
- Desktop (1400px): Full multi-column composition with all spatial relationships optimized
- Tablet (900px): Reduced multi-column, maintained spatial hierarchy
- Mobile (400px): Single column, all content stacked, controls inline with content, preserved hierarchy
- Controls remain usable and visually owned at all sizes
- Source CSS preserves the existing drawer and responsive composition; browser viewport, overflow, keyboard, touch and cross-browser behavior require runtime verification.

**Authenticated Shell Ownership**
- `Definitions` is a User/platform control. When the server-side Definitions allowlist permits it, the control remains beneath the User account in the left column and links directly to the canonical `/objects?type_id=...` Definition collection.
- `Manage` is a selected-Business control. It uses the existing server-resolved `/objects/{selectedBusinessId}` route and remains beneath the current Business context beside the Idiosyncrasy branding; membership and selected-context checks remain server-side.
- The mobile workspace header contains one drawer navigation control, the existing Idiosyncrasy branding asset, and the current Business context. Navigation remains data-defined by the persisted Dashboard Presentation Object graph.
- The shared `Edit layout` control and drag/resize client are mounted for every
  `RenderablePresentation` with an exact persisted context reference, not only
  for the Dashboard. A missing context disables the control with an explicit
  unavailable state; saving uses the existing authorized generic preference
  endpoint and does not mutate Business Objects.

**Business Detail Constituents**
- Business Manage reads the existing Business Definition and constituent objects through the established read projection after the existing selected-Business membership/context checks; it adds no new authority requirement.
- Every defined requirement remains visible even when no constituent object exists. Stored nonblank values are `Present`, an existing object/property with a blank or null value is `Empty value`, and an absent constituent object is `Not created`.
- The presentation does not create defaults, seed values or introduce a second Business constituent model. An unavailable Definition or unauthorized Business remains behind the existing fail-closed boundary.

**Source and focused verification**: ✓ All views redesigned with new composition; ✓ Layout utilities and the mobile workspace header are defined and applied; ✓ User/Definitions and Business/Manage ownership contracts are preserved; ✓ Business Definition requirements are rendered with stored-value status; ✓ persisted Object views use the canonical `/objects` Presentation boundary; ✓ Focused presentation integration tests pass (16 tests, 104 assertions); ✓ The existing UI structure check passes. Browser layout, overflow and interaction behavior remain separate runtime evidence.

**Not Yet Tested**: Icon rendering in browser; button/input visual states on screen; horizontal overflow at edge cases; keyboard Tab navigation; touch target verification on mobile; cross-browser rendering

## Contemporary Visual Modernization Summary

**What Changed:** The three representative views have been redesigned through composition, not decoration.

**Dashboard**: Single-column vertical list → Two-column workspace layout with primary content (Records) and secondary context (Operations) on desktop, stacked responsively on smaller screens.

**Object List**: Flat table below header → Collection-focused layout with prominent type identity, visually dominant table, and integrated pagination.

**Object Detail**: Scattered components (status badge, definition list, buttons) → Strong identity area at top, split layout with properties (left) and grouped actions (right) on desktop, stacked on mobile.

**Design Principles Applied**:
1. ✓ Composition before decoration — Real spatial reorganization, not CSS tweaks
2. ✓ Desktop space used intelligently — Multi-column layouts on 1400px, collapsed responsively
3. ✓ Section ownership visually obvious — Groups have clear headers, related content together
4. ✓ Controls attached to content — Action groups positioned semantically (Inspect near inspection operations, Actions near mutations)
5. ✓ Reduced orphan UI — Status badges, controls, headings grouped coherently
6. ✓ Panels not default — Sections and layout structure drive composition, panels used for nested/empty states only
7. ✓ Responsive hierarchy preserved — Mobile composition maintains hierarchy without forcing multi-column to stack incorrectly

**Result**: A person viewing the dashboard, object list, and object detail will recognize this as a redesigned, more contemporary application interface. The spatial composition, control grouping, and information hierarchy are materially different from the single-column document-like presentation.

## Verification Summary

### Implemented & Verified (Code level)
- ✓ Icon sprite file exists, SVG syntax valid, all symbols present
- ✓ Icon CSS sizing utilities defined and working
- ✓ All 3 templates use correct semantic structure (div.stack, proper section/panel usage)
- ✓ Section pattern applied consistently to dashboard, object_list, object_detail
- ✓ Page/section/object action positioning semantics implemented
- ✓ Button/input/focus CSS defined with proper states
- ✓ New layout utilities defined (.layout-dashboard, .object-detail-layout, .action-group, etc.)
- ✓ Responsive CSS rules for 720px mobile threshold and desktop breakpoints
- ✓ CSS redundancy cleaned (no duplicate rules)
- ✓ Existing route and server-owned authority contracts preserved in source
- ✓ PHP 8.3.33 lint passes for the changed source and target templates; standalone editor diagnostics may report template-context variables supplied by `HtmlRenderer`
- ✓ Canonical PHPUnit suite passes: 413 tests, 2,182 assertions, 0 failures; 6 warnings, 2 deprecations and 3 skipped tests remain.
- ✓ Semantic container types clear (section vs. panel)

### Implemented but Not Yet Runtime-Tested
- ⚠️ Icon rendering in actual browser
- ⚠️ Multi-column layout at actual viewport sizes (1400px, 900px)
- ⚠️ Button/input visual states (hover, focus, active) on screen
- ⚠️ Keyboard Tab navigation and focus visibility
- ⚠️ Touch target adequacy on mobile devices
- ⚠️ Horizontal overflow edge cases
- ⚠️ Cross-browser CSS compatibility
- ⚠️ Touch target sizing on mobile
- ⚠️ Cross-browser CSS compatibility

### Not Implemented (Deferred)
- Capability-level navigation architecture (Phase 5+)
- Broad application rollout beyond 3 representative views
- Accessibility baseline compliance testing (Phase 7+)

### Constraint

The current execution environment cannot perform full browser-based visual verification. These items require:
- Browser rendering (Chrome, Safari, Firefox, Edge)
- Viewport testing at multiple sizes (375px, 768px, 1024px, 1400px)
- Keyboard/mouse/touch interaction verification
- Console error inspection
- Performance profiling

Such verification is deferred to Phase 5 acceptance criteria.

## Observed Visual Baseline
- ✅ All template modifications preserve existing functionality and template variables
- ✅ No PHP syntax errors in any modified view
- ✅ Section structure pattern provides flexible, semantic composition
- ✅ Control ownership clearly established through page/section/object-level positioning
- ✅ Component refinement polish without redesign
- ✅ Responsive layout framework defined with tested breakpoints

## Observed Visual Baseline

The former marketing stylesheet and dashboard templates supplied the visual baseline; the current target presentation is owned by `target/style.css` and `resources/views/target/`.
Current pages load Outfit, Bootstrap 5.3.2 and Lucide icons; these are observed dependencies, not an approved new frontend stack.
Outfit and a 260px sidebar supersede the old design prose's Inter and 240px claims about current implementation.

| Token or property | Current shared value | Meaning |
| --- | --- | --- |
| `--sidebar-width` | `260px` | Expanded sidebar width |
| `--header-height` | `60px` | Header token, also repeated in template styles |
| `--brand-sidebar` | `#202d3d` | Dark sidebar surface |
| `--brand-bg` | `#f3f5f9` | Workspace surface |
| `--brand-accent` | `#38A895` | Primary teal accent |
| `--brand-purple` | `#B04AC6` | Secondary accent/current broad button hover |
| `--brand-text` | `#2c3e50` | Main text |
| `--brand-muted` | `#8c9ba5` | Secondary text; contrast must be checked |
| `--brand-border` | `#e1e7ed` | Borders and separators |
| Body | Outfit with system fallbacks, `13px`, weight `300` | Actual shared base typography |
| Headings/weight helpers | `400`, semibold helper `500`, bold helper `600` | Actual helper mapping, not assumed font-name weights |
| Small text helpers | `.fs-7: 0.875rem`, `.fs-xs: 0.75rem` | Templates can override these; not yet centralized |
| Primary button | `5px` radius, `0.5rem 1.25rem` padding | Current shared rule, not the old radius scale |
| Active navigation | `3px` right accent border | Distinct from hover and inactive opacity |

The familiar horizontal logo, 44px profile avatar, restrained workspace surface and compact information hierarchy are reuse candidates.
Verify referenced asset files exist and render before reusing a template; a logo URL in HTML is not asset verification.
Avoid repeating a platform title beside a logo already carrying its name. Business brand colors must not override semantic error/warning meanings.
Do not claim all styling is tokenized: inline colors, spacing, helper overrides and broad `!important` rules remain in the snapshot.
Before expanding the design system, consolidate tokens under an approved theme contract rather than copying these overrides into every view.

## Section and Panel Component Convention

Both `.section` and `.panel` use identical base styling (rounded border, shadow, padding, background). They serve different semantic purposes:

**Use `.panel` for:**
- Nested cards within a larger section (e.g., empty states inside section content)
- Legacy components that predate the section pattern
- One-off card layouts that don't need structure/context/actions
- Example: `<div class="panel empty-state">` within a section

**Use `.section` for:**
- Main structural containers at page level or within stack layout
- Content that warrants a header with title, context, and optional section-level controls
- Grouping related content with semantic structure
- Example: `<div class="section"><div class="section-header">...` at view top level

**Pattern:** A typical view structure is `<div class="stack">` containing multiple `<div class="section">` elements. Within each section, `<div class="panel">` can be used for empty states, nested cards, or other subsidiary components.

Both styling is identical; the distinction is semantic. Do not merge them unless you also consolidate the distinct use cases they represent.

## Layout and Responsive Behavior

Retain the shell pattern: navigation sidebar, context/action header, independently scrollable main workspace.
The current body hides outer overflow; the main content region must remain reachable by keyboard, touch and viewport resizing.
Desktop navigation becomes persistent at `992px`; below that the sidebar translates off-screen with an overlay and open/close controls.
Overlay z-index is `1040`, sidebar `1050`, with a `0.3s` transform transition in shared CSS.
The former marketing templates and JavaScript contained differing toggle IDs/overlay classes; any reuse requires reconciling handlers rather than assuming one universal implementation.
Keep focus within an open mobile navigation surface where appropriate, support dismissal and return focus to its trigger.
The header groups current context, search where functional, and relevant actions; identity/settings access need not be a primary capability destination.
Current content uses `p-3 p-md-4` spacing: 1rem at small sizes and 1.5rem from Bootstrap's medium breakpoint.
Use constrained reading widths for prose/forms and wider available space for tables/editors; avoid decorative nested panels.
Tables need an accessible horizontal-scroll region on narrow screens, forms stack vertically and toolbars wrap without clipping actions.
Tabs scroll horizontally without wrapping; the shared active indicator is a 2px accent underline.
At `768px`, existing campaign/automation rows become denser and hide some descriptions/progress bars; do not hide essential information without another accessible presentation.
Shared conic rings use 100px/130px sizes around the `576px` breakpoint, but template overrides differ; they are visual assets, not metrics evidence.
Do not carry forward the CSS rule that hides alternate small-screen chart bars as an analytics behavior: responsive visualization must preserve data meaning.

## Reusable Component Contract

Use one consistent family of primary, secondary, danger and ghost actions with default, hover, focus, disabled and pending states.
Use Lucide icons for familiar tool actions with accessible names and tooltips; use clear text commands when a symbol alone is ambiguous.
Use swatches for color, tabs for views, segmented controls for modes, toggles/checkboxes for binary settings and suitable inputs/steppers/sliders for numeric values.
Forms need visible labels, help and field-level validation; placeholders are not labels. Mark required fields and preserve entered values on failure.
Tables may provide sorting, search, filtering and pagination only when the underlying behavior exists; show the active filters and result state.
Repeated item cards and rows may expose a primary action; secondary actions must remain independently usable.
Prefer native buttons/links. Any custom clickable row needs keyboard activation, a visible focus state and no competing nested click targets.
Quick-create/edit modals need a title, labels, focus management, cancellation and clear submit feedback; destructive operations need proportionate confirmation.
Keep component geometry stable as loading text/icons appear; long labels, filenames and translated text must wrap or truncate with an accessible full value.

The older spacing proposal, 0.5/0.75/1/1.5/2/2.75rem, is useful as a consolidation candidate, not a currently implemented token set.
The older 6/8/10/12px radius proposal also was not the shared CSS implementation; choose consistent component roles before adopting it.
Prefer compact controls and modest item/modal radii, with unframed section layouts; do not silently publish a second conflicting token specification.

## Actions, Feedback and Accessibility

Use AJAX for in-page saves, tests, deletes, filters, modal submissions and workflow steps by default; retain safe normal form submission where practical.
Reserve full navigation for actual destinations and explicit navigation links. Keep active tabs/panels, scroll position, context and draft input after an in-page action.
Only update committed UI state after the server confirms the relevant effect; distinguish local save, external draft and uncertain external result.
During requests, prevent duplicate submissions, show progress, announce status and restore controls on every exit path.
Show skeletons for loading lists/tables and a bounded spinner/progress state for charts or remote requests without destabilizing layout.
Empty states distinguish no records, filtered-out records, no permission, no selected context and not-yet-collected data.
Errors need actionable inline feedback and retry where safe; preserve drafts and distinguish validation, authentication expiry, forbidden access, conflicts and remote failure.
Success/error/warning/info feedback must be perceivable without color alone; use text, icons and appropriate live regions.
Ensure keyboard navigation, logical focus order, visible focus, label association, contrast, zoom/reflow and reduced-motion behavior.
Test mobile drawers, tabs, row actions, dialogs and previews with keyboard and assistive technology; Bootstrap/Lucide inclusion does not establish compliance.

The final all-controls policy is an acceptance requirement: every offered control performs its defined action or is explicitly unavailable with a reason.
Existing decorative search, export, guidance fields and placeholder workflows do not satisfy it. Do not report them as functional because they look interactive.
No browser/accessibility verification was performed for this documentation-only change; [status](status.md) records the evidence boundary.

## Brand and Asset Editing

Retain the useful Brand organization as a configurable example, not a fixed business schema:

| Section | Useful fields and editing surfaces |
| --- | --- |
| Brand profile | Name, description and target audience |
| Identity | Logos, typography, color palettes, icon/image styles, interactives, motion, guidance/notes |
| Assets | Images, interactives, video, full articles and documents |
| Voice | Mission, vision, values, narrative, positioning, language, tone, key phrases and do/do-not guidance |
| Deliverables | Products, services, descriptions and selling points |
| Content preferences | Post styles, hashtag strategy, CTA styles; print/infographic templates only when in scope |

Text guidance needs a real editor with save/cancel, validation, dirty-state feedback and optional related document upload.
Allow common guidance choices plus free-form notes, for example a restriction on placing type over images; do not force explanatory knowledge into ordinary scalar settings.
Its meaning, provenance and authority belong to [knowledge](../architecture/knowledge.md) and [business model](../architecture/business-model.md).
File-management surfaces can support grid/list views, search/filter/tagging, drag/drop and file-picker upload, previews, names, notes, replacement and downloads when implemented.
Bulk operations require selection, per-file progress/errors and explicit results; rename and file-note editing need actual persistence, not cosmetic labels.
Typography needs font-file or web-font selection, heading/body examples, sizes and light/dark contrast previews with applicable guidance.
Palette editing should keep the visual swatch, validated hex value, human label and primary/secondary meaning together.
Provide in-context previews without losing the active editor; future AI suggestions remain optional proposals with explicit review.

The removed legacy brand view and controller supported three logo slots and palette mutations.
Guidance textareas, typography management, a general asset library and export/document-upload affordances are not established end-to-end functionality.
Upload security, MIME/size limits, SVG handling and storage lifecycle are owned by [security and operations](security-and-operations.md#uploads-and-safe-rendering).

## Page Builder Pattern

The removed legacy automations view provided a title, page/post type, selected site, author brief, Gutenberg markup editor and local preview.
Its preview uses an iframe with an empty `sandbox` attribute and `srcdoc`; this local rendering is not a full WordPress theme/editor fidelity check.
Keep edit, preview, optional generation, local save/resume/discard and remote draft creation distinguishable.
Resource inspection can present block/template/pattern counts, expandable lists, style swatches and font declarations without leaving the editor.
Changing site/context must clearly change the available resource set and guard against applying stale resources to another destination.
Disable generation while pending, keep edits on failure and return generated markup for review rather than claiming automatic approval.
Treat preview isolation and sanitization as boundaries to test, including network resources and malformed markup; a sandbox is not a complete content validator.
Backend fidelity, discovery limits and draft semantics are owned by [WordPress implementation knowledge](wordpress.md), not duplicated per capability here.

## Shared Detail and Reporting Patterns

A useful detail surface combines identity/summary, relevant dates/status, contextual actions and tabs for related content, schedule or measurements.
Campaign list/edit interactions are source examples, but the old proposed campaign-detail hub, calendar and "Publish All" action were not implemented.
Use reusable tables, forms and projections for such views instead of making campaigns the universal organizing center.
A planner may offer month/week modes, explicit date/time editing and drag/drop with a keyboard alternative once scheduling exists.
State badges need labels as well as colors; status transitions must match backend validation and permissions.
Reports can combine compact KPIs, time-series lines and comparison bars with date/scope filters, units, legends, freshness and an accessible data alternative.
Do not interpret missing analytics as zero performance or display invented measures. Calculations/history belong to [analytics and evolution](../architecture/analytics-and-evolution.md).
Activity feeds can reuse refresh, pagination, actor/time labels and empty/error feedback; activity is not unread notification state or delivery history.
Account forms can reuse identity, avatar and password patterns without inheriting the old organization-admin authorization model.
The [initial runtime specification](architecture.md#identity-and-business-context) and [roadmap](../product/roadmap.md) define the first surface under the settled view/governance contracts.

## IDY-010 Surface UI Direction

IDY-010 is the next major stage after the frozen IDY-001 through IDY-009 sequence. It is a thin, genuinely usable Business-facing surface and a product-learning instrument, not a claim that the finished interface exists. It should enable real Business interactions, exercise the model and governed runtime, reveal usability or missing-capability problems and feed later refinement.

The normal human-facing direction is `Register -> Confirm -> Authenticate -> Create Business -> Enter Business`. The interface must not assume a Genesis-created User (persisted under the legacy Type name Principal), Business, special first Business or bootstrap administrator. It should use natural Business concepts and provide context, navigation, useful objects and relationships, understandable state and outcomes, and an extensible path into real work. Raw IDs, Types, repositories, Commands and Attempts remain diagnostic concepts rather than the normal experience.

Existing login/authentication, page-builder/CMS, generic inspection, transition forms, presentation, navigation, Business context and workflow-related surfaces are reuse candidates. IDY-010 should retain, adapt, extend, replace or classify them based on evidence; it does not require wholesale replacement. The initial balance between generic/model-driven views and purpose-built interactions remains an exploration question, including Business creation, Enquiry creation, Qualification, Decision and Project creation.

The Surface UI is not a second mutation system. Every mutation remains subject to the established CommandHandler, validation, authorization, Policy, workflow and evidence boundaries. UI controllers must not write directly to the database, bypass authority or workflow state, invent authority or accept client-defined Business identity where the server must resolve it. The Surface UI presents the Business Graph and must ultimately support the understandable IDY-009 journey `Enquiry -> Qualification -> Project/Scoping`; it does not implement IDY-009 in this stage.

## First Milestone Surface

**Settled semantic contract:** UI is a projection of authorised model data, and every mutation uses the shared Command pipeline. **Chosen implementation mechanism:** server-rendered PHP views, existing Outfit/Bootstrap/Lucide visual conventions and a small allowlisted model-field renderer; no independent frontend business store. **Status:** partial foundation implemented and focused-tested. The generic list/detail increment maps declared select values to their labels, gives absent values a bounded display, and presents validated View/state and authorized relationship endpoint context. The Operation Form increment projects authoritative `inputs` declarations into labels, controls, required flags, options, retained values and field errors; the existing OperationInputValidator remains authoritative for submitted values. The complete IDY-010 surface remains unbuilt.

Configured Operation Forms currently support text, textarea, number, checkbox, select and identifier controls where compatible with the declared input type; undeclared or unsupported types use an explicit generic text fallback and remain subject to server validation. GET resolves the exact active Business Operation revision, Business ownership and trusted handler for a server-rendered form. A target declaration may additionally provide `label`, `selection: existing` and `target_type_id`; the target projector uses that Type with `PresentationCatalog` and `AuthorizedObjectReader` to list only authorized objects in the resolved Business and uses the existing value normalization/presentation projection boundary for readable option labels. Where a demonstrator target has no configured View definition, the bounded fallback reads only normalized authorized object values; it never accepts a browser-selected field or authority value. Missing metadata remains a supported deferred target-entry case. POST accepts selector values only as the existing role-to-UUID target map and retains the existing CSRF, Business context, revision, handler, effective target authorization and `OperationInvocationService` -> `CommandHandler` boundary. GET discovery never grants authority, trusts hidden Type/Business fields or mutates data; final target authorization remains POST-time after the trusted handler produces its plan.

**IDY-010 HTTP evidence:** the superseded `bin/run-http-acceptance.ps1 -Suite idy010` run passed **42/42** checks on 2026-09-18; the intermediate BUILD report recorded **67/67** checks. The canonical current artifact records **69/69 HTTP acceptance — PASS** on 2026-09-19 using PHP 8.3.33 and disposable database `IDY_TEST_IDY002`, with zero failures, zero runtime diagnostics and clean shutdown. The Enquiry -> Qualification read/result loop is implemented through the existing authenticated Business context, generic View/Form Definitions, `PresentationCatalog`, `PresentationProjector`, `AuthorizedObjectReader`, `OperationInvocationService`, `CommandHandler`, AuthorityGrant/Policy and expected-version boundaries. IDY-010 implementation is closed at this bounded scope; this is not completion of the entire Surface UI, and broader capabilities remain future/refinement work. The full configured PHPUnit result remains **UNKNOWN — the full configured PHPUnit run was previously stopped before producing a final summary.**

The shell contains login/logout, an authorised Business selector, an Objects list and object detail with type, current version, declared state, permitted actions, relationships and history. Generate fields from supported type/view declarations; retain familiar compact form/table patterns. Business selection changes the requested context but the server must validate membership for reads and Commands.

Operation forms send stable Command identity and expected version, retain input on rejection and disable duplicate in-flight submission without relying on that UI protection for idempotency. Show denied, invalid, stale, pending, failed and Unknown/Reconciliation distinctly. Success links to the changed object revision, addressable transition, Command and provenance. A timeout must not produce a success badge or an unsafe automatic retry.

The current transition form is a deliberately narrow declared transition primitive: it resolves the authorized target and Business context, validates the declared form/state and expected version, and delegates the resulting transition Command to `CommandHandler`. This remains legitimate because the frozen Operation Contract requires an Operation revision where applicable, while the transition primitive is the existing presentation-bound transition contract; it does not construct arbitrary effects or create a second mutation authority. Configured Business Operations continue through `OperationInvocationService`, which resolves the exact Operation revision and delegates to the same `CommandHandler`. Any future generalized action form must preserve this distinction or converge both paths explicitly rather than introduce a competing mutation protocol.

Support keyboard operation, associated labels, visible focus, mobile shell navigation and readable object references. History exposes only permitted evidence, including retained failed Attempts and retired objects where allowed. The first screen after login is a usable object/business work surface, not a marketing dashboard or generic CRM. Broader builder/analytics patterns above remain reuse material for later features.

## Surface UI Standard

**Version:** 0.3, 2026-09-23
**Authority:** This section is the authoritative current visual and interaction standard for the Idiosyncrasy Surface UI. It describes presentation only; identity, Business authority, objects, Operations, Commands, Policy and evidence remain owned by their canonical architecture documents. [Legacy implementation](../reference/legacy-implementation.md) is historical reference material, and [implementation status](status.md) records actual verification.

### Visual character and brand

The surface is a restrained, compact product interface: light branded navigation, a calm light workspace, pastel purple/teal emphasis, readable hierarchy and modest framing. It should feel authored and operational rather than like a generic admin template. Decorative imagery is secondary and must not obscure forms, records or state.

Use the Idiosyncrasy horizontal wordmark where the full product identity is needed and the icon variant where space is constrained. Use a dark wordmark on the light shell and light admission surfaces, after verifying that the asset renders. Do not repeat a wordmark as adjacent title text. Existing candidates are `assets/Idiosyncrasy-light-text.svg`, `assets/idiosyncrasy-dark-text.svg` and variants under `assets/brand/`.

The following values are confirmed observations, not a final replacement palette:

| Role | Confirmed evidence | Use |
| --- | --- | --- |
| Target light shell | `#ffffff` | Approved dashboard sidebar |
| Target sidebar text | `#344566` / `#8290aa` | Approved navigation text and muted labels |
| Legacy accent | `#38A895` | Current platform primary teal |
| Target accent | `#146c63` | Current target primary accent |
| Target accent dark | `#0d504a` | Target hover/strong accent |
| Workspace | `#f3f5f9` / `#f7f9f8` | Legacy and target light-surface evidence |
| Surface | `#ffffff` | Target panels and forms |
| Text | `#2c3e50` / `#17212b` | Legacy and target text evidence |
| Border | `#e1e7ed` / `#d8e0e5` | Legacy and target border evidence |
| Secondary accent | `#B04AC6` | Legacy observed accent; not automatically retained |

The unified production palette, semantic contrast ratios and whether the purple secondary accent remains are unresolved design-review decisions. Error, warning, success and focus meanings must not be overridden by Business brand colors.

### Semantic design tokens

Future implementation should consume semantic tokens rather than component-specific literals. Confirmed values are identified above; unresolved values remain review items.

| Token family | Required semantic roles | Evidence/status |
| --- | --- | --- |
| Surface | `page`, `surface`, `surface-elevated`, `surface-inverse` | Target provides `#f7f9f8`, `#ffffff` and a light sidebar; elevated value is proposed |
| Content | `text`, `text-muted`, `text-inverse`, `text-disabled` | Target `#17212b`/`#63717d`; legacy `#8c9ba5` needs contrast review |
| Structure | `border`, `border-strong`, `divider` | Target `#d8e0e5`, legacy `#e1e7ed` |
| Action | `accent`, `accent-strong`, `action-primary`, `action-secondary`, `focus` | Target teal values observed; semantic focus value needs review |
| Status | `success`, `warning`, `error`, `info` | Target warning `#8a4b13` and danger `#a52c35`; success/info values unresolved |
| State | `disabled`, `pending`, `stale`, `unknown` | Behavior is required; exact colors are unresolved and cannot carry meaning alone |
| Spacing | page inset, control gap, panel padding, section gap | Target uses `1rem`, `1.25rem`, `clamp()` padding and `1rem` grid gaps |
| Geometry | control radius, panel radius, avatar, shell/header widths | Target observes `.25rem`, `.3rem/.35rem`, 44px avatar legacy, 16rem shell and 4.5rem header |
| Elevation | panel, dialog, drawer | Target panel shadow is observed; dialog/drawer values remain proposed |
| Typography | family, size, weight, leading, tracking roles | Outfit and Georgia are both observed; final roles require review |
| Layout | content max width, sidebar width, header height | Target max `1100px`, shell `16rem`; legacy `260px`/`60px` remain evidence |
| Breakpoints | mobile, tablet, persistent navigation | Target `720px`; legacy `576px`, `768px`, `992px` require reconciliation |
| Motion | drawer, feedback, hover, reduced motion | Legacy `0.3s` drawer and `0.2s` hover are observed; motion contract is proposed |

### Typography and iconography

The legacy implementation confirms Outfit loaded from Google Fonts at weights 300, 400, 500 and 600 with system fallbacks. The target implementation confirms Georgia with `Times New Roman` fallback. These are two active systems, not permission to merge them silently. The next visual implementation must choose and document a role split or a single family after comparison.

The intended hierarchy is page title, section heading, item heading, body, label, muted help/caption and uppercase eyebrow/status metadata. Headings use tighter leading; body and form text use comfortable leading; labels remain distinct from help text. Existing target evidence includes `h1` at `clamp(1.8rem, 4vw, 2.8rem)`, `h2` at `1.35rem`, eyebrow text at `.75rem` with `.08em` tracking and table headings at `.8rem`. These are implementation evidence, not immutable final values.

Lucide is the confirmed legacy icon source. Use icons for familiar tool actions with accessible names and tooltips; do not use icon-only controls where text is needed for clarity. The target currently has no established icon contract, so adding icons is a future implementation choice.

### Authenticated shell

The application frame has a branded sidebar and a main region. The sidebar contains the verified logo, current Business identity, capability-driven navigation and account/logout controls. Navigation labels must come from actual current target capabilities such as overview, authorized records, Business selection and available Operations; the legacy Marketing OS tree is excluded. Active navigation is visually distinct without depending on color alone. Hover and keyboard focus expose the same destination affordance.

The main region has a contextual header showing the current page and Business context, followed by an independently usable content region. Content is constrained for reading and forms and allowed more width for tables and record views. Account controls are access/settings actions, not a replacement for Business authority or a hidden context grant. The server remains responsible for resolving and validating Business context.

When authenticated, the shell always reserves a top-right User account control. It is the single User control (a User is the authenticated platform account, distinct from a Person profile within a Business; see [User account and Person profile](../architecture/identity-and-governance.md#user-account-and-person-profile)). It uses the authorized profile image when available, an accessible fallback otherwise, and exposes display identity, User profile and logout from one keyboard-operable menu. It is not duplicated as separate profile and logout controls in unrelated navigation areas. `Businesses` is a normal authenticated navigation capability: it lists authorized Business identities, exposes a clear no-Business state, and shows creation/onboarding when server-side `business.create` and Policy checks succeed. `business.create` is free and is not gated by entitlement; Business-scoped operational use is intended to be gated by the Business's entitlement in the future architecture (not implemented; all Businesses are currently treated as active).

On narrow screens the sidebar becomes a drawer or collapsible navigation surface with an explicit trigger, dismissal, visible focus, appropriate focus return and an overlay when used. The target's current `720px` single-column behavior and the legacy `992px` drawer threshold are evidence to reconcile during implementation; neither is silently declared final here.

### Admission and login

Admission is a first-class branded surface with a quiet light background, a readable constrained form region, clear product identity, visible labels and a single primary action. Every public and authentication page, including login, registration, confirmation, invalid-link and error states, must use the same target admission shell, panel treatment, responsive behavior and typography; no page may fall back to an unstyled or legacy-only shell. Login presents the current User identifier and password fields. Registration presents only the current admission inputs and tells the user that confirmation is sent to the registered email address. Confirmation is completed by opening the email link; the normal UI must not ask users to copy or paste a registration token or render one back to the registrant. Successful confirmation redirects directly to login with no redundant success page. A valid accepted token may be retried idempotently for 15 minutes from first use, without issuing duplicate onboarding grants, so mail scanners and link previews do not prevent the registrant from completing the flow; older, malformed, unknown or expired tokens remain invalid. The visual treatment must not restore email/account/client assumptions from the legacy application where they conflict with the User-first lifecycle.

Validation is field-associated and preserves entered values where safe. Authentication errors, invalid input, expired/invalid confirmation, unavailable service, pending submission and successful transitions are distinct states. Loading disables duplicate submission and communicates progress without changing geometry. CSRF, session, password, confirmation and admission behavior remain owned by the current identity implementation.

### Component contracts

| Component | Surface contract |
| --- | --- |
| Buttons/actions | Primary, secondary, danger and quiet actions have stable geometry and default, hover, focus, disabled and pending states. |
| Links | Use links for navigation; make visited/active context clear. Do not style unavailable behavior as a working link. |
| Inputs/selects | Visible labels, associated help/errors, stable focus and retained values. Placeholders are not labels. |
| Checkbox/radio | Native semantics remain available; state is not conveyed by color alone. |
| Forms | Constrained readable width, grouped fields, explicit required state and actionable field errors. |
| Panels/cards | Use modest borders/radii/elevation for genuinely framed tools or repeated items; do not nest decorative cards. |
| Tables | Preserve headings and meaning; provide an accessible horizontal-scroll region on narrow screens. |
| Tabs | Use only for real views; active state is visible and tabs scroll rather than clip on narrow screens. |
| Badges/status | Pair text with any color/icon and reflect authoritative state, not guessed readiness. |
| Notices/flash/toast | Announce success, warning, error and information with text and appropriate live-region behavior. |
| Dialogs | Only for supported workflows; require title, labels, cancellation, focus management and submit feedback. |
| Empty/loading/error | Distinguish no data, no permission, no context, loading and failure. Keep geometry stable. |
| Stale/unknown | Explain expected-version conflict or uncertain outcome; never present uncertainty as success or retry unsafely. |

Use a pop-up dialog when an explicit button opens a quick-create form, focused edit, confirmation or bounded selection and keeping that content inline would add clutter. Keep primary navigation, core Business context switching, long workflows, comparison-heavy lists and content that needs a stable URL visible or on a dedicated page. Every dialog needs a clear trigger label, title, visible labels, initial focus, keyboard dismissal, cancellation, focus return, responsive sizing, sufficient backdrop contrast, validation feedback and clear submit feedback. Preserve entered values on validation failure and do not use a dialog to hide essential status or permission information. On the Businesses screen, Business rows remain visible for direct context switching while `Add business` opens the creation form in a dialog.

### Responsive and accessibility standard

Desktop uses the full shell and persistent navigation when the available width supports it. Tablet preserves the shell hierarchy while allowing content and toolbars to wrap. Mobile uses a drawer/collapsed navigation, stacked forms, wrapped actions and scrollable tables. Dialogs remain within the viewport and retain keyboard access. Essential information is not hidden solely to fit a breakpoint.

All interactive controls are keyboard reachable with logical order and a visible focus indicator. Labels are programmatically associated. Dialogs manage focus on open, cancel and close. The surface must support zoom and reflow without clipped controls or overlapping text, meet contrast requirements for text and focus, and honor reduced-motion preferences. Semantic `main`, `nav`, `aside`, `header`, headings, forms and table structures are preferred over visual-only wrappers.

### Version history and acceptance

| Version/date | Change | Status/evidence |
| --- | --- | --- |
| 0.1 / 2026-09-22 | Established the reviewable Surface UI Standard from current target evidence and legacy archaeology; documented unresolved palette, typography and breakpoint decisions. | Documentation established; visual reconstruction not built. |
| 0.2 / 2026-09-22 | Implemented the first target admission and authenticated-shell reconstruction in `target/style.css` and target views: branded admission composition, current-capability navigation, active states, semantic controls, feedback, focus, responsive tables and reduced-motion behavior. Added the supplied light/dark horizontal wordmarks under the target public boundary and registered them in the target release definition. | PHP lint passed for all 15 target views; asset paths and file copies verified locally; HTTP acceptance was blocked before execution by unavailable local MySQL. |
| 0.3 / 2026-09-23 | Added the compact two-section authenticated sidebar, Principal account/profile access [2026-11-02: "Principal" here means User], Business selector and configuration destination, mobile drawer behavior, compact icon-bearing capability navigation, and a read-only graph-first All records explorer. | Focused Business creation/profile/navigation integration passed 7 tests and 135 assertions. Profile and Business configuration fields, images and logos remain intentionally unwired placeholders; browser responsive verification remains pending. |
| 0.3 / 2026-09-22 | Defined the pop-up interaction rule and applied it to the authenticated Businesses screen: compact Business rows remain visible and `Add business` opens a native dialog for creation. | Focused Business integration tests passed with 565 assertions; the then-current release boundary was recorded as 138 files. The current public target boundary is 150 files and the internal provisioning bundle is 144 files. |
| 0.6 / 2026-10-22 | Separated the canonical outer six-column page grid, generic PO surfaces and independent internal-content layout; recorded the audited recursive-grid defect and the missing governed internal preference mechanism. | Audit documentation and implementation plan established. |
| 0.7 / 2026-10-22 | Implemented independent recursive content delivery and revision-3 governed one-/two-/three-column internal preferences without changing the universal Object or Presentation model. | PHP/Node syntax checks, 8 renderer tests/44 assertions and 40 Presentation integration tests/309 assertions passed; protected STAGING release and browser acceptance remain pending. |

Future revisions must record the version/date, affected tokens/components/layouts, reason, superseded behavior, implementation status and acceptance evidence in this table. A CSS or template change is not a new visual standard until this document is updated. Build validation must cover admission, shell/sidebar states, representative record views, forms, feedback states, responsive viewports and existing functional tests.