video-flow-toon/.impeccable.md

ToonFlow Design Context

Design Context

Users

ToonFlow serves creators and production teams turning novels, scripts, and source material into short-form video or drama assets. Primary users include AI video operators, short-drama producers, novel adaptation teams, prompt engineers, and internal content teams that need to move from planning to script, storyboard, assets, video generation, review, and export inside one workspace.

Their working context is production-heavy rather than casual browsing: users compare long text, inspect generated assets, operate model/provider settings, wait for asynchronous generation, revise prompts, and coordinate many related objects across projects. They need speed, traceability, confidence, and low cognitive friction more than decorative spectacle.

Core jobs to support:

• Create and manage short-drama projects from novels or source scripts.
• Extract chapter events and turn them into story skeletons, adaptation strategies, and structured scripts.
• Use ScriptAgent and ProductionAgent workflows while keeping generated decisions visible and editable.
• Organize characters, scenes, props, storyboard panels, generated images, video clips, and timeline-like tracks.
• Configure third-party text, image, and video model vendors safely.
• Review generated output, correct errors, regenerate selectively, and preserve production continuity across sessions.

Brand Personality

Working personality: capable, cinematic, production-grade.

ToonFlow should feel like an AI production control room for short-drama creation: efficient enough for repeated daily work, confident enough for professional teams, and cinematic enough to remind users that the end product is video storytelling. The interface voice should be direct, calm, and operational. It should reduce uncertainty during long AI tasks through visible progress, clear next actions, and reversible controls.

The product should not feel like a generic AI chat toy, a marketing landing page, or a decorative demo. It should feel like a serious creative workstation with enough visual warmth to make long production sessions comfortable.

Aesthetic Direction

Recommended direction: cinematic utilitarian workstation.

Use a dense but breathable desktop-first layout: persistent navigation, clear work regions, compact controls, object previews, status chips, task cards, editable panels, and canvas/timeline surfaces. The current UI already suggests a minimal black-and-white TDesign/Vue tool surface with rounded panels, left rail navigation, cards, tabs, Monaco editor usage, Vue Flow/infinite-canvas interactions, and production screenshots. The redesign should keep that operational clarity but make hierarchy, spacing, states, and visual rhythm more deliberate.

Signature move: storyboard-first production surfaces. When possible, make the core object visible: a project card should hint at story/style/progress; a storyboard item should carry thumbnail, duration, track, generation state, and dependencies; Agent output should show decision provenance and next action rather than plain chat blocks. The UI should help users see the production chain from novel to script to storyboard to video.

Visual guidance:

• Use the provided AirFlow Studio references as the primary color mood: deep blue-black workspace, soft indigo/violet depth, restrained cyan-teal accents, luminous but controlled data highlights, and cool off-white typography.
• Prefer dark/cinematic workspaces for the main product shell and production views, with enough contrast and surface separation for long editing sessions. Use light surfaces only when dense text editing or document review clearly benefits from them.
• Use cool-tinted neutrals instead of pure gray, pure black, or pure white.
• Use one primary action per surface; secondary actions should be icon buttons or quiet text buttons.
• Keep information dense but organized. Avoid oversized hero sections, decorative cards, nested cards, and generic SaaS marketing layouts.
• Use real thumbnails, generated assets, story snippets, status, and production metrics as visual material. Do not rely on abstract gradient decoration.
• Use motion as feedback: generation started, progress updated, asset completed, error needs intervention. Avoid bounce/elastic motion.

Design Principles

1. Production clarity over decoration. Every screen should answer: what project am I in, what stage is this, what changed, what is blocked, and what can I do next?

2. Preserve the creative chain. Novel events, script decisions, storyboard rows, assets, prompts, and generated videos should feel connected. Users should be able to trace output back to its source and revise without losing context.

3. Dense, calm, repeatable work surfaces. ToonFlow is used for long-form workflows with many objects. Prefer compact tables, split panes, drawers, tabs, inspector panels, and canvases over marketing-like sections or empty white space.

4. Human-in-control AI. Agent actions need visible progress, explicit confirmations for destructive changes, undo or rollback where practical, and readable explanations for generated decisions. Never hide model/provider failures behind vague errors.

5. Media-first proof. For video/image production, thumbnails, previews, track grouping, duration, generation state, and quality review are first-class UI elements. Text-only representations are fallback, not the primary experience.

6. Accessible by default. Target WCAG AA contrast, visible focus states, keyboard-reachable controls, 44px touch targets where mobile/tablet is supported, and prefers-reduced-motion handling for animations.

7. Avoid AI template fingerprints. Avoid purple-blue gradients, dark neon AI dashboards, glassmorphism everywhere, metric-card hero patterns, nested cards, generic rounded-icon feature blocks, gradient text, and monospace typography as a lazy "technical" signal.

Product Surface Inventory

Known product areas from the current repository and bundled screenshots:

• Project dashboard: project cards, creation/edit/delete actions, project metadata.
• Script workflow: source novel, chapter events, story skeleton, adaptation strategy, generated scripts.
• Production workflow: infinite canvas / Vue Flow-style workspace, storyboard panels, derived assets, storyboard images, video tracks, preview and export flow.
• Agent chat/work panels: ScriptAgent and ProductionAgent decision, execution, supervision streams.
• Asset management: characters, scenes, props, images, audio, video clips, uploads, batch generation.
• Image editing flow: node-style image flow editing and image regeneration.
• Settings: model selection, model map prompts, vendor configuration, programmable vendor TypeScript code, skill management, memory management, login/user settings, database import/export.
• Deployment/runtime: web build embedded in data/web, Electron desktop shell, Express/Socket.IO backend, SQLite local data, local data/oss assets.

Technical UI Context

• App shell: Electron desktop client plus web build served from data/web.
• Bundled frontend signals: Vue 3.5, TDesign 1.18, Vue Flow, Monaco editor, Pinia, Vue Router, Socket.IO, Axios, Day.js.
• Backend: Node/TypeScript, Express, Socket.IO, SQLite/Knex, AI SDK providers, ONNX embedding model for memory.
• The frontend source is not in this repository; this repo includes built assets. For substantial UI rewrites, use the ToonFlow web source repository or migrate/reconstruct frontend source before editing.

UI Quality Bar

The target quality is flagship internal production software, not MVP. Screens should be fast to scan, robust in edge cases, and polished enough that a production operator can trust the tool during multi-step generation runs.

Required states for major workflows:

• Empty: explain what to create/import next, with one clear primary action.
• Loading/generating: show task name, stage, elapsed/progress where available, and cancellation/continue affordances when safe.
• Partial success: show what completed, what failed, and what can be retried.
• Error: identify provider/model/action, show actionable recovery, preserve user input.
• Success: confirm result and expose the next useful action.

Color Direction From References

The color system should reference the two AirFlow Studio images provided by the product owner:

• Background mood: near-black with a blue/green undertone, not flat black.
• Depth color: deep navy and muted indigo for app shell, panels, charts, and canvas surroundings.
• Primary accent: cyan-teal for selected states, active labels, brand marks, and the most important progress signals.
• Secondary accent: soft violet/periwinkle for charts, AI activity, generated-state glow, and subtle atmosphere.
• Typography: cool off-white for primary text, lavender-gray for secondary text, muted blue-gray for low-emphasis labels.
• Surface style: translucent-looking dark panels are acceptable, but avoid heavy glassmorphism. Panels should remain readable, bounded, and utilitarian.

Suggested starting tokens:

• --bg-app: #050813
• --bg-shell: #090B18
• --surface-1: #111525
• --surface-2: #1A1D31
• --surface-3: #24263A
• --border-soft: #31354B
• --text-primary: #F1F2FF
• --text-secondary: #B9BCD2
• --text-muted: #7E849D
• --accent-teal: #65D9CB
• --accent-teal-strong: #43C7BD
• --accent-violet: #7B6CFF
• --accent-lavender: #B9A7FF
• --accent-warning: #FFB547
• --accent-danger: #FF6363
• --accent-success: #2BD671

Use these as direction tokens, then convert to OKLCH during implementation so hover, active, border, and disabled states can be generated perceptually rather than by arbitrary hex tweaks.

Visual System Starting Point

This is a starting direction, not a locked brand system:

• Palette: dark cinematic blue-black shell, muted indigo panels, cyan-teal primary accent, violet/periwinkle data and AI-activity highlights, semantic status colors for success/warning/error/info.
• Typography: clear Chinese-first sans-serif stack; consider a more distinctive UI font only if it renders Chinese and Latin well without slowing the desktop app. Do not use monospace globally; reserve it for code/config editors.
• Shape: current 8-12px radii are acceptable for panels and cards. Reference images use softly rounded dark cards; keep tool buttons stable and compact.
• Spacing: 4px base scale; dense screens can use 8/12/16px rhythms, major layout gaps 24/32px.
• Motion: 100-150ms for control feedback, 200-300ms for panel state changes, 300-500ms for larger canvas/task transitions, only transform/opacity where possible.

Anti-References

• Marketing landing page hero layouts for the main app.
• One-note dark neon "AI dashboard" styling. The reference palette is dark and cinematic, but it must stay restrained and production-focused.
• Generic purple/blue gradient branding as the dominant visual language. Violet can be used as atmosphere or chart/data accent, while cyan-teal should carry the clearer product identity.
• Card-inside-card structures for dense settings or production panels.
• Text-only Agent transcripts when structured task/progress/state UI would be clearer.
• Decorative media placeholders when real generated images or project objects are available.

Open Questions To Confirm

• Target users: internal production team only, public creator community, or both?
• Brand tone: should AirLabs/ToonFlow feel more enterprise, creator-friendly, cinematic, or experimental?
• Theme: should the redesign stay mainly light, add full dark mode, or use hybrid light workspace with dark media review?
• References: are there products whose workflow feel you like, such as Runway, CapCut desktop, Figma, Linear, Notion, ComfyUI, or professional NLE tools?
• Constraints: are there existing brand colors, logo assets, or AirLabs visual rules that must be preserved?