stack/skills/ms-frontend-design/references/visual-system.md

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.