Design craft
A working method for frontend design and build. SKILL.md holds what every task needs; the
references/ files hold depth, numbers and code. Read one when its trigger in the table at the end applies.
Scope: a new page, flow or component runs steps 1-8. A small change (one state, one animation, one string) runs only the steps it touches, then step 8 on what changed.
Order of needs
Functional → reliable → usable → pleasurable. Never add delight to something broken, slow or confusing, and never ship without the top layer either: personality deferred to "later" rarely ships.
1. Frame (before any code)
- Job story: When [situation], I want to [motivation], so I can [outcome]. Unknown situation or outcome → ask, or state the assumption as a hypothesis in your summary.
- Pick the ambition the brief asks for, and spend effort there:
| Brief | Invest in | First proof |
|---|---|---|
| Brand site, "premium", "award-level", "full of animation" | One signature interaction grounded in the subject (step 2) | The interaction working on real content: start, middle, interruption, release |
| Launch, editorial, marketing page | The offer is clear and its best evidence is explorable | First screen read on a phone; main action reachable with no waiting |
| App, tool, dashboard | The hardest decision, cost of a mistake, speed of repeat use | A realistic task with changing data, plus recovery from one failure |
| Component or design system | A behavioural contract that survives two different consumers | The same component in two contexts with long content |
- Separate facts from assumptions. Name the visitor's emotional state on arrival; it sets the tone.
- Check what exists: tokens, components, patterns, conventions. Reuse before inventing.
2. Find the signature in the subject
For expressive work, look for a property of the subject the visitor would recognise with the logo covered, and a verb that lets them steer it. A beer pours, foams and shows its colour; a fabric drapes; a typeface has axes; a watch has a movement. Design the interaction around that property.
- Substitution test: swap in an unrelated brand. If the effect still works untouched, it isn't about the subject yet. Return to the subject before adding polish.
- Four beats: what invites input → what responds on contact → what is revealed under sustained input → what remains on release. One persistent object should carry all four.
- More effects never fix "it feels basic". Change the central idea or mechanic instead.
- Every gesture gets a plain equivalent (a slider, a button, a radio group) that reaches the same information.
3. Explore cheaply, prove the hardest part first
- Describe at least three structurally different approaches in a few lines each. Pick one, say why.
- Compose a still frame with real content before motion: reading order, type, imagery, primary action. A frame from the middle of any animation should also look intentional.
- Build the riskiest claim first (the gesture, the scroll scene, the hard workflow) and check it in a real browser before building the rest of the page around it.
4. System first
- Tokens before components. Components consume semantic tokens (
--color-action) that alias primitives (--amber-400). No hex, px or magic numbers inside component styles. - Spacing on a 4-based scale (4, 8, 12, 16, 24, 32, 48, 64). Body 16px/1rem at 1.5 line-height; headings 1.1-1.25. One modular type ratio. Two typefaces max (+ mono). Tabular numerals for changing numbers.
- 1-3 brand colours, neutrals, status colours. Every text pair passes WCAG AA (4.5:1 body, 3:1 large/UI). Colour is never the only signal.
- Motion tokens (durations, easings) live beside colour and spacing.
- Props name meaning (
variant="destructive"), not looks. Repeated overrides mean a missing variant.
5. Every state, not just the happy path
Interactive components: default, hover, focus-visible, active, disabled, loading, error, selected. Screens: empty, loading, partial, error, success, offline. Async work:
- Latest request wins; a slow older response must not overwrite a newer one.
- Keep the user's input after any failure, and keep previous results visible (dimmed) while loading.
- Empty account, no results and failed fetch are different states with different next actions.
Keyboard-operable, semantic HTML first, ARIA only where HTML can't say it, a label on every field, a visible way out of every modal, and focus returned to something sensible when it closes.
6. Emotion, copy and honesty
- Clarity beats cleverness. If a joke needs an extra sentence, cut it. Contractions, plain words.
- Voice is constant, tone shifts: warm on success, plain and calm on errors, gentle on sensitive input.
- Errors: what happened, why, what to do next, and what was kept. Never blame the user. No humour here.
- Empty states invite: what will appear here plus one clear first action.
- Peak-end: place the one big delight at the end of a real accomplishment, never in a frustration valley.
- On high-stakes pages, name the visitor's fears and answer each before the call to action.
- Imagery: a diverse cast by default; ask "who are we excluding?"
- Honesty: label AI-generated imagery and demo data where people could mistake them for real. Copy must match what images show (a can that prints 5.0% means the page says 5.0%).
- Regulated categories (alcohol, finance, health, kids): add the required gate or disclosure and check imagery against the category's advertising norms, e.g. no sexualised imagery for alcohol.
7. Motion
Every animation has a job: context, attention, feedback or personality. No job, no animation.
| Token | Value | Use |
|---|---|---|
--dur-1 | 100ms | press, focus, toggle (≈ the perceptual floor) |
--dur-2 | 200ms | most UI transitions, hover, small enter |
--dur-3 | 300ms | panels, drawers, modals |
--dur-4 | 400-500ms | full-screen or hero choreography only |
--ease-out | cubic-bezier(0,0,.2,1) | entering / gaining attention |
--ease-in | cubic-bezier(.4,0,1,1) | leaving / losing attention (exits ~20-30% shorter) |
--ease-in-out | cubic-bezier(.4,0,.2,1) | moving between on-screen positions |
| spring | critically damped, retargetable | gestures; preserve velocity when the target changes |
- Never block the main action on choreography. A preloader or intro must not hold the primary action for more than about a second, and returning visitors skip it.
- Spatial consistency: things leave the way they came; shared elements morph in place.
- Stagger 30-60ms with a decaying delay (
base*√i); keep the whole sequence under ~300ms. - Scroll scenes: progress maps from the section's measured travel, so the same scroll position always gives the same frame, scrolling up reverses cleanly, and direct links into the middle work.
- Gestures: one owner of progress; the grip stays attached to the pointer; release hands velocity to a spring; interruption mid-flight leaves the UI operable.
- Animate
transformandopacityonly. Underprefers-reduced-motion, remove travel, parallax, zoom and autoplay, keep short fades, and still let user-driven gestures work. - Engineering traps that broke real builds (one property, one owner; paused scroll timelines; snap
labels inside the timeline; non-negative frame time; preloading swappable assets):
references/motion-engineering.md.
8. Verify in a real browser, then hand off
Run scripts/walk.py (Playwright + local Chrome) at desktop, phone and reduced motion: real pointer drag,
scroll through every section, console errors, sideways overflow. A hidden or minimised preview pane
throttles animation frames, so don't judge motion from it. Details: references/verification.md.
Then critique against the job story, not taste:
- Does it meet the job story? Is the primary action the most prominent thing, and reachable everywhere?
- All states present (step 5)? Keyboard, screen-reader labels, contrast?
- Tokens only? Existing components reused?
- Copy follows step 6, including honesty labels?
- Every animation has a job, the right easing direction, an interruption path and a reduced-motion path?
- Does the signature pass the substitution test? Is there one peak, placed at an ending?
- What would I cut? Remove one element or effect and see if it gets better.
Hand off with the rationale: the problem, the approach, alternatives rejected and why, what was
exercised and how (emulation vs a real device), and known limits. Template:
references/process-and-teams.md Appendix B.
References
| Read | When |
|---|---|
references/motion-engineering.md | building any GSAP/ScrollTrigger/Lenis, canvas, gesture or scroll-scene work |
references/verification.md | before calling any visual or interactive work done |
references/imagery.md | generating or preparing images, product cut-outs, art direction |
references/animation.md | choreography, the 7 motion principles, stagger maths, motion tokens |
references/emotion.md | design persona, onboarding, delight, trust and fear, outage copy |
references/design-systems.md | tokens, component APIs, governance, versioning, docs |
references/product-design.md | research, story-first, sketching, feedback, prototyping, testing |
references/design-thinking.md | an ambiguous problem needing empathise/define/ideate/prototype/test |
references/design-engineering.md | choosing prototype fidelity, design↔code handshake |
references/process-and-teams.md | critique sessions, rationale and handoff templates, DesignOps |