# Design Knowledge: Figma, Design Systems & Generative Design

Compiled from Figma best practices, Vercel Geist, Linear Method, Material Design 3, and computational design research.

---

## 10. Figma-Specific Knowledge

### Auto-Layout Principles
RULE: When using Figma auto-layout (equivalent to CSS flexbox):
- **Direction**: Horizontal for nav items, buttons, inline groups; Vertical for page sections, form fields, lists
- **Gap**: Use spacing tokens (8, 12, 16, 24px) — never arbitrary values
- **Padding**: Apply consistent padding per component density (16px standard, 24px spacious, 8px compact)
- **Fill Container vs Hug Contents**: Fill for stretch-to-parent elements (content areas, sidebar items), Hug for intrinsic-size elements (buttons, tags, badges)
- **Absolute positioning**: Use only for overlays, badges on cards, and decorative elements that should ignore flow

### Figma Variables/Tokens
RULE: When setting up Figma variables:
- **Color tokens**: Define as semantic layers (primary, secondary, accent, success, error, warning) not as literal names (blue-500). Alias primitive values to semantic names.
- **Spacing tokens**: Define 4, 8, 12, 16, 20, 24, 32, 48, 64, 96px as number variables
- **Modes**: Create light/dark modes for all color tokens; optionally compact/comfortable for spacing
- **Aliasing**: `--button-primary-bg` → `--color-primary-500` (semantic → primitive) because this indirection allows theme changes by swapping one set of primitives

### Figma Component Architecture
RULE: When building components in Figma:
- **Base components**: Build smallest units first (Button, Input, Badge)
- **Variants**: Use variant properties for state (default, hover, active, disabled), size (sm, md, lg), and type (primary, secondary, ghost)
- **Component properties**: Expose text content, boolean visibility (show icon?), and instance swap (icon selection) as editable properties
- **Naming**: Use slash notation for categories: `Button / Primary / Large`, `Input / Text / Error`

### Figma Design Token Standards (W3C DTCG)
RULE: When exporting tokens for code, use the W3C Design Tokens Community Group format:
```json
{
  "color": {
    "primary": {
      "$value": "#F5A623",
      "$type": "color",
      "$description": "SANDCODE amber primary"
    }
  },
  "spacing": {
    "md": {
      "$value": "16px",
      "$type": "dimension"
    }
  }
}
```
because this standard format enables interoperability between Figma, Style Dictionary, and code frameworks.

### Figma-to-Code Workflow
RULE: When converting Figma designs to code:
1. Extract tokens first (colors, spacing, typography) → CSS custom properties / Tailwind config
2. Build atomic components (Button, Input) → React/Vue components matching variants
3. Compose molecules (SearchBar = Input + Button) → compound components
4. Build pages from compositions → route-level components

### Figma Responsive Design
RULE: When designing responsive in Figma:
- Create separate frames for mobile (375px), tablet (768px), desktop (1280px)
- Apply constraints: left/right/center/scale for absolute-positioned elements
- Use auto-layout with wrap for fluid grids
- Test component behavior at all three widths, not just desktop

---

## 11. Design Systems from Top Companies

### Stripe
**Core rules:**
1. Mathematical typography — precise type scale with consistent ratios
2. Restrained color use — minimal accent colors, predominantly neutral with one strong accent
3. Data-dense but scannable — information architecture with clear hierarchy
4. Micro-copy precision — every label, error message, and tooltip is carefully crafted
5. Smooth but not flashy — animations are subtle (200-300ms), never distracting

### Linear
**Core rules:**
1. Speed-feeling UI — information density optimized for keyboard-first workflows
2. Three-font stack: serif-display (headings) + InterVariable (UI) + monospace (code/data)
3. Dark-first design — default theme is dark, light is secondary
4. Spacing tokens: 6, 12, 16, 24, 32, 64, 128px — geometric progression
5. 160ms ease-out-quad transitions — fast enough to feel snappy, slow enough to perceive

### Vercel
**Core rules:**
1. Minimalism enforced — maximum 3 visual elements per section
2. Dark-first aesthetic — terminal/developer identity through dark backgrounds
3. Geist font family (Sans + Mono) — custom typeface as brand identity
4. 200ms color transitions — consistent micro-interaction timing
5. CSS custom property token system (--ds- prefix) — 55 components, all tokenized
6. Grid system is "a huge part of the new Vercel aesthetic" — intentional grid as visual element

### Apple HIG
**Core rules:**
1. Clarity — content is primary, UI serves content
2. Deference — UI recedes, content advances
3. Depth — layers and motion communicate hierarchy
4. Consistency — system patterns across all apps
5. Progressive typography: 48→40→32px across breakpoints, tighter tracking at large sizes

### Notion
**Core rules:**
1. Text-first — the content IS the interface
2. Minimal chrome — borders and backgrounds only when needed
3. Block-based architecture — every content unit is a discrete, composable block
4. Keyboard-first — slash commands, markdown shortcuts drive creation
5. Function over form — design serves the workflow, not aesthetics

### Figma (their own product)
**Core rules:**
1. Tool UI density — maximize workspace, minimize chrome
2. Professional feel — no playful animations, precise and predictable interactions
3. Layered panels — context-sensitive properties appear based on selection
4. Collaborative affordances — multi-cursor visibility, real-time presence indicators
5. Component system — their product IS design systems, so their own system is exemplary

### GitHub
**Core rules:**
1. Information density — code-first interfaces show maximum useful data
2. Monospace as default — code contexts use mono, prose uses sans-serif
3. Accessibility-first — high contrast, keyboard navigation, screen reader support
4. Progressive disclosure — details hidden until needed (diff expand, comment fold)

### Material Design 3 (Google)
**Core rules:**
1. Dynamic color — entire palette generated from a single seed color using OKLCH math
2. Tonal palette — 13 tonal stops from lightest to darkest for each hue
3. Three color roles: primary (main brand), secondary (supporting), tertiary (accent)
4. Elevation system — shadow + tonal surface colors communicate depth without explicit shadows
5. Duration standards: 235ms (opacity), 500ms (position), easing: cubic-bezier(.4,0,.2,1)

### Radix/Shadcn Pattern
**Core rules:**
1. Unstyled primitives — behavior without opinionated visuals
2. Composable — complex components built from simple primitives
3. Accessible by default — ARIA roles, keyboard navigation built in
4. CSS variables for theming — override colors/spacing without touching component code

---

## 12. Generative & Computational Design

### Seed-Based Deterministic Design
RULE: When generating design identity from project context:
1. Hash project name + category to a number (e.g., DJB2 hash)
2. Map hash to OKLCH hue (0-360) — unique base color per project
3. Generate 10-shade palette (L from 0.15 to 0.95, constant C and H)
4. Derive accent: shift H by harmonious interval (±120° triadic, ±150° split-complementary)
5. Generate spacing scale from 4px or 8px base
6. Select type scale ratio from category: 1.125 (tools), 1.250 (marketing), 1.333 (editorial)
because deterministic generation from seed ensures uniqueness and consistency without model "creativity."

### Procedural Color Generation — OKLCH Method
RULE: When generating a complete palette programmatically:
```
Input: seed string, category
1. hue = hash(seed) % 360
2. chroma = 0.15 (muted/professional) or 0.25 (vibrant/startup) based on category
3. base = oklch(0.5, chroma, hue)
4. shades[0-9] = oklch(0.15 + i*0.09, chroma * (1 - abs(i-5)*0.05), hue)
5. accent_hue = (hue + 150) % 360  // split-complementary
6. accent = oklch(0.55, chroma * 1.2, accent_hue)
7. neutrals = oklch(0.1 to 0.95, 0.01, hue)  // tinted grays
```

### Anti-Randomness — Why Randomness Produces Bad Design
RULE: When generating design, NEVER use random color/layout/typography values because randomness lacks the harmonic relationships that make design cohesive. Instead use:
- **Constrained generation**: values drawn from mathematically related sets (golden ratio, complementary hues)
- **Seeded variation**: deterministic from project identity, different per project but internally consistent
- **Harmonic relationships**: spacing follows geometric progression, colors follow harmony algorithms, type follows modular scale

### Parametric Typography
RULE: When generating type scales, compute from base size and ratio:
```
base = 16px (mobile) / 18px (desktop)
ratio = category_ratio (1.125 for tools, 1.250 for marketing)
h1 = base * ratio^4  (≈ 28px mobile / 44px desktop at 1.250)
h2 = base * ratio^3
h3 = base * ratio^2
h4 = base * ratio^1
body = base
small = base / ratio
```

### Responsive Breakpoint Calculation
RULE: When generating breakpoints from content width:
- Content width = 680-760px (optimal reading)
- Sidebar = 240-280px (navigation)
- Total min = 920-1040px (content + sidebar)
- Therefore: mobile < 768px, tablet 768-1024px, desktop > 1024px
- Full-bleed sections: always 100%, inner container respects content max-width

### Constraint-Based Design Validation
RULE: When validating generated design, enforce these hard constraints:
- Minimum contrast ratio: 4.5:1 (AA) for body text, 3:1 for large text
- Maximum font weights: 3 (400, 500, 700)
- Maximum colors: 1 primary + 1 accent + 10 neutrals + semantic (success/error/warning)
- Minimum touch targets: 44x44px
- Maximum section spacing: 128px desktop, 64px mobile
- Maximum animation duration: 1000ms
- Forbidden: purple gradients on white, 3-column icon grids, Inter/Roboto as sole font

### Existing Generative Design Tools
RULE: When evaluating existing tools for reference:
- **Figma Variables + Modes** — token-driven theming, not generation
- **Material Theme Builder** — OKLCH-based palette from single color, closest to what we need
- **Realtime Colors (realtimecolors.com)** — preview palette on real UI
- **Happy Hues (happyhues.co)** — curated color pairings, not generation
- **Open Props (open-props.style)** — CSS custom property design system
- **Tailwind CSS** — utility-first with constrained spacing/color scales
None of these generate complete design from seed. This is the gap SANDCODE fills.
