Specwright

Who it is for

• Developers shipping an API or SDK
• SaaS teams replacing scattered READMEs
• Developer-relations and technical writers
• Agencies building client product docs

Layout

1. Sticky header: square logo mark + wordmark left, wide search field with ⌘K hint centered, theme toggle and blue primary button right
2. Left sidebar: collapsible groups with emoji icons (Getting Started, Guides, API Reference, Examples)
3. Home hero: 'v2.0' pill badge, large bold centered headline, subcopy, primary + outline buttons
4. Quick-start section: numbered steps left, dark code block right
5. Feature grid (3x2 cards with blue line icons)
6. Popular-topics 2x2 link cards
7. Article pages: breadcrumbs, content with callouts and code tabs, feedback widget, prev/next links; right-hand TOC

Palette

clear, trustworthy, familiar, tidy, technical. Feels like mature developer docs you instantly know how to use.

• background#ffffff
• text slate#344256
• muted text#5f6e84
• primary blue#2563eb
• muted surface#f1f5f9
• border#e1e7ef
• code block#1e293b

Every checked pair, measured again

As vibld’s tokens

The palette on the fifteen colour tokens vibld styles a project with, each text colour on the fill it is read on. Marked tokens are solved from the palette, because no swatch held that role at 4.5:1.

• background
• card
• muted
• primary
• secondary
• accent
• destructive *

Type

Display

Inter Bold 48px, -1.2px tracking, title case; H2 Inter Bold 24px

Body

Inter 16px slate; code in JetBrains Mono 14px

Classic developer-docs pairing: neutral Inter with a crisp monospace for code.

Spacing and imagery

Fixed 280px sidebar, content max ~770px, cards 8px radius with 1px borders, 96px section spacing on home, compact 8px nav rows.

No photos; lucide line icons in brand blue, emoji section icons in the sidebar, dark syntax-highlighted code panels.

Components

• Sticky header with search trigger
• Command palette search modal
• Collapsible sidebar groups
• Mobile drawer nav
• Version badge pill
• Hero with dual CTAs
• Numbered quick-start steps
• Syntax-highlighted code block with copy
• Multi-language code tabs
• HTTP method badges
• Callout blocks (info/warning/success/error)
• Scroll-spy table of contents
• Feedback widget
• Prev/next article links

Interactions

• ⌘K opens fuzzy search with arrow-key navigation and category badges
• Sidebar groups expand/collapse
• TOC highlights current heading on scroll
• Copy button appears on code hover, confirms with check
• Code language tabs remember choice
• Dark/light toggle
• Thumbs up/down feedback state
• Mobile drawer slides in with backdrop and auto-closes on navigation

Data

• DocPage{slug, title, section, order, description, body (markdown/MDX), headings[]}
• Section{id, title, icon, pages[]}
• Endpoint{method, path, summary, params[], examples{curl, js, python, ruby}}
• SearchIndexEntry{title, slug, section, excerpt}

Build prompt

The baseline every prompt in the catalog assumes, then this design’s own ten sections, from goal to guardrails.

Copy the baseline and build prompt

### How to use these prompts
Paste a template's build prompt into your coding agent as the first message. Each prompt names its own stack, tokens and acceptance criteria; the rules below apply to all of them and can be prepended once per project.

### Engineering baseline
- TypeScript strict mode, no `any`, small typed components, feature folders, and one source of truth for design tokens (CSS variables consumed by Tailwind).
- Validate every input with a shared zod schema on the client and again on the server or edge function. Never trust client-side checks alone.
- Show loading, empty and error states for every async view. Surface errors in plain language with a retry, and log details to the console in development only.
- Keep secrets out of the bundle. Only publishable keys (for example a Supabase anon key) belong in client code; service-role keys, API keys and webhooks live in server or edge-function environment variables.

### Data and auth baseline (full-stack templates)
- Enable Row Level Security on every table before inserting data. Default-deny, then add owner-scoped policies (`auth.uid() = user_id`) and explicit role checks for admin views.
- Store roles in a separate table checked by a security-definer function, never in a user-editable profile field.
- Upload files to private storage buckets with size and MIME limits, and serve them through signed URLs.
- Rate-limit public endpoints (forms, auth, AI calls) and add a honeypot field or captcha to anonymous forms.
- Take payments through a hosted checkout and verify webhooks by signature. Never handle raw card data.

### Accessibility and UX baseline
- Target WCAG 2.2 AA: 4.5:1 contrast for normal text and 3:1 for large text, input borders, focus rings and meaningful icons or chart lines. Every palette in this catalog lists its verified pairs; re-check with a contrast tool after any colour change.
- Keep body text at 16px or larger with 1.5 line height, nothing below 12px, no light weights under 24px, and uppercase only for short labels.
- Give every interactive element a visible focus ring, full keyboard support, semantic landmarks, labelled form fields, and alt text on meaningful images.
- Respect `prefers-reduced-motion` for every animation. Give drag-and-drop and carousels keyboard and button alternatives.
- Build mobile-first and test at 375px, 768px and 1280px.

### Content guardrails
- Use original copy, fictional sample data and placeholder or licensed imagery. Do not reuse another product's name, logo, screenshots or marketing text.
- Label demo testimonials and metrics as samples. Collect the minimum personal data the feature needs.

### Goal
Build **Specwright** (an invented name for a fictional API product), a fast, familiar documentation site for developers integrating an API or SDK. It needs a welcoming home page, well-structured guides, an API reference with multi-language examples and instant search, so readers find answers without leaving the page.

### Stack
React 18 + TypeScript + Vite, Tailwind CSS with the typography plugin, shadcn/ui (Radix: Collapsible, Tabs, Dialog/Command, Sheet) and lucide-react. Use MDX (via `@mdx-js/rollup`) for content, Fuse.js for fuzzy search over a build-time index, Shiki or Prism for syntax highlighting, and React Router for routes. No backend. The feedback widget posts to a pluggable endpoint, or just logs, until one is configured.

### Pages & layout
1. **Global shell**: a sticky header (logo mark and wordmark, a centered search trigger with a ⌘K hint, a theme toggle, a primary "Get started" button). A 280px left sidebar with collapsible groups (Getting started, Guides, API reference, Examples); a Sheet drawer on mobile.
2. **Home**: a version pill, a large centered headline and subcopy with primary and outline buttons; a quick start with three numbered steps beside a dark code panel; a six-card feature grid; four "popular topics" link cards.
3. **Article**: breadcrumbs, H1, a lead paragraph, MDX body (callouts, tables, code tabs), a "Was this helpful?" widget, prev/next cards, and a right-hand table of contents from 1280px up.
4. **API endpoint page**: a method badge and path, a parameter table, request and response examples in cURL, JavaScript, Python and Ruby tabs.
5. **404** with a search prompt.

### Design system
- Light: `--background: #ffffff`, `--foreground: #344256`, `--muted-fg: #5f6e84`, `--primary: 221 83% 53%` (≈`#2563eb`), `--muted: #f1f5f9`, `--border: #e1e7ef` (decorative), `--input-border: #6d8ab1`, `--code-bg: #1e293b`.
- Dark: `--background: #0b1220`, `--foreground: #e2e8f0`, `--border: #1f2a3c`, `--input-border: #4b6692`, `--primary: #3c83f6` with `#0b1220` button text.
- Method badges: GET green, POST blue, PUT amber, PATCH violet, DELETE red, each with text and not color alone.
- Fonts: Inter (UI and prose) and JetBrains Mono (code). Scale 13/14/16/18/24/32/48 (13px for badges only); prose 16px, line height 1.7, max 72ch.
- Spacing on a 4px base; content max 768px.
- Radius: 8px cards and code blocks, 6px buttons, full pills.
- Shadows: minimal, with 1px borders as the default.
- Motion: 150ms for everything; the drawer slides in 200ms.

### Components & interactions
SearchDialog (empty "Type to search", no-results state with a suggestion, arrow/Enter/Esc keys, category badges), SidebarGroup (expanded state remembered, active link highlight), Toc (scroll-spy with IntersectionObserver, smooth scroll), CodeBlock (language label, copy button with a copied state, line highlighting), CodeTabs (remember the chosen language across pages in localStorage), Callout (info, warning, success, danger with icons), MethodBadge, ParamTable, FeedbackWidget (selected, submitting, thanks, error), PrevNext, ThemeToggle.

### Data & state
Organize content as MDX files with frontmatter `{title, section, order, description}`. Generate the sidebar and search index at build time. Model endpoints as typed objects `{method, path, summary, params[], examples}`. Keep the theme and code-language preference in localStorage. Write sample content for a fictional API and use example.com domains.

### Accessibility
Include a skip-to-content link and landmarks (`header`, `nav` with an aria-label, `main`, `aside` for the TOC). The search dialog traps focus and returns it on close. Collapsibles use `aria-expanded`. Code-tab switching follows the Radix Tabs keyboard model. `#3c83f6` is only 3.6:1 on white, so light mode uses `#2563eb` for links and buttons; dark mode keeps `#3c83f6`. Keep focus rings visible in both themes.
Verified contrast: body: #344256 on #ffffff = 10.2:1; muted: #5f6e84 on #ffffff = 5.2:1; link: #2563eb on #ffffff = 5.2:1; white on primary: #ffffff on #2563eb = 5.2:1.

### Security
Content is authored and trusted, but still disable raw HTML in MDX or sanitize it with DOMPurify. External links get `rel="noopener noreferrer"`. Placeholder API keys in examples must be obviously fake (`sk_test_xxx`). The feedback endpoint, once wired up, needs rate limiting and zod validation. Keep secrets out of the client and set a strict CSP.

### Performance & SEO
Pre-render every route to static HTML, code-split per page and lazy-load the search index on first ⌘K. Give each page its own title, meta description and canonical URL, and generate `sitemap.xml`. Keep a proper heading hierarchy for anchor links. Target Lighthouse 95+ on all four scores.

### Guardrails
- Write fresh docs copy for a fictional product; no real company or SDK names.
- Don't invent user quotes.
- Collect only anonymous helpfulness votes.
- Keep components small and typed; no `any`. Handle missing pages visibly.
- Done when: (1) ⌘K search finds any page by fuzzy title and content; (2) the TOC tracks scroll position; (3) code tabs persist the chosen language; (4) dark mode passes contrast checks; (5) the mobile drawer works and closes on navigation.

Open the builderAll templatesThis palette on its own