Living set of conventions for visual output: HTML artifacts, wallpapers, diagrams, slides, generated imagery. Covers what’s shared across all of it. Dashboard-specific rules live in Dashboard Conventions; prose inside a visual follows Writing Conventions.
Rules
- Theme both color schemes. Drive colors from CSS custom properties that flip under
prefers-color-scheme, never a hardcoded palette. A page built for one scheme renders dark-on-dark or washed out on the other. This has been re-corrected across four or more sessions. - Smallest effective difference. Make a distinction as subtle as it can be while staying clear. Foreground separates from background without competing with it. Tufte, via Boxes and Arrows.
- Name the axis when describing color. Chroma and value move independently. Say which one changes, because “muted”, “softer”, and “sleeker” each have both readings and a generator picks the wrong one.
Defaults
See Prefer X over Y: the default is what you do unless there’s a reason, and the reason gets stated in one line.
- Prefer warm over cool. In both light and dark. Light vs dark is situational, warm is the constant. Warm and cool near-blacks differ by a few degrees of hue and that’s enough to read.
- Prefer low chroma over low value. “Muted” means desaturated at the same lightness, not darker. Dark palettes also want accent saturation cut 15 to 25 percent, so this is best practice as well as taste. ColorArchive.
- Prefer real domain content over decorative abstraction. Quant finance, graph theory, math notation over generic shapes. The specificity is what makes it land.
- Prefer a dense small-scale repeat over sparse or large motifs. “Not busy” means a ditsy repeat reading as all-over texture, not an empty canvas and not large shapes that overlap. Pattern Weaver.
Process
- Iterate by reference, not adjective. “Layout of image 4, palette of image 13” worked every time in the wallpaper session. Adjectives failed every time.
- State the criteria before generating, so a miss is checkable against something.
- Check the output against the description. A generator’s account of what it made is not evidence; verify against the pixels.
- The quality being aimed at is shibui: simple, subtle, unobtrusive, rewards a second look. Wikipedia.
Learnings
Corrections go in Visual (Chronicles/Learnings/Visual.md), which also holds this doc’s changelog. See 0020-conventions-and-learnings-two-type-capture.