design: one preview page for the three IA change proposals - #435
Draft
eugenia-scandit wants to merge 3 commits into
Draft
design: one preview page for the three IA change proposals#435eugenia-scandit wants to merge 3 commits into
eugenia-scandit wants to merge 3 commits into
Conversation
A designer needs to see ProductChooser, IntentNavigator and ErrorCodeFinder to review them - they ARE their interactions, so a screenshot shows almost nothing and a .tsx shows less. The three live on three different refs, so there was no single thing to look at. This puts all three on one route, /component-preview, so the PR preview gives one URL in real site chrome: real tokens, real fonts, real spacing, and a working light/dark toggle. It is a src/pages route, NOT a docs page, so it is in no sidebar, no framework tree and no docs version, and it is noindex. Nothing here changes the documentation; the preview is removed when this PR closes. The components are copied unmodified, via `git checkout <ref> -- <paths>` rather than cherry-pick, so none of the unrelated work on those branches (a package-lock deletion, the SkillsCallout rewrite, Vale rules, docs-gate scripts) comes along: ProductChooser docs/product-chooser (PR #417) IntentNavigator docs/phase-e-intent-navigator (+ src/data/intents.json) ErrorCodeFinder 0fd2e0a4 on docs/sparkscan-ios-rewrite (+ src/data/troubleshooting-errors.json) ProductChooser normally reads the host page's frontmatter; the page passes the same shape by hand, copied verbatim from docs/sdks/ios/sparkscan/intro.md, and renders it three times - SparkScan on iOS, the same product on Web to show the availability chips and outgoing links following the reader's framework, and MatrixScan Pick for a different block length. ErrorCodeFinder still carries its SAMPLE- placeholder entries. The page says so in a callout, so the reviewer looks at layout and interaction rather than wording. Verified: tsc --noEmit clean, and `docusaurus build` succeeds with the page rendering all three components server-side. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
The shipped component was a reduced port of the demo: a flat taxonomy with no
platform picker, no steps, no expert shortcut, no availability filtering and no
badges. The screenshots of the demo are the intended design, so this brings the
whole thing across, grouped exactly as the demo grouped it:
1. platform bar 11 platforms, remembered between visits
2. expert shortcut "Already know your product? Jump straight in ->"
3. three numbered steps with progressive disclosure, plus "start over"
4. "Why this matters" docs <-> signup parity note
5. the Linux caveat, and a provenance footer
Also adds the 5th barcode task the demo has and the component lacked - "Show
custom info on each item" -> MatrixScan AR - plus Scandit Express on the goals
where the demo offers it, and delivery badges (ready-made UI / full-control SDK
/ no code / no code (web)).
Styles are now a module SCSS in the house idiom: `@import '../../css/_mixins'`,
a :root block of component tokens, nesting, and the `dark`/`transition`/
`flex-row` mixins - matching src/css/components/*.scss and the existing
card.module.scss. The demo's private hex palette is gone; every colour is a
token custom.scss already defines, and those tokens ALREADY flip for dark
(--light-black, --light-blue-100, --light-gray-100, --light-blue-60,
--nav-border, --frameworksBgLight), so both themes come for free. Only the four
badges needed explicit dark values, because the soft green/blue tokens are not
among the ones redeclared for dark.
Three things done differently from the demo, deliberately:
- Availability is COMPUTED from products.json, not copied. The demo hard-coded a
PROD table "derived verbatim from products.json"; a copy drifts the moment the
registry changes. Only what is genuinely absent from that file is declared
here: the hosted products, and Linux.
- Disclosure is CSS, not conditional rendering. The server already renders the
stepped UI, so there is no flash of a different layout before hydration, and
the expert grid stays mounted-but-hidden so every product link is in the
static HTML for search and the retrieval layer.
- The demo's Linux note never appeared: it set `el("linuxNote").hidden` on an
element that does not exist, throwing a TypeError on init and on every
platform change. Here it is a conditional render, so it works.
start.mdx takes the demo's headline and framing copy. The "already know your
product" shortcut now lives in the component, where it belongs, rather than as a
page-level tip.
Verified: tsc --noEmit clean; docusaurus build succeeds; the built /start HTML
contains the platform bar, the shortcut, step 1, the parity note and the product
links.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Four fixes from review.
1. THE EXPERT PANEL WAS OPEN BY DEFAULT - a CSS bug, not a state bug.
`.expertHidden { display: none }` was declared BEFORE `.expert { display:
grid }`, and both are one class deep, so the later display:grid won on source
order and the panel rendered open. It is now `.expert.expertHidden`,
declared after `.expert`, so it cannot lose again. Verified in the compiled
CSS, not just the source.
2. The intent navigator is no longer rendered on /component-preview. It was
already gone from the source in the previous commit; this keeps it that way
and leaves /start as its only home.
3. The product chooser looked wrong on /component-preview for the same reason
the navigator did: markdown.scss scopes its rules to
`#__docusaurus .theme-doc-markdown.markdown` - BOTH classes on one element -
and a src/pages route has neither. The chooser and the finder are now each
wrapped in that container, so they render with docs typography exactly as on
their real pages.
4. The finder is back on the preview page, with the "Still stuck?" support link
and the per-page evaluator beneath it, as it had originally. The evaluator is
PageFeedback, brought over from feat/docs-feedback-widget together with the
DocItem/Footer wrap swizzle that puts it on every real docs page. It depends
only on SkillsCallout/analytics.ts, which is already on main, so none of that
branch's SkillsCallout rewrite came with it. PageFeedback is BrowserOnly, so
it appears in the browser rather than in the static HTML - on a src/pages
route it has to be placed by hand, which is why it is explicit here.
Also removes the "What we would value your view on" list from the preview page.
Verified: tsc --noEmit clean; docusaurus build succeeds; /component-preview
contains the finder, "Still stuck?", the support link and the chooser, and the
feedback widget is in the client bundle.
Co-Authored-By: Claude Opus 5 (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.
What this is
A design-review surface, not documentation. It puts the three IA change proposals on one route so a designer can review them from a single link, in real site chrome — real tokens, real fonts, real spacing, and a working light/dark toggle.
Preview:
/component-preview(link appears in the preview comment below once the workflow finishes)Why
All three components are their interactions — paste-to-filter matching, a three-step narrowing flow, framework-aware links. A screenshot shows almost none of that and a
.tsxshows less. And because they live on three different refs, there was no single thing to look at.Nothing here changes the documentation
src/pagesroute, so it appears in no sidebar, no framework tree, no docs versionnoindex, nofollowgh-pagesunder/pr-preview/, which is a separate host fromdocs.scandit.comand holds nothing elsepr-preview-actiondeletes the preview when this PR closesWhat was copied, and how
Via
git checkout <ref> -- <paths>rather than cherry-pick, so none of the unrelated work on those branches (apackage-lockdeletion, the SkillsCallout rewrite, Vale rules, docs-gate scripts) came along. The components are unmodified.ProductChooserdocs/product-chooser(#417)IntentNavigator+src/data/intents.jsondocs/phase-e-intent-navigatorErrorCodeFinder+src/data/troubleshooting-errors.json0fd2e0a4ondocs/sparkscan-ios-rewriteProductChoosernormally reads its host page's frontmatter; the page passes the same shape by hand, copied verbatim fromdocs/sdks/ios/sparkscan/intro.md. It renders three times — SparkScan on iOS, the same product on Web (so the availability chips and outgoing links visibly follow the reader's framework), and MatrixScan Pick for a different block length.Known, and deliberate
ErrorCodeFinderstill carries itsSAMPLE-placeholder entries. The page flags this in a callout so the reviewer assesses layout and interaction rather than wording. The verified catalogue exists (a 1,385-word support article) and will replace them.Verification
tsc --noEmitcleandocusaurus buildsucceeds, with the page rendering all three components server-side (3 chooser instances, the finder, and the navigator all present in the static HTML)🤖 Generated with Claude Code