veza/apps/web/docs/DESIGN_DIRECTION.md

Design Direction: SUMI — « Encre, pas néon »

Last Updated: 2026-02-12 Status: Active Design Direction Purpose: Define the SUMI design philosophy for the Veza application

Overview

SUMI is a design philosophy rooted in the sumi-e (墨絵) ink wash painting tradition. The guiding motto is:

« Encre, pas néon » — Ink, not neon.

Three pillars:

1. Surgical Minimalism — Every visual element serves a function. If it doesn't inform, guide, or delight purposefully, it doesn't belong.
2. Purposeful Design — Color, motion, and spacing are intentional tools, never decoration.
3. Texture over effect — Depth comes from paper grain, ink wash gradients, and warm neutrals — not from glows, neon pulses, or flashy transforms.

Core Principles

1. Sumi-e Metaphor

The UI draws from ink wash painting:

• Paper grain: subtle texture through warm neutral backgrounds (--sumi-bg-base, --sumi-bg-raised, --sumi-bg-wash). Light theme evokes washi paper (--sumi-bg-void: #f0ece4).
• Ink wash gradients: depth built with opacity layers and glass effects (--sumi-glass-bg), not solid neon colors.
• Pigments, not neon: four earth-toned accent pigments — Accent (slate blue #7c9dd6), Vermillion (brick red #d4634a), Sage (muted green #7a9e6c), Gold (warm ochre #c9a84c). Each used sparingly and intentionally.

2. Color: Warm Neutrals, Muted Pigments

Principle: Warm neutral surfaces, muted earth-toned pigments for accents, high contrast text.

• Backgrounds: Warm dark neutrals with subtle blue-violet undertones (#0c0c0f → #1a1a1f → #222228), not pure black.
• Text: Warm off-white (--sumi-text-primary: #f0ede8) for primary, stone gray (--sumi-text-secondary: #a8a4a0) for secondary. High contrast, WCAG AA compliant.
• Accents: Used only for primary actions, active states, semantic status. Never decorative fills.

Implementation:

• Primary actions: --sumi-accent (buttons, active states, focus rings)
• Secondary actions: --sumi-bg-hover / --sumi-border-default
• Semantic: --sumi-success (sage), --sumi-warning (gold), --sumi-error (vermillion)
• Decorative elements: neutral backgrounds only

3. Typography: Inter + Space Grotesk

Role	Font	Token
Body text	Inter	--sumi-font-body
Headings	Space Grotesk	--sumi-font-heading
Code / mono	JetBrains Mono	--sumi-font-mono
Serif accents	Noto Serif JP	--sumi-font-serif

Text sizes follow SUMI scale: --sumi-text-xs (0.75rem) through --sumi-text-4xl (2.25rem), with --sumi-text-base at 0.875rem.

Hierarchy:

• Headings: --sumi-text-primary + --sumi-font-heading + --sumi-weight-semibold
• Body: --sumi-text-primary + --sumi-font-body + --sumi-weight-regular
• Secondary/metadata: --sumi-text-secondary or --sumi-text-tertiary, sparingly

4. Whitespace & Readability

Principle: Generous whitespace improves visual hierarchy and reduces cognitive load.

Spacing tokens (SUMI scale in index.css):

• --sumi-space-2 (8px) — base unit
• --sumi-space-4 (16px) — standard gap
• --sumi-space-6 (24px) — section gap
• --sumi-space-8 (32px) — card padding, large section spacing
• --sumi-space-12 (48px) — page-level spacing
• --sumi-space-16 (64px) — major separations

Layout gaps:

• --layout-gap (1rem), --layout-gap-sm (0.75rem), --layout-gap-lg (1.5rem)

5. Subtle, Purposeful Interactions

Principle: Hover effects and animations should be functional, not decorative.

Keep (functional):

• Background color changes: hover:bg-[var(--sumi-bg-hover)] for interactive feedback
• Opacity changes: group-hover:opacity-100 for functional overlays (play buttons)
• Border color changes: hover:border-[var(--sumi-border-strong)]
• Text color changes: hover:text-[var(--sumi-text-primary)]
• Transition timing: --sumi-duration-fast (150ms) for colors, --sumi-duration-normal (200ms) for transforms
• Easing: --sumi-ease-default or --sumi-ease-out

Anti-patterns (NEVER do):

• ❌ Scale transforms on hover: no hover:scale-[1.02], hover:scale-105, hover:scale-110
• ❌ Neon glows: no shadow-[0_0_15px_rgba(0,255,255,...)], no shadow-neon-*
• ❌ Decorative animations: no pulsing, no bouncing, no breathing effects for aesthetics
• ❌ Multiple simultaneous effects: no scale + shadow + border combos
• ❌ Image zoom on hover: no group-hover:scale-110 on decorative images

6. Surfaces & Elevation

Depth is conveyed through background layers and shadows, not glows:

Level	Token	Usage
Void	--sumi-bg-void	Page background
Base	--sumi-bg-base	Main content area
Raised	--sumi-bg-raised	Sidebar, cards
Overlay	--sumi-bg-overlay	Dropdowns, popovers
Glass	--sumi-glass-bg + blur	Header, player bar

Shadows (SUMI scale): --sumi-shadow-xs through --sumi-shadow-2xl. Use sparingly — one shadow level per element. --sumi-shadow-glow reserved for focus rings only.

7. Gradients: Functional Only

Keep:

• Functional overlays for text readability: bg-gradient-to-t from-black/80
• Hero sections (featured content, landing)
• Glass effects (via --sumi-glass-bg + backdrop-blur)

Remove:

• Card backgrounds: use solid --sumi-surface-card
• Decorative section backgrounds
• Hover overlays: use solid colors with opacity

Sub-Themes: Contextual Accents

Sub-themes are contextual accent overrides, not global theme replacements. They provide feature-specific color accents while the core SUMI palette stays constant.

Sub-theme	Accent	Token	Context
Nature	Sakura pink	--sakura: #e0a0b8	Nature/ambient content
Graffiti	Magenta	--graffiti-magenta: #c840a0	Urban/graffiti features
Gaming	Gold	--gaming-gold: #d4b040	Gaming-related features
Terminal	Green	--terminal-green: #3eaa5e	Developer/terminal features
Music	Default accent	--sumi-accent	Core music experience

Rules:

• Sub-themes affect only their feature area, not the global shell
• Core backgrounds, text colors, and border tokens remain SUMI
• A sub-theme overrides --sumi-accent locally, nothing else

Anti-Patterns Reference

These patterns contradict SUMI and must be avoided:

Anti-pattern	Why	Alternative
hover:scale-[1.02]	Decorative, not functional	hover:bg-[var(--sumi-bg-hover)]
shadow-neon-cyan/20	Neon aesthetic, not ink	--sumi-shadow-sm
bg-gradient-to-r from-cyan to-blue	Neon gradient	Solid --sumi-surface-card
animate-pulse on decorative elements	Distracting	Static or --sumi-transition-opacity
text-cyan-400 / text-kodo-cyan	Old Kodo neon palette	--sumi-accent or --sumi-text-link
bg-kodo-void / bg-kodo-ink	Old Kodo tokens	--sumi-bg-void / --sumi-bg-base
Class-based theme toggle (dark:)	Stale pattern	[data-theme] attribute

Implementation Checklist

When applying SUMI to a component or page:

Color & Surface

• Backgrounds use SUMI tokens (--sumi-bg-*, --sumi-surface-*)
• Text uses --sumi-text-primary (not text-white or text-kodo-*)
• Accents use --sumi-accent family (not kodo-cyan)
• Semantic colors use --sumi-success, --sumi-warning, --sumi-error
• No neon colors, no kodo-* tokens
• Cards use --sumi-surface-card (solid, no gradient)

Spacing & Layout

• Spacing uses SUMI scale (--sumi-space-*) or Tailwind equivalents
• Layout uses SUMI layout tokens (--sumi-max-width, --sumi-header-height, etc.)
• Generous whitespace between sections

Interactions

• Hover effects are subtle: background/opacity/border color only
• No scale transforms on interactive elements
• No decorative shadows or glows on hover
• Transitions use --sumi-duration-fast / --sumi-ease-default

Typography

• Body text uses --sumi-font-body (Inter)
• Headings use --sumi-font-heading (Space Grotesk)
• Text sizes follow SUMI scale (--sumi-text-*)
• Text contrast meets WCAG AA

Glass & Elevation

• Glass surfaces use --sumi-glass-bg + backdrop-blur
• Shadows use SUMI scale (--sumi-shadow-*)
• Focus rings use --sumi-shadow-glow

Theme Compatibility

• Component works with [data-theme="dark"] and [data-theme="light"]
• No hardcoded colors that break in light theme
• Borders use --sumi-border-* tokens

Examples

✅ Good: SUMI Applied

// Card with SUMI tokens
<Card className="bg-[var(--sumi-surface-card)] border border-[var(--sumi-border-faint)] p-8
  hover:bg-[var(--sumi-bg-hover)] transition-colors duration-[var(--sumi-duration-fast)]">
  <CardHeader>
    <CardTitle className="text-[var(--sumi-text-primary)] font-heading">Title</CardTitle>
  </CardHeader>
  <CardContent>
    <p className="text-[var(--sumi-text-secondary)]">Content</p>
  </CardContent>
</Card>

// Button with SUMI accent
<Button className="bg-[var(--sumi-accent)] text-[var(--sumi-text-inverse)]">
  Primary Action
</Button>
<Button variant="outline" className="border-[var(--sumi-border-default)]
  hover:border-[var(--sumi-border-strong)]">
  Secondary Action
</Button>

❌ Avoid: Anti-SUMI Patterns

// Neon glow + scale transform + gradient
<Card className="bg-gradient-to-r from-kodo-ink to-kodo-graphite
  hover:scale-[1.02] hover:shadow-neon-cyan/20">
  {/* ❌ Gradient bg, scale, neon glow */}
</Card>

// Kodo tokens (deprecated)
<Button className="bg-kodo-cyan text-black">
  {/* ❌ Use --sumi-accent instead */}
</Button>

// Decorative animation
<div className="animate-pulse bg-cyan-500/20">
  {/* ❌ Neon color + decorative animation */}
</div>

Migration Path

Completed

1. ✅ SUMI token system defined in index.css (:root + [data-theme="light"])
2. ✅ Theme switching migrated from class to [data-theme] attribute
3. ✅ Typography tokens: Inter (body) + Space Grotesk (headings) + JetBrains Mono (code)
4. ✅ Glass effects on header and player bar
5. ✅ Shadow and z-index scales defined
6. ✅ Contextual accent tokens (graffiti, gaming, terminal, sakura)

In Progress

• Component migration from kodo-* tokens to --sumi-* tokens
• Audit and removal of remaining neon glows and scale transforms
• Light theme (Washi Paper) refinement

Future Work

• Enforce SUMI tokens via linting rules
• Paper grain texture as optional background layer
• Ink wash gradient presets for hero/feature sections
• Sub-theme contextual scoping

References

• SUMI tokens source: apps/web/src/index.css — :root and [data-theme="light"]
• App Shell layout: apps/web/docs/APP_SHELL.md
• Design Tokens doc: apps/web/docs/DESIGN_TOKENS.md
• Storybook contract: apps/web/docs/STORYBOOK_CONTRACT.md

Benefits

User Experience:

• Reduced cognitive load — warm neutrals are easier on the eyes
• Improved readability — high contrast text, generous whitespace
• Better visual hierarchy — depth through layers, not decoration
• Professional, distinctive aesthetic — ink wash, not neon

Developer Experience:

• Single token system (--sumi-*) — no ambiguity between old/new tokens
• Clear anti-patterns — easy to audit and enforce
• Consistent patterns across dark and light themes
• Meaningful names tied to the sumi-e metaphor

Accessibility:

• WCAG AA compliant contrast ratios
• Clear focus states (--sumi-shadow-glow)
• Reduced visual noise and motion
• Functional-only interactions