Design for web standards

Here’s how to build incredible websites:

1. Fast

• Pages need to load as fast as possible (prefer static pages).
• Optimize image, font, and script loading.
• Navigation needs to be extremely fast to load and view content.

2. Readable

• Be concise (make every word count).
• Avoid technical jargon and idioms.
• Optimize for skimming (good use of bold, italic, lists, headings, images, etc).
• Keep the first-time experience simple and slowly reveal complexity.
• Ensure copy have many examples they can connect to.

3. Helpful

• Make it easy for readers to leave feedback (e.g. typos).
• Automate checking for broken links on git pushes.

4. AI-native

Most traffic now comes from AI crawlers.

• Prefer cURL over “click” if possible.
• Provide prompts in addition to tutorials.

5. Agent-ready

• Support viewing pages as markdown (just add .md to the URL).
• Serve markdown files when Accept: text/markdown is requested.
• Serve an llms.txt file as a directory of markdown files.

6. Polished

• Buttons should have generous hit areas.
• Sidebars should retain scroll position and expanded state.
• Ensure good active/hover states for elements.
• Every heading and section should be linkable with stable anchors.
• Add metadata/canonical tags to ensure docs show up cleanly in search.

7. Localized

• Don’t display /en in the URL by default.
• Use server-side routing to serve the correct language.
• Localize static strings and content.

8. Responsive

• Great mobile menus / Safari iOS support.
• Tooltips on desktop, popovers on mobile.

9. Accessible

• Ensure all images have alt tags.
• Respect prefers-reduced-motion system settings.

10. Usable

• Don’t add scroll-smoothing.
• Minimize horizontal scroll.
• Don’t hide the scrollbar.