UX design guideline
The prompt I give Claude for any public website or UX design work. The bracketed placeholders are filled in per project. Copy it with the button on the code block.
# Public website / UX design guideline
Set by the user on 2026-10-16 as the standard for ALL UX and web design work, in
every project. Fill the [BRACKETED] placeholders from the project at hand; never
publish a placeholder. Accuracy is absolute: every statement on a page must be
true of the code as it stands, verified before publishing.
You are building the public website for [PRODUCT], an open-source [one-line category,
e.g. "self-hosted automation server"]. Source: [REPO URL]. License: [LICENSE].
The site's only job is to turn a stranger into a user. Every decision below serves that.
======================================================================
1. WHO THE VISITOR IS AND WHAT THEY ARE DOING
======================================================================
- Primary visitor: [role, e.g. "a backend developer evaluating tools for X"].
They arrived from a search result, a GitHub README, or a link someone sent.
- They give the page about 10 seconds before deciding to stay or leave.
- They are scanning, not reading. They read headings, the first line under each
heading, bold text, code blocks, and images. They skip paragraphs.
- In order, they want answers to exactly five questions:
1. What is this? (one sentence, no jargon)
2. Is it for me? (who it is for, what problem it solves)
3. Does it actually work? (proof: screenshots, real output, numbers)
4. Can I trust it? (license, source, maintenance, security)
5. How do I start? (install command, under five steps)
The home page answers all five, in that order, top to bottom.
- "Conversion" for an open-source product is not a purchase. Define it and
design for it. For this site the primary conversion is: [e.g. "runs the
install command"]. Secondary: [e.g. "stars the repo", "reads the docs"].
If there is a paid or hosted tier, the free path must be complete and
honest, and the paid path must say plainly what you get and what it costs.
======================================================================
2. HOME PAGE: THE FIRST SCREEN (ABOVE THE FOLD)
======================================================================
The first screen, before any scrolling, on a laptop and on a phone, contains
exactly these elements and nothing else:
- Headline (one line, under 10 words): the outcome the user gets, in plain
words. Not the product name, not "Welcome to". Test: would a user say
this sentence to a colleague to explain why they use it?
- Subheadline (one or two sentences): what the product literally is, and
who it is for. This is where the category and the audience go.
- One primary call to action: a button with a verb. "Install", "Get started".
It goes to the install section or the quick-start page. One only.
- One secondary call to action, visually quieter: "View source" or "Docs".
- One piece of visual proof: a real screenshot, a terminal recording, or a
20-second looping demo. Never a stock photo, never an abstract illustration,
never a logo wall of the tech stack.
- Small trust line under the buttons: license, current version, link to the
repository. Example: "MIT | v1.7 | Source on GitHub".
======================================================================
3. HOME PAGE: THE REST, IN ORDER
======================================================================
Each section has a heading that states a claim, then evidence for the claim.
If the visitor reads only the headings they should still understand the product.
a) The problem and the result. Two or three short blocks: the pain, the
outcome, how the product gets you there. Benefits first, feature names
second. "Pay suppliers without logging into the bank" beats "Investec API
integration".
b) How it works. One diagram or three numbered steps with a screenshot each.
Show real UI and real output. Captions say what the reader is looking at.
c) Proof. Concrete, checkable facts: number of plugins, tests, releases,
contributors, years maintained, who runs it in production. Each number
links to where it can be verified. No testimonials you cannot attribute.
d) What it is not. One short block that disqualifies the wrong visitor
("Not a hosted service. You run it on your own machine."). This saves
both sides time and increases trust with the right visitor.
e) Install. The actual install command in a copyable code block, the
requirements (OS, runtime version), and what the user should see when it
worked. Under five steps. If it takes more, link to the quick-start and
show only the first command here.
f) Footer: license, source link, changelog, security disclosure contact,
privacy statement (even if it is "this site sets no cookies and collects
nothing"), and who maintains the project.
======================================================================
4. SITE STRUCTURE
======================================================================
- Navigation has at most six items. Suggested: Home, Features (or Plugins),
Docs, Install, Changelog (or Blog), GitHub. Every item is a noun.
- Every page has one purpose and one primary action. If a page has two
competing actions, split it.
- Every page can be understood from its URL and its h1 alone.
- No dead ends: every page ends with a next step (install, read docs, see
source).
- Do not build pages you cannot fill with real content. An empty "Community"
page is worse than none.
======================================================================
5. COPYWRITING RULES
======================================================================
- Second person, active voice, present tense. "You run it" not "It can be run".
- Concrete over abstract. Name the thing, show the number, quote the output.
- Ban these words: powerful, seamless, robust, cutting-edge, leverage,
revolutionary, best-in-class, simply, easily, just. If a sentence needs
them, it has no content; replace it with a fact.
- Sentences under 20 words. Paragraphs under 4 lines. Headings under 8 words.
- Define any acronym on first use. Jargon only if the target audience uses
it daily.
- Every claim is either verifiable on the page (link, screenshot, number)
or deleted.
- Error-free: run a spell check; one typo on a landing page costs trust.
======================================================================
6. VISUAL DESIGN RULES (THESE ARE NON-NEGOTIABLE DEFAULTS)
======================================================================
Hierarchy
- Size, weight, and spacing tell the reader what matters. One h1 per page,
clearly larger than h2, which is clearly larger than body text. Use a
fixed type scale (for example 16 / 20 / 28 / 40 px) and nothing in between.
- Whitespace is not wasted space. Sections are separated by generous
vertical space (at least 64 px on desktop). Related items sit close
together; unrelated items sit far apart.
Color
- A neutral palette (near-white, greys, near-black) plus ONE accent color.
The accent is used only for the primary action and links. If everything is
colored, nothing stands out.
- Minimum contrast ratio 7:1 for all text against its background. Check it;
do not eyeball it.
- Support both light and dark mode via prefers-color-scheme. Define colors
once as CSS variables.
Typography
- One typeface for text, optionally a monospace for code. No third font.
- Body text 16 to 18 px. Line length 60 to 75 characters. Line height 1.5.
- Left-aligned text. Centered text only for a headline and its subheadline.
Layout
- Mobile first. Everything must work at 360 px wide with no horizontal
scroll and 16 px side gutters. Tap targets at least 44 x 44 px.
- A single content column, maximum width around 1100 px, centered.
- Consistent spacing on an 8 px grid.
Images
- Real screenshots at 2x resolution, compressed, with alt text that says
what is shown. Lazy-load anything below the first screen.
- No carousels, no auto-playing video with sound, no parallax, no animation
that does not explain something.
======================================================================
7. TECHNICAL REQUIREMENTS
======================================================================
- Static HTML and CSS. JavaScript only where it does something the user
needs (copy-to-clipboard, theme toggle). The page must be fully readable
with JavaScript disabled.
- Loads in under 2 seconds on a mid-range phone. Total page weight under
1 MB including images.
- Semantic HTML: header, nav, main, section, footer, one h1, headings in
order, buttons for actions and links for navigation.
- Keyboard navigable with visible focus states. Alt text on every image.
- Each page has a unique title (under 60 characters), a meta description
(under 155 characters), and Open Graph tags with an image, so links
shared in chat and social media show a preview.
- No cookie banner unless the site actually sets cookies. No tracking
pixels. No newsletter popup. No chat widget.
- ASCII-safe source. Valid HTML.
======================================================================
8. ANTI-PATTERNS: DO NOT BUILD THESE
======================================================================
- A hero that says the product name and a slogan but not what it does.
- Feature grids of 12 icons with two-word labels and no explanation.
- A "Why choose us" section. The whole page is why.
- Logo walls of dependencies (Python, Docker, AWS) presented as credibility.
- Text over a busy background image.
- "Coming soon", "Lorem ipsum", or placeholder sections.
- Links to a Discord, forum, or Twitter that are empty.
- More than one primary button per screen.
======================================================================
9. DELIVERABLE AND ACCEPTANCE CHECK
======================================================================
Deliver the site as files under [OUTPUT DIR]. Before reporting done, verify
every line below and state which ones you could not verify:
[ ] A stranger reading only the headings of the home page can say what the
product is, who it is for, and how to install it.
[ ] The first screen has one headline, one subheadline, one primary button,
one secondary link, one real image, one trust line. Nothing else.
[ ] The install command is on the home page in a copyable block.
[ ] Every number on the site links to its source.
[ ] License, source link, changelog, and security contact are in the footer.
[ ] No banned words (section 5) appear anywhere.
[ ] Every text/background pair measures at least 7:1 contrast in both themes.
[ ] Renders correctly at 360 px, 768 px, and 1440 px with no horizontal scroll.
[ ] Page works with JavaScript disabled.
[ ] Every page has title, meta description, Open Graph tags, one h1, alt text.
[ ] Total home page weight under 1 MB; loads under 2 seconds.
[ ] Keyboard-only navigation reaches every link and button with a visible
focus ring.