# Datamaran prototyping shell

Closing the gap between design intent and product reality.

## The problem

Every time the product team needed to prototype a new screen — a regulatory dashboard, a materiality matrix, a new AI chat pattern — they paid the same invisible tax.

Set up the app shell. Thread in the navigation. Wire up the design tokens. Pick which PrimeVue components to use. Decide where mock data should live. All before a single design idea could be explored.

That overhead was consistently underestimated. Prototypes looked disconnected from the real product. Stakeholders made decisions from Figma frames that had never run in a browser at real viewport sizes, with real component behavior.

That last part is the real cost. When a prototype doesn't behave like the product, stakeholders fill the gap with imagination. Decisions happen on the wrong artifact.

It kept surfacing in reviews. Stakeholders questioning whether what they were looking at matched how the product actually behaved. The friction was consistent enough to make clear this was a structural problem, not a one-off.

## My role

**Senior Product Designer** — I scoped and designed the template as a design infrastructure investment, partnering with a senior front-end developer on the implementation.

## The constraint that shaped everything

Datamaran's AI assistant is a product differentiator. Any meaningful feature exploration needs to show how a new page feels alongside it. But the panel has three display modes, a resizable pane (320–860px), streaming message UI, slash commands, context chips. Nobody rebuilds that for a two-day spike.

So the question was not "how do we prototype faster." It was: how do we make the full product context available from the first line of code?

## The key choices

**An architectural sandbox zone, not a convention.**
The `<div class="main-content">` is the only area prototypes should touch. That constraint is structural — the sidebar, user menu, tokens, and routing are untouchable. Teams cannot accidentally break shared infrastructure while experimenting. I chose architecture over documentation because documentation gets ignored under deadline pressure. Constraints do not.

**The Answers panel shipped as a first-class template component.**
Any prototype immediately inherits the full AI interaction pattern — resizable, docked and floating modes, animated loading states, slash-command function insertion, starter questions for empty state. Teams can explore how new pages feel alongside the assistant without rebuilding the panel. The integration surface is already there.

I rejected the alternative of a simplified mock panel. A stripped-down version would have been faster to build but would have introduced false confidence: a design that works with a simplified AI panel often fails when the real one appears. The full fidelity is the point.

**The full ESG ontology embedded as typed mock data.**
All 99 Datamaran topics, typed in TypeScript, matching the real API shape. This forces honest design. A topic selector that looks clean with three placeholder items often falls apart with "Transition to a circular economy" next to "Spills." Domain content reveals layout problems. Generic lorem ipsum hides them.

The same principle extends across the full Datamaran domain: regulations, media articles, reports, sustainability targets, IROs (Impacts, Risks, Opportunities), and companies. All of it is available as structured mock responses. Prototypes can render a regulation card with a real validation score, an IRO with impact and source metadata, or a benchmark view with actual company names. The data is already there, already typed, already matching the shape of the real API.

**The `design.md` file.**
This is the least obvious choice and the most significant one.

The file is a precise machine-readable specification: use only PrimeVue, write clean single-file components, use mockdata — real data that emulates API calls, produce working code only, never touch global layout. It encodes design intent as a constraint set that an AI code generator reads before producing output.

The result: a designer can direct AI code generation without writing TypeScript. The output meets design standards without a code review. The template is designed not just for human developers but as a structured environment where AI-generated code lands in the right place, in the right style, on the first attempt.

This is a move from design-as-documentation to design-as-environment. The design rules survive handoff because they are embedded in the environment, not communicated in a Notion doc.

## The detail that matters

Consistency stopped requiring coordination.

Before this, every prototype involved a judgment call: which shade of teal is primary, what is the correct border-radius, how should a form field look at error state. Those calls diverged across the team over time. A prototype built by a new team member looked different from one built by a senior designer. Not dramatically different. Different enough to erode trust in the artifact.

`DmPreset.ts` defines the brand from the ground up: the `dm-ocean` palette, Tailwind-compatible spacing and type scale, component overrides for buttons, chips, data tables, and form fields. Every prototype inherits these automatically. The design system enforces itself structurally, not through review cycles.

The `dm-ocean` palette was defined with WCAG contrast ratios in mind. PrimeVue's component library handles keyboard navigation by default — every prototype inherits that accessibility baseline without additional work.

## The outcomes

Stakeholders engage differently when a prototype runs real components with real brand tokens in a real browser. They stop imagining what the product will look like. They respond to what it actually does. Decisions move faster because the artifact under review is trustworthy.

The template has been used for feature explorations across the Answers panel interaction model, new regulatory dashboard patterns, and Double Materiality screen flows. Each prototype started from a full application context rather than a blank page.

Feature explorations that previously spanned multiple days now fit in a single working day.

The metrics to track over time: time from brief to stakeholder-ready prototype, review cycle length, and AI-generated code acceptance rate.

## What I learned

A rapid-prototyping tool is only fast if it makes the prototype feel real. Speed without fidelity just moves the reckoning — from the prototype review into the development sprint.

Running prototypes in real context changed how stakeholders gave feedback. Comments shifted from "this looks different from what we have" to actual product decisions. User testing sessions became more honest — participants were not compensating for a lo-fi artifact, they were reacting to something that behaved like the product.

The alignment benefit compounded. When the prototype matches the product, engineering, product, and design are reviewing the same thing. The conversation changes from "will this work technically" to "does this solve the problem."