How To Write A Code Mockup

What if we delivered Design System components the same way Designers create the very UI we're building?

Jan 23, 2025

Engineers building great design systems mockup their most impactful and valuable abstractions. They play with critical building blocks and ensure reliability before sharing them with others. And they look at how the code will be used from the perspective of an Engineer without any historical context, making adjustments along the way which create more opportunities for others to make correct assumptions.

Below is the procedural and mental framework I rolled out for doing just this when adding components to our design system at VividSeats. Our business goals require high delivery velocity for components inner-sourced by contributors across teams as part of ongoing feature work without sacrificing quality or flexibility in branding and themeability, for which our requirements and standards are about as advanced as it gets.

This process, combined with a healthy dose of scaffolding and automation, is designed to empower any Frontend Engineer at VividSeats to successfully build a design system component to our elevated standards, even without the pre-requisite specialized expertise that comes with a background in design or any focus on foundational work or design systems in previous roles.

👋 Hey, it’s Rob. Welcome to UI Engineering Excellence. If you enjoy this post, please hit the ❤️ button and share/restack 🔁 it with others who might find it helpful!

ℹ️ A code mockup is both a process and a deliverable. We start by diving deep into requirements outlined in design mockups mapping out multiple potential paths to full viability. From there, we refine and converge on a single pattern, charting a roadmap for how it can evolve as the component grows in complexity. Along the way, we adapt and adjust, ensuring the solution aligns seamlessly with our business goals.

1. Identify Requirements & Constraints

Assess The Design Mockup (assuming we have one)
Design mockups aren’t always a given, but when they are available, they serve as the source of truth throughout the development process. Once the component is delivered and live in production, the implementation itself takes over as the definitive reference point.
Identify Design Discrepancies & Constraints
What design decisions—such as sizing, spacing, positioning, or alignment—change across different states? Are there clear boundaries or implicit constraints on how these differences can vary? Which aspects of the component need to be themeable, and which parts of the design remain stable ?

🎯 Goal: Gain just enough understanding to confidently start mocking up code.

2. Choose A Component Pattern

Our UI composition leans heavily on 3 core patterns:

Standalone Components
The component functions as a self-contained unit, with its complexity scaling based on the number and type of props—think Checkbox, Text, etc.
Example:

<Checkbox id="1" checked={checkAll}>{label1}</Checkbox>
<Checkbox id="2" checked={checkAll}>{label2}</Checkbox>

Compound Components
The component is multifaceted with specialized, often optional, subcomponents that are not reusable elsewhere.
Example:

<Checkbox.Group checked={checkAll}>
 <Checkbox>{label1}</Checkbox>
 <Checkbox>{label2}</Checkbox>
</Checkbox.Group>

Base Components
The component is reduced to essential presentation logic common across all variants and then used as the root node in explicit components for specialized variants.
Example:

<SuccessCheckbox />
<ErrorCheckbox />
<InfoCheckbox />
<WarningCheckbox />

🧠 Keep In Mind: Most organism-level components, as well as template/page/view-level components in the Design System, become Compound Components. These typically serve as base components for variants that live outside the Design System. On rare occasions, a compound component may also act as a base for variant components that remain within the Design System. When this happens, we refer to the pattern as a Compound-as-Base Hybrid.

3. Mock Up Multiple Approaches

Just as Designers draft and explore multiple solutions, Engineers contributing to the Design System should draft at least two or three usage mockups for the chosen pattern. This allows us to evaluate how seamlessly Engineers focused on feature work can leverage what we’re building to address common design and UX challenges. Key areas we often explore include:

Pattern Adequacy
How many patterns should we evaluate for this component? More complex components are often compound components, while simpler, atomic components usually offer more flexibility. For example, <Button /> and <Icon /> are commonly used as base components inside and outside the Design System. Should we allow their variants to emerge organically as the system evolves, or explicitly define them upfront? If explicit, which variants make the most sense to include?
Design Responsibility
How many assumptions do components, subcomponents, and variants make about styling their content? To what extent are subcomponents or variants allowed to be aware of or depend on the specifics of their content?
Structural Flexibility
How easily should we be able to rearrange or conditionally render parts of the component? What is the visual or spatial “scope” in these cases—specific content, entire sections, full tabs? Do the variants need to be reusable enough to justify creating discrete components for each?
Prop Composition
How does this component's contract influence the broader system? Does it introduce any new standardized props? If we adjust the type signature of existing standardized props to enhance shared functionality across components, will we need to revisit and update other components using the same prop to maintain the library’s integrity?

☝️ Tip: Keep your mockups lean and to-the-point. Prioritize usage examples and focus on how the code “feels” to read and write when achieving the desired state.

4. (Optional) Mock Up Props

List Standardized Props
Which props from other components are reusable in this component?
List Discrete Props
Identify the props unique to this specific component. Which of these are required, and which are optional? What are their default values? Can we include any pass-through props without exposing underlying implementation details? If using a base component pattern, determine which base component props are abstracted by and omitted from the variant components.
Limit Style/Design Props
Are we helping Engineers focused on feature work make accurate assumptions? For example, if the component requires flexible width, should we provide a width prop for explicit, potentially complex values, or opt for a simpler fullWidth prop to streamline usage?
Explore Multiple Techniques
When design decisions like alignment, size, and roundedness are tightly coupled, should we simplify with a single prop or maintain flexibility by using granular props for each decision? What are the trade-offs, and how does each approach look in practice?
Customize Discrete Events
Can we make event handling more granular and reusable for common scenarios? For example, instead of accepting a generic onKeyDown() handler to augment functionality when the “Tab” key is pressed, could we introduce an onPressTab() prop that leverages a custom TabEventHandler to handle more specific custom TabEvents? (Hint: You best believe we can!)
Standardize Type Signatures
Do we need to introduce new utility hooks or types to support newly standardized props, such as custom event handlers?

🎯 Goal: Make it easy for any consumer (including your future self) to intuitively understand how to use this component and confidently make accurate assumptions, even when facing gaps in technical expertise or domain knowledge.

5. (Optional) Mock Up Reusable Utils

Identify or Create Helper Hooks, Utilities, or Types
e.g. useVerticalAlignment(), useQueryParamState(), EscapeEvent/EscapeEventHandler/useEscapeEvents(), or defining notable constants and enums.
Centralize Reusable Utils
Consolidate logic or styling transformations to streamline the process of building Design System components and reduce duplication.
Explore Multiple Options (As Needed)
For particularly large or complex enums, would breaking them into smaller pieces improve usability? How should functional hooks, like those for filtering and sorting, be composed to handle overlapping or chained behaviors effectively? Consider the trade-offs and implementation details for these approaches.

🎯 Goal: Keep the code DRY and self-documenting while avoiding duplicated logic in each component.

6. (Required) Review With Maintainers

Share Final Mockup / Chosen Approach
Present usage examples to the Design System group. If the work will be carried out by another Engineer, ensure they’re involved in the review process.
Gather Feedback
Verify that the proposed implementation adheres to Design System guidelines, naming conventions, WCAG compliance, and other key standards.
Discuss Future Use
Consider whether the pattern or component could be valuable for other teams or projects. Explore how distribution logic might evolve as the business’s brand composition changes.
Achieve Consensus
Secure approval from the Design System maintainers and move forward with development.

🎯 Goal: Validate the approach and maintain consistency with system-wide standards.

7. Make Adjustments

Tweak the Pattern(s)
Make minor adjustments as unforeseen challenges arise.
Strategically Plan Rewrites
Identify when a shift from one pattern to another might be necessary. If the component becomes overly complex, should it be broken into smaller pieces or rewritten using a more sophisticated pattern?
Add Snippets in Storybook
Create a Storybook story for each design/state variation from the design mockup. Ensure the resulting code snippets precisely match the code mockup for each variant.

🎯 Goal: Deliver a polished, thoughtfully refined implementation, ready for actual build or integration.

Summary

Identify Requirements & Constraints
Choose a Component Pattern
Mock Up Multiple Approaches
(Optional) Mock Up Props
(Optional) Mock Up Reusable Utils
(Required) Review With Maintainers
Make Adjustments

👋 Connect with me on LinkedIn.

PS: If you’re enjoying UI Engineering Excellence, hitting the ❤️ button and sharing/restacking 🔁 goes a long way in helping me grow the publication. Please take a moment to help spread the word. Thank you!