prajwalacharyaa/mochi-redesign

/mochi-redesign

A guided redesign workflow. It does not apply a fixed look. It applies a fixed process: understand the person, find a concept, build a small design system, put everything important on the first screen as cards, move detail into rich popups and dedicated pages, write honest copy, and verify every change at real screen sizes before showing it.

It was distilled from a real portfolio that went from a plain one-column template to a bento-style site over many rounds of owner feedback. The lessons from those rounds (what worked, what got rejected, what broke) are encoded below and in references/.

The output must never look like the site this skill came from. Same discipline, different identity: new concept, new fonts, new colours, new signature detail. If you catch yourself reaching for a marigold brush stroke, a mascot or a bento grid because "that's what the skill does", stop and go back to Phase 1.

How to run it

Arguments are optional free text, e.g. /mochi-redesign client/ or /mochi-redesign the home page only, keep the blog as is.

Work through the phases in order. Each phase ends at a gate: show the owner the result (screenshots, not descriptions) and wait for their reaction before moving on. Redesigns fail when several unreviewed decisions stack up.

Phase	Read first	Gate
0. Intake and audit	references/01-intake-audit.md	Owner confirms goals, audience, scope, what must not change
1. Concept and system	references/02-concept-system.md	Owner picks one direction; tokens written down
2. Content truth	references/03-content.md	Owner approves claims (no overclaiming)
3. First screen	references/04-layout.md	Fits one laptop screen at every target size
4. Detail layer	references/05-interaction.md	Popups scroll inside, lock the page, no layout shift
5. Secondary pages	references/06-content-pages.md	Lists and reader pages match the system
6. Media (optional)	references/07-media.md	Real walkthroughs, compressed, play only in view
7. Polish and QA	references/08-qa.md	Clip check passes, both themes, mobile, lint, build
8. Hand-off	references/09-feedback-and-handoff.md	Clean diff, design doc updated, owner decides on commit

references/10-anti-patterns.md is the list of mistakes made the first time. Read it once before Phase 1 and again before Phase 7.

Non-negotiables

1. Look before you change. Read the existing code, run the site, take screenshots at the target sizes. Never redesign from the code alone.
2. One identity per site. Concept comes from the subject (what the person or product actually is), not from a trend or from this skill's origin.
3. Everything important on the first screen. Visitors should see who, what, and proof (best work) without scrolling. Detail lives one click away, not five screens down.
4. Honest copy. No claim the owner can't stand behind in an interview. Prefer "practised", "have done", "where it fits" over "every", "always", "all". Show proof (numbers, shipped things) instead of adjectives.
5. Verify at sizes, not in your head. Every visual change is followed by the clip check (scripts/clip-check.mjs) and at least one screenshot. Never report "done" from a change you haven't looked at.
6. Small, reversible steps. Change one thing, show it, listen. If the owner rejects something twice, stop guessing: offer 2–3 concrete options with previews and let them choose. If they ask to revert, restore the previous version exactly, not a "close enough" rebuild.
7. Don't break what's live. Keep old routes working, don't touch unrelated pages, don't reformat files you didn't need to change (formatter churn hides the real diff), don't commit or push without being asked.
8. Accessibility floor. Keyboard reachable, visible focus, real buttons and links, prefers-reduced-motion respected, contrast checked in both themes, nothing important conveyed by hover alone.

What "done" looks like

• A first screen that fits a laptop (1280×720 up to 1920×1080) with no cropped content, no horizontal scroll, and a clear focal point.
• A small, written design system (tokens, type, radius, motion rules) that every new component uses.
• Cards that open rich detail (dialogs or pages) instead of long scroll.
• Copy the owner signed off line by line.
• Secondary pages (lists, readers, case studies) that feel like the same site.
• A design doc in the repo (DESIGN.md or similar) describing the system and the decisions, so the next person (or agent) keeps it consistent.

Files in this skill

SKILL.md                         this file: workflow, gates, rules
references/01-intake-audit.md    questions to ask, how to audit the current site
references/02-concept-system.md  finding a concept; tokens, type, signature detail
references/03-content.md         writing truthful, scannable, highlighted copy
references/04-layout.md          first-screen bento layout and card recipes
references/05-interaction.md     dialogs, hover, motion, small delights
references/06-content-pages.md   blog/list/reader pages that keep people reading
references/07-media.md           recording walkthroughs and trailers of real work
references/08-qa.md              viewport matrix, clip check, themes, a11y
references/09-feedback-and-handoff.md  iterating with the owner; finishing cleanly
references/10-anti-patterns.md   what went wrong the first time, and the fix
scripts/clip-check.mjs           CDP script: cropped cards, overflow, fold fit
scripts/shots.mjs                CDP script: screenshots per viewport and theme
templates/                       framework-agnostic snippets (React + Tailwind)