Selectools Design System¶

The concrete tokens, components, animation language, and rules that make up the selectools visual language.

This is the what. For the why — brand personality, design principles, voice and tone — see .impeccable.md at the project root.

Source of truth: landing/index.html (inline <style> block + JS observers). This document mirrors that source. When the source changes, this document must be updated to match.

1. Design tokens¶

All tokens live on :root in landing/index.html and are referenced via var(--name). Never hardcode hex values in component CSS.

1.1 Colors¶

Surface palette¶

Text palette¶

Accent palette¶

Rule: One accent per component. Never mix two accents (cyan + green) on the same element. The exception is the eval report, which uses cyan / amber / green to differentiate metric types — that's intentional and earned.

Glow tokens (used by the execution-pointer system)¶

1.2 Typography¶

Loaded weights: Plus Jakarta Sans 400 / 500 / 600 / 700 / 800; JetBrains Mono 400 / 500.

Type scale (de facto, extracted from existing components)¶

Headings: Tight tracking (letter-spacing: -0.02em to -0.03em). Body: Generous line-height (1.7). Mono labels: Wide tracking (0.12em to 0.18em), uppercase.

1.3 Spacing¶

There is no formal spacing scale — values are chosen per-component for visual rhythm. Common values that recur:

1.4 Radii¶

1.5 Easing & duration¶

Rule: Never use cubic-bezier literals in component CSS. Reference the tokens.

1.6 Layout¶

1.7 Breakpoints¶

Rule: Use content-driven breakpoints. The 700/880/1100 values exist because that's where specific sections break, not because they're standard widths.

1.8 Touch targets¶

@media (pointer: coarse): any touch device, regardless of viewport width. Used to defeat Chrome's "Desktop Site" mode which lies about the viewport. All interactive elements must be ≥44×44px on coarse pointer.

2. Component inventory¶

All components live in landing/index.html. Search for the class name to find the styles.

2.1 Layout shells¶

2.2 Code frame (mac-style terminal)¶

The reusable code window with traffic-light dots and a filename label.

<div class="code-frame code-frame-accent">
  <div class="code-bar">
    <div class="code-dot" style="background:rgba(239,68,68,0.8)"></div>
    <div class="code-dot" style="background:rgba(250,204,21,0.8)"></div>
    <div class="code-dot" style="background:rgba(34,197,94,0.8)"></div>
    <span class="code-bar-label">filename.py</span>
  </div>
  <div class="code-body"><span class="kw">from</span> selectools <span class="kw">import</span> Agent</div>
</div>

Syntax token classes (apply to <span> inside .code-body): | Class | Color | For | |---|---|---| | .kw | #c084fc (purple) | from, import, def, class, return, @. | | .cls | #7dd3fc (cyan-300) | Class names, type annotations. | | .fn | #fbbf24 (amber) | Function names, callable invocations. | | .str | #86efac (green) | String literals. | | .cmt | var(--text-faint) | Comments. | | .num / .bool | #fb923c (orange) | Numeric literals, booleans. |

2.3 Buttons¶

All buttons: transform: scale(0.97) on :active, transition via --ease. Touch hover guards via @media (hover: none).

2.4 Cards & bento¶

Bento mobile rule: at ≤700px, all cells force grid-column: 1 / -1 !important to override any inline style="grid-row:N;grid-column:M / N" placements that pin cells in the 6-col grid.

2.5 The execution-pointer atoms (the unifying device)¶

These are the shared visual vocabulary that every section composes. The "execution pointer" is a conceptual entity (a cyan pulse representing live execution), not a single DOM node. Each section has its own animation that reuses these atoms.

Rule: When you build a new animated section, compose these atoms instead of inventing new ones. Cohesion comes from sharing color, easing, and timing — not from a runtime framework.

2.6 Section-specific components¶

These were designed once for the landing page sections. Reuse if a similar use case appears.

2.7 Bento legacy components (from PR #46)¶

3. Animation language¶

3.1 The reveal pattern¶

Every animated section uses the same pattern:

1. CSS sets the initial state (opacity 0, transform Y, etc.) and defines the animated state under a .in-view modifier class.
2. JS uses an IntersectionObserver (one IIFE per section) to add .in-view when the element enters the viewport.
3. The observer disconnects after the first trigger (one-shot).

(function() {
  var stage = document.querySelector('.my-stage');
  if (!stage) return;
  var io = new IntersectionObserver(function(entries) {
    entries.forEach(function(e) {
      if (!e.isIntersecting) return;
      stage.classList.add('in-view');
      io.disconnect();
    });
  }, { threshold: 0.25, rootMargin: '0px 0px -8% 0px' });
  io.observe(stage);
})();

Standard threshold: 0.25 to 0.35 depending on how committed the user should be. Standard rootMargin: -8% to -10% bottom inset so the animation fires after the section is comfortably in view, not the moment its top edge crosses.

No global helper. Each section's IIFE is self-contained. This makes the diff per-section reviewable and prevents one section's animation from breaking another.

3.2 Stagger recipes¶

Use CSS variables on individual elements to drive per-element delays:

<div class="thing" style="--delay:0.45s">A</div>
<div class="thing" style="--delay:0.65s">B</div>

.parent.in-view .thing {
  transition-delay: var(--delay, 0s);
}

For uniform staggers (e.g. compliance shelf exhibits), use nth-child rules with hard-coded delays. For non-uniform staggers (e.g. capability chips that fire when their corresponding code line is typed), use inline --delay vars.

3.3 Reduced motion¶

Every animated component must have a prefers-reduced-motion: reduce override that snaps to the final state. The fallback must be a complete, intentional static composition — not just "animation: none".

All overrides live in the single @media (prefers-reduced-motion: reduce) block at the bottom of the <style> section. Find the existing block and add to it; do not create a second.

4. Voice & tone rules¶

4.1 Banned punctuation¶

Em-dashes (—, —) in user-facing copy. When every section uses one, it becomes the load-bearing punctuation of the page and reads as AI-generated. Use a period, comma, colon, or rewrite. Source-code comments (CSS/HTML/JS) may keep their em-dashes — they're developer prose, not marketing copy.

4.2 Banned words in body copy¶

4.3 Sentence structure rules¶

• Short sentences over long ones. A period is better than a comma in most marketing contexts.
• No triple-adjective stacks ("fast, secure, and scalable"). Pick one and prove it.
• Numbers over adjectives. "4612 tests" beats "well-tested". "$0.0012 per call" beats "affordable".
• Active voice over passive. "We tested across Python 3.9-3.13" beats "It has been tested across..."
• No redundant phrases. Don't say "in order to" when "to" works. Don't say "the fact that" when "that" works.
• Don't restate the heading in the description. The h2 says it. The desc adds something new.

4.4 Tone¶

• Senior to senior. The reader is a senior engineer evaluating a framework. Don't explain Python concepts. Don't use marketing-school formulas (Problem → Agitation → Solution).
• Earned confidence, not arrogance. Every claim is followed by a number, a code snippet, or a link to proof. "Production-ready" alone is empty. "Production-ready: 4612 tests, 95% coverage, CycloneDX SBOM, audited" is earned.
• Specific over generic. "PII redaction in the constructor" beats "enterprise security". "50 evaluators, free, local" beats "comprehensive testing".

5. Anti-patterns (what NOT to do)¶

These are real mistakes the project has made and corrected. Don't repeat them.

6. File structure¶

7. When to update this file¶

Update docs/design-system.md whenever you:

1. Add a new design token to :root (color, spacing, easing, duration)
2. Create a new reusable component class (anything with .foo__* BEM-style children)
3. Establish a new animation pattern (new IntersectionObserver flow, new keyframe family)
4. Catch a new anti-pattern that someone might repeat
5. Add a banned word or rewrite rule to the voice section

Keep this file in sync with landing/index.html. The file is the documentation; the HTML is the implementation. If they diverge, the implementation wins and this file gets corrected.