Design Guardrails¶

Five critical anti-patterns to avoid.

1. CTA Overuse¶

Problem: Multiple CTAs competing for attention.

AVOID                              INSTEAD
─────────────────────────────      ─────────────────────────────
[Save] [Export] [Share]            [Save] [Export] [Share]
  ↑       ↑        ↑                 ↑       ↑        ↑
Sage    Sage     Sage              Sage   Outline  Neutral

Rule: One Sage CTA per view — white label on deep sage-700 (light), dark label (crater-800) on light sage-400 (dark). Secondary actions go outline; tertiary go neutral.

2. Sage-on-Sage Low Contrast¶

Problem: Sage text on a Sage background fails on poor displays.

Avoid	Instead
Sage 300 on Sage 50	Silt 900 on Sage 50
`#b5cbaf` on `#f1f5ef`	`#161812` on `#f1f5ef`

Rule: Sage text on a Sage fill never clears WCAG AA — use silt-900 for contrast on light surfaces.

Contrast ratios (WCAG AA requires 4.5:1; verify with contrast-check.html):
  Sage 300 on Sage 50   → ~1.6:1  FAIL
  Silt 400 on Sage 50   → ~3.1:1  FAIL
  Silt 900 on Sage 50   → ~16:1   PASS

3. Inverting Crater and Dust¶

Problem: Crater (green-black) and Dust (warm cream) are theme-locked. Dropping a crater-900 panel into light mode creates jarring dark slabs; a Dust surface in dark mode blinds.

Avoid	Instead
`crater-900` panel in light UI	Dust surface (cream)
Dust surface in dark UI	`crater-800` / `crater-900` surface

Rule: Crater is dark-only. Dust is light-only. Never invert. Light mode is warm cream paper, never stark white; dark mode is green-black, never pure black.

Exception: Code blocks may use crater-800/crater-900 in light mode as a deliberate "terminal" affordance.

4. Mixing Signal Colors with Brand Colors¶

Problem: Using Warning gold for errors or Sage for warnings confuses semantic meaning.

Avoid	Instead
Warning gold for error state	Danger 500 (`#c44747`) for errors
Sage for warnings	Warn 500 (`#c6a23c`) for warnings
Brand colors for alerts	Dedicated semantic palette

Rule: Brand palette (Sage, Silt, Crater, Dust) is for identity. Semantic palette (Success, Warn, Danger, Info) is for system feedback.

Brand Palette (Identity)        Semantic Palette (Feedback)
─────────────────────────       ───────────────────────────
Sage → Surfaces, action         Success → Completion, valid
Silt → Text, borders            Warning → Caution, attention
Crater → Dark surfaces          Danger → Errors, destructive
Dust → Light surfaces           Info → Neutral information

5. Typography Without Hierarchy¶

Problem: All text in Silt 900 at similar sizes creates visual noise.

Avoid	Instead
Everything bold/dark	Headlines: Silt 900, Body: Silt 900, Hints: Silt 500
Same weight throughout	Headlines: 600, Body: 400, Labels: 500
Uniform sizes	Display → H1 → H2 → Body → Small

Rule: Use the full typographic scale. Muted text should be Silt 700. Hints and placeholders should be Silt 500.

Visual Hierarchy Ladder:

  ████████████████████  Display (36px, 600, Silt 900)
  ██████████████        H1 (24px, 600, Silt 900)
  ████████████          H2 (20px, 600, Silt 900)
  ██████████            H3 (16px, 600, Silt 900)
  ████████              Body (14px, 400, Silt 900)
  ██████                Muted (14px, 400, Silt 700)
  ████                  Small (12px, 400, Silt 500)

Quick Reference¶

Pattern	Allowed	Forbidden
Sage CTAs	1 per view, white on deep sage	Multiple competing
Sage text	On Crater/Dust surfaces	On Sage backgrounds
Crater surfaces	Dark mode, code blocks	Light mode main surfaces
Brand color for errors	Never	Using for semantic states
All-caps	Labels, badges only	Body text, headings