Foundation
User Journey Maps
Four validated journey maps anchoring UX decisions for the Nodus Design System. Each map traces a persona from entry to success condition — capturing stage goals, actions, emotional register, cognitive load, pain points, failure modes, and design system opportunities.
First-Time Developer
From landing on design.dana.xyz to successfully integrating a first component into a production build. Captures the discovery moment, cognitive load peaks, install friction, and the first 'it works' milestone.
ENTRY POINT
Google search / colleague referral / GitHub README link
SUCCESS CONDITION
Component renders correctly in production build
Discovery
UNCERTAINLOWUnderstand what Nodus DS is and whether it's worth evaluating
Lands on design.dana.xyz homepage, scans above-fold content, reads tagline and component gallery
PAIN POINTS
- Unclear immediately if this is for React, Vue, or framework-agnostic
- No 'who is this for' statement visible without scrolling
FAILURE MODES
- Bounces if no recognizable component category visible in first 3 seconds
- Leaves if 'Get Started' CTA leads to a login wall
DS OPPORTUNITY
Above-fold should surface: stack compatibility, one headline component preview, and a zero-friction first-look path (no auth required).
Orientation
UNCERTAINMEDUnderstand the token system and component taxonomy before touching code
Browses Foundation section — reads Tokens page, clicks through a few component docs
PAIN POINTS
- Three-layer token architecture (Primitive → Semantic → Component) has no visual diagram on first encounter
- Token naming conventions are non-obvious without context (--bh-* vs --ds-*)
FAILURE MODES
- Developer skips token docs and hardcodes hex — creates long-term maintenance debt
- Misunderstands semantic layer and uses primitive tokens in components
DS OPPORTUNITY
Tokens page should include an interactive layer diagram showing a concrete value flowing through all three layers. One worked example (e.g., a button background from primitive to component) eliminates the most common onboarding error.
Setup
FRUSTRATEDHIGHInstall the package and get a minimal working import
Follows install instructions, runs npm install, imports first component, starts dev server
PAIN POINTS
- CSS variable injection step (importing tokens/bauhaus.css and tokens/semantic.css) easy to miss
- No visual feedback if tokens are missing — component renders but looks broken
- Peer dependency version mismatches surface as cryptic errors
FAILURE MODES
- Abandons setup after third unresolved peer-dependency warning
- Ships component without token import — color tokens undefined, renders as fallback values
DS OPPORTUNITY
A setup health-check component or terminal script that validates token injection and peer deps. Could be as simple as a `<DSCheck />` component that renders green when the system is properly configured.
First Component
UNCERTAINMEDRender a real component with correct styling
Copies component usage example from docs, pastes into project, adds token import, sees it render
PAIN POINTS
- Code examples in docs may not reflect latest API surface if docs lag behind releases
- No live playground embedded in component docs — must set up locally before seeing anything
FAILURE MODES
- Uses a deprecated prop name from an older docs version
- Renders component but tokens not imported — silent visual degradation
DS OPPORTUNITY
Embed a live preview with copy-to-clipboard for every component. Show the working import at the top of each component doc page, not buried in a getting-started guide.
Integration
CONFIDENTMEDConnect the component to real data and pass correct props
Replaces static demo values with app state, wires event handlers, adjusts for layout context
PAIN POINTS
- TypeScript prop types for complex components (e.g., DataTable, AgentCard) require reading source
- Variant and state combinations not always documented exhaustively
FAILURE MODES
- Incorrectly passes string to a token-expecting prop
- Misses required aria attributes for accessible interactive components
DS OPPORTUNITY
TypeDoc or Storybook prop table auto-generated from component source, visible in docs. Highlight required vs. optional props with visual distinction.
Production Build
CONFIDENTLOWShip the component in a production build without breakage
Runs build, resolves any tree-shaking or SSR errors, deploys to staging
PAIN POINTS
- CSS-in-JS vs. CSS variable approach can cause hydration mismatches in SSR
- Dynamic theme switching may require client-side check before render
FAILURE MODES
- Build fails due to ESM/CJS module mismatch
- Theme flicker on hydration in Next.js SSR context
DS OPPORTUNITY
Publish a verified compatibility matrix (Next.js App Router, Vite, Remix). Include an SSR-safe pattern in the guides.
First Win
DELIGHTEDLOWSee the component work exactly as designed in production
Views live deployment, sees component render with correct tokens, shares with team
DS OPPORTUNITY
The 'it works' moment should include a path forward: What to build next? Which components pair well? What's the recommended upgrade path? Surface these as contextual next steps in the docs.
Returning Developer
Using the changelog or token update docs to upgrade an existing integration. Captures where they enter the site, how quickly they locate changes, and what causes abandonment.
ENTRY POINT
Direct URL from bookmark / PR comment link / package release notification
SUCCESS CONDITION
Integration updated and tests passing after token or API change
Trigger
UNCERTAINLOWLearn what changed in a new version and assess impact on existing integration
Sees release notification or PR failing, opens changelog, scans version diff
PAIN POINTS
- Changelog entries may not clearly flag breaking vs. non-breaking changes
- Token renames not always linked to migration guides
FAILURE MODES
- Skips changelog and goes straight to upgrading — misses a deprecation and breaks
- Changelog is too verbose — key breaking change buried in minor fixes
DS OPPORTUNITY
Breaking changes deserve visual prominence: a banner or bold callout at the top of each release entry. Token changes should include a before/after diff table.
Impact Assessment
UNCERTAINHIGHIdentify which parts of their codebase are affected
Cross-references changed tokens or components against their current usage
PAIN POINTS
- No automated migration tool or codemod — manual search required
- Token search across a large codebase is error-prone
FAILURE MODES
- Misses a token usage in a rarely-tested code path — ships broken UI
- Overestimates scope of change and delays upgrade indefinitely
DS OPPORTUNITY
Provide a codemod or migration CLI for token renames. Even a regex-based 'find these patterns' guide reduces the cognitive burden significantly.
Token Migration
FRUSTRATEDHIGHUpdate renamed or deprecated tokens across their integration
Searches codebase, replaces old token references, validates visually
PAIN POINTS
- Old token names still accepted (with deprecation warning) — easy to leave stale references
- Visual regression testing not always set up — hard to confirm no unintended changes
FAILURE MODES
- Misrenames a token — picks wrong semantic equivalent
- Updates tokens but not the theme configuration — dark mode breaks
DS OPPORTUNITY
A tokens migration guide with explicit semantic equivalence tables (old → new with why). Side-by-side visual comparison for token meaning changes.
Component API Update
UNCERTAINMEDUpdate prop usage for changed component APIs
Reads component migration notes, updates prop names and types, runs TypeScript
PAIN POINTS
- Prop name changes may require find-and-replace across many files
- Behavior changes (not just API) may not be apparent from TypeScript alone
FAILURE MODES
- TypeScript passes but visual behavior changed — misses a semantic prop change
- Prop change cascades to a composed component they authored — requires tracing
DS OPPORTUNITY
Component migration notes should include 'If you used X for Y reason, now use Z'. Intent-aware documentation, not just name-mapping.
Validation
CONFIDENTMEDConfirm upgrade is correct before merging
Runs test suite, does visual review, checks dark mode, deploys to preview environment
PAIN POINTS
- No official visual regression test fixtures provided by Nodus DS
- Dark mode regressions often only caught in manual review
FAILURE MODES
- Merges and ships with a dark mode token regression
- Tests pass but a Storybook story or docs page example now renders incorrectly
DS OPPORTUNITY
Provide a test utilities package with a set of snapshot-ready component fixtures for CI regression testing. Document the dark mode validation checklist.
Done
CONFIDENTLOWIntegration upgraded and deployed
Merges PR, deploys, monitors for regressions
DS OPPORTUNITY
Post-upgrade: offer a 'what changed since you last visited' summary on the changelog page anchored to the version they came from. Makes the next upgrade feel lighter.
Stakeholder Evaluator
A non-technical decision-maker (EM, Product Lead) assessing whether to adopt the design system for a new project. Captures what signals build trust, what signals uncertainty, and what a credible proof looks like.
ENTRY POINT
Colleague recommendation / vendor evaluation process / design team referral
SUCCESS CONDITION
Decision to adopt or reject Nodus DS for an upcoming project
Awareness
UNCERTAINLOWUnderstand the value proposition at the highest level
Reads homepage, looks for 'why Nodus' content, checks who uses it
PAIN POINTS
- Design system value props often written for developers — technical language alienates non-technical evaluators
- No 'business outcomes' framing visible (time-to-ship, consistency, accessibility compliance)
FAILURE MODES
- Skips the site entirely after seeing developer-focused copy — delegates evaluation without engagement
- Misframes Nodus as a 'component library' rather than a design language for AI-native products
DS OPPORTUNITY
A dedicated 'For decision makers' section or a one-page brief that frames Nodus in outcomes: consistency, accessibility coverage, AI-native differentiation, and time-to-production metrics.
Credibility Check
UNCERTAINMEDAssess whether this is a production-grade, maintained system
Looks for version history, last updated date, release cadence, and team behind it
PAIN POINTS
- No visible release cadence signal — hard to assess if the project is actively maintained
- No explicit SLA or support model stated
FAILURE MODES
- Evaluator interprets sparse release history as abandonment risk
- No organizational backing visible — perceived as a side project, not a platform
DS OPPORTUNITY
Surface a release cadence indicator and last-updated timestamp on the docs homepage. A brief 'built by' attribution and governance statement builds confidence for organizational adoption.
Scope Assessment
UNCERTAINMEDUnderstand what's included and what gaps may exist
Browses component gallery, checks coverage against their use case (forms, tables, data viz)
PAIN POINTS
- Component gallery organized by type — evaluator thinking by use case can't find what they need
- Finance / data-dense interface coverage not prominently signaled
FAILURE MODES
- Concludes coverage is insufficient after browsing only the primary nav — misses advanced patterns
- Can't map components to their team's specific product surface
DS OPPORTUNITY
A 'use case gallery' alongside the component gallery: 'Building a data dashboard? See these 8 components.' Maps coverage to domain intent rather than taxonomy.
Proof Point
CONFIDENTLOWSee a credible, realistic reference implementation
Views A2UI templates gallery, looks for something resembling their product's complexity
PAIN POINTS
- Templates may look polished but evaluator unsure if they're production-representative or demos
- No context about real teams or products that have shipped with Nodus DS
FAILURE MODES
- Dismisses templates as 'too simple' — doesn't explore the Finance or Dashboard category
- Can't connect template quality to production quality without developer input
DS OPPORTUNITY
Annotate templates with production context: 'This pattern is used in live treasury dashboard interfaces.' Authenticity signals close the credibility gap for non-technical evaluators.
Risk Evaluation
UNCERTAINMEDIdentify adoption risks and mitigation paths
Asks: what happens if we need to customize? What if the library updates break our UI?
PAIN POINTS
- No explicit customization / white-label capability stated
- Versioning / stability guarantees not prominently documented
FAILURE MODES
- Rejects adoption due to perceived lock-in risk without understanding token-layer customization
- Overestimates upgrade maintenance burden without seeing the migration tooling
DS OPPORTUNITY
A 'Customization' and 'Stability' page in Foundation addressing: how to extend tokens, what breaking change policy is, and what upgrade support looks like.
Decision
CONFIDENTLOWMake and communicate an adoption decision
Summarizes findings for their team, makes recommendation
PAIN POINTS
- No shareable summary format (PDF brief, one-pager) — evaluator must write one themselves
- No comparison positioning against alternatives (MUI, Shadcn, etc.) stated
FAILURE MODES
- Positive evaluation doesn't progress because internal champions lack collateral to make the case
DS OPPORTUNITY
A printable or shareable 'Design System Brief' that decision-makers can use in internal pitches. Reduces adoption friction at the organizational level.
Designer Onboarding
A product designer joining a team that uses the Nodus DS. Captures how they navigate the token system, how they understand the Bauhaus semantic logic, and at what point they feel confident to design with it.
ENTRY POINT
Team onboarding / Figma file invite / design.dana.xyz link from team lead
SUCCESS CONDITION
Designer feels confident creating new screens using the design system's token language
Context Setting
UNCERTAINMEDUnderstand the design philosophy and why Nodus looks the way it does
Reads Philosophy and Principles pages — tries to understand Bauhaus reference and semantic color logic
PAIN POINTS
- Bauhaus analogy meaningful to some designers, opaque to others — not all designers have modernist design history background
- Semantic color system (Red=Agency, Blue=Temporal, Gold=Validation) has no intuitive mapping on first read
FAILURE MODES
- Designer reads philosophy but doesn't connect it to practical token decisions — treats it as background reading
- Misunderstands agency red as 'danger only' — limits its use
DS OPPORTUNITY
A 'Philosophy in Practice' section: show the same interface with and without semantic color discipline. Make the principle tangible rather than abstract.
Token System Orientation
FRUSTRATEDHIGHUnderstand the three-layer token architecture and how to navigate it
Opens Tokens page, reads layer explanation, tries to trace a color from primitive to component
PAIN POINTS
- --bh-* vs --ds-* naming distinction not immediately intuitive
- No visual flow diagram showing how a token cascades from layer to layer
- Designer tooling (Figma variables) may not map 1:1 to CSS variable names
FAILURE MODES
- Designer uses primitive tokens in mockups — code implementation diverges from design
- Gives up on token system and picks colors visually — breaks semantic consistency
DS OPPORTUNITY
A designer-specific token guide that shows: Figma variable name → semantic CSS token → component usage. Bridges the Figma-to-code gap explicitly.
Bauhaus Semantic Color Fluency
UNCERTAINHIGHInternalize when to use agency red, temporal blue, and validation gold
Reviews color docs, looks at component examples, tries applying colors in a practice screen
PAIN POINTS
- The three-color constraint feels limiting without understanding why — resists instead of embracing
- Edge cases (what color for a 'save' confirmation vs. a 'completed process'?) not always documented
FAILURE MODES
- Uses validation gold for 'warning' (its emotional register) rather than 'enrichment/quality' (its semantic meaning)
- Introduces unapproved colors for edge cases instead of using existing semantic tokens
DS OPPORTUNITY
An interactive semantic color decision tree: 'Is this AI-initiated? → Use Agency. Is this time-based or in-flight? → Use Temporal. Is this about data quality or confirmation? → Use Validation.' Makes the system navigable without memorizing the rationale.
Component Exploration
CONFIDENTMEDUnderstand which components exist and which to use for a given design problem
Browses component gallery, opens component docs, reads usage guidelines
PAIN POINTS
- Taxonomy split (Components / Patterns / Finance) not obvious to a designer — doesn't match how designers think about UI
- No 'when to use vs. when not to use' guidance on all component docs
FAILURE MODES
- Designs a new pattern from scratch that already exists in the system — duplication
- Uses a 'Component' when the task calls for a 'Pattern' — underbuilds the interaction
DS OPPORTUNITY
A designer-oriented component browser organized by task ('How do I show AI status? How do I request user confirmation?') rather than by taxonomy type.
First Screen Design
UNCERTAINHIGHDesign a complete screen using only design system tokens and components
Opens Figma, starts new screen using DS variables, composes layout from components
PAIN POINTS
- Figma variable library may lag behind coded token updates — values mismatch
- Layout tokens (spacing, density) not always mapped in Figma styles
FAILURE MODES
- Hard-codes pixel values because spacing tokens aren't easily accessible in Figma
- Uses old component versions from Figma if library isn't updated — ships inconsistent UI
DS OPPORTUNITY
Publish a 'Figma sync state' page that shows which Figma library version matches which npm package version. Makes Figma-to-code discrepancies visible rather than silent.
Handoff
CONFIDENTMEDHand off the design to a developer with minimal interpretation gaps
Annotates design in Figma with token references, writes component specs, exports for review
PAIN POINTS
- Designers may annotate with visual description instead of token names — creates implementation ambiguity
- No standard annotation template for Nodus token references in Figma
FAILURE MODES
- Developer receives design with hex values in annotations rather than --ds-* tokens
- Spacing annotated as '16px' rather than '--ds-space-inset-md' — disconnects from token system
DS OPPORTUNITY
A Figma annotation kit with pre-built labels for common Nodus tokens. Could be a Figma plugin or a shared component library with token callout components.
Confidence
DELIGHTEDLOWDesign fluently within the system without referring to docs constantly
Uses token system and component library from memory, contributes pattern suggestions to team
DS OPPORTUNITY
The confident designer becomes a system contributor. Create a clear path for suggesting new patterns or tokens — a feedback loop from practitioners back into the system.