Sphere Design

Online sync

On every session start that activates this skill, fetch version.json. If remote.version > local.version, fetch full manifest.json and changelog.md, surface the diff to the user, and replace local manifest on user OK. Cache-Control: short (5min) on version.json, long (immutable per version) on /v/<version>/manifest.json.

Offline: If version_check_endpoint is unreachable (no network, dev wifi down), continue with local manifest and warn 'sphere-design: offline — using cached vX.Y.Z'.

Color tokens

Font tokens

Forbidden: Playfair Display · DM Serif Display · Inter · Roboto · Open Sans

Conversion funnel

Every Sphere page follows a 7-step trajectory: Hook → Trust → Value → Proof → Process → Social → Conversion. Skip steps at your peril — readers fall out at each gap.

1. 1Hook

   value prop in <12 words + primary CTA

   components: SolutionHero, ServiceHero, IndustryHero, SphereIQHero, SphereHero

   ⚠ headline that describes WHO YOU ARE instead of WHAT THE READER GETS

2. 2Trust

   social proof via real client logos

   components: TrustedBy

   ⚠ no logo strip, OR generic stock imagery instead of real clients

3. 3Value

   3-6 concrete value propositions

   components: ValueProposition, Differentiators, BenefitsList, WhatWeDeliver

   ⚠ 9+ value props in one grid (decision paralysis); features instead of benefits

4. 4Proof

   real outcomes with real numbers and named clients

   components: CaseStudiesGrid, ScrollCases, ImpactMetrics, NumbersSection

   ⚠ stock-photo case studies; vanity metrics with no context; 'enterprise client' instead of named brand

5. 5Process

   how engagement works — removes fear-of-unknown

   components: ProcessSteps, StepsTimeline

   ⚠ skipping this — readers stall when they don't know what happens after they click CTA

6. 6Social

   named-person testimonials with role + company

   components: TestimonialsCarousel, VideoTestimonials

   ⚠ first-name-only quotes; no company; no role; star ratings without source

7. 7Conversion

   single low-friction CTA matching hero CTA

   components: ContactForm, HubspotForm, GetStartedBanner

   ⚠ multiple competing CTAs; long form fields above ask; CTA href that doesn't match hero

Scannability

A Sphere page must be readable as a scrolled outline of headings + bolded key phrases + scannable tiles. A user who reads NOTHING but the H1, H2s, and tile titles must still understand the value prop and know how to convert.

• Hero primary CTA + final CTA must agree (same destination — usually #contact-form). Never split user attention.
• No competing CTAs within 1 viewport. Pick one primary action per scroll-screen.
• Heading hierarchy must scan: 1 H1, 5-8 H2s, H3s only inside complex sections.
• Every section must answer 'what does this give me?' in its H2.
• If a page has no clear next step at the bottom, it's broken — add GetStartedBanner.
• Tile/card grids: titles must be 2-6 words. If your tiles need 10-word titles, the tiles are wrong — use a list with sub-headings instead.
• Body paragraphs: max 4 lines on desktop. If you need more, split into a list or sub-section.
• Bold the noun-phrase that converts. One bold phrase per paragraph max.
• Trust signals (TrustedBy, NumbersSection, Testimonials) should appear within first 2 scrolls — not buried at the bottom.

Component catalog

Top reusables grouped by role. Each entry documents adoption, suitable content, content-fit limits, and overflow strategy. Never stretch a component past its limits — pick a different component instead.

_additional: 120+ more reusables exist (TwoColumns, UseCases, WhatWeDoTabs, RoiCalculator, EuAiActRiskGauge, ManagedServicesSection, ModernizeStacks, NumberedBenefitsSplit, OutcomeGoals, PodPackages, StrategySection, TechPartners, TechStackTable, ValueProposition, WebinarLeadSection, WhatWeDeliver, WhitepaperDownloadSection, ...). Before inlining anything, grep `src/components/` for matching shapes. Long-tail content-fit docs land in v1.2.

Page recipes

Canonical section compositions per page type. Each section in the order maps to a funnel step (see funnel_mapping).

Reality-check pass

Every section choice is reality-checked against (a) content fit, (b) scannability, (c) funnel role. If the content exceeds the component's design intent, the answer is a DIFFERENT component, not stretching the current one.

• content-fit — for each section, count the items/words/chars in your content; cross-check against the component's content_limits; if you're over the ideal, list 2 alternative components that fit better and recommend the best.
• scannability — after composing the page, list the H1 + all H2s + all tile titles. If that outline reads as gibberish or a non-sequitur, the page fails — redesign before shipping.
• funnel-completeness — map every section to a funnel step (1-7). Steps missing from your page are bounce risks — confirm with user before omitting.
• duplicate-purpose — if two consecutive sections serve the same funnel step (e.g. two 'value' grids back-to-back), one is redundant — collapse.
• CTA-coherence — hero CTA destination MUST match final CTA destination. Mid-page CTAs (CtaBanner) MUST match too. Inconsistent CTAs split user intent.

Changelog

# sphere-design — changelog

## 1.3.1 — 2026-05-23

**Adds 5 more tripwires lifted from the same /platforms/acumatica session that shipped v1.3.0.** Twice in that session I shipped violations of rules I had JUST added to the manifest — `lora-highlight-no-stranded-article` on the 'An / alternate assessment' H2 (rule existed, ship still violated it), and `case-studies-default-scrollcases` on the ScrollCases call where I passed industry-icon PNGs as the per-story image (rule said "pass real case-study heroes, not industry icons"; I passed industry icons). The skill works only if rules are re-audited against the just-written code, not just dropped in the manifest. Hence the new meta-tripwire.

- **`re-audit-after-new-rule-shipped`** — META: when a new tripwire is added mid-session, the last ~100 lines of code/copy I wrote must be re-audited against the new rule BEFORE declaring done. Adding a rule + shipping a violation of it in the same session = the rule was theatre, not enforcement.
- **`whatwedeliver-blue-band-both-white`** — extends `dark-text-on-blue-default`. On default-blue `<WhatWeDeliver>`, pass `headingHighlightColor="#ffffff"`. The default highlight is brand-blue `#1677ff` — on a brand-blue band the italic accent is INVISIBLE. Both halves of the double-font heading must be explicitly white on blue.
- **`hero-tiles-frosted-glass`** — `SolutionHero` `tiles` render as frosted glass over the hero image. Canonical class set: `border border-white/10 bg-white/5 backdrop-blur-3xl shadow-2xl`. NOT `bg-black/40 backdrop-blur-md` (dark card, weak blur, no glass feel). Andrii flagged 'much stronger' twice — `3xl` = 64px is the canonical strength. Enforced at the SolutionHero component level since this release.
- **`case-studies-real-hero-via-payload-api`** — extends `case-studies-default-scrollcases`. ScrollCases `image` per story MUST come from each case study's actual `heroImage.url` in the Payload `case_studies` collection. Fetch with `curl 'http://localhost:3001/api/case-studies?where%5Bslug%5D%5Bequals%5D=<slug>&depth=2&limit=1'`. NEVER use industry-icon PNGs or guess the image filename from the slug.
- **`form-id-override-needs-explicit-ask`** — extends `contact-form-canonical`. Do NOT override `hubspotPortalId` / `hubspotFormId` on `<ContactForm>` unless the user EXPLICITLY asked. The component defaults (`5257433` / `26e96821-…`, the inline-HTML generic Sphere contact form) are the right CRM destination for most pages. Lifting per-page form IDs from WP migration is the wrong default.

**Schema bump:** none (additive — `nonsense_check.tripwires` array extended by 5 entries).

## 1.3.0 — 2026-05-23

**Adds 7 execution tripwires** lifted from the /platforms/acumatica rebuild session. Every rule traces to a specific repeat-failure Andrii flagged that day; each one is now a first-class entry in `nonsense_check.tripwires` so the next agent (or me, next session) catches them before shipping.

- **`hero-must-show-clients`** — first viewport must surface BOTH the hero message and client logos. Default pattern: `SolutionHero` with `compact: true` + `tiles` (3-4 credibility chips) immediately followed by `<TrustedBy/>`. A tall full-bleed SolutionHero with no logos visible above the first scroll = bounce risk.
- **`contrast-check`** — audit every (text color × surface color) pair before shipping. Specifically watch white-text components (e.g. `ValueProposition` default `text-white` headingPrefix) on light backgrounds: the heading goes invisible. Re-check after every `backgroundColor` override on a reusable component.
- **`no-png-icons-as-background`** — `WhatWeDeliver` with `image` renders the image as a FULL-BLEED tile background with a darkening gradient overlay. Built for photographic case-card imagery, NOT for icon PNGs. For icon tiles use `Differentiators` with `icon` as a design-system key.
- **`dark-text-on-blue-default`** — `WhatWeDeliver` defaults to `bg-blue-600`. Passing `textColor: '#1f2025'` (dark) without overriding `backgroundColor` produces black-on-blue heading. Correct pattern: no `textColor`, white double-font heading via `headingStart` + `headingHighlight` (Lora italic).
- **`case-studies-default-scrollcases`** — `ScrollCases` (May 2026) is the canonical case-studies component for new pages — categories filter, per-story imagery. `CaseStudiesGrid` is the legacy migrated-WP block; only use when preserving an exact 1:1 WP port.
- **`lora-highlight-no-stranded-article`** — Lora italic highlight must be a meaningful 2+ word phrase. Never leave articles ('An', 'The'), prepositions ('Of', 'With'), or conjunctions ('And') OUTSIDE the italic span. Either include them in the italic or restructure.
- **`contact-form-canonical`** — the reusable `<ContactForm>` component is the default site contact band. Custom inline HubSpot sections are forbidden as the page's main conversion unless the user explicitly asks for a one-off. ContactForm supports `sectionId` + `hubspotPortalId` + `hubspotFormId` overrides — keep the canonical design, change only what's needed.

**Schema bump:** none (additive — `nonsense_check.tripwires` array extended by 7 entries; everything else unchanged).

## 1.2.0 — 2026-05-22

**Adds:**

- **Nonsense-check pass.** New top-level `nonsense_check` with 14 tripwires that fire on copy that reads fine but says nothing — meaningless filler, unsourced stats, canonical-drift numbers, title/content mismatch, broken promises, audience-mismatched jargon, duplicate ideas, unsupported superlatives, vague verbs ("help / leverage / enable / empower / utilize"), undefined acronyms, headlines that talk about us instead of the reader, filler sentences, dead CTAs, trademark misuse. Runs after content provenance, before final preflight.
- **Typography best practices.** New top-level `typography_best_practices`: full weight hierarchy (300/400/500/600/700/900 with roles), line-heights per use, letter-spacing per scale, max line widths (12-20ch for H1, 65ch for body, 6 words for tile titles), responsive scale ratios, italic Lora rules ("one accent per heading, value-noun only"), 8 anti-patterns.
- **Font tokens with full install spec.** Each font now documents weights_used, styles_used, source URL, Next.js install snippet, HTML-mockup install snippet (Google Fonts `<link>` for offline drafts). DM Sans: weights 300/400/500/700/900. Lora: 400/600/700 with italic style (italic 600 + 700 are the only ones actually used in headings).
- **Geist Mono removed.** Not used anywhere in user-facing Sphere surfaces. Loaded in layout but unused; manifest now declares the design system as DM Sans + Lora only.
- **Preflight expanded.** Adds nonsense-check pass + typography spot-check (one Lora accent per heading, body ≥ 16px, bolded phrase ≤ 3 words).

**Schema bump:** `meta.schema_version` 2 → 3 (added `typography_best_practices`, `nonsense_check` top-level keys; expanded `tokens.fonts` with weights/styles/install fields; dropped `tokens.fonts.mono`).

## 1.1.0 — 2026-05-22

**Adds:**

- **Online manifest sync.** Manifest now hosted at `https://www.sphereinc.com/dev/skills/sphere-design/`. Every session activation checks `version.json`; if newer, fetches updated manifest + surfaces changelog before consumers continue. Falls back to cached manifest on network failure.
- **Per-component content-fit limits.** Each component in the catalog now documents `suitable_for`, `content_limits` (min/max/ideal item counts, character bounds, requires), and `overflow_strategy` (which alternative component to pick when content exceeds intent). Components stretched past their limits are forbidden; the skill recommends a better-fit alternative instead.
- **Scannability section.** Page-level rules ensuring H1 + H2s + tile titles read as a scannable outline. Includes F-pattern guidance, max paragraph length, single bold per paragraph, trust-signal placement.
- **7-step conversion funnel.** Every page maps to Hook → Trust → Value → Proof → Process → Social → Conversion. Section recipes now annotated with `funnel_mapping`. Missing steps surfaced as bounce risks.
- **Reality-check pass.** Five whole-page checks before JSX: content-fit, scannability, funnel-completeness, duplicate-purpose, CTA-coherence.
- **More component coverage.** Added `_proof_metrics`, `_video`, `_meta_blocks` groupings. Documented ImpactMetrics, IntroMetricsSection, VideoTestimonials, VideoCta, StepsTimeline content-fit.
- **`reality_check` top-level key.** Codifies the five checks and the principle "stretching a component past its design intent = pick a different component".
- **`scannability_audit`** notes on existing recipes (`about` and `testimonials`) — flags known visual-density issues from the 2026-05-22 rebuild as v1.2 candidates.

**Schema bump:** `meta.schema_version` 1 → 2 (added `online`, `scannability`, `conversion_funnel`, `reality_check` top-level keys; added per-component `suitable_for` / `content_limits` / `overflow_strategy`).

**Distribution change:** primary distribution flips from "manual cp -R" to "online sync from canonical URL". The Sphere Partners site is the source of truth for the manifest, version blob, and changelog.

## 1.0.0 — 2026-05-22

Initial release. Baked from `SphereSoftware/SPW` @ `6c09a68`.

**Scope:**

- Frozen token palette (brand-blue `#1677ff`, brand-cyan `#16e3ff`, dark `#1f2025`, brand-blue-soft `#eaf2ff`, slate scale).
- Frozen font stack (DM Sans / Lora / Geist Mono via `next/font`).
- Forbidden-color list (`#3B82F6`, `#185FA5`, `#0A1628`, `#7ab3ff` — common drift to brand-blue).
- Forbidden-font list (Playfair Display, DM Serif Display, Inter — common drift to Lora).
- Top-30 component catalog with adoption counts + role + use.
- Five canonical page recipes (`service_landing`, `about`, `testimonials`, `industry_page`, `solution_landing`, `blog_post`).
- `SPHERE_NUMBERS_STATS` canonical facts + observed mockup-extras with usage rule.
- Content rules (preserve verbatim, no invented quotes, monday voice, changelog required before push).
- Preflight checklist (tsc → curl-verify → restart-warning for `src/data/*` → consumer-audit for shared components).