Communitygithub.com

design-craft

Shows an agent how to art-direct and build "design craft" so the concrete output is a landing page, homepage, or portfolio. The procedure moves through Design craft, Order of needs, 1. Frame (before any code). Use it when a new assignment calls for this craft.

What is design-craft?

design-craft is a Claude Code agent skill that shows an agent how to art-direct and build "design craft" so the concrete output is a landing page, homepage, or portfolio. The procedure moves through Design craft, Order of needs, 1. Frame (before any code). Use it when a new assignment calls for this craft.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Iitian001/design-craft/tree/HEAD/skills/design-craft

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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:
BriefInvest inFirst 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 pageThe offer is clear and its best evidence is explorableFirst screen read on a phone; main action reachable with no waiting
App, tool, dashboardThe hardest decision, cost of a mistake, speed of repeat useA realistic task with changing data, plus recovery from one failure
Component or design systemA behavioural contract that survives two different consumersThe 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.

TokenValueUse
--dur-1100mspress, focus, toggle (≈ the perceptual floor)
--dur-2200msmost UI transitions, hover, small enter
--dur-3300mspanels, drawers, modals
--dur-4400-500msfull-screen or hero choreography only
--ease-outcubic-bezier(0,0,.2,1)entering / gaining attention
--ease-incubic-bezier(.4,0,1,1)leaving / losing attention (exits ~20-30% shorter)
--ease-in-outcubic-bezier(.4,0,.2,1)moving between on-screen positions
springcritically damped, retargetablegestures; 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 transform and opacity only. Under prefers-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:

  1. Does it meet the job story? Is the primary action the most prominent thing, and reachable everywhere?
  2. All states present (step 5)? Keyboard, screen-reader labels, contrast?
  3. Tokens only? Existing components reused?
  4. Copy follows step 6, including honesty labels?
  5. Every animation has a job, the right easing direction, an interruption path and a reduced-motion path?
  6. Does the signature pass the substitution test? Is there one peak, placed at an ending?
  7. 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

ReadWhen
references/motion-engineering.mdbuilding any GSAP/ScrollTrigger/Lenis, canvas, gesture or scroll-scene work
references/verification.mdbefore calling any visual or interactive work done
references/imagery.mdgenerating or preparing images, product cut-outs, art direction
references/animation.mdchoreography, the 7 motion principles, stagger maths, motion tokens
references/emotion.mddesign persona, onboarding, delight, trust and fear, outage copy
references/design-systems.mdtokens, component APIs, governance, versioning, docs
references/product-design.mdresearch, story-first, sketching, feedback, prototyping, testing
references/design-thinking.mdan ambiguous problem needing empathise/define/ideate/prototype/test
references/design-engineering.mdchoosing prototype fidelity, design↔code handshake
references/process-and-teams.mdcritique sessions, rationale and handoff templates, DesignOps

Related Skills