Skip to content

DESIGN

Introduction

Renderflow's design philosophy describes how the project should feel to the people who depend on it.

Conformance

This document is authored in conformance with:

  • .github/specs/architecture/document.spec.md
  • .github/specs/architecture/experience/design.spec.md

Purpose & Scope

This document defines the desired experience of using and understanding Renderflow.

It covers experiential goals, interaction philosophy, emotional qualities, and human-centered design direction. It does not define component libraries or layout implementation.

Definitions

  • Experience: the cumulative feeling of interacting with Renderflow across CLI, docs, outputs, and diagnostics.
  • Interaction philosophy: the recurring design stance that shapes user-facing behavior.
  • Cognitive load: the amount of mental effort required to understand what the system is doing.

Renderflow Design Philosophy

Renderflow should feel explicit

The system should help people see what they declared, what Renderflow inferred, and what will happen next.

Renderflow should feel calm under complexity

A simple single-output build should feel lightweight, while graph planning, plugins, and AI-assisted transforms should become available without making the basic path feel heavy.

Renderflow should feel trustworthy

Dry runs, diagnostics, stable terminology, and deterministic behavior should make the system feel dependable rather than magical.

Renderflow should feel empowering

The project should reward curiosity by exposing plans, optimization modes, plugin metadata, and system health instead of hiding them behind expert-only interfaces.

Renderflow should feel governed when intelligence is involved

AI-assisted behavior should communicate that the operator remains in charge and that automation is bounded by policy and explicit configuration.

Interaction Principles

  • Show intent before expensive execution when practical.
  • Make the happy path short without making the advanced path obscure.
  • Explain failures in terms of next action, not only internal error state.
  • Favor terminology that matches the ontology and architecture.
  • Let documentation and diagnostics teach the system as it is being used.

Requirements, Constraints & Guidelines

Requirements

  • Experience goals must align with the personal model and architectural principles.
  • Trust, clarity, and user agency must be visible in downstream interfaces.
  • The design philosophy must remain implementation-independent.

Constraints

  • Specific screen layouts, framework choices, or component details must not appear.
  • Temporary aesthetic trends must not define the design philosophy.
  • This document must not duplicate the design system.

Guidelines

  • Prefer clarity over ornament.
  • Prefer explicit feedback over hidden automation.
  • Prefer progressive disclosure over overwhelming density.

Authoring Contract

Purpose

Own Renderflow's design philosophy and experiential goals.

Responsibilities

This document owns:

  • the desired feel of using Renderflow,
  • interaction philosophy,
  • experiential goals,
  • accessibility and clarity as design values.

Non-Responsibilities

This document does not own:

  • design tokens,
  • implementation code,
  • product-specific layouts,
  • system decomposition.

Inputs

  • PURPOSE.md
  • PRINCIPLES.md
  • PERSONAL_MODEL.md
  • ARCHITECTURE.md

Outputs

  • DESIGN_SYSTEM.md
  • user-facing documentation
  • CLI and diagnostics behavior

AI Generation Rules

AI systems should describe the experience Renderflow should create, not a set of screens.

Validation

A contributor should be able to use this document to judge whether a change improves or weakens clarity, trust, and agency.

Acceptance Criteria

  • The design philosophy is explicit.
  • Interaction principles are understandable.
  • The document aligns with the personal model and principles.
  • Implementation-specific design details are absent.

AI Authoring Strategy

AI systems should:

  1. read upstream identity, ontology, personal-model, and architecture documents,
  2. infer the desired user experience,
  3. describe interaction qualities and values,
  4. avoid specifying layouts or components.

Rationale & Context

Renderflow already contains user-facing experiences that imply a philosophy: dry runs, graph explainability, watch mode resilience, plugin diagnostics, and AI-specific safety guidance. This document makes the intended experience behind those surfaces explicit.

Dependencies & External Integrations

Upstream Dependencies

  • PURPOSE.md
  • PRINCIPLES.md
  • PERSONAL_MODEL.md
  • ARCHITECTURE.md

Downstream Dependencies

  • DESIGN_SYSTEM.md
  • documentation UX
  • CLI and diagnostic behavior

Examples & Edge Cases

Example

A graph command that can export text, Mermaid, DOT, JSON, YAML, and Markdown supports the design goal that complex plans should still feel inspectable.

Edge Case

An advanced optimization feature may increase conceptual complexity, but it can still fit the design philosophy if the simple path remains clear and the feature is explained progressively.

Validation Criteria

This document is valid when contributors can explain how Renderflow should feel without naming any specific UI framework or terminal styling library.

  • .github/specs/architecture/document.spec.md
  • .github/specs/architecture/experience/design.spec.md