# Writing design.md

Use this outline as a section menu, not a form to fill. Keep the result declarative: state what each element does, when it applies, and what controls its appearance. Omit unsupported sections. A guide based on one screenshot can be useful while acknowledging that interaction and mobile behavior remain unknown.

## Suggested outline

### Title and intent

Choose a neutral aesthetic name. Describe its character in two or three sentences. State the captured surfaces, intended tasks, and content densities. When references differ, define shared foundations and the conditions for choosing each mode. Identify three or four defining decisions that a future design must preserve.

### Composition and hierarchy

Explain how to choose a composition around the new reader's task. Describe reading order, emphasis, content grouping, and the relationship between actions and supporting detail. Preserve those relationships across page types rather than copying a source sitemap or hero layout.

Make rules observable. For example: “Dense comparison tables use the content width; narrative text uses a narrower reading measure.” Include such a rule only if supported by the capture or labeled as a proposed default.

### Visual vocabulary

Use a compact table: `Role | Value or description | Usage | Basis`. Add a surface or mode column when a value varies by context.

Include the small set of values that controls the aesthetic:

- Color roles: canvas, surface, primary text, secondary text, action, status, and boundary, where visible.
- Type roles: display, heading, body, label, and data. Give family characteristics, size, weight, line height, and tracking where supported.
- Layout: reading measure, content or pane width, gutters, spacing rhythm, row/header heights, and density where relevant.
- Shape: radii, boundaries, elevation, and imagery or icon treatment when distinctive.

The basis is `measured`, `estimated`, or `proposed`. Sampled screenshot colors describe rendered pixels, not necessarily original tokens. Use approximate values or ranges for visual estimates. A handful of semantic CSS variables can help implementation; define them once and use neutral names. Full stylesheets and exhaustive source-token dumps add little to a portable guide.

Keep source font or package attribution in the evidence manifest. For typography, describe usable substitutes through traits: “low-contrast sans serif, open counters, tall lowercase forms; monospace for aligned numeric data.” Preserve role and metrics without naming the source font.

### Components and behavior

Describe the few components that carry the aesthetic, within their applicable surface. For each, give purpose, anatomy, variants, and observed states. Include navigation, controls, tables, cards, or dialogs only where the references support them. Capture icon size, stroke or fill, alignment, and state roles where visible; specify geometry and proportions rather than guessing the icon package. Explain pane boundaries, shared baselines, and scroll ownership when they shape the working interface.

Describe responsive transformations rather than listing guessed device breakpoints. Document motion by trigger, property, duration, and easing when observed. State how keyboard focus, reduced motion, contrast, and touch interaction should work; label additions as proposed when unobserved. Preserve the aesthetic while correcting inaccessible source behavior.

For physical references, use relevant materials, finishes, proportions, lighting, and control geometry instead of interface states.

### Extension rules and limits

State what stays fixed and what changes for a new product: type hierarchy may stay fixed while navigation labels and content grouping change. Give one or two short neutral examples only where they clarify an ambiguous rule. Describe aesthetic failure modes specifically and pair each with the intended treatment.

End with concise uncertainties and proposed defaults. Keep provenance URLs in the evidence manifest. `design.md` must be usable without loading that manifest or the raw references.

## Review questions

- Can another agent choose values and component treatments without the source site?
- Can the rules support two different tasks or page types within the captured scope?
- Are website, product, and presentation-frame rules assigned to the correct surfaces?
- Are precision and confidence consistent with the inspected evidence?
- Does every strong rule describe a design relationship rather than a source implementation accident?
- Does the document meet the skill's brand-neutrality contract?
