🚀 RTT Facilities — Design System Onboarding Guide
How to Work Inside a Governed Design System
Welcome to the RTT Facilities Design System.
This guide helps new contributors understand how to work inside the system without breaking meaning, governance, or trust.
You do not need to read every document to get started —
but you do need to understand the principles below.
1. What This Design System Is#
The RTT Facilities design system is:
- A governance surface, not a style guide
- A shared language for infrastructure decision‑making
- A system designed to scale across cities, domains, and decades
Design here exists to clarify risk, readiness, and accountability.
2. What This Design System Is Not#
It is not:
- A branding exercise
- A UI trend collection
- A playground for experimentation
- A place for one‑off visuals
Exploration happens outside the canonical system.
3. The Mental Model#
Before touching Figma or code, internalize this:
Design choices encode meaning.
Meaning affects decisions.
Decisions affect public trust.
That is why governance exists.
4. How the System Is Structured#
The design system is governed through five core artifacts:
- Design Governance Charter — authority and principles
- Component Creation Checklist — when components are allowed
- Naming Convention — how meaning is encoded
- Component Proposal Form — how new components enter
- Figma Library Structure — where components live
If you are unsure what to do, start with the checklist.
5. Your First Rule as a Contributor#
Do not create a new component until you are sure one is needed.
Most work involves:
- Reusing existing components
- Applying variants correctly
- Improving documentation or usage clarity
New components are the last resort.
6. If You Think You Need a New Component#
Follow this sequence:
- Review the existing component library
- Complete the Component Proposal Form
- Confirm naming using the Naming Convention
- Validate schema alignment
- Submit for steward review
Do not design first and justify later.
7. Naming Is Not Optional#
Component names:
- Encode function and governance intent
- Must survive redesigns and tooling changes
- Are frozen once approved
If you cannot name a component clearly, it is not ready to exist.
8. Audience Awareness#
Every component must declare its audience:
- Operator
- Department leadership
- City executive
- Public / resident
Complexity is gated, not hidden.
9. Accessibility Is Governance#
Accessibility is not a “nice to have.”
If a component:
- Relies on color alone
- Obscures meaning
- Creates cognitive overload
…it fails governance review.
10. Stewardship & Review#
A Design System Steward exists to:
- Preserve clarity
- Prevent duplication
- Maintain semantic integrity
Review is not gatekeeping —
it is how the system stays usable over time.
11. Common Mistakes to Avoid#
- Creating components for one‑off layouts
- Naming components after appearance
- Encoding state in names
- Introducing ad‑hoc metrics
- Bypassing documentation
These are treated as governance risks.
12. What Success Looks Like#
When the system is working:
- Contributors reuse instead of reinvent
- Dashboards explain themselves
- Governance state is visible
- Meaning survives turnover
- Trust accumulates quietly
13. Where to Go Next#
Depending on your role:
- Designers → Review the Figma Library Structure
- Engineers → Review the Global Index Schema
- Reviewers → Review the Governance Charter
- New contributors → Start with the Checklist
14. Canonical Status#
This onboarding guide is canonical.
All contributors should read it before working in the design system.
Why this guide matters#
This document:
- Reduces onboarding friction
- Prevents accidental drift
- Makes governance feel supportive, not heavy
- Turns a complex system into a calm workspace