nanaselect

Appearance

NanaSelect design brief — hand-off document ​

This is the self-contained hand-off (issue #263): paste or upload this single document, plus the attached tokens.json, to a design-generating AI. It condenses the full package (docs/design/*.md); the source files remain the reference for humans. Version: 2026-07-02, package v1.

1. What you are designing ​

NanaSelect is a standalone product-selection web app that guides architects, builders, and homeowners to the right-sized NanaWall system (opening glass walls; 24 systems) — not the most expensive one that clears a filter. The core failure it fixes: an architect specifies an over-engineered NW Acoustical 645 when a cheaper NW Aluminum 640 — or a far cheaper SL45 — meets the actual requirement, and the over-spec gets value-engineered out at bid (often to a competitor). The app asks one project question at a time, educates at each decision, converges on a recommendation with visible reasoning, actively surfaces cheaper alternatives that suffice, and hands off into nanawall.com's configurator (where cost is calculated) and product resources.

Your deliverable is defined in §8. The one-sentence aesthetic: calm, confident, architectural — a well-set technical publication, not a marketing site. Photography and educational content carry the interest; chrome stays quiet.

2. Design principles (ordered; lower number wins conflicts) ​

  1. Educate through every decision. One decision per screen. The factor's trade-off education renders inline above the options as first-class reading content (real typographic hierarchy, never a tooltip, never collapsed, never fine print). Options may carry a one-line "what this means."
  2. Right-size, don't up-sell. The cheaper-alternative call-out is the product's hero element: card-level prominence, affirmative success treatment (soft green fill + border — never warning yellow, never muted gray), its own action, phrased as good news. Tiers (Budget / Mid / Premium / Ultra) are equal-weight fit descriptors — no gilding "Ultra", no graying "Budget". The recommendation always shows why (which answers drove it). Coverage warnings are calm verification prompts, not red alarms.
  3. Guide, don't just filter. Linear stepped progression; "Step N of M" + progress indicator always visible; one primary forward action per screen (final step: See results, never Next); never show live result counts during the flow.
  4. Standalone, but connected. Brand continuity with nanawall.com through tokens (type, teal, neutrals) — not by cloning its chrome. Configurator/ resources links styled as journey continuations ("See cost in the configurator"), not external-link afterthoughts.
  5. Meet the expert where they are. Persona self-selection by card on the home page; /compare is deliberately denser (the expert's room); right-sizing nudges still appear on fast paths.

Admin surfaces are exempt from 1–3: dense, fast, utilitarian.

3. Brand tokens — the only source of brand values ​

  • Attached: tokens.json — the full 3-tier NanaWall token tree extracted from production nanawall.com (@nanawallweb/design-tokens v1.0.0): color scales (teal, gray, red, green), typography, spacing, borders, shadows, breakpoints, animation, and per-component context tokens.
  • Key brand facts: fonts 'Source Sans Pro', sans-serif + 'Source Serif Pro', serif; body 19px/29px; type scale 19–31px; weights 300/400/600; brand teal (color.brand.primary = teal-300, active = teal-500); headings gray-14 on white; house motion 0.15s ease-in-out.
  • Never invent a brand value; never eyedropper nanawall.com. If you need a token that doesn't exist (see §3.1), propose a value harmonized with the attached scales and list it explicitly in your delivery notes as a proposed token.

3.1 Delivery contract: the 40 --ns-* theme tokens ​

The app is themed: your design must be expressible as values for these 40 custom properties plus markup that references only them. Hardcoded hex/font/radius literals fail the app's build.

  • Surfaces: --ns-color-bg, -surface, -surface-muted, -surface-inset, -surface-inverse, -surface-inverse-hover
  • Text: --ns-color-text, -text-muted, -text-subtle, -text-faint, -text-heading, -text-inverse
  • Borders: --ns-color-border, -border-subtle
  • Accent: --ns-color-accent, -accent-hover, -accent-strong, -accent-soft, -on-accent
  • States: --ns-color-danger/-soft/-border, --ns-color-success/-soft/-border, --ns-color-warning/-soft/-border
  • Misc: --ns-color-focus, --ns-color-overlay
  • Fonts: --ns-font-sans, --ns-font-serif, --ns-font-mono, --ns-font-size-base
  • Radii: --ns-radius-sm, --ns-radius-md, --ns-radius-lg, --ns-radius-full
  • Shadows: --ns-shadow-sm, --ns-shadow-md

Where a token has a brand source in tokens.json, use it (e.g. accent ← color.brand.primary, success-soft ← color.background.highlight). Known gaps with no extracted source (warning trio, success border, mono stack, stepper/table specifics): propose values per the rule above.

4. Screens (design priorities: P1 first and best) ​

Public — all five principles apply:

  • / Home (P1). Sections: resume banner (returning users; in-progress and completed variants) · hero + single primary CTA into /select · persona track cards (architect/pro, builder, homeowner) · how-it-works (3 steps) · right-sizing story (the 645→640→SL45 example) · showcase imagery (≤3 photos) · compare entry. No lead-capture form, ever. Static-first: every dynamic section may be absent (no tracks, no session, no images) and the page must still look designed.
  • /select Guided stepper (P1 — the signature screen). One factor per step; 14 factors today, design for 5–20. Anatomy: progress ("Step N of M" + indicator) · factor name + description · education callout · radio-group options with optional "what this means" lines · Previous (not on step 1) / Next (final: See results). States: unselected default, clear selected state (re-click clears — selection reads as a toggle), resume-offer card (non-modal), education-less factor renders with no gap.
  • /select Results (P1 — the payoff). Recommended system (photo, name, tier) · rationale with equal visual weight · the cheaper-alternative nudge (§2.2) · shortlist of close matches · actions: compare shortlist, configurator deep-link, resources. States: coverage warning (calm), empty (honest dead-end: which answers to relax + advisor hand-off), brief loading skeleton.
  • /select/<track> Track entry (P2). Same stepper + a persona header.
  • /compare Comparison matrix (P2 — expert register, denser). System picker (any of the 24) · sticky header (names/photos) + sticky first column (attributes) · ~60 attribute rows grouped by category · difference highlighting · nudge attachable to a column · "??" cells as quiet em-dashes · mobile: horizontal scroll, first column pinned. Empty state = inviting picker, not a blank table.

Admin (/admin/*, P3) — separate dense register, separately themed. Define the patterns: list data-table (sortable, row actions, pagination, empty-with-create, bulk select), detail form (persistent labels, inline validation, save feedback, destructive confirm), audit-trail rows (mono timestamps), retired/draft visual muting. Sections: systems, attributes, factors, right-sizing rules, tracks, tiers, media, corpus, drupal-sync, eloqua, audit, themes.

5. Components (behavioral requirements condensed) ​

  • Buttons: primary (one per screen) / secondary / link / destructive (admin); hover + focus-visible ring (--ns-color-focus) + active + disabled; ≥44px touch targets.
  • Stepper progress: text + visual track/fill; scales 5–20 steps; announces N-of-M to screen readers.
  • Option group: radio semantics; selected state obvious beyond the dot (fill/border shift).
  • Right-sizing nudge: success trio card — cheaper system name, what it still satisfies, own action; works on results page and attached to a compare column.
  • Coverage warning: warning trio, icon + text + "verify with an advisor"; never blocks.
  • Cards: track cards (whole-card click, equal heights, survives long copy); system cards (must render with no photo — collapse the media slot, no gray placeholder).
  • Comparison table: as in §4; numeric/technical values may use --ns-font-mono.
  • Media: rendition widths thumb 160 / card 480 / hero 1200 / full 2000; landscape-biased containers with center-weighted cover cropping; galleries keyboard-navigable; video posters, no autoplay-with-sound.
  • Resume banner: non-modal card; resume + start-fresh + dismiss; must not push the hero below the fold on mobile.
  • Overlays: admin only (--ns-color-overlay scrim, focus trap, Escape). Public surfaces use no modals.
  • Motion: default 0.15s ease-in-out; everything respects prefers-reduced-motion.

6. Art direction & content ​

  • Imagery: real Drupal-sourced architectural photography of installations (wide openings, indoor–outdoor thresholds, daylight) — no stock, no generated images, no white-background renders, no heavy grading/duotones. Text over photos only with a measured scrim. Every layout degrades to zero images gracefully.
  • Voice: knowledgeable advisor, plain language, explains at point of use ("STC 45 means normal speech next door is inaudible"). Banned: urgency, superlative stacking, exclamation points, framing expensive as safe. Buttons are specific verbs ("Compare these 3"), never "Submit"/"Learn more". Honest about data gaps.
  • Real content only — no lorem ipsum. Use the real systems (SL45, SL60, SL70, SL73, NW Aluminum 640/840, NW Acoustical 545/645, NW Reinforced 647/847, NW Clad 740, NW Wood 540, NW MultiSlide 630, HSW60/66/75, WD65, PrivaSEE, ClimaCLEAR, …), the real factors (interior/exterior, geography, climate, residential/commercial, ADA compliance, interior + exterior acoustic control, durability, opening shape, material & finish, stacking, panel sizes, sill depth & floor type, structural requirements), the real nudge example (NW Acoustical 645 → NW Aluminum 640 → SL45), and the real tiers. If you need data the brief doesn't carry, say so in delivery notes — don't invent specs.

7. Hard constraints ​

  • Stack: Svelte 5 + Tailwind v4 (CSS-first; tokens map through a @theme inline block) on Cloudflare Workers (SSR).
  • No external runtime dependencies: no font/icon/CSS CDNs, no component libraries, no runtime CSS-in-JS. Fonts must be self-hostable.
  • Performance: public flow stays light; images only via the rendition pipeline, lazy below the fold; server-rendered pages readable before JS.
  • Accessibility — WCAG 2.1 AA: contrast ≥4.5:1 text / 3:1 large+UI (verify your token pairs numerically); full keyboard operability with visible focus; real semantics (radio groups, N-of-M progress announcements, landmarks, alt text); no meaning by color alone (state colors pair with icon/text); ≥44×44px touch targets; reduced-motion respected.
  • Responsive, mobile-first. Breakpoints 480 / 768 / 1024 / 1280 — these are the app's breakpoints and deliberately override the (marketing-site) breakpoint tokens inside tokens.json. The P1 flow must be excellent on a phone; compare may be best on desktop but usable on mobile.
    • Amendment (2026-07) — per the public-experience direction §3, the list gains 1536+ behavior (1920 reference canvas). Above 1280 the active layout file governs width via --ns-layout-max-width: Editorial 90rem (1440) with full-bleed hero/band moments, Standard 72rem (1152), Spotlight a ~60rem reading column paired with full-bleed imagery; the compare matrix may widen to 96rem when 4 systems are chosen. Display type and section rhythm scale fluidly via clamp() ramps across 1024→1920 rather than stepping at a breakpoint, and the stepper keeps its focused ~44rem question column at every width. This is a deliberate, recorded deviation from the original four-stop list — not drift.

8. Deliverables ​

  1. A theme: values for all 40 --ns-* tokens (§3.1) as a CSS custom- property block, brand-sourced where possible, proposed-and-flagged where not.
  2. Screen designs (HTML/CSS mocks or high-fidelity descriptions) for, at minimum: home, one stepper step (use the real "Interior acoustic control" factor with education), the results view with the 645→640→SL45 nudge, and the compare view with 3 systems — using only var(--ns-*) references and real content.
  3. Delivery notes: proposed tokens beyond the 40 (with rationale), any content the brief lacked, and any place you deviated from a principle and why.

9. How your design will be judged ​

Scored 1–5 per heuristic; average <4, or ❤️ on H1–H3, is rejected regardless of aesthetics.

  • H1 Nudge test — the cheaper-alternative call-out reads as first-class good news (success treatment, prominence, own action), not fine print or an upsell banner.
  • H2 One decision — stepper mock has exactly one factor, education visible without interaction, one primary action, visible progress; no result counts.
  • H3 Token fidelity — shippable as a theme: every value maps to the 40 names; brand values trace to tokens.json; extras are explicit proposals.
  • H4 Real-content survival — longest real names, 3-paragraph education, 14-step progress, "??" cells: nothing breaks.
  • H5 Empty-state grace — home with zero dynamic content still looks designed.
  • H6 Register separation — public calm/educational vs. admin dense/utilitarian, same brand.
  • H7 Continuity without mimicry — recognizably NanaWall beside nanawall.com, clearly a focused tool.
  • H8 Accessibility spot-check — sampled contrast pairs pass; keyboard path through the stepper is coherent; focus visible; targets ≥44px.

Calibration: emulate TurboTax's guided-interview clarity, Apple's help-me-choose education, Wirecutter's budget-pick framing, Stripe's register separation — the quality, not the pixels. Reject-on-resemblance: the current NanaWall product finder (filter-as-you-go, result counts), car-brand build-&-price prestige tiering, big-box faceted search, quizzes that gate results behind lead capture, generic SaaS dashboard kits.