Design Foundations

The design foundations of Tuffex are grounded in three core axioms: Physical Honesty, Sub-100ms Velocity, and Deterministic Discipline.

It governs not merely raw CSS variables, but the physical geometric, material, and optical baselines of professional desktop interaction.

Geometry & Squircles

G2 Curvature Continuity & Squircles

Standard CSS border-radius relies on circular fillets ($G^1$ tangent continuity). Curvature $\kappa$ jumps abruptly from $0$ on straight edges to $1/R$ at the fillet boundary, inducing an optical crease (the Specular Break defect).

TuffEx implements superellipses (Lamé curves / squircles) on windows and cards: $$\left| \frac{x}{a} \right|^n + \left| \frac{y}{b} \right|^n = 1 \quad (n \approx 4 \sim 5)$$ The rate of curvature change across the boundary is zero ($G^2$ continuity), delivering seamless optical continuity and eliminating corner pinching.

Concentric Radii Geometric Law

When nested containers share the same numeric radius, the corner gap expands by $\sqrt{2}$ (approximately 1.414x), creating an ungrounded, pinched visual defect. TuffEx enforces the geometric conservation law: $$R_{\text{outer}} = R_{\text{inner}} + \text{Padding}$$

Inset Clearance Against Caret Clipping

Corner curves encroach into content boxes. To prevent input carets from clipping into corner arcs, the horizontal inset must fully cover the radius: $$Padding_{\text{horizontal}} \ge R$$ Single-line text containers apply a 0.65x golden optical padding ratio, neutralizing the bottom-heavy illusion created by typographic leading.

Surfaces & Refraction

The Default to Refraction Mandate

All container components featuring a surface layer (modals, drawers, CoreBox panels, interactive cards) must strictly default to refraction. Switching to flat or mask mandates explicit manual user confirmation.

Snell's Refraction & RGB Dispersion Pipeline

TxBaseSurface leverages a GPU-accelerated SVG Displacement Map filter simulating Snell's Law as light traverses crystal prisms. Red, Green, and Blue channels carry asymmetric angular offsets, separating subtle spectral dispersion fringes along refracted contours.

120Hz Fallback & 140ms Elastic Recovery

During 120Hz window dragging, complex shaders drop instantaneously (0ms) to an ultra-lightweight mask, zeroing GPU load in one frame. Once motion ceases, the system applies 140ms damped recovery, harmonizing material fidelity with smooth tracking.

Color Science & Dark Palette

#141414 Canvas & 3-Tier Elevation

Why reject pure black #000000?

1. Preventing OLED Purple Smearing: Switching OLED pixels off introduces latency, creating purple ghosting streaks when scrolling.
2. Preserving Shadow Elevation: Shadows must physically register darker than the background. #141414 provides depth headroom for cast shadows.
3. Three-Tier Elevation: Canvas --tx-bg-color: #141414, Container --tx-fill-color-blank: #1c1c1e, Elevated --tx-fill-color-light: #252528.

Dark Mode Retinal Bloom Weight Compensation

Under the Helmholtz optical irradiation effect, white strokes over dark canvases bleed into the retina, appearing 10%–15% bolder than light mode equivalents. Under variable font environments, TuffEx calibrates dark weights downward:

• Body copy: 400 (Light) $\to$ 380–400 (Dark)
• Inline emphasis: 500 (Light) $\to$ 460 (Dark)
• Headings: 600 (Light) $\to$ 560 (Dark)

color-mix Ink Fusion & WCAG 4.5:1

Semantic text never uses isolated raw hues; it blends dynamically with primary ink: color: color-mix(in srgb, var(--tx-color-danger) 55%, var(--tx-text-color-primary)). Contrast ratios consistently clear 4.58:1 – 4.81:1 across themes, ensuring strict WCAG 2.1 AA compliance.

Typography & 13–14px Baseline

• 13px–14px Productivity Anchor: Desktop productivity tools avoid oversized marketing typography, keeping crucial context within the human 2-degree foveal vision window.
• Monospace 0.9em Optical Scale: Code typefaces carry 15% taller x-heights; inline <code> scales to 0.9em to preserve typographic line rhythm.
• Modern Soft Line Breaks: Long prose uses text-wrap: pretty to eliminate terminal orphans; short titles use text-wrap: balance; hardcoded <br> tags are banned.
• Zero Tracking on Body Copy: Modifying body letter-spacing destroys font kerning pairs and impairs reading velocity.

Micro-Motion & Micro-Interactions

• Motion as Spatial Anchors: Micro-interactions resolve within 90ms–180ms; animations must never block user keystrokes or clicks.
• 0ms Instant Hover: Transitioning colors on :hover is banned (preventing sluggish lag); semantic shifts isolate transitions to .is-morphing.
• 90ms+90ms Confirmation Rhythm: Menus apply a two-beat feedback rhythm (90ms clear highlight + 90ms active pulse) before closing.
• Four Compositor Properties: Confined strictly to translate, scale, rotate, and opacity; variables are banned in keyframes; dual alternating keyframe names eliminate reflow.

AI Streaming & Anti-Jitter

• useStreamPacer Cadence: Releases units at 24ms intervals with a 600ms latency ceiling, smoothing network burstiness.
• Twin-Layer Reserve Mirror: Pre-measures full grid heights, eliminating stream height jitter and scrollbar twitching.
• Immediate Text Selection & Copying: Release tokens are standard DOM text nodes; users can drag-select and trigger Cmd+C at any millisecond without waiting.

Color System Tokens

Brand + semantic

Primary ramps

Text color and accessibility baseline

Backgrounds and borders

Implementation & Extended Concepts

• Style Source: packages/tuffex/packages/components/style/variables.scss, exported through @talex-touch/tuffex/base.css.
• Extended Architecture Manual: For in-depth mathematical derivations and physics models, see apps/nexus/content/docs/dev/concepts/.