Design guide

Document type: UX/UI and implementation design guide · Audience: UX/UI, frontend, backend (handoff) · Not covered here: Executive program framing or platform engineering requirements — see Executive overview and Software engineering requirements specification

This guide describes what users see and how teams implement against the mockups. Backend engineers should use the “Backend handoff” section for contracts and boundaries when a real product is built.

1. UX principles

Clarity: Primary actions grouped under text disclosures and labeled lists.
Consistency: Reference viewports (phone, Ableton-style, desktop) for comparable screenshots.
Progressive disclosure: Sections collapsed by default until the user expands them.
Accessibility: Interactive controls use aria-pressed, groups, and focus styles.

2. Information architecture (shell)

Area	Role
UI configuration	Background modifiers and mockup viewport size presets.
Mockups	Loads HTML from `mockups/`: Standalone App Launch image; Plugins mock-ups (Utility, Pan, EQ, Saturator); Components (chromeless list + per-control pages); General User Interface Mockups (Settings, Presets, Export, Help).
Documents	Executive overview, software engineering requirements specification, this design guide; Archived documents hub for non-primary specs.
Viewport	Single iframe (`#mockup-iframe`) loads all mockups. Frame appears only when Mockups is open; loads HTML when the user picks an entry. UI configuration / Documents alone do not show an empty frame. Background theme is persisted (localStorage). Open sections, selected mockup, and viewport size are restored after refresh. Standard mockups show the frame title strip (macOS-style traffic lights); the red control closes the mockup. Component mockups use chromeless mode (chrome hidden).

3. Frontend implementation

3.1 Stack (current)

Static HTML, CSS (styles/backgrounds.css), vanilla JS in scripts/shell.js (shell only).
Nerd Font families loaded for UI chrome; icons via patched font glyphs.

3.2 Visual tokens

Panel: translucent left rail; viewport frame when Mockups is open.
UI configuration / Documents: stack tiles (cards). Mockups: flat rows + section headings.

3.3 Mockup pages

mockups/blueprint-01-mockup-wireframe.html: standalone launch art (same language as main.html) as the main mockup; below it, a collapsible Mockups and Wireframes block containing the You are a… card and black-on-white wireframe with standard wireframe subtext. Legacy pages under mockups/ may remain for reference.
Prefer semantic HTML and focus order matching visual order.

4. Backend handoff

The published site has no backend. For a future VST or web companion, backend teams should treat this repo as reference UI only.

API boundary (future): Presets, export jobs, or user settings would live behind authenticated APIs; mockups do not prescribe payload shapes—derive OpenAPI when product scope is fixed.
Data ownership: DAW-local vs cloud TBD; not specified in static mockups.
Real-time: No WebSocket or streaming assumptions in current mockups.

5. Deliverables checklist

UX/UI: Keep mockup HTML aligned with agreed menu labels and flows.
Frontend: When porting to app shell, preserve viewport and theme semantics where applicable.
Backend: Document new endpoints in repo or API portal when runtime work begins.

6. Fonts (inventory)

All typefaces referenced in this repo:

Font family (CSS name)	Where used	Source
`NF JetBrains` (JetBrains Mono NL Nerd Font)	Available in shell via `@font-face`; use when specified.	Nerd Fonts / OFL · jsDelivr
`NF FiraCode` (Fira Code Nerd Font)	Shell · optional monospace accent.	Nerd Fonts / OFL
`NF Hack` (Hack Nerd Font)	Shell stack tile titles, chrome.	Nerd Fonts / OFL
`NF UbuntuMono` (Ubuntu Mono Nerd Font)	Shell body default on `index.html`.	Nerd Fonts / UFPL
`system-ui`, `Segoe UI`, `Roboto`, sans-serif	Documents (`doc-styles.css`), several mockups.	System stack
`ui-monospace`, `monospace`	Fallback after Nerd Font stacks.	System

Third-party fonts (operational): Shell Nerd Font files are served from jsDelivr (see @font-face in styles/backgrounds.css). That implies a network request on first paint, CDN availability, and (for strict privacy policies) a third-party domain. Mitigations if needed: self-host font files under assets/fonts/ and point src: to local URLs; or rely on ui-monospace / system stacks only (visual change).

7. Launch art & wireframes

Standalone launch art (gradient, favicon mark, progress bar) lives in mockups/main.html and is reused in Blueprint 1. Wireframes in this repo use a white canvas with black structural lines and explicit Wireframe subtext. Favicon: assets/favicon.svg.

← Back to Iconoclast