name: designcortex description: "DesignCortex is a perceptual frontend skill for Claude Code — exact CSS values, lookup tables, and formulas grounded in visual science so Claude stops writing averaged-out frontend code." version: 1.0.0

DesignCortex

What This Is

A lookup table for your eyes. Every value here is testable, measurable, and the result of converging evidence from Material Design 3, Apple HIG, Ant Design, Radix, and years of production frontend work. When Claude writes frontend code without these values, it averages what it has seen. That average is wrong.

Before: opacity: 0.5 on disabled buttons, box-shadow: 0 4px 6px rgba(0,0,0,0.1) everywhere, letter-spacing: normal at all sizes, hover states that are just opacity: 0.8.

After: Values that match how human eyes actually perceive contrast, depth, weight, and motion.

§1 — Typography Precision

Letter-Spacing by Size

Large type has open optical counters. Without negative tracking, it looks loose. Small type needs neutral or slightly positive tracking for legibility.

Rule: If a font has built-in optical sizing (variable font with opsz axis), reduce these adjustments by ~40%.

Line-Height by Size

As font size increases, line-height ratio decreases. Large text with 1.5 line-height looks like double-spacing.

Rule: Serif body text needs +0.05 to +0.1 more. Monospace needs +0.05 to +0.1 as well.

Font-Weight Hierarchy

Use exactly 3 weights. Not 2 (too flat), not 5 (too noisy).

Exceptions: 600 when 500 lacks contrast against 400 in a specific face. 300 only for display text 48px+ in typefaces designed for light weights. Never for UI text.

Responsive Type Scale (clamp formulas)

--font-size-body:    clamp(0.938rem, 0.875rem + 0.25vw, 1rem);
--font-size-lead:    clamp(1rem, 0.875rem + 0.5vw, 1.125rem);
--font-size-h3:      clamp(1.125rem, 0.875rem + 1vw, 1.5rem);
--font-size-h2:      clamp(1.25rem, 0.75rem + 2vw, 2rem);
--font-size-h1:      clamp(1.5rem, 0.5rem + 4vw, 3rem);
--font-size-display: clamp(2rem, -0.5rem + 8vw, 4.5rem);

Text Rendering (always apply)

body {
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-rendering: optimizeLegibility;
}

Paragraph Spacing

Space above headings > space below. This binds the heading to its content.

h2 { margin-top: 2.5em; margin-bottom: 0.75em; }
h3 { margin-top: 2em; margin-bottom: 0.5em; }
p  { margin-bottom: 1.25em; }

Optimal Reading Width

.prose { max-width: 65ch; }

Not 680px. Characters are the unit of reading comfort. ch scales with font-size.

§2 — Color Precision

State Overlay Opacities

MD3, Radix, and Ant Design converge within ±2% of these values.

Implementation:

.interactive { position: relative; }
.interactive:hover::after {
  content: ""; position: absolute; inset: 0;
  background: currentColor; opacity: 0.08;
  pointer-events: none; border-radius: inherit;
}
.disabled { opacity: 0.38; pointer-events: none; }

Dark Mode Text (halation prevention)

Pure white on dark = halation (glowing/bleeding text). Affects ~33% of population (astigmatism).

Dark Mode Surfaces (not pure black)

Dark mode elevation = lighter surface (no shadows).

Brand Color Dark Mode

Desaturate and lighten to prevent vibration:

/* Light */ --brand: oklch(55% 0.24 264);
/* Dark */  --brand: oklch(68% 0.20 264);

Use oklch() for perceptually uniform manipulation.

§3 — Spacing System

Base-4 Scale

--space-1: 4px;   --space-2: 8px;   --space-3: 12px;  --space-4: 16px;
--space-5: 20px;  --space-6: 24px;  --space-8: 32px;  --space-10: 40px;
--space-12: 48px; --space-16: 64px; --space-20: 80px; --space-24: 96px;

Component Padding Lookup

Section Spacing

Fluid Spacing

--section-gap: clamp(3rem, 2rem + 4vw, 6rem);
--container-pad: clamp(1rem, 0.5rem + 2vw, 3rem);

§4 — Shadow & Elevation

--shadow-xs:  0 1px 2px 0 rgba(0,0,0,0.05);
--shadow-sm:  0 1px 3px 0 rgba(0,0,0,0.10), 0 1px 2px -1px rgba(0,0,0,0.10);
--shadow-md:  0 4px 6px -1px rgba(0,0,0,0.10), 0 2px 4px -2px rgba(0,0,0,0.10);
--shadow-lg:  0 10px 15px -3px rgba(0,0,0,0.10), 0 4px 6px -4px rgba(0,0,0,0.10);
--shadow-xl:  0 20px 25px -5px rgba(0,0,0,0.10), 0 8px 10px -6px rgba(0,0,0,0.10);
--shadow-2xl: 0 25px 50px -12px rgba(0,0,0,0.25);

Dark mode: Shadows invisible. Use surface lightening instead.

§5 — Motion & Timing

Exit rule: Exits are faster than enters. Always. Objects arriving settle. Objects leaving get out of the way.

--ease-default: cubic-bezier(0.4, 0, 0.2, 1);
--ease-in:      cubic-bezier(0.4, 0, 1, 1);
--ease-out:     cubic-bezier(0, 0, 0.2, 1);
--ease-spring:  cubic-bezier(0.34, 1.56, 0.64, 1);

Reduced Motion (mandatory)

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

Only Animate

✓ transform, opacity, clip-path, background-color ✗ width, height, top, left, margin, padding, border-radius, box-shadow

§6 — Interactive States

Focus Ring

:focus-visible { outline: 2px solid var(--color-brand); outline-offset: 2px; }
:focus:not(:focus-visible) { outline: none; }

2px width. 2px offset. Brand color. Visible on all backgrounds.

Button States

.btn { transition: background-color 150ms ease-out, transform 100ms ease-out; }
.btn:hover { filter: brightness(0.92); }
.btn:active { transform: scale(0.97); filter: brightness(0.85); }
.btn:disabled { opacity: 0.38; pointer-events: none; }

Input States

Touch Targets

Extend tap area without visual change:

.icon-btn { position: relative; width: 24px; height: 24px; }
.icon-btn::before { content: ""; position: absolute; inset: -10px; }

§7 — Layout Formulas

Container Widths

Z-Index System

--z-dropdown: 100;  --z-sticky: 200;    --z-drawer: 300;
--z-modal-bg: 400;  --z-modal: 500;     --z-popover: 600;
--z-toast: 700;     --z-tooltip: 800;

Never use arbitrary values. Fix stacking context, don't escalate.

Aspect Ratios

.hero       { aspect-ratio: 21/9; }
.card-image { aspect-ratio: 3/2; }
.thumbnail  { aspect-ratio: 1/1; }
.video      { aspect-ratio: 16/9; }

Fluid Clamp Formula

For value MIN→MAX across viewport VP_MIN→VP_MAX:

clamp(MIN, CALC + Xvw, MAX)

Example — 16px→48px across 320px→1280px:

padding: clamp(1rem, 0.333rem + 2.08vw, 3rem);

§8 — Anti-Slop Checklist

3+ matches = the output is slop. Start over.

Typography: Inter with no justification. letter-spacing: normal on 24px+ headings. Same weight for headings and body. line-height: 1.5 on everything. No max-width on prose.

Color: Disabled at 0.5. Hover is opacity: 0.8. Pure #FFF on dark. Pure #000 dark bg. Full-saturation brand on dark.

Spacing: Mixed 16px and 15px in same view. Same spacing for sections and components. Heading margin-top ≤ margin-bottom.

Shadow: Same shadow on everything. Shadows on dark mode. Shadow + border on same element.

Motion: transition: all 0.3s ease. No prefers-reduced-motion. Same duration enter/exit. Animating width/height/margin.

Layout: z-index: 9999. No content max-width. Magic breakpoints. px fonts with no scaling.

§9 — Quick Reference

5 Values Claude Gets Wrong

1. Disabled opacity:   0.38    not 0.5
2. Hover overlay:      0.08    not "opacity: 0.8"
3. Dark mode bg:       #09090B not #000000
4. Dark mode text:     #F1F5F9 not #FFFFFF
5. Heading tracking:   -0.02em not normal

5 CSS Values That Signal Quality

1. letter-spacing: -0.02em   (headings — optical awareness)
2. opacity: 0.38             (disabled — system knowledge)
3. outline-offset: 2px       (focus — accessibility care)
4. transition: 150ms ease-out (buttons — motion intent)
5. max-width: 65ch           (prose — reading science)

§10 — Presets

Using DesignCortex with [preset], build [request].

Custom config: answer 6 questions — theme, brand color, fonts, density, radius, separation method.

DesignCortex by 0xDragoon — MIT License Not opinions. Values. Testable, measurable, perceptually grounded.