Web Design Playbook
A design implementation workflow that reproduces quality through patterns. The core is the back-and-forth with the "accumulation file" described below: absorbing good designs and writing back the learnings from what you create. The more you use it, the more it grows into a pattern unique to that user.
Accumulation File (the heart of this skill)
The authoritative source for storing each user's design preferences and reference sites. Location: ~/.claude/design-taste.md. If it doesn't exist, create it on first use with this template:
# Design Taste — My Design Accumulation
## Proven Principles
<!-- Add one line per "what stuck / what didn't stick" based on reactions to your designs -->
## Reference Sites Collection
<!-- When you see a site you like, add it here with a note on what's good about it -->
| Site | URL | What's Good |
|---|---|---|
When to Append (Absorption)
- When the user shares a URL saying "I like this site", "use this as reference", or "something like this", immediately check the site, articulate in one line what is good about it (layout/color scheme/typography/motion/information design), and add it to the reference sites collection.
- When a user's reaction to a design reveals "what stuck / what didn't stick", add one line to the proven principles.
When to Read (Usage)
- Always read before implementing a design (step 1 of the workflow). Use it as a reference for design direction, color palette, and motion decisions.
Workflow
1. Load the Reference Layer (mandatory before implementation)
Read in priority order:
- The project root's
DESIGN.md— the authoritative source for the project. Highest priority. - The accumulation file
~/.claude/design-taste.md— the user's personal, proven preferences. - The "Design Principles (Default)" below — fallback values when the above two don't apply.
2. Set the Direction
- If the tone is not yet determined, first present a rough mockup of one screen (hero + representative section) to get agreement on direction. Changing direction after building all pages is the most costly mistake.
- Once the direction is fixed, document it in DESIGN.md format (YAML tokens + prose intent) and commit it to the project. From then on, any implementer — human or AI — can read this to maintain consistent tone.
3. Implementation
- Before creating decorative parts (buttons, headings, cards, loaders, background patterns, etc.) from scratch, check Web BENTO for existing parts.
- Individual page:
https://amix-design.com/tl/web-bento/parts/<slug>.html— slug = gradient / heading / button / card / text-effect / divider / hover / glass-shadow / badge / loading / form / background-pattern / speech-bubble / list / alert / table - When reusing, adapt to the project's colors, border radius, and fonts (commercial use OK, no credit required. Redistribution as a part collection is prohibited, so do not bundle them).
- Individual page:
- Consider motion implementations from lightweight options first: CSS / Framer Motion → Rive / Lottie → Three.js. Always respect
prefers-reduced-motion.
4. Real-Device Testing (mandatory before deployment)
- Take screenshots of at least three widths (390 / 880 / 1280px) in a browser and visually inspect (using Chrome DevTools MCP, etc.). A successful build and a visually sound result are two different things.
- Japanese text checks: line break issues in headings (orphans of particles at line start, mid-word breaks), content clipping, information that is only readable on hover.
- Handling Japanese line breaks: split into nowrap block lines by semantic grouping; use
word-break: auto-phrase; wrap prohibition characters in nowrap<span>tags.
5. Feedback Learnings
- When user reactions reveal "what stuck / what didn't stick", immediately add a line to the "Proven Principles" section in the accumulation file.
- Repeating this process will gradually replace generic guidelines with "this user's proven preferences." That is the true value of this playbook.
Design Principles (Default)
Default values until the accumulation file has enough evidence. These are only defaults — feel free to change them if they don't fit:
- White base + one accent color + giant typography + concrete theme motifs. Multi-color or dark×gold "luxury" directions tend to feel like clichéd AI templates.
- Playful interactivity + event-like motion, but never sacrifice information readability.
- Evoke emotion through the theme's metaphor (example: a soccer tournament site → newspaper front page; a film screening event → school festival). Avoid falling back on the generic gradient + glass card combination.
Customization Guide (adapt this to your own needs)
| Component | How to Customize |
|---|---|
| Design Principles (Default) | Once you have your own evidence, the accumulation file becomes the authority. Delete this section or rewrite it to match your own patterns. |
| Accumulation File Location | For team sharing, place it in the repository (e.g., design/taste.md) and update the path in this document. |
| Testing Widths (390/880/1280px) | Adjust to your project's actual breakpoints. |
| Japanese Text Check | For multilingual sites, replace with typography checks (hyphenation, etc.) for the relevant language. |
| Sources of Inspiration | If you follow a particular designer or school of thought, add their references to Step 1. |
Prohibited Items
- Do not use AI image generation to create fictional IP, characters, or products (this causes the most trouble in contexts involving real IP). Decoration is limited to abstract geometry, typography, brand colors, official assets, and photography.
- Do not bundle redistributable material collections or third-party content into the repository (reference them via links instead).
Recommended Companion Skills (Optional)
- Taste Skill — Quality guard against slop:
npx skills add Leonxlnx/taste-skill -g -s design-taste-frontend(+high-end-visual-design/redesign-existing-projects) - DESIGN.md validation:
npx @google/design.md lint