Designing a web page or flow
Read web-craft first. An existing DESIGN.md or design system is the authority: follow it, do not invent a new
direction for an existing product.
1. Direction before code (new products and new large surfaces)
Decide and write down, briefly:
| Decision | Answer |
|---|---|
| User and job | Whose task does this surface make easier? |
| Priority | What must be seen and done first? |
| Composition | Editorial flow, split layout, dense workspace, product showcase, or something else |
| Typography | Character, scale, line length, script coverage for every planned language |
| Visual material | Real product images, photography, illustration, diagrams or type-led |
| Surface and density | Borders, tone, whitespace, data density, page rhythm |
| Motion | Functional feedback, plus narrative motion only where the product needs it |
| Signature detail | One or two consistent details that support the brand |
References: the existing brand comes first, then what the user gave. For a new direction pick a few fitting sources
and say what each one contributes (density, photography, rhythm, interaction, type). Adjectives like "modern" or
"clean" are not a decision. Do not copy logos, text or a whole composition. Options for a new product must differ in
composition and priority, not only in colour. Details: references/direction-and-references.md,
references/composition.md, references/typography.md.
2. Tokens
Colour (semantic, light and dark), type scale, spacing, radius, elevation and motion live as tokens in one place and
map onto the kit's theme. Elevation is limited: borders and surface tone first, a few single-layer low-opacity
shadow tokens for floating layers, lighter surfaces instead of shadows in dark mode, and no animated box-shadow.
Details: references/tokens-color-elevation.md.
3. Copy and hierarchy
Every text does one job. No eyebrow above a heading by default (progress, a date, a parent object or legal context
only; tier labels like "Premium" become a badge on the feature). Subtitles stay only for scope, result, risk or a
concrete fact. Heading levels follow structure, not font size. Placeholders never replace labels. Buttons
say what happens. Details: references/copy-hierarchy.md.
4. States
Build a state matrix for every data surface and form: initial load (layout-matched skeleton, delayed to avoid a
flash, static under reduced motion), empty (first use vs no results), error with retry and kept data, refreshing,
paging error, submitting, success, forbidden, not found, offline. Details: references/states.md.
5. Forms
Validate on blur, re-validate on change once an error shows, async checks debounced. On submit with errors: focus the
first invalid field, scroll it into view below any sticky header, open the collapsed section or step that holds it,
and show an error summary on long forms. Messages say what is wrong and how to fix it, sit next to the field and
are linked with aria-describedby. The submit button is disabled only while sending. Server field errors land on
their fields with the same scroll and focus. Details: references/forms.md.
6. Motion
Fill the motion matrix (references/motion-matrix.md) before picking a library:
- Buttons and links: hover where hover exists, pressed, focus-visible, loading, disabled.
- Dialogs, sheets, menus, popovers, toasts: always an enter and an exit animation (opacity plus a small scale or
translate, exit finishes before unmount), focus trap and return, dismissal. Details:
references/overlays.md. - Lists: insert, remove and reorder are understandable.
- Charts: a short draw-in on first view, transitions on data change, none above a measured data size, none under
reduced motion; tooltips reachable by keyboard and a table alternative. Details:
references/charts.md. - Marketing narrative: limited, product-specific, never hides content behind an animation.
Duration, easing and distance come from tokens. Not every page gets the same fade-up stagger. No artificial delay on forms or data screens. Reduced motion is handled centrally and covers CSS, libraries and video.
7. Responsive
Breakpoints follow content. Define what navigation, filters, tables, sticky actions, dialogs and popovers do on a
narrow screen. Check 320 px, long translated text, 200% zoom, touch and keyboard. A web dialog does not become a
React Native bottom sheet by default. Details: references/responsive.md.
8. Check the result
Look at it in a browser at mobile and desktop widths, in both themes and both languages, with keyboard only, and with reduced motion on. A static screenshot does not review motion; interact with it.
When a kit is reused across very different products, run the divergence test in references/pilot-divergence.md.