Principles

These 13 principles guide every UI design decision made by designers and Coding Agents, with DESIGN_SYSTEM.md §3 as the single source of truth. Five also map to mandatory implementation rules in the repository-root AGENTS.md, with the corresponding rule number shown on each principle.

The 11 hard implementation rules live separately in the repository-root AGENTS.md §2; the two sets complement each other, and overlapping entries cross-reference both ways. Principle #7’s “13 text styles” counts typography tiers — a coincidence, not these 13 principles.

1
Shared-first
Build reusable UI in packages/design-system/src/shared.tsx, then import into pages. Never copy component code inline. Implementation rule: AGENTS.md §2 #5.
Why: One source of truth means token changes propagate everywhere automatically.
See Component Library →
2
Tokens-first
Use CSS variables and utility classes for every color, size, and spacing. Never hardcode hex, px font sizes, or arbitrary spacing values. Implementation rule: AGENTS.md §2 #1.
Why: Tokens are the only way light/dark mode and future rebrands stay coherent.
See Foundations →
3
One Primary button per view
Use PrimaryButton (gradient CTA) at most once per view. Multiple gradient CTAs dilute the focal point.
Why: The gradient is a visual anchor — duplicating it creates ambiguity about the primary action.
4
1–2% gradient budget
The brand gradient (#7652B9 → #B46470 → #CA9D8C) is reserved for the single focal element per view: the primary CTA, a hover affordance, or a hero title.
Why: Gradient saturation breaks the hierarchy and reads as decorative rather than meaningful.
5
Callouts are blue, not gradient
Use --color-accent-blue (#3171FF) for selected chips, links, progress, and focus rings. Never substitute the brand gradient for these signals.
6
StatusTag success green is unique
The success tokens (--color-accent-green / --color-accent-green-bg) appear only inside StatusTag variant="success". Do not repurpose them for other UI.
Why: Reserving the color keeps "success" visually unambiguous across the product.
7
13 text styles only
Use .type-display-xl, .type-display, .type-h1, .type-h1--emphasized, .type-body, .type-body-emphasized, .type-h2, .type-h2-emphasized, .type-h3, .type-detail, .type-detail-emphasized, .type-caption, .type-footnote. Never use raw px sizes or Tailwind’s native type/weight scale (text-sm, text-base, font-bold, font-medium …). Forbidden running-text sizes: 9, 10, 13, 17, 18, 24, 28, 32 px. 11/12 are valid only via .type-footnote / .type-caption. ("13" here counts the text-style tiers — it is a coincidence that there are also 13 principles.) Implementation rule: AGENTS.md §2 #2.
See Foundations →
8
Icons = lucide-react
All icons come from lucide-react. No emoji in product UI. Never render letters or abbreviations as icon stand-ins. Never import another icon library or inline SVG. Implementation rule: AGENTS.md §2 #6.
See Foundations →
9
Dark-mode is automatic
All colors must come from CSS variables bound to :root / .dark. Monochrome PNG assets use .icon-theme for auto-inversion. Lucide SVGs inherit currentColor.
10
Three-panel shell
Every feature is a slot inside NavPanel, ConversationPanel, or InspectorPanel. Do not introduce new top-level chrome.
See Layout →
11
Review queue for new components
If an existing shared component cannot satisfy a need, build the new one in packages/design-system/src/shared.tsx and add it to the company viewer catalog. When the candidate originates in WorkPal, also register its promotion status in WorkPal's Review Queue tab. Approved components stay in shared.tsx; rejected ones revert to the closest existing primitive.
12
Bg fill or border, not both
A card / panel uses EITHER a background fill (bg-bg-hover, bg-bg-page, bg-card, etc.) OR a border (border-stroke-outline) — never both on the same surface. Pick whichever creates the right visual separation in the surrounding context. Default for an inline mini-preview, intro card, or hover zone is bg fill; default for a free-standing card on the page background is border-only. Exception: dashed borders (border-dashed) carry placeholder/skeleton/drop-zone semantics and may coexist with bg fills. Implementation rule: AGENTS.md §2 #4.
Why: Stacking bg-change + border on the same element produces a redundant double-frame — either signal alone is enough to lift the element from its surroundings. Doubling competes with surrounding chrome and breaks the design's quiet hierarchy.
13
Tab structure — Pattern A or Pattern B
Documentation tabs follow one of two structures. Pattern A: Intro card → L2 SectionTitle (OUT of box) → content WRAPPED in a single border-only box (rounded-2xl border-stroke-outline p-5); use it for Foundations, Components, Review, Layouts, and AI Interaction Patterns. Pattern B: Intro card → flat list of cards (no L2 wrapper) → each card has IN-box L3 title (16px); use it for Principles, Agent Videos, and Voice & Tone. Same-level content must look identical across tabs: every Pattern A section content uses the same box chrome; every Pattern B card uses the same chrome.
Why: Without this rule, sections drift between in-box and out-of-box across tabs (cf. App Shell vs Color Palette vs 8.X Pattern), and same-level content uses different sizes (Principles 16px vs Agent Videos 22px). The border-box wrap on Pattern A also gives the section visual closure — a SectionTitle followed by bare paragraphs reads as "loose copy", not "section content".