Design Fundamentals
Reference principles for any Bee agent producing, evaluating, or documenting UI work. These apply universally — the target project's design system provides specific values on top of these.
Two-Path Design Flow
Before applying any design principle, determine which path you're on:
Path A — Existing Design System: The project has design tokens, Tailwind config, CSS custom properties, or a component library. Follow what exists. Never override. Never suggest alternatives. Extract, document, and ensure new work is consistent with the established system.
Path B — Greenfield (No Design System): No design system detected. Run a design discovery with the developer using AskUserQuestion before making any visual decisions. See the Design Discovery section below.
Priority System
When design concerns conflict, resolve by priority:
| Priority | Category | Severity |
|---|
| 1 | Accessibility | CRITICAL |
| 2 | Performance | HIGH |
| 3 | Layout & Responsive | HIGH |
| 4 | Typography & Color | MEDIUM |
| 5 | Animation & Transitions | MEDIUM |
| 6 | Style & Visual Polish | LOW |
Accessibility always wins. A beautiful animation that breaks keyboard navigation is a defect, not a feature.
Accessibility
Non-negotiable minimums:
- Color contrast: 4.5:1 ratio for normal text, 3:1 for large text (WCAG AA)
- Touch targets: 44x44px minimum for interactive elements
- Focus visibility: every interactive element must have a visible focus indicator — never remove outline without replacing it
- ARIA landmarks: use semantic HTML (
nav, main, aside, footer) before reaching for ARIA roles
- Alt text: meaningful images get descriptive alt text, decorative images get
alt=""
- Keyboard navigation: all interactive elements reachable and operable via keyboard
- Color-blind safety: never rely on color alone to convey meaning. Status indicators (success, error, warning), form validation, charts, and badges must pair color with a secondary signal — icon, label, pattern, or shape. Test against deuteranopia (red-green, ~8% of men) and protanopia.
- Motion: respect
prefers-reduced-motion — disable or reduce animations when set
Design Discovery (Greenfield Only)
When no existing design system is found, discover the developer's intent before proposing anything. Use AskUserQuestion for each decision.
1. Mood / Tone
Ask: "What visual feel are you going for?"
Options should be contextual to the app, but examples: "Clean & Minimal" / "Bold & Vibrant" / "Warm & Approachable" / "Editorial & Refined"
2. Color Palette
Search online for color combinations from Sanzo Wada's Dictionary of Color Combinations that match the mood and the app's domain. Sanzo Wada was a Japanese artist who cataloged harmonious color combinations — these palettes are distinctive, curated, and avoid generic AI defaults.
- Search for combinations that fit the mood (e.g., "Sanzo Wada warm earthy combinations" or "Sanzo Wada cool editorial palette")
- Present 3-4 palette options to the developer via AskUserQuestion, showing the hex values and a brief description of each palette's character
- The developer picks one, and you derive primary, secondary, accent, and neutral colors from it
- Always verify contrast: proposed text/background combinations must pass WCAG AA (4.5:1 for normal text)
3. Typography
Ask about font character, not specific font names. The tone informs the pairing:
- Minimal/Clean: geometric sans (heading) + humanist sans (body)
- Editorial/Refined: serif with character (heading) + clean sans (body)
- Bold/Vibrant: strong display font (heading) + readable sans (body)
- Warm/Approachable: rounded sans or soft serif (heading) + friendly body font
Present 2-3 specific pairings via AskUserQuestion based on the chosen tone. Avoid generic defaults — see Anti-Generic Rules below.
4. Component Style
Ask: "What shape language fits your product?"
Options: "Rounded & soft" / "Sharp & geometric" / "Mixed (rounded buttons, sharp cards)"
This informs border-radius, shadow usage, and border style across all components.
5. Execution Pattern
The chosen mood maps to concrete CSS patterns. Present this as part of the design brief — it gives the programmer agent specific techniques, not just adjectives.
- Clean & Minimal: generous whitespace, subtle
box-shadow (0 1px 3px rgba(0,0,0,0.08)), thin borders (1px solid), muted backgrounds, no gradients, precision spacing
- Bold & Vibrant: saturated colors, layered shadows for depth, noise/grain textures (
background-image: url(noise.svg)), geometric patterns, strong borders, high-contrast type
- Warm & Approachable: soft shadows (0 4px 12px rgba(0,0,0,0.06)), rounded corners (8-16px), warm neutral backgrounds, illustration-friendly layouts, generous padding
- Editorial & Refined: dramatic type scale (large headings, small body), generous negative space, minimal color (near-monochrome + one accent), serif headings, strong vertical rhythm
Typography
Hierarchy
- Size and weight create hierarchy. A clear type scale (e.g., 12/14/16/20/24/32px) creates visual hierarchy without relying on color or decoration.
- Line height: 1.4-1.6 for body text, 1.1-1.3 for headings.
- Measure (line length): 45-75 characters per line for body text.
- Weight progression: regular for body, semibold for subheadings, bold for headings.
Pairing
- Two fonts maximum. One display/heading font, one body font. They should contrast in style but share a visual quality (both geometric, both humanist, etc.)
- The heading font carries personality. It can be distinctive and characterful.
- The body font carries readability. It should be clean and comfortable at small sizes.
Spatial Composition
Spacing Scale
- Consistent scale: spacing follows a base unit (e.g., 4px: 4/8/12/16/24/32/48/64). Random values (13px, 17px) signal unintentional design.
- Spacing creates grouping: elements that belong together have less space between them (Gestalt proximity).
- Vertical rhythm: consistent spacing between sections. Headers get more space above than below.
Grid Systems
Use a structural grid for layout consistency:
- 12-column grid is the default for web layouts — flexible enough for 1, 2, 3, 4, or 6 column arrangements
- CSS Grid or Flexbox — use Grid for two-dimensional layouts (rows + columns), Flexbox for one-dimensional flow
- Max-width container — constrain content width (e.g.,
max-width: 1200px; margin: 0 auto) to prevent lines from stretching on wide screens
- Gutter consistency — use the spacing scale for gutters (e.g., 16px or 24px). Don't mix gutter sizes within the same layout level.
- Grid-breaking elements draw attention. A full-bleed image, an oversized heading, or an element that overlaps its container — used sparingly, these create memorable moments.
Layout
- Generous negative space signals confidence and clarity. Don't fill every pixel.
- Asymmetry is intentional. Centered layouts are safe but predictable. Off-center compositions, unequal columns, and staggered grids create visual interest when done deliberately.
- Density matches context. Data-heavy dashboards need density. Marketing pages need breathing room. Match spatial treatment to what the content demands.
Progressive Disclosure
Manage cognitive load by showing less and revealing more on demand. This applies to any UI with moderate-to-high information density.
- Show the essential, hide the rest. Settings pages, dashboards, and complex forms benefit from collapsible sections, tabs, or "show advanced" toggles.
- Prioritize by frequency of use. The most common actions should be visible. Rare actions go behind a menu or expandable section.
- Multi-step over mega-form. A wizard/stepper with 3 focused steps beats a single page with 20 fields. Each step should feel completable.
- Progressive detail in data. Tables and lists show summary rows; clicking reveals detail. Cards show headline + key metric; expanding shows the full picture.
- Don't hide critical actions. Save, submit, delete, and primary CTAs should always be visible — never behind a disclosure pattern.
Color & Theme
- 60-30-10 distribution: apply your palette with intention — 60% dominant color (backgrounds, large surfaces), 30% secondary (cards, sections, supporting elements), 10% accent (CTAs, highlights, active states). This prevents the "everything is the same color" problem and gives the accent real impact.
- Dominant + accent: a strong primary color with a sharp accent outperforms timid, evenly-distributed palettes.
- Use CSS variables for all color values. Never hardcode hex values in components.
- Semantic colors: define success, warning, error, info independently from brand palette.
- Dark/light considerations: if the app needs both themes, design the token system for it from the start — not as an afterthought.
Motion & Interaction
- Transitions: 150-300ms for UI feedback (fast enough to feel responsive, slow enough to notice).
- High-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions.
- Hover and focus states: every interactive element should respond to hover and show clear focus. These aren't optional polish — they're usability.
- Prefer CSS-only for simple transitions. Reach for animation libraries only for complex orchestration.
- Respect
prefers-reduced-motion: disable or simplify all animations when set.
Anti-Generic Rules
Avoid these common AI defaults that make every project look the same:
- Fonts: Do not default to Inter, Roboto, Arial, or system fonts for every project. Choose fonts that match the project's personality.
- Colors: Do not default to purple gradients on white backgrounds, or blue-to-purple hero sections. Derive colors from the design discovery or existing system.
- Layouts: Do not default to centered card grids, hero-with-CTA-below, or three-column feature sections unless the content specifically calls for them.
- Components: Do not default to the same rounded-corner cards with subtle shadows everywhere. Match component style to the project's shape language.
- Variety: No two projects should look the same. The design discovery exists to produce context-specific choices, not to converge on safe defaults.
Responsive Breakpoints
| Breakpoint | Width | Target |
|---|
| Mobile | 375px | Phones (portrait) |
| Tablet | 768px | Tablets, large phones (landscape) |
| Desktop | 1024px | Small laptops, tablets (landscape) |
| Wide | 1440px | Desktop monitors |
- Mobile-first: start with the smallest layout and add complexity at larger sizes.
- Content-driven breakpoints: if a layout breaks at 920px, add a breakpoint at 920px.
- Test at boundaries: 375px, 768px, 1024px, 1440px.
Visual Quality Checklist
Quick checks before shipping UI work:
Applying These Principles
When running design discovery (design-agent, greenfield path):
- Follow the Design Discovery flow: mood → Sanzo Wada palette search → typography pairing → component style. Use AskUserQuestion for every decision.
When documenting an existing design system (design-agent, existing path):
- Use the accessibility, typography, and spacing sections as the reference frame for what to extract. Never suggest alternatives to what exists.
When writing specs (spec-builder):
- These principles inform design-aware ACs. "CTA button meets 44x44px touch target minimum" is an AC grounded in this skill.
When coding UI (programmer):
- Follow the anti-generic rules. Use CSS variables. Match the design brief. If no brief exists, flag it — don't invent a design system on the fly.
When reviewing (verifier, reviewer):
- Check UI work against the priority system. Accessibility issues are blockers. Style issues are suggestions.