Replace preview/ HTML with React-only docs (foundations + live charts)#2
Merged
Replace preview/ HTML with React-only docs (foundations + live charts)#2
Conversation
The /docs/<Name>/ pages already render every component live via the IIFE bundle + Babel-standalone runner. The 39 hand-written HTML "spec cards" under preview/ duplicated that for non-chart components and were a separate maintenance surface that drifted from the React truth. Killing them. Removed: - 38 preview/components-*.html, brand-*, colors-*, type-*, spacing-* files plus responsive-check.html and the shared _card.css. - renderBrandIndex() in build-docs.mjs and its writeFileSync block. - "Spec cards" entry from NAV_ITEMS, footer links, and the root index "Spec" section. - Dead .preview-frame CSS class (had no remaining usages). - preview/** copy step in build-site.mjs. - preview/** path filter in pages.yml and e2e.yml. Adjusted: - Chart-page placeholder note no longer links to the deleted spec card; says "Live render coming in the chart bundle pass." A follow-up commit replaces this placeholder with live rendering. - Sparkline.test.tsx comment no longer references preview cards. Verified: pnpm typecheck clean, 143/143 unit tests pass, build:site emits 58 component pages (51 core + 7 charts) across 9 categories. llms.txt unchanged (still 7.8 KB, charts section intact). No e2e tests reference /preview/ paths (#preview locator in smoke.spec.ts is the playground render pane). Foundations replacement (live-rendered design tokens) and live chart rendering are queued as separate commits in this PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces the hand-written brand/color/type/spacing spec cards with a single live-rendered Foundations page. Reads tokens from colors_and_type.css (CSS custom properties) and src/tokens.ts (type aliases) — no hex values are hardcoded in the generator. What the page renders: - Color · Brand red (10 swatches) - Color · Brand gray (10 swatches) - Accent · semantic (--accent, --accent-hover, --accent-press, --accent-soft, --accent-fg) - Surface & ink (theme-aware --bg-*, --fg-*, --border-* tokens that flip on data-theme switch) - Typography · families (--font-display, --font-sans, --font-mono) - Typography · scale (display, h1-h4, body, small, micro, code with live --fs/--lh/--ls values surfaced) - Spacing scale (--space-1 through --space-24, bars rendered at the literal pixel value) - Radii (--radius-xs through --radius-2xl + --radius-full) - Shadows (--shadow-xs/sm/md/lg) - Motion (--dur-* combined with --ease-*, animated boxes with Replay buttons) - TypeScript types (every type alias from src/tokens.ts with its union value, sourced from extractTypeAliases) Hex values are read at runtime via getComputedStyle so the page mirrors the stylesheet 1:1 and the surface-token chips re-resolve when the user toggles the theme. Wiring: - New renderFoundationsPage() in build-docs.mjs. - mkdir + writeFileSync in the exec block emits _site/docs/foundations/index.html. - Root index "Start here" grid promoted from 3 → 4 cards (Component reference, Foundations, Playground, Sample apps). - Docs index has a top-of-page Foundations callout linking to the new page. - renderSidebar prepends a Foundations entry, so component pages expose a quick way to jump to the tokens page. Verified: typecheck clean, 143/143 unit tests pass, build:site emits the new page (37.5 KB) plus the existing 58 component pages. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The chart docs pages were the last surface still falling back to a
static placeholder. They now render live in the browser, same as the
core component pages, completing the "React-only docs" goal of this
PR (no hand-written HTML left).
Approach — separate IIFE bundle:
- New scripts/bundle-entry-charts.ts re-exports `src/charts/*` plus
React + ReactDOM's createRoot. esbuild rolls it into
rcs-charts.iife.js as `window.RCSCharts`.
- build-site.mjs runs a second esbuild pass for this entry. Heavy
WebGL peer deps (@deck.gl/core, @deck.gl/layers, d3-force) are
marked --external; the chart components already have canvas2d /
SVG fallback paths when the WebGL handoff fails to import. That
keeps the chart bundle at ~794 KB instead of ~2.3 MB.
- The chart bundle ships its own React. Because chart demos render
standalone in their own createRoot — never nested inside the main
bundle's React tree — the "two React instances" footgun does not
apply, and they read theme via CSS custom properties (not
Context).
- esbuild also emits rcs-charts.iife.css (~1.6 KB) from the dynamic
`await import("uplot/dist/uPlot.min.css")` in Chart.tsx. The
chart-page <head> includes it.
build-docs.mjs:
- runner.js now exposes both `runExample` (uses window.RCS) and
`runChartExample` (uses window.RCSCharts), refactored to share a
`transformExample` helper. Each runner verifies its bundle is
loaded and surfaces the failure inline.
- renderComponentPage picks the right runner via a `runFn` variable
and conditionally injects `<script src="../bundle/rcs-charts.iife.js">`
+ the chart CSS into chart pages only.
- Static chart placeholder removed: chart pages now use the same
`<div class="demo-render">` and a hidden code panel as core pages.
- Dead .demo-render--static / .demo-static-note CSS rules dropped.
Verified: pnpm typecheck clean, Sparkline unit tests still pass,
pnpm build:site emits both bundles (rcs.iife.js 236 KB +
rcs-charts.iife.js 794 KB) and 58 component pages. Spot-checked
generated HTML: /docs/Chart/ pulls both bundles + the chart CSS and
calls runChartExample; /docs/Button/ pulls only the main bundle and
calls runExample.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Removes the last hand-written HTML surface from this repo. Every component, design token, and chart in the docs site is now driven by React + the IIFE bundle pipeline — no more dual maintenance between
preview/*.htmland the live/docs/<Component>/pages.Three commits, each independently reviewable:
refactor(docs): remove hand-written preview/ HTML surface— drops 39 files underpreview/(38 spec cards +_card.css+responsive-check.html), therenderBrandIndex()generator, the "Spec cards" nav entry / footer link / root-index section, the dead.preview-frameCSS, thepreview/**copy step inbuild-site.mjs, and thepreview/**path filters inpages.yml/e2e.yml.feat(docs): auto-generate /docs/foundations/ from design tokens— replaces the deleted brand/colors/type/spacing spec cards with a single live page at/docs/foundations/. Sections: Color (semantic + brand + accent + surface), Typography, Spacing, Radii, Shadows, Motion, plus a TypeScript-types reference. Swatches render viastyle="background:var(--token)"and a tiny inline script reads computed CSS values + watchesdata-themeondocumentElementso hex labels stay accurate across light/dark/system. No hex hardcoded —colors_and_type.cssandsrc/tokens.tsremain the only source of truth.feat(docs): live-render chart pages via separate rcs-charts bundle— chart pages were the last surface still showing a static placeholder. Newscripts/bundle-entry-charts.tsre-exportssrc/charts/*plus React +createRoot;build-site.mjsrolls it intorcs-charts.iife.js(~794 KB) aswindow.RCSCharts. Heavy WebGL peer deps (@deck.gl/core,@deck.gl/layers,d3-force) are externalized — chart components already have canvas2d / SVG fallback paths, which keeps the bundle from ballooning to ~2.3 MB. Runner gains arunChartExamplehelper; chart pages get<script src="../bundle/rcs-charts.iife.js">+ the chart CSS injected into<head>/<body>only when needed.Notes on the chart bundle
createRoot()and never nest inside the main bundle's React tree, so the "two React instances in one tree" footgun does not apply. They consume theme via CSS custom properties (readChartTheme()), not Context.rcs-charts.iife.css(~1.6 KB) for the dynamicawait import("uplot/dist/uPlot.min.css")inChart.tsx. Linked from chart pages only./docs/Button/, etc.) load only the main bundle — verified via grep on the generated HTML.Test plan
pnpm typecheckcleanpnpm run build:sitesucceeds; emits both bundles + foundations page + 58 component pages (51 core + 7 charts)_site/docs/Chart/index.htmlpulls bothrcs.iife.jsandrcs-charts.iife.js, includes the chart CSS, callsrunChartExample_site/docs/Button/index.htmlpulls onlyrcs.iife.js, callsrunExample(no chart bundle leakage)_site/docs/foundations/index.htmlexists, ~36 KB, 36 token-driven swatches viavar(--…)_site/viapnpm run serve:site, confirm a chart page renders live, foundations swatches reflect theme switchFiles removed
preview/_card.css,preview/responsive-check.html, and 37preview/*.htmlfiles (brand-, colors-, components-, type-, spacing-*).Files added
scripts/bundle-entry-charts.ts— chart-only IIFE entry_site/docs/foundations/index.html— generated, not committed (built by CI/Pages)Files modified
scripts/build-docs.mjs— drop preview generator, addrenderFoundationsPage(), dual-runner support, conditional chart-bundle script tagsscripts/build-site.mjs— second esbuild pass for chart bundle, droppreview/copy stepscripts/build-llms.mjs— already taught about charts subpath in a prior PRscripts/parse-source.mjs—parseChartsExports()helper (committed earlier).github/workflows/pages.yml,.github/workflows/e2e.yml— droppreview/**path filterstests/unit/Sparkline.test.tsx— docstring no longer references preview cards🤖 Generated with Claude Code