# Selectools Design Context

Persistent design guidelines for the selectools docs site and landing page.
All AI-assisted design work should reference this file.

**Companion document**: [`docs/design-system.md`](docs/design-system.md) holds the
concrete tokens, component inventory, animation language, and anti-patterns.
This file is the **why** (brand, voice, principles); the design system is
the **what** (the actual CSS vars, class names, and reusable patterns).
Read both before making design changes.

## Design Context

### Users

Python developers building production AI agents — from individual devs evaluating frameworks to engineering teams migrating from LangChain/CrewAI. They arrive skeptical of yet-another-framework and need fast proof that this is different. Context: scanning docs during tool evaluation, often comparing 3–4 options in parallel. The job: confirm selectools is production-grade, easy to adopt, and won't lock them in.

### Brand Personality

**Bold, Developer-First, Complete.**

- **Bold**: Confident assertions backed by metrics (4612 tests, 95% coverage, 50 evaluators). Not arrogant — earned confidence.
- **Developer-First**: Code over marketing. Show real Python, not diagrams of Python. Respect the reader's intelligence.
- **Complete**: One `pip install`, everything built-in. No ecosystem sprawl, no plugin fatigue.

**Emotional goal**: Confidence and relief — "Finally, something that just works." The reader should feel trust that this is production-grade, not anxious about hidden complexity.

**Voice**: Direct, assertive, technically precise. Use concrete numbers over vague claims. Short sentences. No buzzwords ("leverage", "synergy", "revolutionary"). Say what it does, show the code, prove it with data.

### Aesthetic Direction

**Visual tone**: Dark, technical, polished — like a well-built IDE. Calm backgrounds with bright cyan accents that draw the eye to what matters.

**Current palette** (maintain):
- Background: `#0f172a` (slate-950)
- Surface: `#1e293b` / `#273548`
- Accent: `#22d3ee` (cyan-300) — the signature color
- Text: `#e2e8f0` (primary), `#94a3b8` (secondary), `#64748b` (tertiary)
- Semantic: green (success), amber (warning), red (danger), blue (links/CTAs)

**Typography** (maintain):
- UI: Plus Jakarta Sans (400–800)
- Code: JetBrains Mono (400–500)
- Tight heading tracking (-0.02em), generous body line-height (1.7)

**Signature elements**: Grain texture overlays, cyan glow hover states, staggered reveal animations, pill-shaped badges, `cubic-bezier(0.16, 1, 0.3, 1)` easing.

**References** (aspire toward):
- Stripe docs — clarity, progressive disclosure, beautiful code blocks
- Vercel landing pages — bold headlines, metrics-forward, dark theme done right
- Tailwind CSS docs — developer-friendly, scannable, instant utility

**Anti-references** (explicitly avoid):
- Generic SaaS landing pages — cookie-cutter hero/features/pricing with no personality
- Hacker News minimalism — too bare, no visual design, feels unfinished
- LangChain docs — maze-like navigation, hard to find things (complexity as anti-pattern)

**Theme**: Dark mode primary. Light mode supported in docs via MkDocs Material toggle.

### Design Principles

1. **Code is the hero.** Every section should lead with or include real, runnable Python. Design serves the code — syntax highlighting, generous whitespace, copy buttons, proper font sizing. If a section has no code, question whether it belongs.

2. **Prove, don't claim.** Replace adjectives with numbers. "Fast" → "<0.5ms overhead". "Well-tested" → "4612 tests, 95% coverage". Metrics earn trust; superlatives erode it.

3. **Scannable in 10 seconds.** A developer evaluating frameworks will scan, not read. Bold headlines, visual hierarchy, comparison tables, and status badges should communicate value before the first paragraph is read.

4. **No visual noise.** Every element earns its place. Grain textures and glow effects are subtle (opacity < 0.02). Animations are functional (reveal hierarchy, confirm interaction), never decorative. When in doubt, remove.

5. **Respect the reader.** No patronizing tooltips for obvious concepts. No marketing fluff between code sections. Progressive disclosure: simple first, depth on demand. The docs should feel like a senior engineer wrote them for other senior engineers.

### Accessibility

- **Target**: WCAG 2.1 AA compliance
- Minimum contrast ratio 4.5:1 for body text, 3:1 for large text and UI components
- All interactive elements keyboard-navigable with visible focus indicators (cyan glow ring)
- Code blocks: sufficient contrast for all syntax colors against `#1e293b` background
- Reduced-motion: respect `prefers-reduced-motion` — disable reveal animations, pulse effects
- Screen reader: semantic HTML, proper heading hierarchy, alt text on all images/diagrams
- Color alone never conveys meaning — pair with icons, text, or patterns

### Component Patterns

**Cards**: 1px border (`#334155`), 8–12px radius, 28px padding, grain overlay. Cyan border + shadow on hover.

**Buttons**:
- Primary: Cyan background, dark text, scale(0.97) active state
- Secondary: Transparent with cyan border, cyan text
- Ghost: No border, cyan text on hover

**Code blocks**: 8px radius, 1px border, 13px JetBrains Mono, line numbers for long snippets, always include copy button.

**Section labels**: 11px monospace, uppercase, 0.12em letter-spacing, cyan color. Used above h2 headings.

**Status badges**: Pill-shaped (100px radius). Green = stable, amber = beta, red = deprecated.

**Admonitions** (docs): 8px radius, 4px left border in accent color, subtle background tint.
