Brand system

AI Software Platform System

Foundation route: `contexts/web-app-system.html#ai-software-platform-system`.

Foundation route: contexts/web-app-system.html#ai-software-platform-system.

This source governs INTO-branded AI software platforms: project management, content operations, video generation pipelines, agent workspaces, dashboards, approval systems, collaborative operating rooms, internal tools, and future AI-native products. It extends the web-app system and does not override the design foundations, tokens, accessibility, or media waterfall.

1. Design Philosophy

INTO software should feel operationally powerful, calm, premium, and governable. The interface helps people understand what work exists, what the AI is doing, what evidence supports it, what needs human judgment, and what action is safe to take next.

The product language is editorial software, not generic admin dashboard. Use quiet hierarchy, strong information architecture, visible evidence, restrained motion, and exact states. Slightly cinematic moments are allowed only when they clarify command, focus, execution, review, render progress, or a major decision.

2. Product Assumptions

The default implementation stack is React, TypeScript, Tailwind CSS, shadcn/ui-style copied components, class-variance-authority, lucide-react, and Motion or Framer Motion.
Products support both light and dark mode through theme tokens.
Core records have lifecycle, ownership, permissions, review, audit, and version history.
AI output can be draft, suggestion, comparison, transformation, execution plan, generated media, or long-running task.
Irreversible or client-visible actions need evidence, preview, approval, audit, and rollback where possible.
Mobile supports read, review, approve, triage, capture, and light edits. It does not need to reproduce every desktop density pattern.

3. Visual Identity Direction

The system translates INTO into product UI:

Warm Light is the default work surface.
Blueprint Dark is for command, focus, review, presentation, photo/video preview, dramatic conclusion, and high-contrast operator moments.
Petrol signals primary action, current path, selection, active filter, and chosen option.
Saffron signals caution, milestone, comparison, deadline pressure, render checkpoint, or chart signal.
Green and red remain semantic state colors only.
Newsreader gives editorial weight to page titles, section breaks, quotes, major numerals, and title moments.
Lexend is the product workhorse for body, controls, labels, tables, and operational text.
IBM Plex Mono handles IDs, timestamps, states, paths, metrics, table headers, and source markers.
Lucide-style icons clarify commands, navigation, state, and tools. Icons do not become decoration, badges, or AI sparkle.

4. Light And Dark Mode Design Tokens

Use tokens/into-consulting.theme.css as the source of truth. Application code maps semantic component needs to --into-* variables. Do not introduce raw color values in components.

Need	Light/Dark token
Page background	`--into-app-surface-page`
Panel surface	`--into-app-surface-panel`
Muted surface	`--into-app-surface-muted`
Hover surface	`--into-app-surface-hover`
Skeleton surface	`--into-app-surface-skeleton`
Drop target	`--into-app-surface-drop-target`
Overlay	`--into-app-surface-overlay`
Scrim	`--into-app-surface-scrim`
Selected outline	`--into-app-selected-outline`
Primary text	`--into-text-primary`
Secondary text	`--into-text-secondary`
Muted text	`--into-text-muted`
Hairline	`--into-line-soft`
Strong divider	`--into-line-strong`
Action/current path	`--into-accent`
Positive state	`--into-state-positive`
Warning/milestone	`--into-state-warning`
Critical state	`--into-state-critical`
Focus ring	`--into-app-focus-ring`
Panel shadow	`--into-app-shadow-panel`
Floating shadow	`--into-app-shadow-floating`
Command shadow	`--into-app-shadow-command`
Accent glow	`--into-app-glow-accent`
Warning glow	`--into-app-glow-warning`
Glass surface	`--into-app-glass-surface`
Glass border	`--into-app-glass-border`
Backdrop blur	`--into-app-blur-surface`

Color usage by element:

Element	Rule
Background	Warm Light for normal work; Blueprint Dark only for governed focus, command, review, media preview, or dramatic moments.
Navigation	Neutral text and hairlines; petrol for current path or selected item.
Primary action	Petrol fill, inverse text, one per surface.
Secondary action	Hairline or pale surface; never competes with primary.
Selected row/filter/tab	Petrol text, rail, outline, underline, or soft surface before fill.
Warning	Saffron for caution, milestone, deadline, comparison, or render checkpoint.
Success	Green only when the task completed or the state is favorable.
Error/destructive	Red only for failure, blocked, destructive, or overdue-critical states.
AI cue	Four-point star or small mono label only; no purple-blue AI theming.
Chart	Teal/gray sequence with Saffron signal; avoid ungoverned categorical rainbows.
Media preview	Dark stage or neutral surface; overlays must preserve contrast and never hide focal content.

5. Typography System

Role	Family	Weight	Size / line-height	Letter spacing	Margins	Usage
App page title	Newsreader	400	`2rem / 1.15`	`0`	`0 0 1rem`	H1 for current page or workflow.
App section title	Newsreader	400	`1.25rem / 1.2`	`0`	`0 0 0.75rem`	Panels, sections, detail regions.
App body	Lexend	400	`1rem / 1.5`	`0`	`0 0 1rem`	Main copy and explanations.
App small	Lexend	400	`0.8125rem / 1.45`	`0`	`0`	Helper text, metadata, hints.
App label	IBM Plex Mono	500	`0.6875rem / 1.2`	`0`	`0 0 0.5rem`	Table headers, mono eyebrows, state labels.
App mono	IBM Plex Mono	400	`0.8125rem / 1.45`	`0`	`0`	IDs, paths, model names, timestamps.
App numeric	IBM Plex Mono	400	`0.875rem / 1.3`	`0`	`0`	Counts, hours, dates, money, render duration.
Button label	Lexend	500	`0.875rem / 1`	`0`	`0`	Buttons, segmented controls, menu commands.

Display and italics:

Newsreader display classes are allowed for covers, H1s, section breaks, quotes, major numerals, and editorial title moments.
Italics are limited to one short heading phrase for editorial contrast or quotation-like emphasis.
Never use italics in buttons, labels, body emphasis, table cells, chart labels, data labels, errors, badges, or AI output status.

6. Layout And Spacing System

Use the foundation baseline:

0.25rem micro baseline for type alignment.
0.5rem structural baseline for spacing, grid gutters, padding, controls, rows, and layout rhythm.
No arbitrary gaps when a token exists.
Browser-facing CSS uses rem and does not set a custom root font size.

Viewport grid:

Viewport	Columns	Side margin	Gutter	Rule
Mobile	1	`1rem`	`1rem` internal	Show the next useful decision first.
Tablet	6	`1.5rem`	`1rem`	Collapse sidebars into sheets or rails.
Desktop	12	`2rem`	`1.5rem`	Use dominant work region plus support.
Wide	12	`3rem+`	`1.5rem`	Increase side air before widening prose.

Max widths:

Reading-shaped pages: 60-72ch.
Normal app content: --into-app-content-max / 80rem.
Hybrid review pages: 90rem.
Full-width exhibits: tables, charts, screenshots, diagrams, media preview, timelines, boards, and dense evidence only.

Density:

Density	Use	Controls	Rows	Padding
Compact	Repeated operations, tables, queues	`2rem-2.5rem`	`2.5rem`	`1rem-1.5rem`
Standard	Default product UI	`2.5rem`	`3rem`	`1.5rem-2rem`
Spacious	Empty states, onboarding, review, media preview	`2.75rem-3rem`	`3rem+`	`2rem-3rem`

7. Surface, Elevation, Border, And Radius System

Use the containment ladder before adding boxes:

No box: type, spacing, alignment, and grid.
Hairline group: related controls, rows, and quiet boundaries.
Full-width exhibit: data table, chart, timeline, media preview, diagram, screenshot, prompt trace, or audit log.
Card: discrete peer item, metric, decision, record, approval item, or comparable module.

Radius:

Small controls: --into-radius-small.
Cards and peer modules: --into-radius-card.
Dialogs, drawers, command palette, media panels: --into-radius-panel.
Pill radius only for compact status dots, avatars, or segmented geometry where the object is truly round.

Elevation:

Default surfaces use hairlines, not shadows.
Panel shadow is allowed for command palettes, popovers, dropdowns, hover previews, floating drawers, media lightboxes, and drag overlays.
Floating shadow must never make the app feel like stacked cards.
Glow is reserved for active command surfaces, current render focus, selected media frames, and high-contrast Blueprint moments. It is not decoration.
Glass is dark/photo/media-stage only and needs controlled blur, border, contrast, and focus-visible state.

8. Motion And Animation Principles

Motion must name a job:

Confirm an action.
Reveal evidence.
Move work through a workflow.
Show long-running AI progress.
Resolve a drag/drop, reorder, or board move.
Transition between command, sheet, modal, or media preview states.
Stabilize AI streaming output.
Compare versions or model outputs.

Motion tokens:

Fast: --into-motion-duration-fast for hover, pressed, focus, small state.
Medium: --into-motion-duration-medium for sheet, tab, list, accordion.
Slow: --into-motion-duration-slow for composed reveal or media progress.
Ease: --into-motion-precision.

Use Motion or Framer Motion for composed state transitions, AnimatePresence for mounted/unmounted surfaces, layout for controlled layout changes, and a global reduced-motion provider such as MotionConfig reducedMotion="user". When reduced motion is active, replace transform travel with opacity or instant state.

Do not animate routine dashboard chrome, decorative loops, badge fields, sparkle effects, or page-load theatre.

9. Core Component Library

Every component must define purpose, anatomy, variants, states, responsive behavior, accessibility, motion, and reference-app usage before code.

Component	Purpose	Anatomy	Variants	Required states	Responsive / accessibility / motion	Reference uses
App shell	Holds global orientation.	Topbar, sidebar/rail, content, detail area.	Sidebar, rail, bottom tabs, command path.	Current, collapsed, permission-limited, offline.	Landmarks, skip link, focus order; mobile bottom tabs or compact menu.	All three apps.
Top navigation	Workspace and global actions.	Mark/name, breadcrumb, search, command, user menu.	Product, workspace, admin.	Current, scrolled, loading, permission.	Sticky only when useful; no shadow unless content passes under.	Project manager, social suite.
Sidebar navigation	Peer areas and object hierarchy.	Groups, items, counts, collapse control.	Expanded, rail, nested two levels max.	Current, disabled, permission, sync.	Mobile sheet or bottom tabs; labels required.	Project areas, content channels, pipeline stages.
Command palette	Fast navigation and action.	Search input, grouped results, shortcuts, footer.	Global, scoped, action-only, search-only.	Open, empty, loading, permission-filtered, failed action.	Combobox/listbox semantics, Escape, focus restore.	Find task, create post, render action.
Breadcrumbs	Show path and parent context.	Home, parents, current item.	Compact, full, object path.	Current, truncated, permission-limited.	Text labels; do not hide current page.	Project/task detail, campaign asset, video version.
Page headers	State the current job.	Eyebrow, H1, support line, primary action.	Object, list, dashboard, review.	Loading, stale, permission, archived.	Mobile action moves near task; no oversized hero.	All three apps.
Cards	Discrete peer objects.	Header, body, metadata, action.	Metric, record, decision, route, media asset.	Hover, selected, focus, loading, empty, error.	No nested cards; card is a peer item only.	Task card, post draft card, clip version card.
Panels	Persistent work regions.	Header, controls, body, footer.	Main, detail, inspector, evidence, media.	Loading, partial, blocked, read-only.	Hairline boundaries; may become sheet on mobile.	Evidence, inspector, render settings.
Tabs	Sibling views inside one area.	Tablist, trigger, panel.	Underline, segmented, vertical.	Selected, focus, disabled, loading.	Keyboard tablist behavior; not top-level nav.	Overview/activity/files, drafts/calendar, preview/history.
Accordions	Progressive disclosure.	Trigger, content, optional summary.	Single, multiple, nested max one level.	Open, closed, disabled, error inside.	Native button trigger; avoid hiding required actions.	Advanced filters, prompt details, render settings.
Buttons	Trigger actions.	Label, optional leading/trailing icon, spinner.	Primary, secondary, quiet, icon-only, split, destructive, loading, permission-disabled.	Hover, active, focus, disabled, loading, current, blocked.	Lexend 500; horizontal padding greater than vertical; icon-only needs tooltip/name.	All actions.
Button groups	Mutually related commands.	Group container, buttons, separators.	Segmented, toolbar, split.	Selected, mixed, disabled, overflow.	Roving focus where applicable; no color-only state.	View switcher, editor controls.
Inputs	Collect short values.	Label, field, helper, error.	Text, search, numeric, URL, token.	Focus, dirty, validating, error, success, disabled, read-only.	Labels required; field width matches expected value.	Task name, post title, render name.
Textareas	Draft longer content.	Label, field, counter, helper/error.	Plain, prompt, comment, markdown.	Focus, dirty, autosaving, limit, error.	Preserve resize when useful; no layout jump.	Prompt editor, caption draft, review note.
Selects	Choose from small known sets.	Trigger, value, list, option.	Single, multi, searchable.	Open, empty, disabled, invalid.	Native or accessible listbox; do not use for huge search.	Status, channel, model, owner.
Comboboxes	Search and select from larger sets.	Input, list, result, selected chips.	Single, multi, create-new.	Loading, empty, permission-filtered, error.	Combobox semantics; keyboard navigation.	Assign people, choose assets, select sources.
Checkboxes	Binary or multi-select.	Box, label, helper.	Single, group, indeterminate.	Checked, unchecked, mixed, disabled, error.	Label click target; state not color-only.	Bulk select, options, consent.
Toggles	Immediate binary setting.	Label, switch, state text.	On/off, permission-disabled.	On, off, focus, disabled, loading.	Use when effect is immediate; otherwise checkbox.	Automation safe mode, publish lock.
Date pickers	Choose date/range.	Field, calendar, presets.	Date, range, due date, schedule.	Open, invalid, blocked date, timezone.	Keyboard date entry; timezone visible when relevant.	Due date, social schedule, render deadline.
Upload	Bring files into system.	Drop zone, file list, progress, errors.	Single, multi, folder, replace.	Drag, uploading, paused, failed, scanned, complete.	Keyboard file input; progress text.	Assets, source files, video inputs.
Tables	Compare records.	Caption, toolbar, head, rows, row actions, pagination.	Static, selectable, sortable, editable, expandable, virtualized.	Loading, empty, filtered-empty, selected, error, partial, sync.	Native table unless grid behavior needed; stacked records on mobile.	Task list, content queue, render jobs.
Kanban boards	Move work through states.	Columns, cards, WIP counts, filters.	Single lane, swimlane, backlog.	Dragging, invalid move, blocked, no permission, archived.	Keyboard move alternative; mobile priority queue.	Task board, content status, video pipeline.
Timeline views	Show sequence and dependency.	Scale, phases, markers, current line.	Horizontal, vertical, dependency.	Active, delayed, blocked, completed, uncertain.	Mobile vertical phases; clear dates.	Project plan, campaign calendar, render process.
Calendar views	Schedule work and publishing.	Grid, event, filters, timezone.	Month, week, agenda.	Today, scheduled, conflict, missed, draft.	Agenda fallback on mobile; timezone accessible.	Content calendar, review schedule.
Workflow pipeline	Track multi-step process.	Stages, counts, blockers, owner.	Linear, branching, approval, render.	Queued, active, waiting, blocked, failed, completed.	Ordered list semantics or accessible grid.	All workflow products.
Approval queues	Decide what can proceed.	Item, evidence, risk, reviewer, action.	Content, execution, client-visible, second approval.	Requested, needs evidence, approved, rejected, expired, executed.	Decision card on mobile; consequence named.	Reviews, publishing, render approval.
Agent activity feeds	Show AI and system action.	Actor, action, timestamp, source, result.	Compact, detailed, filtered.	Streaming, failed, reverted, redacted.	Live region for active jobs; filterable history.	Agent task log, content AI actions, render agent.
AI chat panels	Conversational input only when useful.	Input, transcript, sources, actions.	Drafting, Q&A, review assistant.	Streaming, cited, partial, low-confidence, failed.	Stabilize layout; approval outside chat.	Ask project, draft caption, review script.
Prompt editors	Govern AI instructions.	Prompt, variables, tests, version, preview.	Simple, advanced, diff, template.	Dirty, validating, test running, saved, conflict.	Code-like editing with labels and history.	Prompt library, social prompts, video prompts.
Output preview panels	Inspect generated output.	Preview, metadata, sources, actions.	Text, image, video, post, diff.	Loading, partial, degraded, approved, failed.	Dark stage allowed for media; captions attached.	Draft preview, post preview, video preview.
Version history	Restore or compare changes.	List, diff, metadata, restore.	Record, prompt, asset, render.	Current, selected, restored, failed restore.	Restore preview before mutation.	Project plan versions, post edits, video cuts.
Status badges	Fast scannable state.	Text, optional dot, optional icon.	Neutral, info, warning, success, critical, AI.	Current, stale, disabled.	No decorative badge fields; text always present.	Any status.
Toasts	Short async feedback.	Message, optional action, close.	Success, info, warning, retry.	Open, dismissed, retrying.	`aria-live`; never hides primary controls.	Saved, queued, failed retry.
Tooltips	Clarify compact controls.	Trigger, content.	Label, help, shortcut.	Open, delayed, disabled trigger.	Not required to complete task; accessible name separate.	Icon buttons.
Modals	Interruptive decisions.	Header, body, footer.	Confirm, destructive, short form.	Open, loading, blocked, error.	Focus trap/restore; destructive consequence named.	Delete task, publish confirm, cancel render.
Drawers	Contextual work without route loss.	Header, body, footer, close.	Detail, filter, edit, evidence, approval, import map.	Dirty, saving, blocked, destructive pending.	Full-screen sheet on mobile.	Task detail, asset inspector, render settings.
Empty states	Explain absence and next step.	Title, cause, action, optional example.	First-use, filtered-empty, permission-empty.	N/A.	One action; no illustration unless useful.	Empty project, no drafts, no renders.
Loading skeletons	Preserve layout while loading.	Static blocks matching structure.	Table, card, media, form.	Loading, slow-loading.	No shimmer required; announce long waits.	All async views.
Error states	Recover from failure.	Cause, affected object, next action.	Field, inline, page, blocking, system.	Retrying, failed, partial.	Focus error summary; no color-only error.	Sync fail, publish fail, render fail.
Confirmation states	Show accepted outcome.	Message, changed object, next action.	Inline, toast, receipt.	Success, undo available.	Quiet, non-blocking unless receipt matters.	Save, approval, publish.
Data visualization blocks	Make data actionable.	Conclusion, chart/table, source, controls.	KPI, trend, funnel, workload, forecast.	Loading, stale, partial, no data, calculation error.	Source and period visible; keyboard-accessible data table fallback.	Workload, campaign performance, render metrics.
Settings screens	Configure product.	Sidebar, sections, forms, audit.	Workspace, user, AI, security, billing.	Dirty, saving, permission, audit.	Dangerous changes isolated.	Product-wide settings.
User/permission screens	Manage access.	Roles, members, scopes, audit.	Member list, role matrix, invite.	Pending invite, disabled, revoked, conflict.	Explain roles and visible consequences.	All apps with shared work.

Component Specification Template

Use this template before building or generating any reusable web-app primitive. The template makes component intent, CSS-token binding, states, responsive fallback, accessibility, and anti-patterns explicit enough for implementation.

Anatomy: named subparts, landmarks, semantic element, and required content.
CSS property table: map every surface, line, spacing, radius, shadow, focus, motion, and density decision to an existing --into-* token.
Variants: production variants only, with when-to-use rules.
States: loading, empty, error, success, partial, permission, conflict, sync-delayed, selected, focused, disabled, read-only, and reduced motion where relevant.
Responsive collapse: desktop, tablet, mobile, 390px, and 200 percent zoom behavior.
Accessibility contract: roles, names, keyboard path, live regions, focus management, touch targets, and contrast check.
Anti-patterns: the specific failures the primitive must prevent.

CSS property family	Required token binding
Page and panel surfaces	`--into-app-surface-page`, `--into-app-surface-panel`, `--into-app-surface-muted`
Selected, hover, skeleton, drop target	`--into-app-surface-selected`, `--into-app-surface-hover`, `--into-app-surface-skeleton`, `--into-app-surface-drop-target`
Text	`--into-text-primary`, `--into-text-secondary`, `--into-text-muted`, `--into-text-faint`, `--into-text-inverse`
Lines and focus	`--into-line-soft`, `--into-line-strong`, `--into-app-focus-ring`, `--into-app-selected-outline`
Action and state	`--into-accent`, `--into-accent-hover`, `--into-accent-soft`, `--into-state-positive`, `--into-state-warning`, `--into-state-critical`
State soft surfaces and ink	`--into-state-positive-soft`, `--into-state-positive-ink`, `--into-state-warning-soft`, `--into-state-warning-ink`, `--into-state-critical-soft`, `--into-state-critical-ink`
Spacing and structure	`--into-space-*`, `--into-app-content-padding`, `--into-app-content-padding-tablet`, `--into-app-content-padding-mobile`
Controls, rows, touch	`--into-app-control-small`, `--into-app-control-medium`, `--into-app-control-large`, `--into-app-row-height`, `--into-app-row-height-compact`, `--into-app-touch-target`
Density modes	`--into-density-compact-`, `--into-density-comfortable-`
Radius and containment	`--into-radius-small`, `--into-radius-card`, `--into-radius-panel`
Elevation and overlays	`--into-app-shadow-hairline`, `--into-app-shadow-panel`, `--into-app-shadow-floating`, `--into-app-shadow-command`, `--into-app-scrim-modal`, `--into-app-scrim-overlay`
Glass and command surfaces	`--into-app-glass-surface`, `--into-app-glass-surface-hover`, `--into-app-glass-border`, `--into-app-glass-border-hover`, `--into-app-blur-surface`
Motion	`--into-motion-instant`, `--into-motion-micro`, `--into-motion-quick`, `--into-motion-measured`, `--into-motion-precision`

Data Table Primitive

Template part	Specification
Anatomy	Caption, optional description, toolbar, saved view, filter/search, bulk action, table head, sortable headers, body rows, row action, expansion slot, pagination, empty/error/loading region.
CSS property table	Surfaces use `--into-app-surface-page` and `--into-app-surface-panel`; selected rows use `--into-app-surface-selected` plus `--into-app-selected-outline`; row height uses `--into-app-row-height` or `--into-app-row-height-compact`; sticky header lines use `--into-line-soft`; focus uses `--into-app-focus-ring`; status uses state tokens only.
Variants	Static comparison, selectable, sortable, editable, expandable, virtualized, permission-limited, audit log. Use ARIA grid only when cell-level editing changes the keyboard model.
States	Loading skeleton, empty, filtered-empty, selected, focused, disabled row, partial data, row error, sync delayed, permission denied, bulk-selected, expansion open, stale values.
Responsive collapse	Desktop keeps comparison columns. Tablet hides P3/P4 columns behind row details. Mobile becomes stacked records with P1 identity, P1 state, P1 owner/date, row action, and detail sheet; never hide critical state or next action.
Accessibility contract	Native `table`, caption, `th scope`, `aria-sort`, visible row actions, keyboard selection, focus-visible, status text, row expansion name, and no hover-only controls.
Anti-patterns	Horizontal scroll as the only mobile strategy, icon-only column headers, color-only row state, bulk actions without selection count, virtualized rows without stable focus recovery.

Form Field Primitive

Template part	Specification
Anatomy	Label, required/optional note, input/control, helper, validation message, character or unit affordance, dirty/saved state, field-level permission note, form-level error summary.
CSS property table	Field surfaces use `--into-app-surface-panel`; field lines use `--into-line-soft` and `--into-line-strong`; error uses `--into-state-critical`, `--into-state-critical-soft`, and `--into-state-critical-ink`; success uses positive tokens; warning uses Saffron state tokens; padding uses `--into-space-*`; control height uses app control tokens; focus uses `--into-app-focus-ring`.
Variants	Text, search, numeric, currency, URL, select, combobox, textarea, checkbox group, radio group, toggle, date, file upload, prompt variable, import mapping field.
States	Idle, focus, dirty, autosaving, saved, validating, error, warning, success, disabled, read-only, permission-denied, conflict, external sync delayed.
Responsive collapse	Desktop may use two-column forms only when fields are independent. Tablet collapses dependent groups. Mobile is one column with the error summary before fields and a sticky save bar that never covers focused input.
Accessibility contract	Visible label, helper via `aria-describedby`, error text linked to invalid field, form summary receives focus after failed submit, required state in text, native input where possible, no placeholder as label.
Anti-patterns	Hidden validation, disabled controls without reason, save buttons outside keyboard order, helper text replaced by icon-only tooltip, layout jump on error.

AI Workspace Shell Primitive

This primitive defines shell zones only. Prompt input, slash commands, streaming output, citations, traces, tool calls, model awareness, confidence, disclosure, refusal, feedback, attachments, and artifacts remain owned by brand/ai-interface-patterns.md.

Template part	Specification
Anatomy	App landmark shell, current path, task header, transcript or workbench, evidence/source panel, proposed-change region, approval gate, execution log, rollback route, persistent input, status/live region.
CSS property table	Warm reading surfaces use `--into-app-surface-page`; focus/review panels use `--into-app-surface-panel`; command or floating input uses glass tokens; selected evidence uses `--into-app-surface-selected`; AI state markers use `--into-ai-*` tokens only where already defined; approval warnings use state tokens.
Variants	Drafting, review, approval, execution, monitoring, rollback, side-by-side comparison, evidence-first.
States	Queued, streaming, cited, partial, low-confidence, source-missing, needs-human, approved, executing, failed, reverted, paused, cancelled, permission-limited.
Responsive collapse	Desktop can hold transcript, evidence, and approval side by side. Tablet turns evidence into a drawer. Mobile shows next safe decision first, then evidence, then transcript; input remains reachable without covering approval controls.
Accessibility contract	Announce AI status changes through a restrained live region, keep source links navigable, expose model/tool metadata in text, ensure approval controls are keyboard reachable, and never execute irreversible actions without human confirmation.
Anti-patterns	Generic chat as the whole product, purple-blue AI styling, hidden tool execution, evidence detached from decision, approval buried below the transcript.

Template part	Specification
Anatomy	Trigger, scrim when modal, surface, title, description, body, affected object, primary/secondary/destructive actions, close control, status or error region, focus return target.
CSS property table	Scrims use `--into-app-scrim-modal` or `--into-app-scrim-overlay`; surface uses `--into-app-surface-panel`; lines use `--into-line-soft`; elevation uses `--into-app-shadow-floating` or `--into-app-shadow-command`; spacing uses `--into-space-*`; focus uses `--into-app-focus-ring`; enter/exit uses motion tokens.
Variants	Confirm modal, destructive modal, short form modal, detail drawer, filter drawer, edit drawer, evidence drawer, approval sheet, import mapping sheet.
States	Open, closing, dirty, saving, saved, error, blocked, destructive pending, permission denied, loading, reduced motion, interrupted by route change.
Responsive collapse	Desktop drawers may be side panels and modals stay bounded. Tablet drawers may widen. Below mobile, drawers and most modals become full-screen sheets with close, save, and destructive action visible without horizontal overflow.
Accessibility contract	`dialog` semantics or accessible library primitive, title and description, focus trap when modal, focus restore, Escape behavior where safe, background inert, visible close, action consequence copy.
Anti-patterns	Modal for primary browsing, destructive action without object/consequence, sheet without close, hidden save, nested overlays, focus lost to page background.

10. AI-Native Component Patterns

AI must feel powerful but governed.

Pattern	Required UI contract
Human-in-the-loop approval	Show requested action, evidence count, risk, reviewer, consequence, approve/reject/request-change, audit result.
AI-generated drafts	Label as draft, show source/context, edited-by history, confidence or caveat when useful, and publish gate.
AI suggestions	Inline suggestion with accept, reject, explain, and source link. Never auto-apply risky changes.
Confidence indicators	Use only when calibrated and useful; pair numeric/label signal with explanation and next step.
Agent status	Queued, thinking, searching, drafting, waiting, needs human, executing, failed, complete, reverted.
Long-running tasks	Progress stage, elapsed time, expected next stage, cancel/pause when possible, activity log.
Background jobs	Persistent job tray or activity feed; no hidden execution.
Review queues	Group by risk, due date, owner, and client-visible consequence.
Prompt editing	Variables, test corpus, version history, approval, rollback, and permission states.
Prompt versioning	Diff, author, date, affected workflows, restore preview, approval state.
AI memory/context	Show included sources, excluded sources, freshness, privacy boundary, edit route.
Citations	Attached to claim or generated block; source title, date, owner, and retrieval state.
Output comparison	Side-by-side variants with criteria, source, model, cost/time if relevant, and selected rationale.
Audit logs	Prompt/request, context, model/tool, evidence, human reviewer, execution, rollback.
Human/AI handoff	Owner, current state, what AI did, what human must decide, due time, safe next action.
AI action failure	Error cause, affected objects, retry, rollback, manual route, support log.
Needs human judgment	Stop automation; show why judgment is needed and which role can decide.
Safe automation	Mode, scope, limit, approval threshold, rollback plan, kill switch, last run.

11. Workflow And Pipeline UI Patterns

Use workflow primitives by job:

Project work: table for comparison, board for state movement, timeline for dependency, detail drawer for record work, approval queue for reviews.
Content operations: calendar for scheduled publishing, pipeline for draft to publish, preview panel for channel output, queue for approval, audit for external visibility.
Video generation: stage pipeline for prompt, source, generation, render, review, approval, export; preview stage for media; render queue for jobs.

Pipeline anatomy:

Intake -> Draft/Generate -> Review -> Approve -> Execute/Render/Publish -> Measure -> Archive.

Each stage defines owner, allowed actions, required evidence, state color, automation level, manual override, and rollback.

12. Collaboration UI Patterns

Presence appears only when it changes editing, lock, review, approval, or handoff behavior.
Comments must anchor to records, fields, rows, chart points, media frames, sources, or decisions.
Reviews separate comment approval, content approval, execution approval, and client-visible approval.
Notifications use object, reason, action format: “Video v4 render failed: retry or open logs.”
Client-visible and external-link states must be labelled before export, publish, share, or agent execution.
AI cannot silently overwrite human work. Conflicts show prior, attempted, and latest values plus recovery.

13. Dashboard And Analytics UI Patterns

Dashboards exist to answer “what changed, why it matters, and what to do.”

Required analytics anatomy:

Conclusion title.
Period and source.
Metric or chart.
Delta with meaning.
Segment/filter controls.
Caveat or calculation note where relevant.
Drill-in route.
Next action.

Use no more than four KPI modules in the first viewport. Use tables when precise comparison matters. Use charts only when shape, distribution, trend, or comparison is the point.

14. Form And Data-Entry Patterns

Label every field. Placeholder is never the label.
Group by decision or object, not visual symmetry.
Show helper text before error text when the rule is not obvious.
Validate inline and summarize errors at the form level after submit.
Dirty forms need save, cancel, unsaved-change warning, and conflict recovery.
Import forms use upload, map, validate, preview, commit, report.
Prompt forms include variables, source scope, privacy boundary, test run, version, approval, and rollback.
Media forms include asset constraints, aspect ratio, source rights, caption, and export destination.

15. State Design

State	UI requirement
Empty	Explain absence, scope, and one next action.
Loading	Show static structure quickly; avoid unstable controls.
Success	Quiet confirmation with changed object and next action if needed.
Warning	Saffron signal plus consequence and recovery.
Error	Cause, affected object, recovery, retry/manual path.
Disabled	Visible reason when the action is expected.
Read-only	Explain lock, role, source, or archived state.
Processing	Stage, progress, elapsed time, cancel/pause if safe.
Approval	Reviewer, evidence, consequence, expiry, approve/reject/change.
Partial data	Show loaded scope, missing scope, freshness, and risk.
Permission denied	Required role, owner, request route, safe fallback.
Conflict	Prior value, attempted value, latest value, choose/retry route.
Offline/sync delayed	Last successful sync, affected records, retry/reconnect.
Archived/deleted	Retention, restore path, audit, permanent consequence.
Reduced motion	Same information without transform-heavy transitions.

16. Accessibility Guidelines

Meet WCAG 2.2 AA for text and interactive contrast.
Preserve keyboard path for the primary workflow.
Never remove focus-visible.
Icon-only controls need accessible names and tooltips.
Tables use captions, scoped headers, aria-sort when sortable, and keyboard row actions.
Use native table semantics unless cell-level editing requires ARIA grid.
Dialogs and modal drawers trap focus, restore focus, and support Escape where safe.
Toasts and asynchronous status changes use live regions.
State is never color-only.
Touch targets are at least 2.75rem where touch is likely.
200 percent zoom preserves reading order and access to primary actions.
Streaming AI output needs status announcements without overwhelming screen readers.
Canvas or media-only views need static summaries and keyboard-equivalent controls.

Component-specific checklist:

Component	Required accessibility checks
App shell	Landmarks, skip link, current route, keyboard order, collapsed-nav labels, bottom-tab labels, and no icon-only primary navigation.
Data table	Caption, scoped headers, `aria-sort`, keyboard row actions, selection count, expansion control name, partial/error text, and stacked-record mobile equivalence.
Form field	Visible label, helper association, error association, required text, dirty/save state, error-summary focus, conflict recovery, and mobile sticky-bar clearance.
AI workspace shell	Status live region, navigable citations/evidence, model/tool metadata in text, approval controls before irreversible execution, and rollback route.
Modal / drawer / sheet	Title, description, focus trap when modal, focus restore, Escape behavior, inert background, visible close, consequence copy, and full-screen mobile sheet behavior.
Toast / alert	`aria-live`, persistent critical alerts, retry action text, no hidden primary control, and no color-only severity.
Canvas / PixiJS view	Static summary, data-table fallback when the canvas carries data meaning, keyboard-equivalent controls, reduced-motion path, and paused hidden render loops.

Contrast verification table:

Pair	Warm Light ratio	Blueprint Dark ratio	Status
Primary text on page	16.67:1	15.83:1	AA pass
Secondary text on page	13.01:1	11.60:1	AA pass
Muted text on page	7.14:1	7.10:1	AA pass
Primary text on raised panel	15.43:1	14.66:1	AA pass
Primary text on muted surface	14.23:1	13.08:1	AA pass
Inverse text on accent action	9.44:1	7.57:1	AA pass
Inverse text on critical action	5.14:1	6.71:1	AA pass
Positive action text/surface pair	5.02:1	9.11:1	AA pass
Warning ink/surface pair	11.14:1	11.78:1	AA pass

17. Responsive Design Rules

Mobile: one task, one decision, one primary action. Dense data becomes stacked records, one-lane queue, agenda, or sheet.
Tablet: keep the main work visible; move inspectors into drawers or side sheets.
Desktop: use dominant work region with supporting inspector, evidence, or activity region.
Wide desktop: widen exhibits before prose. Increase side air before line length.
Sticky bars must not cover focused fields, row actions, media controls, or approval decisions.
Tables collapse by priority fields, not by hiding critical state.
Boards collapse to a queue or one lane. Do not miniaturize all columns.
Calendars collapse to agenda.
Media previews preserve aspect ratio and controls.

18. Implementation Guidance For React, Tailwind, And Shadcn-Style Components

Implementation principles:

Treat shadcn/ui as open component source and anatomy, not as a visual theme.
Use copied component ownership: components live in the product repo and can be restyled to INTO tokens.
Use Tailwind CSS variables or @theme inline to expose --into-* tokens as utilities. Components should reference semantic tokens, not raw values.
Use class-variance-authority for component variants and sizes.
Use lucide-react for icons when a familiar command icon exists. Keep icons currentColor, outline, and accessible.
Use Radix-style primitives for dialog, sheet, popover, dropdown, tooltip, command, tabs, accordion, select, and checkbox when available.
Use Motion for state transitions that need mount/unmount or layout animation. Wrap the app in reduced-motion support.

Suggested component file shape:

// components/ui/button.tsx
import { Slot } from "@radix-ui/react-slot"
import { cva, type VariantProps } from "class-variance-authority"
import { Loader2 } from "lucide-react"
import { cn } from "@/lib/utils"

const buttonVariants = cva(
  "inline-flex items-center justify-start gap-2 rounded-[var(--into-radius-small)] font-[var(--into-font-sans)] font-medium tracking-[0] transition-colors focus-visible:outline-none focus-visible:shadow-[var(--into-app-focus-ring)] disabled:pointer-events-none disabled:opacity-55",
  {
    variants: {
      variant: {
        primary: "bg-[var(--into-accent)] text-[var(--into-text-inverse)] hover:bg-[var(--into-accent-hover)]",
        secondary: "border border-[var(--into-line-soft)] bg-transparent text-[var(--into-text-primary)] hover:bg-[var(--into-app-surface-hover)]",
        quiet: "bg-transparent text-[var(--into-text-secondary)] hover:text-[var(--into-text-primary)]",
        destructive: "bg-[var(--into-state-critical)] text-[var(--into-text-inverse)]",
      },
      size: {
        compact: "h-[var(--into-button-height-compact)] px-[var(--into-button-padding-x-compact)] py-[var(--into-button-padding-y-compact)] text-[var(--into-type-floor-button-compact)]",
        default: "h-[var(--into-button-height-default)] px-[var(--into-button-padding-x-default)] py-[var(--into-button-padding-y-default)] text-[var(--into-type-floor-button)]",
        touch: "h-[var(--into-button-height-touch)] px-[var(--into-button-padding-x-touch)] py-[var(--into-button-padding-y-touch)] text-[var(--into-type-floor-button)]",
      },
    },
    defaultVariants: { variant: "secondary", size: "default" },
  }
)

Naming conventions:

Components: AppShell, PageHeader, DataTable, ApprovalQueue, AgentActivityFeed, PromptEditor, OutputPreviewPanel.
Variants: variant, size, density, state, tone.
Props for high-risk controls: isLoading, isCurrent, permissionReason, destructiveLevel, requiresApproval, auditEvent.
State names are product vocabulary: queued, generating, needsHuman, approved, publishing, rendering, failed, reverted.

Acceptance criteria:

No hard-coded colors, shadows, radii, spacing, or type in components when a token exists.
Light and dark mode render every component state.
Every interactive component has keyboard, focus-visible, loading, disabled, error, and reduced-motion behavior where relevant.
Components expose enough props that builders do not invent visual variants at the screen layer.

19. Example Screens

Project Manager AI

Screen: Workstream command center.

App shell: project sidebar, top command path, global search.
Main region: timeline plus task table; one current blocker highlighted.
Inspector: AI proposal with evidence, owner, risk, approval gate.
Components: App shell, command palette, page header, table, board/timeline, approval queue, agent activity feed, detail drawer, comments, audit log.
States: draft, active, blocked, needs human, approved, overdue, sync delayed, conflict, archived.
Mobile: “Today / Needs Review” queue with blocker, owner, due date, evidence, approve/request-change actions.
QA proof: human can assign work, review AI suggestion, approve execution, and audit the change without losing context.

Screen: Campaign content operations.

App shell: channels, campaigns, approvals, calendar, assets, settings.
Main region: content pipeline from brief to draft to review to scheduled to published.
Preview: channel-specific post preview with image/video/caption, source citations, brand checks, and approval state.
Components: calendar, kanban board, prompt editor, output preview, approval queue, upload, comments, version history, analytics block.
States: generated draft, needs brand review, citation missing, scheduled, publish failed, published, pulled, client-visible.
Mobile: approval inbox and scheduled-post preview, not full calendar grid.
QA proof: user can create an AI draft, inspect sources, edit prompt, compare versions, approve, schedule, publish, and recover from failure.

Video Generation Pipeline

Screen: Render pipeline and review room.

App shell: projects, source assets, prompts, renders, approvals, exports.
Main region: stage pipeline for prompt, source, generation, render, review, approval, export.
Media region: dark preview stage with caption, source notes, version selector, timeline markers, and render status.
Components: upload, prompt editor, workflow pipeline, render queue, output preview, version history, approval gate, activity feed, error recovery.
States: source missing, queued, generating, rendering, preview ready, needs human judgment, approved, export failed, published, reverted.
Mobile: render status plus approval/reject/request-change decision card.
QA proof: user can start a render, monitor progress, compare versions, approve or reject, export with audit, and retry failed render safely.

20. Design QA Checklist For AI Builders And Coders

Read ai/START_HERE.md, contexts/web-app-system.html, media/web-apps.md, this file, and templates/web-app/style-system.md.
Run the implementation sufficiency audit before final screens.
Confirm all referenced tokens exist in tokens/into-consulting.theme.css.
Confirm light and dark mode for every component state.
Confirm component variants are built through props or CVA, not ad hoc screen classes.
Confirm one primary action per surface.
Confirm AI actions show evidence, source/context, approval, audit, and rollback where needed.
Confirm no silent AI overwrite path exists.
Confirm keyboard path completes the primary workflow.
Confirm focus-visible and error recovery.
Confirm 390px mobile behavior for dense tables, boards, calendars, and drawers.
Confirm reduced-motion behavior for every animated surface.
Confirm no decorative badge walls, nested cards, generic SaaS chrome, purple-blue AI styling, or stock imagery.
Confirm favicon uses assets/favicon.svg or an export from that square mark.
Confirm major examples show real workflow pressure and one next useful decision.

21. Self-Audit Results And Repairs Made

The web-app system already covered baseline type, spacing, grid, heuristics, data views, forms, AI review, collaboration, and accessibility. The following gaps would still cause implementation drift for AI software platforms:

Gap	Why it would block builders	Repair encoded here
No single AI software platform source	Builders would scatter product UI rules across media, template, and HTML summaries.	Added this source file and route it from the hybrid web-app system.
Surface/elevation/glass tokens were less explicit than color tokens	Product teams would invent shadows, glow, and glass per app.	Added app shadow, glow, glass, and blur token requirements.
Component list did not cover the full requested platform library	AI coders could omit prompt editors, version history, render queues, permission screens, or media previews.	Added a component matrix covering the requested primitives and states.
New reference apps were not represented	Examples would keep optimizing for workshop/timesheet/polling rather than project/social/video platforms.	Added Project Manager AI, Social Media AI Suite, and Video Generation Pipeline screen contracts.
React/Tailwind/shadcn guidance needed a current implementation contract	Coders could copy shadcn visuals or hard-code Tailwind values.	Added token-first, copied-component, CVA, Lucide, Radix, and Motion guidance.
AI governance needed a stronger state vocabulary	AI features could look powerful while hiding risk, evidence, or rollback.	Added AI-native patterns for approval, confidence, memory/context, audit, safe automation, and failure recovery.

This repair makes the design system complete enough for a coding AI to build a first component library and the three reference application screens without inventing core visual language, interaction states, or AI governance logic.