Imported from Ibranuraliev/pink-beauty (skills/web-design/SKILL.md). Install upstream with npx skills add Ibranuraliev/pink-beauty --skill web-design. Copyright stays with the author.

Web Design Architecture Skill

This skill guides Claude through creating a complete design specification for a web project — from design tokens to component inventory to Figma handoff structure. The output is a design document that a developer and designer can use as the single source of truth for building the UI.

Purpose

Good websites are built on a design system, not a collection of one-off decisions. This skill ensures that before a single line of code is written, every visual decision is made deliberately: what colors mean, how type scales, which components repeat, how layouts adapt across breakpoints. A well-specified design system makes development 3× faster and keeps the product visually consistent forever.

Workflow

Step 1 — Read Context

Before starting, always read:

• The project PRD (if it exists) — extract positioning, target audience, brand personality
• Any research documents — extract visual trends and competitor insights
• Any existing brand assets the user mentions

Extract these from the PRD:

• Brand segment (luxury / mid-premium / mass)
• Brand personality adjectives
• Existing color hints or preferences
• Typography preferences
• Competitor references

Step 2 — Design System Architecture

Build the design spec in this order. Each section feeds the next.

2.1 Design Tokens — the foundation

Design tokens are the atomic decisions everything else inherits from. Define them first.

Color tokens:

--color-primary:       [main brand color]
--color-primary-dark:  [hover/active state]
--color-primary-light: [tints, backgrounds]
--color-accent:        [secondary brand color]
--color-neutral-900:   [main text]
--color-neutral-700:   [secondary text]
--color-neutral-400:   [placeholder/disabled]
--color-neutral-100:   [subtle backgrounds]
--color-neutral-50:    [page background]
--color-white:         #FFFFFF
--color-error:         [form errors, alerts]
--color-success:       [confirmations]

Why this matters: All components reference tokens, not raw hex values. When the brand color changes, you update one token and everything updates. No hunting through 200 CSS files.

Spacing scale (8pt grid — use multiples of 8):

--space-1:  4px
--space-2:  8px
--space-3:  12px
--space-4:  16px
--space-6:  24px
--space-8:  32px
--space-12: 48px
--space-16: 64px
--space-24: 96px
--space-32: 128px

Why 8pt grid: Most screens divide evenly by 8. Designs built on 8pt feel harmonious and are easier for developers to implement consistently.

Border radius tokens:

--radius-sm:   4px   (inputs, small chips)
--radius-md:   8px   (cards, buttons)
--radius-lg:   16px  (modals, panels)
--radius-xl:   24px  (featured cards)
--radius-full: 9999px (pills, avatars)

Shadow tokens:

--shadow-sm:  0 1px 3px rgba(0,0,0,0.08)
--shadow-md:  0 4px 12px rgba(0,0,0,0.10)
--shadow-lg:  0 8px 32px rgba(0,0,0,0.12)
--shadow-xl:  0 16px 48px rgba(0,0,0,0.14)

Transition tokens:

--transition-fast:   150ms ease
--transition-base:   250ms ease
--transition-slow:   400ms ease-in-out
--transition-spring: 300ms cubic-bezier(0.34, 1.56, 0.64, 1)

2.2 Typography System

Font selection criteria:

• Heading font: Sets the personality. Serif = elegant/traditional. Sans-serif bold = modern/confident. Script = personal/warm.
• Body font: Must be readable at 16px on mobile. Inter, Nunito, Source Sans are reliable.
• Accent font: Optional. Used sparingly for decorative labels, quotes. Never for navigation or body text.

Type scale (Major Third — ratio 1.250):

--text-xs:   12px / line-height 1.4  (labels, captions)
--text-sm:   14px / line-height 1.5  (secondary text, meta)
--text-base: 16px / line-height 1.6  (body — MINIMUM for readability)
--text-lg:   18px / line-height 1.6  (lead paragraphs)
--text-xl:   20px / line-height 1.5  (card titles)
--text-2xl:  24px / line-height 1.4  (section headers)
--text-3xl:  30px / line-height 1.3  (page titles)
--text-4xl:  36px / line-height 1.2  (hero subheading)
--text-5xl:  48px / line-height 1.1  (hero heading desktop)
--text-6xl:  60px / line-height 1.0  (display / oversized)

Mobile type scale: Reduce text-5xl → text-3xl and text-4xl → text-2xl on screens < 768px. Never let headings overflow the viewport width.

Font weight semantic roles:

400 — body, descriptions
500 — labels, navigation
600 — subheadings, emphasis
700 — CTAs, headings
800/900 — display headings (use sparingly)

2.3 Layout & Grid System

Breakpoints:

--bp-sm:  480px   (large phones)
--bp-md:  768px   (tablets, landscape phone)
--bp-lg:  1024px  (small laptops)
--bp-xl:  1280px  (desktop)
--bp-2xl: 1536px  (wide screens)

Mobile-first principle: Write base styles for mobile, then use @media (min-width: ...) to enhance for larger screens. Never the reverse.

Container widths:

max-width: 1280px  (content area)
max-width: 768px   (prose / text-heavy sections)
padding:   0 24px  (mobile gutters)
padding:   0 48px  (desktop gutters)

Grid system:

• 12-column grid for desktop layout
• 4-column grid for tablet
• 1–2 columns for mobile
• Gap: 24px (mobile), 32px (desktop)

Section spacing pattern:

Section padding vertical: 80px desktop / 48px mobile
Hero section:             100vh or min 600px
Feature section:          auto-height with padding
CTA banner:               60px padding vertical
Footer:                   48px padding vertical

2.4 Component Library

For every project, define these components. Each has a state matrix.

Atoms (smallest, no dependencies):

Molecules (composed of atoms):

Organisms (complex sections):

2.5 Interactive States & Micro-animations

Every interactive element needs defined states. Undefined states become inconsistent UI.

Button hover pattern:

• Scale: transform: scale(1.02) — subtle growth
• Background: darken 8–12% or shift hue slightly
• Shadow: increase to --shadow-md
• Transition: --transition-fast (150ms)

Card hover pattern:

• Shadow: elevate from --shadow-sm to --shadow-md
• Optional: translate Y by -4px (transform: translateY(-4px))
• Transition: --transition-base (250ms)

Scroll-reveal animations: Use Intersection Observer (not scroll events — better performance).

Pattern: Elements start at opacity: 0, translateY: 20px
On enter viewport: opacity: 1, translateY: 0
Duration: 400ms ease-out
Stagger delay for grid items: 100ms per item

Avoid:

• Animations that block content (no long delays before showing text)
• Parallax on mobile (causes jank and motion sickness)
• Spinning/rotating loaders (use skeleton screens instead)
• Transitions > 500ms on UI interactions (feels sluggish)

Before/After slider:

• Drag handle with spring physics (cubic-bezier(0.34, 1.56, 0.64, 1))
• Touch-friendly handle (min 44px)
• Works with both mouse drag and touch swipe

2.6 Imagery & Media System

Photography rules:

• All photos consistent in: color temperature (warm/cool), contrast, and crop ratio
• Hero images: 16:9 or full-bleed, min 1920×1080px, WebP
• Cards: 4:3 or 1:1 (square), consistent across all cards in a section
• Team photos: 1:1 (square) or 3:4 (portrait), identical crop and background
• Gallery: Mixed ratios allowed, but consistent editing style

Image optimization pipeline:

Original → WebP conversion → Responsive srcset
Sizes: 400w, 800w, 1200w, 1600w
Loading: lazy (all below-fold), eager (hero only)
Blur placeholder: base64 LQIP (Low Quality Image Placeholder)

Video:

• Hero video: MP4 + WebM, max 10MB, autoplay muted loop, poster frame required
• No autoplay with sound (browsers block it anyway, and it's bad UX)
• Video aspect ratio: 16:9 or full-bleed

2.7 Accessibility Baseline

These are not optional — they affect SEO, usability, and legal compliance.

Colour contrast (WCAG AA):

• Normal text (< 18px): min contrast ratio 4.5:1
• Large text (≥ 18px bold or ≥ 24px): min 3:1
• UI components and focus indicators: min 3:1
• Tool: webaim.org/resources/contrastchecker

Focus states: Every interactive element needs a visible focus ring. Use outline: 2px solid --color-primary with outline-offset: 2px. Never outline: none without a replacement.

Semantic HTML requirements:

• One <h1> per page
• Heading hierarchy: h1 → h2 → h3 (no skipping levels)
• All images: meaningful alt text or alt="" for decorative
• Forms: <label> for every <input>
• Buttons: descriptive text (not just icons)
• Nav: <nav> with aria-label

Touch targets:

• Min 44×44px for all tappable elements
• Min 8px spacing between adjacent targets

2.8 Design → Development Handoff

Structure the Figma file (or design doc) in this order:

📁 00_Foundations
   ├── Colors (all tokens)
   ├── Typography (all styles)
   ├── Spacing & Grid
   └── Icons

📁 01_Components
   ├── Atoms
   ├── Molecules
   └── Organisms

📁 02_Pages
   ├── Homepage
   ├── Services
   ├── Gallery
   ├── Team
   ├── About
   ├── Branches
   ├── Booking
   └── Contact

📁 03_Responsive
   ├── Mobile (375px)
   ├── Tablet (768px)
   └── Desktop (1280px)

📁 04_States
   ├── Loading states
   ├── Empty states
   └── Error states

For each component in Figma:

• Show all states (default, hover, active, disabled)
• Annotate spacing with actual token names
• Mark which elements are dynamic (CMS-driven)
• Include mobile variant if different

Output Document Structure

Always produce a file named 03_Design-System.md in the project folder with this structure:

# Design System: [Project Name]

## 1. Brand Identity Summary
## 2. Design Tokens
   - Colors (full palette with hex codes)
   - Typography (fonts + scale)
   - Spacing (the scale)
   - Radius, Shadow, Transition
## 3. Layout System
   - Grid + breakpoints
   - Container + section spacing
## 4. Component Inventory
   - Atoms list
   - Molecules list (with descriptions)
   - Organisms list (with descriptions)
## 5. Page-by-Page Design Notes
   - Key layout decisions per page
   - Critical interactive elements
## 6. Animation Philosophy
## 7. Imagery Guidelines
## 8. Accessibility Checklist
## 9. Figma File Structure
## 10. Developer Handoff Notes
    - CSS custom properties list
    - Framework recommendations
    - Key implementation notes

Key Principles to Remind the Model

Consistency over creativity. A design system that's boring but consistent is better than one that's creative but unpredictable. Users trust predictable patterns.

Space is not wasted. White space (negative space) communicates quality. Luxury brands use more padding. Mass-market brands compress. The spacing scale communicates positioning.

Mobile constraints improve everything. Designing for a 375px screen first forces the most important content to the top. Then desktop becomes an enhancement, not the baseline.

Performance is a design decision. Every full-bleed video, complex animation, and high-res photo is a performance cost. A design that requires 5s load time is a bad design, regardless of how beautiful it looks.

Typography does 80% of the work. Get the type scale, weight contrast, and line-height right, and the page looks good even with placeholder boxes. Get it wrong, and no amount of color or imagery fixes it.