Skip to content

docs: align styler page with measured 2.6.x numbers (drop stale 10.3 KB / marketing claims)#16

Merged
vitbokisch merged 1 commit into
mainfrom
docs/2.6.x-objective-claims
May 21, 2026
Merged

docs: align styler page with measured 2.6.x numbers (drop stale 10.3 KB / marketing claims)#16
vitbokisch merged 1 commit into
mainfrom
docs/2.6.x-objective-claims

Conversation

@vitbokisch

Copy link
Copy Markdown
Member

Why

The styler docs had several stale or marketing-shaped claims that didn't match measured reality:

  • Bundle size was reported as ~10.3 KB gzipped (and ~10.34 KB in another spot) across 4+ pages. A fresh build of the current 2.6.x source is 4.82 KB gzipped / 13.65 KB minified / 33.97 KB unminified.
  • The "45% smaller than sc / 40% smaller than emotion" headline was computed against that stale size.
  • The micro-benchmark table claiming "2.8–1034x faster" came from an older vitest-bench iteration that's no longer the canonical suite.

What this PR does

  • Bundle: replaces the stale claim everywhere it appears (content/docs/index.mdx, connectors/index.mdx, core/index.mdx, styler/api.mdx, styler/index.mdx) with the fresh 4.82 KB gzipped number.

  • Bundle table: keeps the competitor comparison but as raw KB only (no "X% smaller" framing).

  • Competitive bench: replaces the old micro-benchmark table with the actual css-perf.bench.tsx numbers — 3-run medians on bun 1.3.13 / react 19.2.6, equivalent work (sc wrapped in ServerStyleSheet):

    Scenario styler ops/s emotion sc 6
    SSR static (500 renders) 719 335 210
    SSR dynamic (500 renders) 434 307 202
    SSR themed (500 renders) 363 286 184
    CSR mount (100 mounts) 13912 13817 13702
    CSR update (100 updates) 13108 13032 13239
    CSR many (50 distinct comps) 18933 18302 5705

    Plus a "vs best competitor" column so readers can see the gaps at a glance.

  • Helper-level microbench: adds a short section with the measured helper-vs-helper deltas from perf-audit-bench.tsx (_staticResolved +149%, hashUpdate +46% long / +15% short, HTML_PROPS in obj +19%) with the honest caveat that they don't move the headline bench because the headline bench doesn't exercise those paths.

  • CI-gated framing: notes that the bench workflow fails on >10% regression vs main on the same runner (which caught and forced revert of one PR #253 candidate).

  • Drops "marketing-shaped" superlatives ("blazing fast", "high-performance" descriptor in the table) in favour of measured statements.

Test plan

  • bun run build — Next.js docs site builds (67 static pages) without errors
  • No lint changes
  • No broken links (only existing in-repo links updated)

Companion to the perf work shipped in ui-system #233, #242, #244-251, #253, #254.

🤖 Generated with Claude Code

Stale claims fixed:
- bundle: docs said "~10.3 KB gzipped" everywhere; fresh build is 4.82 KB
  gzipped / 13.65 KB minified / 33.97 KB unminified
- "45% smaller than sc / 40% smaller than emotion" headline removed; the
  table now shows raw KB so readers compute their own
- micro-benchmark table (css() creation 25.2M, "2.8–1034x faster",
  etc.) removed — those numbers came from an older vitest-bench iteration
  that's no longer the canonical suite

Replaced with what's actually measured today:
- Bundle-size table with fresh build numbers + competitor snapshot
- Competitive bench (css-perf.bench.tsx, 3-run medians, bun 1.3.13 /
  react 19.2.6, equivalent work — sc wrapped in ServerStyleSheet so all
  three serialize CSS): styler 2.14× emotion on ssr-static, 1.41× on
  ssr-dynamic, 3.32× sc on csr-many, all 3 within ~1% on csr-mount/update
- Helper-level microbench (perf-audit-bench.tsx): _staticResolved +149%
  on nested-static, hashUpdate +46% on long CSS, HTML_PROPS +19% on
  lookup mix
- "CI-gated perf" framing — bench workflow fails on >10% regression vs
  main on the same runner (caught and forced revert of one recent
  normalizeCSS slice-batch change)

Other pages: bundle-size mentions updated everywhere they reference
styler (index, connectors, core, api).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@vitbokisch vitbokisch merged commit 3c2ef7d into main May 21, 2026
1 check passed
@vitbokisch vitbokisch deleted the docs/2.6.x-objective-claims branch May 21, 2026 11:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant