jason.woltje
3ea385223e
ms-archify (evidence-based architectural mapping), ms-sdlc, ms-proactive-agent, ms-goal, ms-grill-me, ms-frontend-design.
91 lines
4.9 KiB
Markdown
91 lines
4.9 KiB
Markdown
# Visual system and interface writing
|
||
|
||
## VIS-01 — Subject-specific direction (SHOULD)
|
||
|
||
Ground visual decisions in the product, audience, content, and existing brand.
|
||
For a new direction, describe its composition, type roles, palette roles, and
|
||
one or two subject-specific choices. For an extension, inspect and reuse the
|
||
established system. Do not invent a new brand for a small repair.
|
||
|
||
Check whether imagery, hierarchy, density, and vocabulary serve the actual
|
||
brief. Visual novelty is not an acceptance test. Cream palettes, dark themes,
|
||
serifs, gradients, rounded cards, and uppercase labels are valid when they
|
||
have a purpose; none should appear merely out of habit.
|
||
|
||
## VIS-02 — Semantic tokens (SHOULD)
|
||
|
||
Reuse existing tokens first. For new systems define a compact set of roles:
|
||
|
||
| Area | Useful roles | Verification |
|
||
| --- | --- | --- |
|
||
| Color | canvas, surface, text, muted text, action, danger, focus | Check actual foreground/background pairs in relevant states and themes. |
|
||
| Type | display, heading, body, label, data | Repeated roles use consistent size, weight, and line height. |
|
||
| Space | component padding, related-item gap, group gap, section gap | Grouping survives wrapping and long content. |
|
||
| Geometry | content width, gutter, radius, elevation | Width and containment follow content priority; depth signals relationships. |
|
||
| Motion | feedback purpose, duration, easing, reduced-motion behavior | State remains understandable with motion reduced or removed. |
|
||
|
||
Add a token or variant for a repeated meaning, not every isolated value. A
|
||
small spacing scale based on 4 or 8 units is a possible house convention,
|
||
not a design law. Avoid competing CSS rules that conceal the intended spacing.
|
||
|
||
## VIS-03 — Typography and reading (SHOULD)
|
||
|
||
Choose type for legibility, tone, language coverage, loading cost, and the
|
||
existing brand. One family can supply hierarchy; a second needs a clear role.
|
||
Define a coherent scale instead of inventing each heading independently.
|
||
|
||
House starting points for running prose: about 45–75 characters per line and
|
||
1.4–1.6 line height. Adjust for the actual font, script, size, and content.
|
||
These are preferences, not accessibility thresholds. Controls, data tables,
|
||
and display text need their own metrics. Do not infer leading solely from
|
||
whether a font has serifs.
|
||
|
||
Inspect actual text, fallback fonts, long headings, and zoom. Avoid clipping,
|
||
fixed-height text containers, and shrinking text to force a layout to fit.
|
||
Use logical alignment appropriate to the language; reserve centered text for
|
||
content that remains easy to scan. Use tabular numerals when numeric alignment
|
||
helps comparison. Establish a fallback if a custom font fails.
|
||
|
||
## VIS-04 — Composition and restraint (SHOULD)
|
||
|
||
Give the primary task or message a clear place in the hierarchy. A marketing
|
||
site may benefit from an expressive opening; a work tool may need immediate
|
||
access to data and controls. Use real content to determine layout and density.
|
||
|
||
Outlines, dividers, labels, numbering, and cards should encode information.
|
||
Number items when sequence or rank matters. Reserve repeated containers for
|
||
content that is meaningfully comparable. Concentrate bold expression where
|
||
it helps the brief, and remove decoration that competes with the task.
|
||
|
||
Check wide and narrow compositions, long or missing content, image crops,
|
||
and consistent alignment. Choose layout transitions when content needs them,
|
||
then test around those transitions; device names alone do not define breakpoints.
|
||
|
||
## VIS-05 — Purposeful motion (SHOULD; reduced-motion support MUST)
|
||
|
||
Use motion to explain feedback, continuity, or a meaningful change. Keep
|
||
non-user-triggered effects restrained. Do not delay access to content for an
|
||
entrance animation. Respect reduced-motion preferences by removing or
|
||
replacing nonessential movement while preserving the information conveyed.
|
||
|
||
Verify the changed states with reduced motion enabled and ordinary animation
|
||
disabled. Hover may enhance an interaction but cannot be its only entry point.
|
||
|
||
## VIS-06 — Copy is functional content
|
||
|
||
Truthful behavior is a requirement; tone guidance is a heuristic.
|
||
|
||
Name actions by their outcome: "Save changes", "Download report", "Send
|
||
message". Keep vocabulary consistent through the flow, including success and
|
||
error messages. Use audience-appropriate language; technical terminology is
|
||
appropriate when it helps that audience make a decision.
|
||
|
||
Use concise active sentences and sentence case by default. Errors identify
|
||
the problem and recovery; empty states explain the condition and useful next
|
||
step. Distinguish first use, no matching results, and unavailable data.
|
||
|
||
Use supplied business facts. Mark sample content as sample in prototypes;
|
||
do not fabricate testimonials, customer counts, response times, team members,
|
||
contact methods, or privacy promises for a finished site. Maintain consistent
|
||
business identity and shared text through common configuration/components.
|