| name | design-reference |
| description | Analyses up to 5 reference websites provided by the client, visits each one, and generates a structured design guide (docs/design-reference.md) that captures the patterns, features, and qualities the client admires. Use when the client provides URLs of websites they like. Run before design-system. |
Design Reference Skill
Turn client-provided reference websites into a structured design guide that feeds directly into the design-system, page-builder, and brand-alignment skills.
When to Use
The client provides up to 5 URLs of websites they admire and says something like:
- "I like these websites"
- "Build something similar to these"
- "Here are some references"
- "I want my site to feel like this"
Input
The client provides 1 to 5 URLs. Accept them in any format:
- Listed in conversation
- Written in
docs/style-brief.md under a references section
- Provided as a simple list
Hard limit: 5 URLs maximum. If the client provides more, ask them to choose their top 5. Analysing too many references dilutes the findings.
Step 1: Visit Every Reference Site
Use the WebFetch tool to visit each URL. For each site, analyse the homepage first, then follow up to 2 internal pages (about, services, or contact) if they are linked from the homepage.
For each reference site, extract:
Layout and Structure
- Overall page layout approach (single column, split, grid, asymmetric)
- How the hero section is constructed (full-bleed image, video, text-only, split layout, animated)
- Section rhythm and spacing (tight or generous, alternating backgrounds, dividers)
- How content blocks flow down the page
- Footer structure and content
- Whether the site uses a sidebar, and where
Navigation
- Number of navigation items and their labels
- Navigation style (sticky, transparent-to-solid on scroll, hamburger on desktop, mega menu)
- How the mobile menu behaves
- Whether there is a prominent CTA in the navigation bar
- How sub-pages are organised
Typography
- Heading style (serif, sans-serif, display, all-caps, mixed case)
- Approximate heading sizes and weight (bold, light, extra-bold)
- Body text style and readability
- Whether text is large and spacious or compact and dense
- Any decorative text treatments (gradient text, outlined text, oversized characters)
Colour and Visual Tone
- Dominant colour palette (dark, light, colourful, monochrome, earthy, bold)
- Background approach (white, dark, coloured sections, gradients, textures)
- Accent colour usage and where it appears
- Overall mood (luxury, playful, corporate, warm, minimal, industrial, editorial)
- Contrast strategy (high contrast, soft tones, dark mode)
Imagery and Media
- Photo style (professional studio, candid, lifestyle, aerial, abstract)
- Image treatment (full-bleed, rounded corners, overlapping, masked shapes, duotone)
- Whether illustrations or icons are used prominently
- Video usage (background video, embedded, none)
- Image-to-text ratio on key pages
Interactions and Animation
- Scroll animations (fade in, slide up, parallax, reveal on scroll)
- Hover effects on cards, buttons, images, or links
- Page transitions or loading animations
- Any interactive elements (sliders, tabs, accordions, counters)
- Whether animations feel subtle or dramatic
Calls to Action
- Primary CTA style (button shape, colour, size, placement)
- CTA wording patterns (action-oriented, inviting, formal)
- How many CTAs appear per page
- Whether CTAs are repeated at section breaks or only at top and bottom
Features and Functionality
- Contact forms and their complexity
- Testimonial or review display format
- Team or staff presentation style
- Service/product listing approach
- Blog or news section presence
- Social media integration
- Map or location display
- Any unique or standout features
Step 2: Identify Common Patterns
After visiting all reference sites, identify what the client is drawn to. Look for patterns that appear across multiple references:
Strongly Recurring (appeared in 3+ sites)
These are likely core preferences the client expects. Prioritise them.
Partially Recurring (appeared in 2 sites)
These are probable preferences. Include them unless they conflict with strongly recurring patterns.
Unique to One Site (appeared in 1 site only)
Note these but do not assume the client wants them. They may have admired that site for other reasons.
Step 3: Filter Through Our Standards
Not everything from reference sites should be adopted. Filter every finding against our established practices.
Must Respect
| Our Standard | How It Applies |
|---|
| Astro + Tailwind + Alpine.js | All features must be achievable within this stack. No React, Vue, or heavy JS frameworks. |
| Zero unnecessary JavaScript | Flashy JS-heavy interactions should be noted but translated into CSS/Alpine.js equivalents or omitted. |
| Self-hosted everything | External font services, analytics scripts, or CDN dependencies from reference sites are not adopted. Identify the fonts and find Fontsource equivalents. |
| Mobile-first | Desktop-first patterns from reference sites are reinterpreted as mobile-first. |
| Performance budget | Under 500KB first load, 95+ Lighthouse. Heavy video backgrounds or large animation libraries are noted but flagged. |
| East African English | Any copy style observations are filtered through our language and tone standard. |
| Brand alignment | Reference patterns serve the client's brand and ideal customer, not the reference site's. |
| Accessibility | Any pattern that compromises accessibility (low contrast text, missing alt text, keyboard traps) is corrected in the guide. |
| Distinctive design | Even when drawing from references, the final site must feel original to the client, not a clone. |
Translation Rules
When a reference site uses technology or patterns outside our stack:
| Reference Site Uses | We Translate To |
|---|
| React/Vue components | Astro components + Alpine.js for interactivity |
| Framer Motion / Lottie | CSS animations + GSAP ScrollTrigger (if justified) |
| Google Fonts CDN | Fontsource self-hosted equivalent |
| Video backgrounds | Static hero image with subtle CSS animation, or flag as optional enhancement |
| Infinite scroll | Paginated sections or "Load more" with Alpine.js |
| Complex carousels | Simple Alpine.js slider or CSS scroll-snap |
| Parallax libraries | CSS background-attachment: fixed or lightweight IntersectionObserver |
| Cookie banners / chat widgets | Note as optional; do not include by default |
Step 4: Generate the Design Reference Guide
Create docs/design-reference.md with the following structure:
---
generated: true
sources: [list of URLs analysed]
generated_date: YYYY-MM-DD
---
# Design Reference Guide
## Reference Sites Analysed
| # | URL | What the Client Likely Admires |
|---|-----|-------------------------------|
| 1 | ... | Brief summary of standout qualities |
| 2 | ... | ... |
## Core Design Direction
One paragraph summarising the overall aesthetic direction
these references point toward. Name the direction clearly
(e.g., "Editorial Minimal", "Warm Corporate", "Bold Industrial").
## Layout Patterns
### Recommended Page Structure
- Homepage layout approach
- Inner page layout approach
- Section rhythm and spacing guidance
### Hero Section
- Recommended hero style with reasoning
- Fallback approach if photos are limited
### Section Flow
- How sections should alternate
- Background treatment between sections
- Spacing recommendations
## Typography Direction
### Heading Font
- Style: [serif/sans-serif/display]
- Character: [description of the feel]
- Fontsource candidates: [2-3 specific font names to evaluate]
- Reference: "Similar to what [reference site] uses"
### Body Font
- Style: [serif/sans-serif]
- Priority: readability
- Fontsource candidates: [2-3 specific font names]
### Text Treatment
- Heading sizes and weight pattern
- Any decorative treatments to consider
- What to avoid
## Colour Direction
### Palette Mood
- Overall tone: [dark/light/colourful/earthy/etc.]
- Dominant colour family: [description]
- Accent usage: [how and where]
### Background Strategy
- Page background approach
- Section background alternation
- Whether dark sections are appropriate
### Colour Candidates
Suggest 2-3 palette directions with hex values for the
design-system skill to evaluate. Do not lock in a final
palette — that is the design-system's job.
## Navigation Pattern
- Recommended nav style
- Number of items
- Mobile menu approach
- CTA in navigation: yes/no and style
## Image and Media Approach
### Photo Treatment
- Border radius
- Hover behaviour
- Layout style (grid, overlapping, full-bleed, contained)
### Recommended Image Roles
Map to photo-manager categories:
- Hero: [style and dimensions]
- Team: [style and dimensions]
- Services: [style and dimensions]
- Gallery: [if applicable]
## Animation and Interaction
### Scroll Animations
- Entry animation style (fade, slide, scale)
- Speed and timing feel
- Stagger behaviour for groups
### Hover Effects
- Button hover style
- Card hover style
- Image hover style
### What to Skip
- Animations from references that are too heavy for our stack
- Interactions that would require frameworks outside our stack
## Call-to-Action Style
- Primary CTA: shape, colour approach, size
- CTA wording direction (aligned with east-african-english)
- Placement pattern across pages
## Standout Features to Consider
List specific features from reference sites worth
implementing, with feasibility notes:
| Feature | Seen On | Feasibility | Notes |
|---------|---------|-------------|-------|
| ... | ... | Easy/Moderate/Complex | ... |
## Features to Skip
List features from reference sites that do not fit
our stack, performance budget, or the client's needs:
| Feature | Reason to Skip |
|---------|---------------|
| ... | ... |
## Do's and Don'ts for This Project
### Do
- [Specific guidance based on reference analysis]
### Don't
- [Specific warnings based on reference analysis]
Step 5: Save and Report
- Write the completed guide to
docs/design-reference.md
- Summarise the findings for the client in conversation:
- Name the design direction identified
- List the 3-5 most important patterns extracted
- Note any reference features that were filtered out and why
- Confirm which Fontsource font candidates to evaluate
- Ask the client if the direction feels right before proceeding to the design-system skill
How This Skill Connects to Others
Client provides URLs
↓
design-reference ← THIS SKILL (analyse → generate guide)
↓
docs/design-reference.md is created
↓
design-system reads it ← alongside docs/style-brief.md
↓
page-builder reads it ← for layout patterns, section structure, features
↓
brand-alignment reads it ← to verify the final site honours the reference direction
The design-system skill should read docs/design-reference.md alongside docs/style-brief.md when making typography, colour, and component decisions. If the two files conflict, the style brief takes priority — it represents the client's direct instructions, while the reference guide represents interpreted preferences.
Rules
- Never clone a reference site. Extract patterns and qualities, not specific designs. The client's site must be original.
- Never copy text from reference sites. Content comes only from the client's
docs/ files.
- Always filter through our stack. If a feature cannot be built with Astro + Tailwind + Alpine.js without significant compromise, flag it honestly.
- Name fonts by Fontsource availability. Do not recommend a font that is not available on Fontsource. If a reference site uses a proprietary font, find the closest Fontsource alternative.
- Be honest about limitations. If a reference site achieves its effect through heavy JavaScript, video, or a framework outside our stack, say so clearly and propose the best achievable alternative.
- Maximum 5 URLs. Do not analyse more, even if the client insists. Quality of analysis drops with quantity.
- Confirm before proceeding. Always present the guide summary to the client and get confirmation before the design-system skill begins work.
