commit 87279e170cae8653a8e459b5c6742ccb9eaead8a Author: zlei9 Date: Sun Mar 29 10:21:57 2026 +0800 Initial commit with translated description diff --git a/README.md b/README.md new file mode 100644 index 0000000..3a142bd --- /dev/null +++ b/README.md @@ -0,0 +1,116 @@ +# Frontend Design Ultimate + +🎨 Create distinctive, production-grade static sites with React, Tailwind CSS, and shadcn/ui β€” no mockups needed. + +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) +[![ClawHub](https://img.shields.io/badge/ClawHub-frontend--design--ultimate-purple)](https://clawhub.ai/skills/frontend-design-ultimate) + +## What is this? + +An OpenClaw/Claude Code skill that generates bold, memorable web designs from plain text requirements. No Figma, no wireframes β€” just describe what you want. + +**Key Features:** +- 🚫 **Anti-AI-slop** β€” Explicit guidance to avoid generic designs (no Inter, no purple gradients, no centered layouts) +- πŸ“± **Mobile-first patterns** β€” Responsive CSS that actually works +- ⚑ **Two workflows** β€” Vite (pure static) or Next.js (Vercel deploy) +- 🧩 **shadcn/ui components** β€” 10 common components pre-installed, add more with CLI +- πŸ“¦ **Single-file bundling** β€” Bundle entire sites to one HTML file + +## Quick Start + +### Install the Skill + +```bash +# OpenClaw +openclaw skill install frontend-design-ultimate + +# Claude Code (copy to .claude/skills/) +git clone https://github.com/kesslerio/frontend-design-ultimate-clawhub-skill.git ~/.claude/skills/frontend-design-ultimate +``` + +### Use It + +Just describe what you want: + +``` +Build a SaaS landing page for an AI writing tool. Dark theme, +editorial typography, subtle grain texture. Pages: hero with +animated demo, features grid, pricing table, FAQ accordion, footer. +``` + +The skill will: +1. Commit to a bold aesthetic direction +2. Choose distinctive typography (no Inter!) +3. Build with React + Tailwind + shadcn/ui +4. Apply mobile-first responsive patterns +5. Output production-ready code + +## What Makes This Different? + +### vs. Generic AI Design +| Generic AI | This Skill | +|------------|------------| +| Inter font everywhere | Distinctive typography choices | +| Purple gradients | Context-appropriate palettes | +| Centered layouts | Intentional spatial composition | +| No animations | Orchestrated motion | +| Solid backgrounds | Atmospheric textures | + +### Based On +- **Anthropic's frontend-design** β€” Design philosophy, anti-AI-slop guidance +- **Anthropic's web-artifacts-builder** β€” React+Tailwind+shadcn scaffolding +- **Community frontend-design-v2** β€” Mobile-first responsive patterns + +## Workflows + +### Option A: Vite (Pure Static) +```bash +bash scripts/init-vite.sh my-site +cd my-site +npm run dev + +# Build +npm run build + +# Bundle to single HTML +bash scripts/bundle-artifact.sh +``` + +### Option B: Next.js (Vercel) +```bash +bash scripts/init-nextjs.sh my-site +cd my-site +npm run dev + +# Deploy +vercel +``` + +## Documentation + +- [SKILL.md](SKILL.md) β€” Main skill instructions +- [references/design-philosophy.md](references/design-philosophy.md) β€” Anti-AI-slop manifesto +- [references/mobile-patterns.md](references/mobile-patterns.md) β€” Responsive CSS patterns +- [references/shadcn-components.md](references/shadcn-components.md) β€” Component quick reference +- [templates/site-config.ts](templates/site-config.ts) β€” Editable content config example + +## Requirements + +- Node.js 18+ +- npm + +## License + +Apache 2.0 β€” See [LICENSE](LICENSE) + +## Credits + +Built on the shoulders of: +- [Anthropic's Claude Skills](https://github.com/anthropics/skills) +- [shadcn/ui](https://ui.shadcn.com) +- [Tailwind CSS](https://tailwindcss.com) +- [nhatmobile1's frontend-design-v2](https://github.com/nhatmobile1/claude-skills) + +--- + +Made with 🎨 by [Kessler.io](https://kessler.io) diff --git a/REVIEW.md b/REVIEW.md new file mode 100644 index 0000000..a837349 --- /dev/null +++ b/REVIEW.md @@ -0,0 +1,139 @@ +# Skill Review: frontend-design-ultimate + +Review Date: 2026-02-01 +Reviewer: Niemand Code (automated) + +## Source Skill Consistency Check + +### 1. Anthropic frontend-design βœ… + +| Source Requirement | Our Implementation | Status | +|-------------------|-------------------|--------| +| "BOLD aesthetic direction" | SKILL.md:47-70 "Design Thinking" section | βœ… Matches | +| Typography: avoid Inter, Roboto, Arial | SKILL.md:76 "BANNED" list, references/design-philosophy.md:30-47 | βœ… Matches | +| Color: dominant + sharp accents | SKILL.md:96-108 | βœ… Matches | +| Motion: orchestrated page load | SKILL.md:111-120, references/design-philosophy.md:142-170 | βœ… Matches | +| Spatial: asymmetry, overlap | SKILL.md:122-127 | βœ… Matches | +| Backgrounds: atmosphere, textures | SKILL.md:129-145 | βœ… Matches | +| Anti-AI-slop philosophy | Throughout + references/design-philosophy.md | βœ… Matches | + +**Consistency: 100%** + +### 2. Anthropic web-artifacts-builder βœ… + +| Source Requirement | Our Implementation | Status | +|-------------------|-------------------|--------| +| React 18 + TypeScript + Vite | scripts/init-vite.sh:15-17 | βœ… Matches | +| Tailwind CSS + shadcn/ui | scripts/init-vite.sh:22-50 | βœ… Matches | +| Path aliases (@/) | scripts/init-vite.sh:176-190 | βœ… Matches | +| 40+ shadcn components | scripts/init-vite.sh:23-47 (manual install) | ⚠️ Partial | +| Parcel bundling | scripts/bundle-artifact.sh | βœ… Matches | +| Single HTML output | scripts/bundle-artifact.sh:44 | βœ… Matches | + +**Note on shadcn**: Source uses `npx shadcn@latest add` for all components. Our init-vite.sh manually installs Radix deps but doesn't pre-add all shadcn components. Consider using `npx shadcn@latest add --all`. + +**Consistency: 90%** + +### 3. Community frontend-design-v2 βœ… + +| Source Requirement | Our Implementation | Status | +|-------------------|-------------------|--------| +| Hero gridβ†’flex mobile fix | references/mobile-patterns.md:10-55 | βœ… Matches | +| Accordion for large lists | references/mobile-patterns.md:59-105 | βœ… Matches | +| Form element consistency | references/mobile-patterns.md:238-280 | βœ… Matches | +| Breakpoint reference | references/mobile-patterns.md:375-390 | βœ… Matches | +| Pre-implementation checklist | SKILL.md:228-250 | βœ… Matches | +| Color contrast checklist | references/mobile-patterns.md:300-335 | βœ… Matches | + +**Consistency: 100%** + +--- + +## Code Quality Issues + +### scripts/init-vite.sh + +1. **Line 23-47**: Manual Radix UI installation is verbose. Could use: + ```bash + npx shadcn@latest init -y + npx shadcn@latest add --all -y + ``` + +2. **Missing error handling**: No check if npm commands fail. + +3. **Missing Node version check**: Should verify Node 18+. + +### scripts/init-nextjs.sh + +1. **Line 25**: Uses `-y` flag which may not be supported by all versions of shadcn CLI. + +2. **Hardcoded component list**: Only installs 10 components vs "40+" claimed. + +### scripts/bundle-artifact.sh + +1. **Good**: Has `set -e` for error handling. +2. **Good**: Checks for package.json and index.html. +3. **Minor**: Could add cleanup of node_modules/.parcel-cache on error. + +--- + +## Gaps & Improvements + +### Missing from Source Skills + +1. **Testing guidance**: web-artifacts-builder mentions Playwright/Puppeteer testing. We don't. + +2. **Motion library**: frontend-design mentions "Motion library for React". We don't specify framer-motion or alternatives. + +3. **Node version pinning**: web-artifacts-builder mentions "auto-detects and pins Vite version". Our scripts don't. + +### Recommended Additions + +1. Add `framer-motion` to dependencies for complex animations. + +2. Add `.nvmrc` or `engines` in package.json for Node 18+. + +3. Add example components (Hero, Features, Pricing) as templates. + +4. Consider adding a `--dark` flag to init scripts for dark-mode-first projects. + +--- + +## ClawHub Publishing Readiness + +| Requirement | Status | +|-------------|--------| +| SKILL.md present | βœ… | +| Valid frontmatter | βœ… | +| Description for discovery | βœ… Good keywords | +| LICENSE file | βœ… Apache 2.0 | +| README.md | βœ… | +| No hardcoded secrets | βœ… | +| Scripts executable | βœ… | + +**Ready for publishing: YES** + +--- + +## Summary + +| Category | Score | +|----------|-------| +| Source consistency | 97% | +| Code quality | 85% | +| Documentation | 95% | +| Publishing readiness | 100% | + +**Overall: Ready to publish with minor improvements recommended.** + +### Priority Fixes + +1. [ ] Fix init-vite.sh to use `npx shadcn@latest add --all` instead of manual Radix installs +2. [ ] Add framer-motion to dependencies +3. [ ] Add Node version check to scripts + +### Nice-to-Have + +1. [ ] Add example component templates +2. [ ] Add --dark flag for dark-mode-first +3. [ ] Add Playwright testing example diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..a8a7846 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,379 @@ +--- +name: frontend-design-ultimate +description: "使用React、Tailwind CSSε’Œshadcn/uiεˆ›ε»Ίη‹¬η‰Ήηš„η”ŸδΊ§ηΊ§ι™ζ€η«™η‚Ήγ€‚" +homepage: https://github.com/kesslerio/frontend-design-ultimate-clawhub-skill +metadata: + openclaw: + emoji: "🎨" + requires: + bins: ["node", "npm"] +--- + +# Frontend Design Ultimate + +Create distinctive, production-grade static sites from text requirements alone. No mockups, no Figma β€” just describe what you want and get bold, memorable designs. + +**Stack**: React 18 + TypeScript + Tailwind CSS + shadcn/ui + Framer Motion +**Output**: Vite (static HTML) or Next.js (Vercel-ready) + +## Quick Start + +``` +"Build a SaaS landing page for an AI writing tool. Dark theme, +editorial typography, subtle grain texture. Pages: hero with +animated demo, features grid, pricing table, FAQ accordion, footer." +``` + +--- + +## Design Thinking (Do This First) + +Before writing any code, commit to a **BOLD aesthetic direction**: + +### 1. Understand Context +- **Purpose**: What problem does this interface solve? Who uses it? +- **Audience**: Developer tools? Consumer app? Enterprise? Creative agency? +- **Constraints**: Performance requirements, accessibility needs, brand guidelines? + +### 2. Choose an Extreme Tone +Pick ONE and commit fully β€” timid designs fail: + +| Tone | Characteristics | +|------|-----------------| +| **Brutally Minimal** | Sparse, monochrome, massive typography, raw edges | +| **Maximalist Chaos** | Layered, dense, overlapping elements, controlled disorder | +| **Retro-Futuristic** | Neon accents, geometric shapes, CRT aesthetics | +| **Organic/Natural** | Soft curves, earth tones, hand-drawn elements | +| **Luxury/Refined** | Subtle animations, premium typography, restrained palette | +| **Editorial/Magazine** | Strong grid, dramatic headlines, whitespace as feature | +| **Brutalist/Raw** | Exposed structure, harsh contrasts, anti-design | +| **Art Deco/Geometric** | Gold accents, symmetry, ornate patterns | +| **Soft/Pastel** | Rounded corners, gentle gradients, friendly | +| **Industrial/Utilitarian** | Functional, monospace, data-dense | + +### 3. Define the Unforgettable Element +What's the ONE thing someone will remember? A hero animation? Typography treatment? Color combination? Unusual layout? + +--- + +## Aesthetics Guidelines + +### Typography β€” NEVER Generic + +**BANNED**: Inter, Roboto, Arial, system fonts, Open Sans + +**DO**: Distinctive, characterful choices that elevate the design. + +| Use Case | Approach | +|----------|----------| +| Display/Headlines | Bold personality β€” Clash, Cabinet Grotesk, Satoshi, Space Grotesk (sparingly), Playfair Display | +| Body Text | Refined readability β€” Instrument Sans, General Sans, Plus Jakarta Sans | +| Monospace/Code | DM Mono, JetBrains Mono, IBM Plex Mono | +| Pairing Strategy | Contrast weights (thin display + bold body), contrast styles (serif + geometric sans) | + +**Size Progression**: Use 3x+ jumps, not timid 1.5x increments. + +### Color & Theme + +**BANNED**: Purple gradients on white, evenly-distributed 5-color palettes + +**DO**: +- **Dominant + Sharp Accent**: 70-20-10 rule (primary-secondary-accent) +- **CSS Variables**: `--primary`, `--accent`, `--surface`, `--text` +- **Commit to dark OR light**: Don't hedge with gray middle-grounds +- **High contrast CTAs**: Buttons should pop dramatically + +```css +:root { + --bg-primary: #0a0a0a; + --bg-secondary: #141414; + --text-primary: #fafafa; + --text-secondary: #a1a1a1; + --accent: #ff6b35; + --accent-hover: #ff8555; +} +``` + +### Motion & Animation + +**Priority**: One orchestrated page load > scattered micro-interactions + +**High-Impact Moments**: +- Staggered hero reveals (`animation-delay`) +- Scroll-triggered section entrances +- Hover states that surprise (scale, color shift, shadow depth) +- Smooth page transitions + +**Implementation**: +- CSS-only for simple animations +- Framer Motion for React (pre-installed via init scripts) +- Keep durations 200-400ms (snappy, not sluggish) + +### Spatial Composition + +**BANNED**: Centered, symmetrical, predictable layouts + +**DO**: +- Asymmetry with purpose +- Overlapping elements +- Diagonal flow / grid-breaking +- Generous negative space OR controlled density (pick one) +- Off-grid hero sections + +### Backgrounds & Atmosphere + +**BANNED**: Solid white/gray backgrounds + +**DO**: +- Gradient meshes (subtle, not garish) +- Noise/grain textures (SVG filter or CSS) +- Geometric patterns (dots, lines, shapes) +- Layered transparencies +- Dramatic shadows for depth +- Blur effects for glassmorphism + +```css +/* Subtle grain overlay */ +.grain::before { + content: ''; + position: fixed; + inset: 0; + background: url("data:image/svg+xml,...") repeat; + opacity: 0.03; + pointer-events: none; +} +``` + +--- + +## Mobile-First Patterns + +See **[references/mobile-patterns.md](references/mobile-patterns.md)** for detailed CSS. + +### Critical Rules + +| Pattern | Desktop | Mobile Fix | +|---------|---------|------------| +| Hero with hidden visual | 2-column grid | Switch to `display: flex` (not grid) | +| Large selection lists | Horizontal scroll | Accordion with category headers | +| Multi-column forms | Side-by-side | Stack vertically | +| Status/alert cards | Inline | `align-items: center` + `text-align: center` | +| Feature grids | 3-4 columns | Single column | + +### Breakpoints + +```css +/* Tablet - stack sidebars */ +@media (max-width: 1200px) { } + +/* Mobile - full single column */ +@media (max-width: 768px) { } + +/* Small mobile - compact spacing */ +@media (max-width: 480px) { } +``` + +### Font Scaling + +```css +@media (max-width: 768px) { + .hero-title { font-size: 32px; } /* from ~48px */ + .section-title { font-size: 24px; } /* from ~32px */ + .section-subtitle { font-size: 14px; } /* from ~16px */ +} +``` + +--- + +## Build Workflow + +### Option A: Vite (Pure Static) + +```bash +# 1. Initialize +bash scripts/init-vite.sh my-site +cd my-site + +# 2. Develop +npm run dev + +# 3. Build static files +npm run build +# Output: dist/ + +# 4. Bundle to single HTML (optional) +bash scripts/bundle-artifact.sh +# Output: bundle.html +``` + +### Option B: Next.js (Vercel Deploy) + +```bash +# 1. Initialize +bash scripts/init-nextjs.sh my-site +cd my-site + +# 2. Develop +npm run dev + +# 3. Deploy to Vercel +vercel +``` + +--- + +## Project Structure + +### Vite Static +``` +my-site/ +β”œβ”€β”€ src/ +β”‚ β”œβ”€β”€ components/ # React components +β”‚ β”œβ”€β”€ lib/ # Utilities, cn() +β”‚ β”œβ”€β”€ styles/ # Global CSS +β”‚ β”œβ”€β”€ config/ +β”‚ β”‚ └── site.ts # Editable content config +β”‚ β”œβ”€β”€ App.tsx +β”‚ └── main.tsx +β”œβ”€β”€ index.html +β”œβ”€β”€ tailwind.config.ts +└── package.json +``` + +### Next.js +``` +my-site/ +β”œβ”€β”€ app/ +β”‚ β”œβ”€β”€ layout.tsx +β”‚ β”œβ”€β”€ page.tsx +β”‚ └── privacy/page.tsx +β”œβ”€β”€ components/ +β”œβ”€β”€ lib/ +β”œβ”€β”€ config/ +β”‚ └── site.ts +└── tailwind.config.ts +``` + +--- + +## Site Config Pattern + +Keep all editable content in one file: + +```typescript +// config/site.ts +export const siteConfig = { + name: "Acme AI", + tagline: "Write better, faster", + description: "AI-powered writing assistant", + + hero: { + badge: "Now in beta", + title: "Your words,\nsupercharged", + subtitle: "Write 10x faster with AI that understands your style", + cta: { text: "Get Started", href: "/signup" }, + secondaryCta: { text: "Watch Demo", href: "#demo" }, + }, + + features: [ + { icon: "Zap", title: "Lightning Fast", description: "..." }, + // ... + ], + + pricing: [ + { name: "Free", price: 0, features: [...] }, + { name: "Pro", price: 19, features: [...], popular: true }, + ], + + faq: [ + { q: "How does it work?", a: "..." }, + ], + + footer: { + links: [...], + social: [...], + } +} +``` + +--- + +## Pre-Implementation Checklist + +Run this before finalizing any design: + +### Design Quality +- [ ] Typography is distinctive (no Inter/Roboto/Arial) +- [ ] Color palette has clear dominant + accent (not evenly distributed) +- [ ] Background has atmosphere (not solid white/gray) +- [ ] At least one memorable/unforgettable element +- [ ] Animations are orchestrated (not scattered) + +### Mobile Responsiveness +- [ ] Hero centers on mobile (no empty grid space) +- [ ] All grids collapse to single column +- [ ] Forms stack vertically +- [ ] Large lists use accordion (not horizontal scroll) +- [ ] Font sizes scale down appropriately + +### Form Consistency +- [ ] Input, select, textarea all styled consistently +- [ ] Radio/checkbox visible (check transparent-border styles) +- [ ] Dropdown options have readable backgrounds +- [ ] Labels use CSS variables (not hardcoded colors) + +### Accessibility +- [ ] Color contrast meets WCAG AA (4.5:1 text, 3:1 UI) +- [ ] Focus states visible +- [ ] Semantic HTML (nav, main, section, article) +- [ ] Alt text for images +- [ ] Keyboard navigation works + +--- + +## shadcn/ui Components + +10 common components pre-installed (button, badge, card, accordion, dialog, navigation-menu, tabs, sheet, separator, avatar, alert). Add more with `npx shadcn@latest add [name]` or install all with `npx shadcn@latest add --all`. + +See **[references/shadcn-components.md](references/shadcn-components.md)** for full component reference. + +Most used for landing pages: +- `Button`, `Badge` β€” CTAs and labels +- `Card` β€” Feature cards, pricing tiers +- `Accordion` β€” FAQ sections +- `Dialog` β€” Modals, video players +- `NavigationMenu` β€” Header nav +- `Tabs` β€” Feature showcases +- `Carousel` β€” Testimonials + +--- + +## References + +- **[references/design-philosophy.md](references/design-philosophy.md)** β€” Extended anti-AI-slop guidance +- **[references/mobile-patterns.md](references/mobile-patterns.md)** β€” Detailed responsive CSS +- **[references/shadcn-components.md](references/shadcn-components.md)** β€” Component quick reference +- **[templates/site-config.ts](templates/site-config.ts)** β€” Full siteConfig example + +--- + +## Examples + +### Prompt β†’ Output + +**Input**: +> "Portfolio site for a photographer. Minimal, editorial feel. +> Grid gallery with lightbox, about section, contact form." + +**Design Decisions**: +- Tone: Editorial/Magazine +- Typography: Cormorant Garamond (display) + Inter... wait, banned. Plus Jakarta Sans (body) +- Color: Near-black bg (#0c0c0c), warm white text (#f5f5f0), copper accent (#b87333) +- Unforgettable: Full-bleed hero image with text overlay that reveals on scroll +- Motion: Gallery images fade in staggered on scroll + +**Output**: Complete Next.js project with responsive gallery, lightbox component, and contact form with validation. + +--- + +*Based on Anthropic's frontend-design, web-artifacts-builder, and community frontend-design-v2 skills.* diff --git a/_meta.json b/_meta.json new file mode 100644 index 0000000..8eb47be --- /dev/null +++ b/_meta.json @@ -0,0 +1,6 @@ +{ + "ownerId": "kn7fmw4ybcy50qzp1d2dvb1h517znaes", + "slug": "frontend-design-ultimate", + "version": "1.0.0", + "publishedAt": 1770018489918 +} \ No newline at end of file diff --git a/references/design-philosophy.md b/references/design-philosophy.md new file mode 100644 index 0000000..48c8da6 --- /dev/null +++ b/references/design-philosophy.md @@ -0,0 +1,301 @@ +# Design Philosophy β€” Anti-AI-Slop Manifesto + +This reference extends the core SKILL.md with deeper guidance on creating distinctive designs. + +## The Problem: AI Slop + +Generic AI-generated designs share these telltale signs: + +### Typography Sins +- Inter, Roboto, Arial everywhere +- Timid weight ranges (400-600 only) +- Minimal size progression (1.25x-1.5x) +- No distinctive pairing strategy + +### Color Crimes +- Purple/blue gradient on white (the cardinal sin) +- 5+ evenly-distributed colors with no hierarchy +- Muted, "safe" palettes that offend no one and delight no one +- Gray backgrounds that signal "I gave up" + +### Layout Laziness +- Everything centered +- Perfectly symmetrical +- Predictable card grids +- No visual tension or interest + +### Motion Mediocrity +- No animations at all, OR +- Generic fade-in on every element +- No orchestration or timing consideration + +### Background Boredom +- Solid white +- Solid light gray +- Maybe a subtle gradient if feeling "bold" + +--- + +## The Solution: Intentional Design + +### Commit to an Extreme + +The middle ground is where designs go to die. Pick a direction and push it: + +**Maximalism Done Right**: +- Dense, layered compositions +- Overlapping elements with clear hierarchy +- Rich textures and patterns +- Multiple animations coordinated +- Every pixel working + +**Minimalism Done Right**: +- Extreme restraint (3 colors max) +- Typography as the star +- Negative space as intentional element +- Single, perfect animation +- Nothing extraneous + +Both require courage. Both create memorable designs. + +### Typography as Identity + +Typography isn't decoration β€” it's the voice of the design. + +**Building a Type Hierarchy**: +```css +/* Display: Make a statement */ +.display { + font-family: 'Clash Display', sans-serif; + font-size: clamp(3rem, 8vw, 6rem); + font-weight: 600; + letter-spacing: -0.02em; + line-height: 1; +} + +/* Heading: Support the display */ +.heading { + font-family: 'Satoshi', sans-serif; + font-size: clamp(1.5rem, 3vw, 2.5rem); + font-weight: 500; + letter-spacing: -0.01em; + line-height: 1.2; +} + +/* Body: Effortless reading */ +.body { + font-family: 'Plus Jakarta Sans', sans-serif; + font-size: 1rem; + font-weight: 400; + line-height: 1.6; +} + +/* Mono: Technical credibility */ +.mono { + font-family: 'JetBrains Mono', monospace; + font-size: 0.875rem; + letter-spacing: 0; +} +``` + +**Font Pairing Strategies**: + +| Strategy | Display | Body | Effect | +|----------|---------|------|--------| +| Contrast | Serif (Playfair) | Sans (Inter... no, Plus Jakarta) | Editorial elegance | +| Harmony | Geometric (Satoshi) | Geometric (General Sans) | Modern consistency | +| Tension | Brutalist (Clash) | Humanist (Source Sans) | Edgy but readable | +| Technical | Mono (JetBrains) | Sans (IBM Plex Sans) | Developer-focused | + +### Color as Emotion + +Color isn't about "what looks nice" β€” it's about what the design FEELS. + +**Building a Palette**: + +```css +/* Dark, Confident, Premium */ +:root { + --bg-primary: #0a0a0a; + --bg-secondary: #171717; + --bg-tertiary: #262626; + --text-primary: #fafafa; + --text-secondary: #a3a3a3; + --accent: #22c55e; /* Confident green */ + --accent-subtle: rgba(34, 197, 94, 0.1); +} + +/* Light, Warm, Approachable */ +:root { + --bg-primary: #fffbf5; + --bg-secondary: #fff7ed; + --bg-tertiary: #ffedd5; + --text-primary: #1c1917; + --text-secondary: #78716c; + --accent: #ea580c; /* Warm orange */ + --accent-subtle: rgba(234, 88, 12, 0.1); +} + +/* High Contrast, Editorial */ +:root { + --bg-primary: #ffffff; + --bg-secondary: #f5f5f5; + --text-primary: #000000; + --text-secondary: #525252; + --accent: #dc2626; /* Bold red */ + --accent-subtle: rgba(220, 38, 38, 0.05); +} +``` + +**The 60-30-10 Rule**: +- 60% dominant (background) +- 30% secondary (cards, sections) +- 10% accent (CTAs, highlights) + +### Motion as Narrative + +Animation tells a story. What's your story? + +**Page Load Orchestration**: +```css +/* Hero elements enter in sequence */ +.hero-badge { + animation: fadeSlideUp 0.6s ease-out 0.1s both; +} +.hero-title { + animation: fadeSlideUp 0.6s ease-out 0.2s both; +} +.hero-subtitle { + animation: fadeSlideUp 0.6s ease-out 0.3s both; +} +.hero-cta { + animation: fadeSlideUp 0.6s ease-out 0.4s both; +} + +@keyframes fadeSlideUp { + from { + opacity: 0; + transform: translateY(20px); + } + to { + opacity: 1; + transform: translateY(0); + } +} +``` + +**Scroll-Triggered Reveals**: +```javascript +// Intersection Observer for scroll animations +const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + entry.target.classList.add('animate-in'); + } + }); +}, { threshold: 0.1 }); + +document.querySelectorAll('.reveal').forEach(el => observer.observe(el)); +``` + +**Hover States That Surprise**: +```css +.card { + transition: transform 0.2s ease, box-shadow 0.2s ease; +} + +.card:hover { + transform: translateY(-4px); + box-shadow: + 0 20px 40px rgba(0, 0, 0, 0.1), + 0 0 0 1px rgba(255, 255, 255, 0.05); +} + +/* Or more dramatic */ +.card:hover { + transform: scale(1.02) rotate(-0.5deg); +} +``` + +### Backgrounds as Atmosphere + +The background sets the mood before any content is read. + +**Gradient Mesh**: +```css +.gradient-mesh { + background: + radial-gradient(at 40% 20%, hsla(28, 100%, 74%, 0.3) 0px, transparent 50%), + radial-gradient(at 80% 0%, hsla(189, 100%, 56%, 0.2) 0px, transparent 50%), + radial-gradient(at 0% 50%, hsla(355, 100%, 93%, 0.3) 0px, transparent 50%), + radial-gradient(at 80% 50%, hsla(340, 100%, 76%, 0.2) 0px, transparent 50%), + radial-gradient(at 0% 100%, hsla(269, 100%, 77%, 0.3) 0px, transparent 50%); +} +``` + +**Noise Texture**: +```css +.noise::before { + content: ''; + position: fixed; + top: 0; + left: 0; + width: 100%; + height: 100%; + background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 400 400' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noiseFilter'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noiseFilter)'/%3E%3C/svg%3E"); + opacity: 0.03; + pointer-events: none; + z-index: 1000; +} +``` + +**Dot Pattern**: +```css +.dots { + background-image: radial-gradient(circle, #333 1px, transparent 1px); + background-size: 20px 20px; +} +``` + +**Glassmorphism**: +```css +.glass { + background: rgba(255, 255, 255, 0.1); + backdrop-filter: blur(10px); + border: 1px solid rgba(255, 255, 255, 0.1); + box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1); +} +``` + +--- + +## Design Decision Framework + +When stuck, ask these questions: + +1. **What's the ONE thing?** β€” If users remember one element, what is it? +2. **Would I screenshot this?** β€” Is there a moment worth sharing? +3. **Does it feel designed?** β€” Or does it feel generated? +4. **What's the emotion?** β€” Confident? Playful? Serious? Luxurious? +5. **Is it brave?** β€” Did I play it safe or commit to a direction? + +--- + +## Anti-Pattern Detection + +Before shipping, scan for these: + +| Anti-Pattern | Fix | +|--------------|-----| +| Inter font | Replace with distinctive alternative | +| Purple gradient | Choose contextual palette | +| All centered | Add asymmetry or left-align | +| No animations | Add orchestrated page load | +| Solid background | Add texture, gradient, or pattern | +| Evenly spaced colors | Apply 60-30-10 rule | +| Generic cards | Add unique styling treatment | +| Default shadows | Use layered, atmospheric shadows | + +--- + +*Remember: Claude is capable of extraordinary creative work. Don't hold back.* diff --git a/references/mobile-patterns.md b/references/mobile-patterns.md new file mode 100644 index 0000000..17c27d1 --- /dev/null +++ b/references/mobile-patterns.md @@ -0,0 +1,519 @@ +# Mobile-First Patterns + +Comprehensive responsive CSS patterns learned from real-world implementation failures. + +## Hero Sections + +### Problem +2-column grid layouts leave empty space when one column is hidden on mobile. + +### Solution +Switch from `display: grid` to `display: flex` on mobile. + +```css +/* Desktop: 2-column grid */ +.hero { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 64px; + align-items: center; + padding: 80px 0; +} + +/* Mobile: Centered flex */ +@media (max-width: 768px) { + .hero { + display: flex; + flex-direction: column; + align-items: center; + text-align: center; + padding: 40px 20px; + gap: 24px; + } + + .hero-content { + align-items: center; + } + + .hero-badge { + align-self: center; + } + + .hero-title { + font-size: 32px; + text-align: center; + } + + .hero-subtitle { + font-size: 14px; + text-align: center; + } + + .hero-cta { + flex-direction: column; + align-items: center; + width: 100%; + } + + .hero-cta .btn { + width: 100%; + max-width: 280px; + } + + .hero-visual { + display: none; + } +} +``` + +**Key Rule**: Grid reserves space for hidden columns. Flex doesn't. + +--- + +## Large Selection Lists + +### Problem +Horizontal scroll for 20+ items is unusable on mobile β€” text gets cut off. + +### Solution +Collapsible accordion with category headers. + +```tsx +function MobileSelector({ categories }) { + const [expanded, setExpanded] = useState(null); + + return ( +
+ {categories.map(cat => ( +
+ + +
+ {cat.items.map(item => ( + + ))} +
+
+ ))} +
+ ); +} +``` + +```css +.category-items { + display: flex; + flex-wrap: wrap; + gap: 8px; +} + +@media (max-width: 768px) { + .category-items { + display: none; + } + + .category.expanded .category-items { + display: flex; + flex-direction: column; + padding: 12px; + background: var(--bg-secondary); + border-radius: 8px; + } +} +``` + +--- + +## Form Layouts + +### Problem +Multi-column form layouts get cut off on mobile. + +### Solution +Stack vertically with full width. + +```css +.form-row { + display: flex; + gap: 16px; +} + +.form-group { + flex: 1; +} + +@media (max-width: 768px) { + .form-row { + flex-direction: column; + } + + .form-group { + width: 100%; + } + + .form-row.half-width { + /* Even "half width" fields go full on mobile */ + flex-direction: column; + } +} +``` + +--- + +## Status/Alert Cards + +### Problem +Inconsistent text alignment when stacking horizontal elements vertically. + +### Solution +Both `align-items: center` AND `text-align: center`. + +```css +.alert { + display: flex; + align-items: flex-start; + gap: 12px; + padding: 16px; + border-radius: 8px; +} + +.alert-icon { + flex-shrink: 0; +} + +.alert-content { + flex: 1; +} + +@media (max-width: 768px) { + .alert { + flex-direction: column; + align-items: center; /* Center flex items */ + text-align: center; /* Center text within items */ + gap: 8px; + } + + .alert-content { + text-align: center; /* Explicit for nested elements */ + } + + .alert strong { + text-align: center; /* Block elements need explicit */ + } +} +``` + +**Key Rule**: Stacked flex items need BOTH `align-items: center` AND `text-align: center`. + +--- + +## Grid Layouts + +### Universal Mobile Collapse + +```css +.pricing-grid, +.feature-grid, +.team-grid, +.stats-grid, +.testimonial-grid { + display: grid; + gap: 24px; +} + +/* Desktop configurations */ +.pricing-grid { grid-template-columns: repeat(3, 1fr); } +.feature-grid { grid-template-columns: repeat(3, 1fr); } +.team-grid { grid-template-columns: repeat(4, 1fr); } +.stats-grid { grid-template-columns: repeat(4, 1fr); } +.testimonial-grid { grid-template-columns: repeat(2, 1fr); } + +/* Tablet */ +@media (max-width: 1024px) { + .team-grid { grid-template-columns: repeat(2, 1fr); } + .stats-grid { grid-template-columns: repeat(2, 1fr); } +} + +/* Mobile: Everything single column */ +@media (max-width: 768px) { + .pricing-grid, + .feature-grid, + .team-grid, + .stats-grid, + .testimonial-grid { + grid-template-columns: 1fr; + } +} +``` + +--- + +## Navigation + +### Mobile Menu Pattern + +```tsx +function MobileNav() { + const [open, setOpen] = useState(false); + + return ( + <> + {/* Mobile menu button */} + + + {/* Mobile menu overlay */} +
setOpen(false)} /> + + {/* Mobile menu panel */} + + + ); +} +``` + +--- + +## Form Element Consistency + +### Always Style as a Group + +```css +/* WRONG - Only targets input */ +.input { + border: 2px solid var(--border); + border-radius: 8px; +} + +/* CORRECT - All form fields */ +.input, +.select, +.textarea { + border: 2px solid var(--border); + border-radius: 8px; + padding: 12px 16px; + font-size: 16px; /* Prevents iOS zoom */ + background: var(--bg-secondary); + color: var(--text-primary); +} +``` + +### Textarea Border Radius Exception + +Pill-shaped inputs look wrong on textareas: + +```css +.input, +.select { + border-radius: 100px; /* Pill shape */ +} + +.textarea { + border-radius: 16px; /* Softer, but not pill */ +} +``` + +### Dropdown Option Styling + +`