Button
componentSolidOutlineTransparentDisabled
scale
UI/UX Design & Front-End Internship · Redlands, CA · Remote · Summer 2021
Calcite Design System Documentation
1Header & Interactive Preview
2Usage Guidelines (Do’s & Don’ts)DoDon’t
3Component API & Properties
4Code Snippets & Examples
Problem & Context
The challenge
During my internship at Esri, the Calcite Design System was evolving rapidly on GitHub and Figma.
However, internal designers and developers lacked a clear, unified documentation website to reference component behavior, usage rules, and code snippets.
Without a centralized hub, team members spent extra time clarifying component specs, leading to inconsistent implementations across web and mobile products.
GitHubFigmaComponent specs
Documentation site
I reframed the core problem
How might I build a clear, searchable internal documentation portal so 20+ designers and developers can quickly find component usage rules, accessibility guidance, and code snippets without breaking their workflow?
Target audience & team dynamics
Designing internal documentation requires catering to two distinct user groups with different goals:
UI/UX Designers
Front-End Engineers
UI/UX Designers
Need visual examples, variant states, layout rules, clear do’s and don’ts, and accessibility standards to maintain visual consistency across products.
Front-End Engineers
Need fast property tables, exact HTML/CSS/JS code snippets, component API details, and clean code examples with zero extra clutter.
The core constraint
The core constraint
Documentation must serve both designers and engineers without forcing either group to wade through irrelevant details.
Designers
Developers
One page
Designers need quick visual context, while developers need clean, copyable code.
The site had to balance both needs cleanly while staying easy to maintain as the design system expanded.
Goals & Phased Execution Strategy
Crawl, Walk, Run
To deliver a scalable documentation portal within my 3-month internship, I used a 3-step process:
Crawl (Audit & Structure)
Audited existing Calcite components on GitHub and Figma to identify documentation gaps, usage inconsistencies, and missing guidelines across 20+ components.
Walk (Layout & Component Mechanics)
Designed structured documentation page layouts in Figma, establishing a clear visual hierarchy that separated visual guidance from technical code specs.
Run (Build & Launch)
Developed the responsive frontend using HTML, CSS, and JavaScript, delivering a live documentation portal and hand-off guide for the design team.
System Architecture & Information Layout
Four clear regions
To make component pages scannable and easy to navigate, I structured each component documentation page into four clear regions:
1
Header & Interactive Preview
Component title, description, live interactive preview, and quick status tags.
2
Usage Guidelines (Do’s & Don’ts)
Visual examples showing correct and incorrect layout, spacing, and color applications.
3
Component API & Properties
Structured tables listing props, slots, events, and default values for developers.
4
Code Snippets & Examples
Copyable HTML and JavaScript code blocks for fast implementation.
Components
Typography
foundationAa
Heading
Body text sits at a readable size and weight.
Caption
Text and Link
componentA short line of text with a link inside it.
Helper text in a quieter tone.
Key Design Decisions & Technical Execution
Decision 1: Separating Design Guidance from Code Specs
- What I Did: I created two distinct views within each component page. Designers could quickly scan visual rules and variant states, while developers could toggle directly to technical specs and code snippets.
- What It Replaced: A single long text document where code blocks and visual guidelines were mixed together, forcing users to scroll past irrelevant information.
DesignCode
Decision 2: Clear Visual Hierarchy for Guidelines
- What I Did: I introduced side-by-side visual cards for “Do” (green indicator) and “Don’t” (red indicator) examples, keeping descriptions brief and focused on specific interaction rules.
- What It Replaced: Text-heavy guidelines that described visual mistakes in paragraphs instead of showing them visually.
Do
Don’t
Decision 3: Live Component Behavior & Copyable Code Blocks
- What I Did: I built clean, interactive component previews alongside one-click copy buttons for code snippets.
- What It Replaced: Static screenshots of code that required developers to manually type out component syntax.
Copy
Chip
componentDefaultSelectedSuccessError
Input
componentLabelPlaceholderMessage under the field
Switch
componentNotice
componentTitleOne short line of message text.
Testing, Discoverability & Results
Usability testing & iterative feedback
I conducted iterative mockup reviews and A/B tests with internal designers and developers to refine the navigation and page layouts.
A
B
By testing different information arrangements, I identified where developers experienced friction when looking for property definitions.
Measured impact
- 50%+ Improvement in Content Discoverability: Reorganizing component pages and visual hierarchy reduced search friction, allowing team members to locate component specs and code snippets significantly faster.
- Strong Team Alignment: Supported 20+ designers and developers in maintaining consistent component usage across Esri’s digital products.
What I Learned From This Project
Internal documentation is a product
Treating internal tools with the same user-centered design rigor as public-facing software creates huge efficiency gains for engineering and design teams.
Design for dual audiences
Designers and developers read documentation differently. Structuring pages to serve both needs without clutter is essential for design system adoption.
Build for evolution
Designing a flexible documentation layout ensures that new components can be added seamlessly as the design system grows.
Note: Due to privacy and NDA guidelines, proprietary internal metrics and unreleased component specifications have been generalized.