# Principles

> The 13 design principles behind Frame’s AI product interfaces, with links to the foundations, components and layouts that apply them.

Web page: https://system.beibeidesign.com/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. 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 →](https://system.beibeidesign.com/components/buttons/)
2. 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 →](https://system.beibeidesign.com/foundations/)
3. 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. 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. 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. 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. 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 →](https://system.beibeidesign.com/foundations/)
8. 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 →](https://system.beibeidesign.com/foundations/)
9. 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. 10 Three-panel shell Every feature is a slot inside NavPanel, ConversationPanel, or InspectorPanel. Do not introduce new top-level chrome. [See Layout →](https://system.beibeidesign.com/layout/)
11. 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. 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. 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".