Web Apps And Platforms

Foundation source: contexts/design-foundations-system.html.

System Waterfall

Apply in order: update ledger, foundation context, tokens and brand systems, media framework, channel data, this web-app sheet, web-app template, app QA. Implementation CSS uses rem and tokens; product patterns may specialize the foundation, but cannot override accessibility, reading, state, or containment rules.

Requirement

This file governs INTO Consulting web-app and platform interfaces: SaaS products, internal platforms, dashboards, admin tools, AI workspaces, and interactive operational systems.

Constraints

• INTO Consulting only.
• Warm Light is the default app surface.
• Blueprint Dark is reserved for operator focus, title/section pauses, command modes, and high-contrast review moments.
• Use Newsreader, Lexend, and IBM Plex Mono only.
• Petrol marks action, current path, selection, and primary affordance.
• Saffron #FFC64F marks caution, milestone, comparison, and chart signal only.
• Green and red are semantic state colors only.
• The four-point star is a north-star or compact AI cue only.
• Icons are allowed when they clarify action, state, navigation, or tool use. Use the brand icon system: outline, currentColor, accessible labels, and no decorative icon fields or repeating icon patterns.
• Use the editorial containment ladder before boxing content.
• No stock imagery, neon, gradient blobs, decorative badges, purple-blue AI styling, or generic SaaS chrome.

Dark-Editorial Section Breaks In Web-App Context

Web apps stay Warm Light by default. A dark-editorial section break is allowed only when the product needs a mode shift: onboarding pause, command/focus moment, media review room, major workflow transition, or dramatic conclusion.

Route the treatment through the canonical sources instead of restating values:

• Photography and macro prompts: brand/photography-system.md.
• Layer order, deep teal base, CSS bokeh backstop, overlay, and use/not-use rules: contexts/design-foundations-system.html#dark-editorial-cover.
• Glass button behavior: brand/button-system.md (Canonical Variant: btn-glass).
• Grain and reduced-motion boundaries: brand/texture-system.md and brand/motion-system.md.

Rules:

• Use dark-editorial breaks as a short pause or exhibit, not as the primary app workspace.
• Keep controls sparse: one primary action and optional btn-glass secondary action. Dense filters, tables, forms, and approval queues return to Warm Light work surfaces.
• Text sits on negative space, a quiet third, or a controlled overlay; never over the macro focal zone.
• Do not introduce a third theme, generic AI glow, decorative canvas background, or glass-heavy dashboard chrome.

Bet

INTO web apps should feel like operational editorial software: sparse, scannable, practical, and evidence-led. This costs some visual novelty and dashboard density, but it protects future products from looking like generic SaaS templates.

Failure Modes

• A dashboard becomes a mountain of boxes.
• Petrol turns into decoration instead of action/current-path signal.
• AI surfaces use purple-blue visual tropes instead of evidence, explainability, and controlled agency.
• Tables and forms become inaccessible under density pressure.
• Loading, empty, error, and success states are invented per product.
• Legacy agency-platform drafts are treated as canonical.

Research Transfer

Use external systems for structure and quality bars only. Do not copy their identity.

• Carbon: data tables need title/description, toolbar, sortable headers, pagination, selectable/expandable variants, row hover, skeleton loading, and AI presence rules.
• Apple HIG: sidebars navigate peer areas; toolbars orient the view and expose frequent commands; tables should preserve scanability and support sorting when useful; loading should show something as soon as possible.
• Atlassian: forms need clear labels, field grouping, validation, and button placement that follows the task.
• Stripe: dashboards organize resources, search, settings, team/security, and operational logs around real work; empty states should route users to the next action.
• Primer and Geist: mature systems separate product UI from brand UI and use tokens, accessible states, and compact components for repeated work.
• shadcn/ui: use composition and component anatomy for sidebar, dialog, sheet, command, table, form, tabs, toast, tooltip, empty, skeleton, and chart patterns. Restyle every component through INTO type, color, radius, density, icons, and containment rules. Do not copy its default visual identity.

Use the foundation context for IBM/Carbon-style baseline/grid transfer, Material-style baseline discipline, WCAG text-spacing resilience, NN/g heuristics and scanning behavior, Material card containment, and editorial image/text placement. Transfer the principle only; INTO owns the visual result.

Product-Grade Example Screens

Human review examples must look like credible products, not component inventories. Every major app spec should include at least one scenario screen that shows real data, real workflow pressure, and complete state behavior.

Presenter-led workshop apps that combine slide rhythm, local state, export, localization, and facilitator narration route to media/interactive-workshops.md and templates/interactive-workshop/style-system.md before normal web-app shell patterns. Use this file for persistent products and operational apps.

Preferred examples:

• Collaborative workshop UI: agenda, facilitator controls, decision prompt, participant input, poll or vote, evidence, owner, timer, and next action.
• Timesheet UI: weekly grid, person/project rows, exceptions, totals, approval state, missing-note recovery, and export.
• Polling web app: question, live results, response count, abstentions, evidence link, close state, and result animation with reduced-motion fallback.
• Admin or settings UI: sidebar, detail pane, permissions, audit, dangerous actions, and client-visible warning.
• Project Manager AI: workstream command center with project sidebar, command path, timeline, task table, blocker queue, AI proposal, evidence panel, and approval gate.
• Social Media AI Suite: campaign content operations with channel calendar, brief, AI draft, brand review, source checks, preview, schedule, publish, failure recovery, and analytics.
• Video Generation Pipeline: render review room with prompt, source upload, generation, render queue, media preview, version comparison, approval, export, and retry/revert path.

Example rules:

• Lead with one dominant composed app viewport before supporting component or variant examples.
• Apply the containment ladder before adding panels: no box by default, hairline grouping for related controls, full-width exhibit for composed app views, and cards only for discrete peer examples.
• Prefer one composed screen over many isolated cards.
• Use shadcn-like anatomy only at the composition level: sidebar, command bar, tabs, sheet, table, form, toast, or chart. INTO owns the visual result.
• Show motion as state clarification: live poll result reveal, current agenda marker, evidence synthesis, drawer entrance, or conflict resolution.
• Avoid overlapping text, cropped buttons, fake placeholder dashboards, and equal-weight boxes.
• For narrow viewports, convert dense tables into labelled record rows when horizontal scrolling would make the specimen feel broken.
• Do not add another specimen because the page feels thin. New specimens must prove a workflow, state, responsive behavior, accessibility behavior, or recovery path that the current lead specimen does not prove.
• Improve the lead product scene before adding supporting examples.
• Major specimens require desktop and 390px mobile renders, design critique, heuristic UI/UX audit, a recorded report under research/reviews/, and the top findings implemented before closeout.

Specimen Governance

Use this gate before adding any major app example.

Gate	Pass condition
Workflow	The specimen shows a real job, actor, data, state, and next action.
Behavior	The specimen proves a specific missing behavior such as permission denial, partial data, sync delay, conflict, recovery, approval, or mobile handoff.
Containment	The layout uses no box, hairline grouping, full-width exhibit, then cards only for discrete peer items.
Responsive	Desktop and 390px mobile renders show no text overflow, cropped controls, sticky overlap, or squeezed dashboard behavior.
Accessibility	Controls have labels, touch targets are at least 2.75rem when touch is likely, and state is not color-only.
Audit	A design critique and heuristic UI/UX audit are recorded, and the top findings are implemented.

UI Heuristic Gate

Every app surface is reviewed against these gates before it is considered system-compliant:

• Visibility of status: loading, saving, sync, error, success, empty, and partial data are visible.
• Match to real-world language: labels name the operator’s job, record, evidence, owner, and next action.
• Control and freedom: undo, cancel, back, reset, import preview, and recovery paths exist where risk warrants them.
• Consistency: navigation, tables, forms, buttons, and state colors reuse the same tokens and vocabulary.
• Error prevention: destructive, irreversible, client-visible, and permission-sensitive actions require preview, confirmation, or blocked-state explanation.
• Recognition over recall: visible context, breadcrumbs, captions, row labels, and action names reduce memory load.
• Efficient shortcuts: repeated work can use command palette, keyboard, filters, bulk actions, saved views, or recent items.
• Minimalist focus: one primary action per surface and no decorative card walls, badge clutter, or redundant labels.
• Recovery: errors name the problem, affected records, and next safe step.
• Help: contextual help appears near the task when the consequence is not obvious.

Miller/chunking rule: group visible choices into meaningful sets of roughly 3-6 when the user must remember them. Do not apply a blind seven-item cap when recognition, search, and hierarchy make a larger set easier to use.

Preferred next state specimen:

• Permission/error recovery: show the blocked action, required role, current owner, affected records, partial evidence, safe fallback, audit route, and recovery action. Do not reduce this to a red alert card.

AI Software Platform Source

Use brand/ai-software-platform-system.md for the complete 21-section operational source when building INTO-branded AI products. It covers design philosophy, assumptions, identity, light/dark tokens, typography, layout, surfaces, motion, component library, AI-native patterns, workflow, collaboration, analytics, forms, states, accessibility, responsive behavior, React/Tailwind implementation, example screens, QA, and self-audit repairs.

Minimum platform contract:

• AI products expose source/context, proposed changes, evidence, approval, execution, audit, rollback, and “needs human judgment” states.
• Component primitives include purpose, anatomy, variants, states, responsive behavior, accessibility, motion, and example use before code.
• React/Tailwind implementations use INTO variables and CVA-style variants; shadcn/ui supplies anatomy only.
• Lucide icons clarify familiar commands and always have accessible labels.
• Motion is allowed only for state, evidence, workflow, command, media, or long-running task clarity.
• Surface/elevation styling uses app shadow, glow, glass, and blur tokens only where a command, overlay, drawer, media stage, or active focus moment needs depth.

AI Interface Pattern Library

Use brand/ai-interface-patterns.md and contexts/web-app-system.html#ai-interface-patterns before designing any AI-native screen. The AI software platform source defines the product system; the pattern library owns the recurring AI interface surfaces.

Required AI pattern coverage:

• Prompt input: multi-line composer, token meter, slash trigger, attachment, voice affordance when supported, send/stop, and generation lock.
• Slash command menu: / trigger, fuzzy results, groups, recent/pinned, nested commands, permission filtering, Escape restore.
• Streaming text output: waiting state, readable chunk reveal, stop control, copy while streaming, mid-stream error, reduced-motion fallback.
• Citations and source attribution: inline markers, source pane, confidence ranking, broken-source state, required-vs-optional citation rules.
• Agent trace and tool calls: default-collapsed trace, step statuses, tool name, input/output summary, full-detail expansion, retry/redaction state.
• Generation states: idle, queued, in-progress, streaming, paused, complete, error, cancelled, refused.
• Model awareness: subtle current model, capability disclosure, cost/latency hint, unavailable reason, refusal-with-model-suggestion when valid.
• Confidence, disclosure, refusal, and feedback: calibrated uncertainty only, AI/source/human-review markers, calm refusal plus safe alternative, and feedback captured as an evaluation record.
• Attachment and artifact panel: upload, scan/progress, source list, generated artifact preview, download/export, and version history.

AI screens fail review when they treat chat as the whole product, hide evidence, detach citations from claims, use purple-blue AI styling, expose raw tool JSON by default, or make generated artifacts look final before review.

Design System Self-Audit Gate

Before final example screens, implementation guidance, or QA checklists, audit the target app against these ten questions. If any item is not covered, repair the system or app spec before building screens.

Question	Minimum pass condition
Light and dark tokens	Warm Light and Blueprint Dark define page, raised, muted, hover, skeleton, overlay, scrim, selected, focus, semantic, chart, and app aliases.
Component variants	Navigation, buttons, command palette, tables, forms, drawers, modals, alerts, timelines/pipelines, AI workspace, approvals, and comments have variants.
Interaction states	Default, hover, active, focus-visible, selected/current, disabled, loading, empty, error, success, partial, read-only, permission, offline/sync, conflict, undo, approved, archived, deleted, and reduced-motion states are assigned where relevant.
Workflow and AI patterns	Approval, review, evidence, execution, rollback, audit, and AI-human handoff are explicit.
Complex layout	Shell, sidebar, command bar, dominant work region, detail region, full-width exhibit, and mobile task priority are defined.
Data-heavy screens	Dashboards, tables, forms, timelines, pipelines/boards, approval queues, audit logs, charts, and exports are supported.
Animation	Motion has a communication job, duration/easing, reduced-motion fallback, cleanup, and static final state.
Accessibility	Keyboard path, focus, semantics, contrast, labels, error summary, live regions, touch target, and 200% zoom behavior are defined.
Responsive rules	Dense data has mobile fallback: stacked records, one-lane queue, focused route, sheet, or takeaway-first summary.
Reference apps	Collaborative workshop, timesheet approval, and polling apps have required screens, states, desktop/mobile proof, and recovery paths.

Implementation risk if skipped: a coding AI will invent component variants, state names, mobile behavior, and approval logic differently in each app.

Component State Matrix

Reusable app primitives need variants, required states, responsive behavior, and accessibility behavior before implementation.

Primitive	Variants	Required states	Mobile fallback	Accessibility
App shell	Top nav, sidebar, rail, bottom tabs, command path	Current, collapsed, expanded, disabled route, permission-limited, offline	Bottom tabs or compact menu	Landmarks, skip link, focus, labels
Button/action	Primary, secondary, quiet, icon-only, split, destructive, loading, permission-disabled	Default, hover, active, focus, disabled, loading, current, blocked, confirm	2.75rem touch height, visible primary action	Name, busy state, tooltip, keyboard, disabled reason
Command palette	Global, scoped, action-only, search-only	Open, empty, loading, permission-filtered, shortcut conflict, action result, failed action	Full-screen route or sheet	Combobox/listbox, arrows, Escape, focus restore
Data table	Static, selectable, sortable, expandable, editable, virtualized	Loading, empty, filtered-empty, selected, focus, disabled row, partial, error, sync	Stacked record rows	Caption, scoped headers, aria-sort, keyboard actions
Form field	Text, select, checkbox, radio, segmented, date, file, mapped import column	Idle, focused, dirty, validating, error, success, disabled, read-only, permission	Single column, sticky save that does not cover fields	Label, helper/error link, error summary focus
Drawer/sheet	Detail, filter, edit, approval, evidence, import mapping	Open, closing, dirty, saving, saved, error, blocked, destructive pending	Full-screen sheet	Title, description, focus trap/restore, Escape
Timeline/pipeline/board	Timeline, kanban, approval queue, workflow rail, swimlane	Queued, active, blocked, delayed, completed, skipped, failed, reassigned, dragged	Priority queue or one-lane stepper	Ordered list or accessible grid plus keyboard drag alternative
AI workspace	Drafting, review, approval, execution, monitoring, rollback	Queued, streaming, cited, partial, low-confidence, needs-human, approved, executing, failed, reverted	Evidence and approval first	Live stream status, sources, human approval, no silent irreversible action
Approval gate	Content, execution, second approval, client-visible	Draft, requested, reviewed, approved, rejected, expired, executed, reverted	Decision card	Reviewer, timestamp, consequence, keyboard confirmation, audit
Toast/alert	Toast, inline, page, blocking, system banner	Info, success, warning, critical, retrying, dismissed, resolved	Inline near affected task	Live region, action text, no color-only severity

Data Views, Timelines, And Pipelines

Choose data views by job:

• Dashboard summary: use when the operator needs a conclusion before acting. Require period, source, filters, drill-in route, and one primary next action.
• Data table: use when the operator compares records or needs precise values. Require caption, toolbar, search, filters, sort, selection, export, row actions, row focus, empty/error/partial/sync states, and stacked mobile records.
• Timeline: use for sequence, duration, dependency, and milestones. Require time scale, current marker, owner, dependency, milestone, delayed/blocked state, and a vertical phase fallback on mobile.
• Pipeline or board: use when work moves through states. Require columns, WIP count, owner, priority, allowed/invalid move, drag/drop and keyboard move behavior, permission handling, and one-lane mobile queue.
• Approval queue: use when the user decides whether work becomes visible, executable, or exportable. Require reviewer, evidence count, risk, requested action, approve/reject/request-changes states, expiration, execution, and revert path.
• Audit log: use for accountable history. Require actor, timestamp, source, prior/new value, reason when supplied, filters, export, redaction state, and permission-limited state.

Reference Application Contracts

The three reference apps must satisfy these implementation contracts before they are considered ready for final screens.

App	Required screens / regions	Required states	Proof before final
Collaborative workshop / agent operations room	Agenda, prompt, participant input, poll/vote, evidence panel, owner assignment, timer, AI proposal, approval gate, export state	Live, paused, empty participant input, submitted, partial evidence, permission blocked, AI streaming, approval requested, approved, export held	Facilitator moves from prompt to evidence-backed decision to approval/export with keyboard path and mobile task priority.
Timesheet approval surface	Weekly grid, person/project rows, exceptions, totals, missing-note recovery, approval queue, export/report, audit trail	Draft, submitted, exception, missing note, approved, rejected, locked, partial export, sync delayed, permission denied	Reviewer identifies exception, requests correction, approves valid rows, and exports clear totals on desktop and mobile.
Polling / route-confidence app	Question, options, live results, response count, abstentions, evidence link, close state, result explanation, reduced-motion result view	Not started, live, user voted, abstained, closed, tied, low confidence, evidence missing, result published, permission blocked	Participant votes or abstains; operator closes poll, explains result, and publishes only with evidence and permissions.

Layout Grid

Default desktop app shell:

• Top nav: 3.5rem.
• Sidebar: 15.5rem expanded, 4rem collapsed rail.
• Content padding: 2rem desktop, 1.5rem tablet, 1rem mobile.
• Main content max width: 80rem on reading-shaped pages.
• Grid-shaped pages, dashboards, data tables, boards, and timelines may use full available width.
• Use 12 columns for desktop app composition, 6 columns for tablet, and one column for phone.
• Use 1rem gutters for dense tool areas and 1.5rem gutters for dashboard and evidence areas.
• Viewport grid default: mobile one column with 1rem side margin; tablet 6 columns with 1.5rem side margin and 1rem gutters; desktop 12 columns with 2rem side margin and 1.5rem gutters. Wide desktop increases side air before widening prose.

Use the grid to clarify priority, not to fill every cell. Wide evidence, tables, timelines, and AI transcripts should get a full row when cramped.

Type Scale

App interfaces use a denser scale than brand collateral. Use brand/typography-spacing-system.md for font roles, weight ceilings, and text rhythm before creating new app specimens.

Role	Rule	Use
App page title	Newsreader 2rem/1.15, weight 400, letter-spacing 0	Page H1
App section title	Newsreader 1.25rem/1.2, weight 400, letter-spacing 0	Panels, detail sections
App body	Lexend 1rem/1.5, weight 400, letter-spacing 0	Default app copy
App small	Lexend 0.8125rem/1.45, letter-spacing 0	Helper text, metadata
App label	IBM Plex Mono 0.6875rem/1.2, uppercase, letter-spacing 0	Labels, table headers, state eyebrows
App mono	IBM Plex Mono 0.8125rem/1.45, letter-spacing 0	IDs, codes, paths
App numeric	IBM Plex Mono 0.875rem, tabular numerals, letter-spacing 0	Money, hours, counts, dates

Minimum app text floors:

• Body and explanations: 1rem.
• Table cells: 0.875rem absolute, 1rem preferred.
• KPI labels: 0.8125rem minimum; KPI explanations: 0.9375rem preferred.
• Chart labels: 0.75rem absolute.
• Chart annotations: 0.8125rem minimum.
• Source notes and footnotes: 0.6875rem absolute, 0.75rem preferred.
• Button labels: 0.875rem default, 0.8125rem compact.

Display and italic rule:

• Newsreader display classes appear only on H1s, covers, section breaks, quotes, major numerals, or editorial title moments.
• Italics are limited to one short heading phrase for editorial contrast or quotation-like emphasis. Never use italics in buttons, tabs, labels, table cells, charts, data labels, body emphasis, or error text.

Do not shrink text to make dense UI fit. Reflow tables into labelled records, use full-width exhibits, split the panel, or move detail into a drawer before going below the floor.

Spacing And Density

Use the INTO spacing scale. App-specific density adds:

• Baselines: 0.25rem micro baseline for type alignment and 0.5rem structural baseline for spacing, grid, and component layout.
• Control small: 2rem.
• Control medium: 2.5rem.
• Control large: 3rem.
• Table row: 3rem default, 2.5rem compact.
• Touch target floor: 2.75rem.
• Panel padding: 1.5rem compact, 2rem standard.
• Modal/drawer padding: 2rem desktop, 1.5rem mobile.
• Compact mode tokens: --into-density-compact-control, --into-density-compact-row, --into-density-compact-gap, --into-density-compact-padding, and --into-density-compact-panel-padding.
• Comfortable mode tokens: --into-density-comfortable-control, --into-density-comfortable-row, --into-density-comfortable-gap, --into-density-comfortable-padding, and --into-density-comfortable-panel-padding.

Compact density is allowed only when it improves repeated work. It never removes focus rings, labels, helper/error text, table captions, or row hover. Comfortable density is the default for approval, evidence review, prompt composition, media preview, and mobile/touch-heavy work. Mixed-density screens keep the main decision comfortable and repeated support lists compact.

Default text rhythm:

• Label to title: 0.75-1rem.
• Page title to supporting copy: 1.25-1.75rem.
• Copy to action row: 1.75-2.25rem.
• Copy to table, chart, form, or AI trace: 2-3rem.

No arbitrary gaps when a spacing token exists.

Reading And Bento Patterns

• Vertical/layer-cake scanning is the default for dashboards, record pages, review queues, mobile, docs, and long operational screens.
• Z-pattern is reserved for sparse command screens, onboarding decisions, covers, and focused empty states.
• F-pattern scanning is a failure mode for dense unformatted pages. Add headings, summaries, tables, or split the route.
• Bento is allowed only for a small set of comparable peer modules or one dominant module plus supporting modules. It is banned as decorative dashboard clutter, nested card layouts, or a substitute for hierarchy.

App Shell

Top Nav

Top nav orients the user, not the brand.

• Height: 3.5rem desktop, 3rem mobile.
• Left: compact mark or product/workspace name.
• Center/left: breadcrumb, current object, or command path.
• Right: search, command trigger, notifications, help, user menu.
• Use hairline bottom border. Avoid drop shadows.
• Petrol may mark the current path, not every nav icon.

Sidebar

Sidebar is for top-level peer areas and workspace hierarchy.

• Expanded width: 15.5rem.
• Collapsed rail: 4rem.
• Active item: petrol left rule or selected text, not a filled badge.
• Groups use mono section labels and Lexend nav items.
• Do not nest deeper than two visible levels. Use a detail panel or record view when hierarchy gets deeper.
• On mobile, replace the sidebar with a bottom tab bar or compact menu.

Command And Action Bar

Command bars act on the current page or selected rows.

• Left: search, filters, view switcher, density control.
• Right: primary action, export, overflow menu.
• Use icon buttons for tool commands when the icon is familiar and labelled. Use icon+text when ambiguity or risk is high.
• One primary action per surface.
• Batch mode replaces the normal action bar only after selection.

Page Header

Page headers carry the conclusion, not decoration.

• Mono eyebrow: object type, area, or status.
• Newsreader title: current page, record, or workflow.
• Supporting line: owner, period, source, count, or last updated.
• Primary action sits on the right on desktop and becomes the mobile primary action in the bottom bar or top action menu.

Component Rules

Dashboard Layout

Dashboards summarize work only when the reader can act.

• Lead with the operational conclusion.
• Use no box by default; use hairline grouping before cards.
• Cards are for peer metrics, decisions, alerts, or work queues only.
• Avoid more than four KPI tiles in the first viewport.
• Every metric includes period, source, delta, and implication.
• Use full-width exhibits for charts, timelines, or tables that need space.

Data Table

Tables are core operational surfaces.

• Caption/title and optional description are required.
• Toolbar supports search, filters, view settings, export, and primary action.
• Header row uses app labels and sortable state when useful.
• Rows use hairline dividers, hover state, selected state, and keyboard focus.
• Numeric, money, hour, and date cells use mono/tabular numerals.
• Persist row actions when touch is likely; hover-only actions are desktop only and must appear on focus.
• Pagination or virtual scrolling must expose current range and total when known.
• Loading uses static skeleton rows, not decorative shimmer.
• Empty tables preserve table context and place the empty message in the body.
• On mobile, convert rows to stacked record cards with P1 fields visible and P2 fields behind expansion.

Filters And Search

• Search is a 2.5rem control with visible label or accessible name.
• Filters appear as text labels, selects, checkboxes, or segmented controls.
• Chips are interactive filters, not decorative status badges.
• Active filters can be removed individually and cleared together.
• Filtered-empty state must say what filter produced zero results.

Forms

• Label above every field. Placeholder is never the label.
• Field width should match expected content length.
• Group fields by decision or data object, not by visual symmetry.
• Error state includes visible error text, not color alone.
• Disabled fields stay visible and explain why when the reason matters.
• Dirty forms need a save/cancel path and unsaved-change warning.
• Multi-step forms need progress, back, cancel, and final confirmation.

Detail Panels And Drawers

• Detail panels show record context, evidence, and quick actions.
• Drawers are for contextual edit, filters, or focused review.
• Default drawer width: 30rem; wide drawer: 40rem.
• Use a neutral hairline left edge only when it clarifies the drawer boundary. Do not use repeated accent rails as decoration.
• Mutating drawers use a backdrop; quiet filter drawers can skip it.
• Mobile drawers become full-screen sheets.

Modals

• Modals are for interruptive decisions, destructive confirmation, or short focused tasks.
• Do not put primary browsing or record detail in modals.
• Width stops: 30rem, 45rem, 60rem.
• Header, body, footer are separated by spacing or hairlines.
• Escape closes non-destructive modals.
• Destructive modals name the object, consequence, and recovery path.

Cards And Containment

Use the editorial containment ladder:

1. No box: typography, alignment, and spacing.
2. Hairline group: related controls or light separation.
3. Full-width exhibit: table, chart, screenshot, timeline, or AI trace.
4. Card: discrete peer item, metric, route, record, decision, or example.

Avoid nested cards. Avoid bento grids unless every item is a comparable peer.

Tabs, Menus, And Buttons

• Tabs switch sibling views inside one area or record. They are not top-level navigation.
• Menus expose secondary actions and must remain keyboard navigable.
• Primary buttons use petrol fill.
• Secondary buttons use hairline or pale surface.
• Quiet buttons are text or icon+text.
• Current tabs, row selections, filters, slide thumbnails, and active items use petrol text, rail, outline, underline, or soft surface before fill. They should not look like extra primary buttons.
• Saffron is never used for ordinary buttons, tabs, or selected items.
• Glass buttons are dark/photo-only and need controlled translucent surface, hairline border, and visible focus.
• Icon-only buttons need accessible labels and focus-visible state.
• Normal icon-plus-label buttons use inline-flex row anatomy with label first and optional trailing icon second. Do not stack icon above text.
• Button labels stay 0.875rem default or 0.8125rem compact minimum. Shorten labels, widen controls, or split actions before shrinking type.
• Split buttons separate the default action from the alternate-action menu.
• Destructive buttons name consequence and recovery before high-risk execution.
• Loading buttons prevent duplicate activation and announce busy state.
• Permission-disabled buttons remain visible and expose the missing role, owner, or prerequisite.
• Icons inside buttons are allowed and preferred for familiar tools such as search, filter, settings, more, close, expand, collapse, copy, edit, save, export, upload, download, undo, redo, and refresh. Do not use icons as decorative badges.
• Define default, hover, active, disabled, loading, current, permission, destructive-confirmation, and focus-visible states when relevant.

Toasts And Alerts

• Toasts confirm background or completed actions. They do not carry complex instructions.
• Inline alerts explain page, form, or workflow state.
• Use state dots or left rules; do not flood surfaces with green, red, or Saffron.
• Critical alerts stay until dismissed or resolved.
• Toasts use aria-live="polite" unless they block a task.

States

Every operational surface defines:

• Default.
• Hover.
• Active/pressed.
• Focus-visible.
• Selected/current.
• Disabled.
• Loading.
• Empty.
• Error.
• Success.
• Partial data.
• Read-only.
• Permission denied.
• Offline or sync delayed when relevant.

Loading should show structure quickly. Empty states should explain the absence and one next step. Error states should name the failure and recovery path. Success states should be quiet and should not interrupt continued work.

AI Chat And Agent Workspace

AI surfaces use INTO restraint and evidence discipline.

• No purple-blue AI styling.
• Use the four-point star only as a compact AI cue or north-star marker.
• AI messages must separate user input, agent reasoning summary, evidence, citations, proposed action, and execution log when those layers exist.
• Every generated result needs source, confidence or uncertainty when useful, and a visible review/approve path before irreversible action.
• Agent workspaces should show queue, current task, evidence drawer, action log, and handoff state.
• Agent workspaces should be composed review surfaces, not chat bubbles in a card. Use clear zones for input/output, evidence, proposed change, approval gate, execution log, and rollback path.
• Streaming should stabilize layout. Do not let text growth move critical controls.
• AI tables or cells generated by AI need a visible compact cue and an explainability affordance.

Workflow And Status Surfaces

• Use workflow rails for sequence, owners, due dates, and blockers.
• Saffron marks milestone, caution, comparison, or decision point.
• Green marks completed or favorable state.
• Red marks blocked, failed, destructive, or overdue-critical state.
• Status copy must say what changed and what happens next.
• Do not use decorative badges for every field. Use text first, then dot or mono label only when state must scan fast.

Operational UX Patterns

Record Lifecycle

Every core object defines its lifecycle before screens are built.

Default lifecycle states:

• Draft: editable, not final, can be deleted if no external dependency exists.
• Active: in use, visible in primary tables and search.
• Pending review: blocked from execution until a named reviewer acts.
• Approved: locked or partially locked depending on object type.
• Archived: hidden from default views, searchable, restorable when allowed.
• Deleted or voided: irreversible or high-friction recovery; visible in audit where compliance requires it.

Each lifecycle state defines allowed actions, disabled actions, owner, review requirements, audit event, recovery path, and mobile behavior.

Permissions And Roles

Permission rules must be visible enough that operators understand why an action is unavailable.

• Use roles such as owner, editor, approver, viewer, admin, and external collaborator only when the product needs them.
• Disabled actions stay visible when the operator can reasonably expect them.
• Permission-denied states explain the required role, owner, or route.
• Preview/impersonation mode uses a persistent operator banner and never hides that the view is simulated.
• Dangerous admin changes require audit logging and, where appropriate, a second approval.

Activity Log And Audit Trail

Every operational platform needs a durable record of important changes.

• Log who acted, what changed, when, source surface, prior value, new value, and reason when supplied.
• AI actions log prompt/request, evidence set, reviewer, approval, execution, and rollback where available.
• Audit logs use tables or chronological lists with mono timestamps.
• Do not bury audit history in a modal if it is needed for compliance or handoff.

Collaboration, Review, And Shared Work

Collaboration is operational, not social. Show shared-work signals only when they change editing, review, approval, visibility, or recovery behavior.

Presence:

• Show active collaborators only where their activity changes lock, edit, review, handoff, or approval behavior.
• Use restrained text states such as Avery editing scope or Orion reviewing evidence.
• Do not use avatar piles, decorative online dots, social badges, or generic activity chrome.

Comments and annotations:

• Anchor comments to records, fields, table rows, chart points, evidence, or decisions.
• Comments expose author, timestamp, anchor, resolved/reopened state, and owner when follow-up is required.
• Source-linked comments are required when a comment challenges evidence, claim, AI output, or client-visible content.
• Free-floating comment streams fail the system.

Assignments and ownership:

• Task-like items show owner, due date when relevant, state, and escalation path.
• Unassigned is a risk state, not blank metadata.
• Ownership changes that affect execution, approval, or client visibility create an audit event.

Approvals:

• Approval states: draft, requested, reviewed, approved, rejected, executed, reverted.
• Approval records name reviewer, timestamp, evidence set, and permitted action.
• Comment approval, content approval, and execution approval are separate.
• Client-visible or irreversible actions require explicit approval state.

Conflict handling:

• Collaborative conflicts show prior value, attempted value, latest value, actor, timestamp, and recovery path.
• Simultaneous edits, stale data, locked fields, and read-only copies need explicit states.
• AI must not silently overwrite human work. AI-generated changes show prompt or request, evidence set, reviewer, approval state, and rollback route.

Notifications:

• Notification center categories: assigned, mentioned, approval needed, failed sync, due soon, blocked.
• Every durable notification names object, reason, actor or system source, and action.
• Batch low-priority notifications. Do not create badge spam.

Sharing and visibility:

• Use explicit states: internal, private, restricted, client-visible, external link.
• Client-visible and external-link states are labelled before export, send, share, or agent execution.
• Permission denial explains role, owner, workspace, or request-access route.

Command Palette And Global Search

Cmd/Ctrl + K opens the global command surface when the product has more than one major area.

• Group results by records, navigation, recent items, and permitted actions.
• Permission-filter action results.
• Show keyboard hints only where they reduce repeated work.
• Empty state states what was searched and which scopes are included.
• Recent items must not expose records the user can no longer access.

Bulk Actions And Selection Mode

Bulk action mode replaces the normal toolbar after selection.

• Show selected count, clear selection, and allowed actions.
• For mixed-permission selections, show partial availability before execution.
• Bulk destructive actions require confirmation; reversible bulk changes should prefer undo.
• Partial success reports changed count, failed count, failed rows, and retry path.

Inline Editing

Inline editing is for fast correction, not complex workflow.

• States: idle, editing, dirty, saving, saved, validation error, conflict, read-only, and reverted.
• Auto-save is allowed only when conflict and rollback are solved.
• Explicit save is required for high-risk values, money, permissions, legal terms, AI execution settings, or destructive changes.
• Conflicts show prior value, attempted value, latest server value, and choice.

Error Severity Ladder

Use the smallest feedback surface that lets the operator recover.

Level	Surface	Use
Field error	Inline field message	A single field is invalid or missing.
Inline warning	Near the affected element	A value is risky but not blocked.
Page alert	Top of content or form	The page or form needs attention.
Blocking error	Main content region	The task cannot continue.
System outage	App-level banner/status page	The product or integration is degraded.

Form validation failures need both an error summary and inline field errors. Move focus to the error summary after failed submit and link each summary item to the affected field.

AI Review And Approval Gate

AI-generated work moves through explicit states:

1. Draft.
2. Cited.
3. Needs review.
4. Approved.
5. Executed.
6. Reverted or superseded.

Irreversible actions require visible evidence, reviewer identity, approval timestamp, execution log, and rollback policy. AI content should not look “complete” before it is reviewed.

Integration And Sync States

Integrations define:

• Connected.
• Syncing.
• Delayed.
• Degraded.
• Failed.
• Expired authentication.
• Disconnected.
• Reconnecting.

Show last successful sync, next retry, affected records, and reconnect action. Do not show stale integrated data without a visible timestamp.

Onboarding And First Run

First-run setup should move the operator toward real work.

• Use a short setup checklist: connect source, import data, invite team, review settings, create first record.
• Allow “skip for now” only when the skipped step is not required.
• Empty first-run pages should not pretend data exists.
• Sample data must be visibly labelled and easy to remove.

Notification Center

Use toast, inline alert, or notification center based on durability.

• Toast: transient success or background action.
• Inline alert: contextual recovery or validation.
• Notification center: durable follow-up, assignment, approval, failed sync, or handoff.
• Batch low-priority notifications.
• Critical notifications need read/unread state and owner.

Import And Export

Import flows need preview before commit.

• Steps: upload, map fields, validate, preview errors, commit, report.
• Error rows must be downloadable or filterable.
• Exports show scope, filters, file type, generated time, and data sensitivity.
• Background exports notify completion and preserve a download route.

Version History And Restore

Use version history when content, settings, AI outputs, or commercial values can change materially.

• Show version timestamp, actor, summary, and changed fields.
• Restore action must preview what will change.
• AI-generated versions include model/provider when relevant, evidence set, reviewer, and approval state.

Null And Empty Cell Policy

Do not use one symbol for every absence.

State	Display
Unknown	Unknown or Not captured
Not applicable	N/A
Zero	0, 0.0, or currency zero as real value
Pending	Pending with timestamp if useful
Failed to load	Error text or retry affordance
Intentionally blank	Blank only where that matters

Destructive Action Matrix

• Reversible low-risk action: execute, then offer undo.
• Reversible medium-risk action: confirm if context is ambiguous, otherwise offer undo.
• Irreversible high-risk action: confirmation modal naming object, consequence, and recovery path.
• Catastrophic or compliance-relevant deletion: type-to-confirm plus audit log and, when needed, second approval.
• Cancel is not destructive unless it discards unsaved work.

Data Visualization Panels

Use brand/data-visualization-system.md.

• Chart titles state the conclusion.
• Use teal for answer, gray for context, Saffron for signal.
• Direct labels beat legends when space permits.
• Every chart panel includes period, unit, source, and note.
• Interactive charts need loading, empty, partial-data, error, keyboard, focus, tooltip, static, and reduced-motion states.

Settings And Admin Screens

Settings screens need predictable structure over novelty.

• Use a two-column reading layout on desktop: settings nav plus detail.
• Group settings by object and risk: profile, workspace, team, access, billing, integrations, data, audit.
• Dangerous actions live in their own section with consequence copy.
• Admin tables use the standard data table contract with role, permission, last active, owner, and audit columns when relevant.

Responsive Behavior

Responsive And Mobile Behavior Playbook

Every production web-app screen needs desktop, tablet, mobile, 390px, and 200 percent zoom behavior before handoff. The mobile version preserves the next useful decision; it is not a scaled desktop dashboard.

Band	Width	Shell behavior	Content behavior	QA gate
Mobile	Below 768px	Sidebar becomes bottom tabs, menu, or full-screen sheet with current path retained.	One column; table rows become stacked records; drawers/modals become sheets.	No horizontal overflow at 390px; primary action reachable without hiding focused fields.
Tablet	768-1023px	Sidebar may collapse to rail; inspectors become drawers.	Keep the main work visible; secondary evidence moves to drawer or below.	No squeezed boards, cropped buttons, or hidden warning state.
Desktop	1024-1279px	Full shell, command, main work, and one support region.	Comparison tables and evidence panels can sit beside the work.	Current path, evidence, and next action visible above fold.
Wide	1280px and above	Widen exhibits before prose; add side air before increasing line length.	Add support regions only when they carry active work.	No decorative columns or empty dashboard chrome.

Touch and pointer floors:

Control type	Minimum touch target	Desktop density	Mobile behavior
Primary / secondary button	--into-app-touch-target	May use compact control height when pointer-only.	Use full touch target and keep label visible.
Row action	--into-app-touch-target	Can live inline or in row action menu.	Moves into stacked record footer; never hover-only.
Icon-only control	--into-app-touch-target	Requires accessible name and tooltip.	Use icon plus label when ambiguity costs time.
Sheet close / save	--into-app-touch-target	Header or footer allowed.	Always visible without covering focused input.

Gesture policy:

Gesture	Allowed use	Required fallback
Tap	Primary activation, row expansion, tab switch.	Keyboard Enter/Space and visible focus.
Long press	Optional secondary shortcut only.	Visible menu or action button.
Swipe	Non-destructive archive/dismiss only when common to the app.	Explicit action button and undo where reversible.
Drag/drop	Ordering or board movement only when it clarifies state.	Keyboard move control or action menu alternative.
Pinch/zoom	Media or canvas inspection.	Zoom controls plus static summary.

Column collapse decisions:

Data priority	Desktop	Tablet	Mobile
P1 identity	Visible column	Visible column	Record title
P1 state/risk	Visible column	Visible column	Status line near title
P1 owner/date	Visible column	Condensed column	Metadata row
P1 action	Visible row action	Row action menu	Record footer action
P2 evidence	Visible or expandable	Expandable drawer	Detail sheet
P3 audit/detail	Detail panel or expansion	Expansion	Secondary route
P4 raw/debug data	Hidden by default	Hidden by default	Hidden behind details

Shell transitions:

• Desktop sidebars collapse to rails only when labels remain discoverable.
• Evidence, filters, and inspectors become drawers on tablet and full-screen sheets on mobile.
• Modals below mobile become sheets unless the decision is a short critical confirmation.
• Sticky save and approval bars must account for keyboard, viewport, and focus position; they cannot cover the active field or destructive consequence copy.
• Density reflow can reduce padding and gaps through existing density tokens; it cannot remove labels, captions, focus rings, helper text, or type floors.

Breakpoints:

• Mobile: below 768px.
• Tablet: 768-1023px.
• Desktop: 1024px and above.
• Wide: 1280px and above.

Rules:

• Sidebar collapses to bottom tabs or menu below 768px.
• Top nav reduces to back/control, title, and one menu.
• Page headers collapse metadata into a secondary row or overflow menu.
• Tables become stacked record cards below 768px.
• Mobile shows the next useful decision first and moves secondary navigation, dense columns, charts, and audit detail behind focused routes or sheets.
• Modals become full-screen sheets below 640px.
• Drawers become full-screen sheets below 768px.
• Touch targets stay at least 2.75rem.
• Sticky save/action bars must not cover form fields.

Motion

Motion enacts meaning.

• Hover/focus response: 120-160ms.
• Pressed state: 120ms.
• Drawer/sheet enter: 200-250ms using --into-motion-precision.
• Modal enter: opacity plus subtle scale only if needed.
• Loading skeletons are static.
• No shimmer, bounce, decorative page-load animation, or staggered card entrances.
• Respect prefers-reduced-motion with a readable final state.

GSAP Interaction Sequencing

GSAP is allowed when native CSS transitions are too limited for precise interface sequencing.

Allowed jobs:

• Drawer, sheet, popover, and command-palette entrance/exit.
• Workflow step transitions and state-change handoffs.
• Evidence reveal, chart callout, annotation, and comparison focus.
• AI stream settling, approval gate transition, and execution-log insertion.
• Drag/drop feedback when it clarifies what will move or change.

Not allowed:

• Decorative loops, parallax, page-load theatre, idle ornament, or counters that animate without meaning.
• Hiding critical content until an animation completes.
• Animating layout properties when transform or opacity can do the job.
• Using motion as the only indicator of state.

Requirements:

• Declare the communication job before using GSAP.
• Use timeline labels for multi-step sequences.
• Prefer transform and opacity.
• Use gsap.matchMedia() or equivalent reduced-motion branching.
• Revert or kill timelines on unmount, route change, or drawer close.
• Preserve a static final state for tests, screenshots, and reduced motion.

PixiJS Simple Rendering

PixiJS is allowed for simple 2D renderings when DOM, CSS, or SVG would make the interface less clear or less performant.

Allowed jobs:

• Lightweight node maps.
• Dense 2D timelines.
• Spatial queues.
• Mini simulations for operational flow.
• Canvas-heavy status maps.
• Sprite-like renderers where many simple objects need smooth updates.

Not allowed:

• Decorative animated backgrounds.
• Mascot, game-like, or novelty canvas scenes.
• WebGL because it looks impressive.
• Replacing accessible data tables, source labels, or audit records.
• Particle fields, sparkle systems, glow effects, or purple-blue AI styling.

Requirements:

• Provide a static SVG, table, or text fallback.
• Provide an accessible summary and keyboard-equivalent controls.
• Respect reduced motion and pause hidden/offscreen render loops.
• Handle resize without layout overlap.
• Clean up ticker, renderer, textures, and event listeners on unmount.
• Keep INTO colors, hairlines, and restraint; petrol remains signal/action, not decoration.

Accessibility

• WCAG 2.2 AA for text and interactive states.
• Focus-visible on every interactive element.
• All controls have visible labels or accessible names.
• Tables use captions, th scope, and aria-sort when sortable.
• Use native table semantics for static tabular data; use ARIA grid only when cell-level keyboard navigation or editing is required.
• Modals trap focus and restore focus on close.
• Drawers and sheets announce their title and role.
• Toasts and async status changes use live regions.
• Color never carries state alone.
• Keyboard-only users can complete primary table, form, AI review, and admin tasks.
• At 200% zoom, the app must preserve reading order, focus order, and access to primary actions.

Screen QA Scorecard

Score each production screen before handoff.

Area	Pass Condition
Purpose	The screen’s primary job is obvious in five seconds.
Hierarchy	The current path, conclusion, evidence, and next action are visible.
State coverage	Loading, empty, error, success, partial, permission, and read-only states exist.
Lifecycle	Object state and allowed actions are clear.
Permissions	Denied or disabled actions explain why.
Recovery	Errors include recovery path.
Keyboard	Primary task works without a pointer.
Mobile	Mobile supports read, approve, and light edit without layout overlap.
Brand	Warm Light default, petrol action, no decorative SaaS chrome.

Agent Rule

Before generating or implementing an INTO web app, load this file, contexts/web-app-system.html, brand/button-system.md, brand/data-visualization-system.md, brand/diagram-system.md, and tokens/into-consulting.theme.css. For AI-native surfaces, also load brand/ai-software-platform-system.md and brand/ai-interface-patterns.md. Treat archive/source-evidence/website/design.md, archive/source-evidence/website/app-tokens.css, and archive/source-evidence/website/App Style Sheet.html as legacy calibration only. The canonical system is the routed web-app system.