04-code-organization/08-ui-files.md

UI files

UI files

UI files render the visible interface of a Vroq app. They should focus on layout, composition, and connecting UI events to actions or local state.

UI code should stay readable and avoid mixing unrelated concerns like networking or deep state mutation.

Typical UI file types

Common UI files include:

• components (reusable presentation units)
• sections (feature-local UI fragments)
• top-level feature sections
• the root App.js

Responsibilities

UI files should:

• compose components and sections
• read necessary state
• dispatch actions in response to user events
• manage small local UI state when needed
• prefer provided Vroq design-system containers and typography helpers before using low-level HTML-like props or custom styling
• use the real calling signatures of framework helpers after reading the actual framework files when there is any doubt

UI files should not:

• contain reducer logic
• perform raw API calls directly
• hide complex state mutation

Event handling

UI events should normally dispatch actions or call small helper functions.

Example:

import { Button } from "/vroqjs/ui.js";

Button("Add", () => store.dispatch(addFile(file)))

This keeps state transitions visible in reducers.

Critical framework API rule

Do not guess the calling convention of UI helpers.

Before using a component, helper, or design-system primitive for the first time, read its actual implementation or framework source file to confirm:

• exported name
• argument order
• supported props
• child/content conventions
• return shape if relevant

Do not assume a component behaves like a similarly named React, HTML, or design-system primitive from another framework.

For example, Text(...) takes the text content first and props after that:

Text("Hello VroqJS")
Text(String(value), { weight: 700 })

Do not write:

Text({ as: "h1" }, "Hello VroqJS")

That pattern renders the props object as text such as [object Object] because the first argument is treated as the string content.

Design-system-first rule

Prefer provided Vroq containers and typography helpers before reaching for HTML-like props or custom styling.

Good:

VStack(
  { gap: "xl" },
  H1("Hello VroqJS"),
  H2("Counters")
)

Also good:

Card(
  VStack(
    { gap: "md" },
    H3("Counter A"),
    Text(String(value), { weight: 700 })
  )
)

Use low-level props such as as, size, or custom style only when the provided design-system helper is not sufficient for the required result.

Why this rule exists:

• it keeps apps visually consistent
• it preserves the value of the shared Vroq design system
• it prevents every app from inventing local HTML-like styling patterns
• it makes future framework-wide visual improvements apply automatically

When using a framework helper for the first time or when a signature is uncertain:

1. read the real framework file in appid: vroq 2. confirm the argument order and exported names 3. prefer the higher-level design-system helper when one exists 4. only then write or patch app code

Keeping UI readable

Good UI files:

• keep layout clear
• extract large fragments into sections
• extract reusable patterns into components

Avoid deeply nested logic in a single UI file.

Final rule

UI files should describe **what the interface looks like and how users interact with it**, while business logic lives in reducers, actions, and API clients.