1# Surfaces
2 
3Border radius, optical alignment, shadows, and image outlines.
4 
5## Concentric Border Radius
6 
7When nesting rounded elements, the outer radius must equal the inner radius plus the padding between them:
8 
9```
10outerRadius = innerRadius + padding
11```
12 
13This rule is most useful when nested surfaces are close together. If padding is larger than `24px`, treat the layers as separate surfaces and choose each radius independently instead of forcing strict concentric math.
14 
15### Example
16 
17```css
18/* Good — concentric radii */
19.card {
20  border-radius: 20px; /* 12 + 8 */
21  padding: 8px;
22}
23.card-inner {
24  border-radius: 12px;
25}
26 
27/* Bad — same radius on both */
28.card {
29  border-radius: 12px;
30  padding: 8px;
31}
32.card-inner {
33  border-radius: 12px;
34}
35```
36 
37### Tailwind Example
38 
39```tsx
40// Good — outer radius accounts for padding
41<div className="rounded-2xl p-2">       {/* 16px radius, 8px padding */}
42  <div className="rounded-lg">          {/* 8px radius = 16 - 8 ✓ */}
43    ...
44  </div>
45</div>
46 
47// Bad — same radius on both
48<div className="rounded-xl p-2">
49  <div className="rounded-xl">          {/* same radius, looks off */}
50    ...
51  </div>
52</div>
53```
54 
55Mismatched border radii on nested elements is one of the most common things that makes interfaces feel off. Always calculate concentrically.
56 
57## Optical Alignment
58 
59When geometric centering looks off, align optically instead.
60 
61### Buttons with Text + Icon
62 
63Use slightly less padding on the icon side to make the button feel balanced. A reliable rule of thumb is:
64`icon-side padding = text-side padding - 2px`.
65 
66```css
67/* Good — less padding on icon side */
68.button-with-icon {
69  padding-left: 16px;
70  padding-right: 14px; /* icon side = text side - 2px */
71}
72 
73/* Bad — equal padding looks like icon is pushed too far right */
74.button-with-icon {
75  padding: 0 16px;
76}
77```
78 
79```tsx
80// Tailwind
81<button className="pl-4 pr-3.5 flex items-center gap-2">
82  <span>Continue</span>
83  <ArrowRightIcon />
84</button>
85```
86 
87### Play Button Triangles
88 
89Play icons are triangular and their geometric center is not their visual center. Shift slightly right:
90 
91```css
92/* Good — optically centered */
93.play-button svg {
94  margin-left: 2px; /* shift right to account for triangle shape */
95}
96 
97/* Bad — geometrically centered but looks off */
98.play-button svg {
99  /* no adjustment */
100}
101```
102 
103### Asymmetric Icons (Stars, Arrows, Carets)
104 
105Some icons have uneven visual weight. The best fix is adjusting the SVG directly so no extra margin/padding is needed in the component code.
106 
107```tsx
108// Best — fix in the SVG itself
109// Adjust the viewBox or path to visually center the icon
110 
111// Fallback — adjust with margin
112<span className="ml-px">
113  <StarIcon />
114</span>
115```
116 
117## Shadows Instead of Borders
118 
119For **buttons, cards, and containers** that use a border for depth or elevation, prefer replacing it with a subtle `box-shadow`. Shadows adapt to any background since they use transparency; solid borders don't. This also helps when using images or multiple colors as backgrounds — solid border colors don't work well on backgrounds other than the ones they were designed for.
120 
121**Do not apply this to dividers** (`border-b`, `border-t`, side borders) or any border whose purpose is layout separation rather than element depth. Those should stay as borders.
122 
123### Shadow as Border (Light Mode)
124 
125The shadow is comprised of three layers. The first acts as a 1px border ring, the second adds subtle lift, and the third provides ambient depth:
126 
127```css
128:root {
129  --shadow-border:
130    0px 0px 0px 1px rgba(0, 0, 0, 0.06),
131    0px 1px 2px -1px rgba(0, 0, 0, 0.06),
132    0px 2px 4px 0px rgba(0, 0, 0, 0.04);
133  --shadow-border-hover:
134    0px 0px 0px 1px rgba(0, 0, 0, 0.08),
135    0px 1px 2px -1px rgba(0, 0, 0, 0.08),
136    0px 2px 4px 0px rgba(0, 0, 0, 0.06);
137}
138```
139 
140### Shadow as Border (Dark Mode)
141 
142In dark mode, simplify to a single white ring — layered depth shadows aren't visible on dark backgrounds:
143 
144```css
145/* Dark mode — adapt to whatever setup the project uses
146   (prefers-color-scheme, class, data attribute, etc.) */
147--shadow-border: 0 0 0 1px rgba(255, 255, 255, 0.08);
148--shadow-border-hover: 0 0 0 1px rgba(255, 255, 255, 0.13);
149```
150 
151### Usage with Hover Transition
152 
153Apply the variable and add `transition-[box-shadow]` for a smooth hover:
154 
155```css
156.card {
157  box-shadow: var(--shadow-border);
158  transition-property: box-shadow;
159  transition-duration: 150ms;
160  transition-timing-function: ease-out;
161}
162 
163.card:hover {
164  box-shadow: var(--shadow-border-hover);
165}
166```
167 
168### When to Use Shadows vs. Borders
169 
170| Use shadows | Use borders |
171| --- | --- |
172| Cards, containers with depth | Dividers between list items |
173| Buttons with bordered styles | Table cell boundaries |
174| Elevated elements (dropdowns, modals) | Form input outlines (for accessibility) |
175| Elements on varied backgrounds | Hairline separators in dense UI |
176| Hover/focus states for lift effect | |
177 
178## Image Outlines
179 
180Add a subtle `1px` outline with low opacity to images. This creates consistent depth, especially in design systems where other elements use borders or shadows.
181 
182### Color rules (non-negotiable)
183 
184- **Light mode**: pure black — `rgba(0, 0, 0, 0.1)`. Exact values: R=0, G=0, B=0.
185- **Dark mode**: pure white — `rgba(255, 255, 255, 0.1)`. Exact values: R=255, G=255, B=255.
186- Never use a near-black or near-white from the project palette (e.g. slate-900, zinc-900, `#0a0a0a`, `#111827`, `#f5f5f7`). Tinted outlines pick up the surrounding surface color and read as dirt on the image edge.
187- Never match the outline to the project's accent or ink color. The outline is a neutral separator, not a themed element.
188 
189### Light Mode
190 
191```css
192img {
193  outline: 1px solid rgba(0, 0, 0, 0.1);
194  outline-offset: -1px; /* inset so it doesn't add to layout */
195}
196```
197 
198### Dark Mode
199 
200```css
201img {
202  outline: 1px solid rgba(255, 255, 255, 0.1);
203  outline-offset: -1px;
204}
205```
206 
207### Tailwind with Dark Mode
208 
209```tsx
210<img
211  className="outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10"
212  src={src}
213  alt={alt}
214/>
215```
216 
217Use `outline-black/10` and `outline-white/10` specifically — not `outline-slate-*`, `outline-zinc-*`, `outline-neutral-*`, or any tinted scale.
218 
219**Why outline instead of border?** `outline` doesn't affect layout (no added width/height), and `outline-offset: -1px` keeps it inset so images stay their intended size.
220 
221## Minimum Hit Area
222 
223Interactive elements should have a minimum hit area of 44×44px (WCAG) or at least 40×40px. If the visible element is smaller (e.g., a 20×20 checkbox), extend the hit area with a pseudo-element.
224 
225### CSS Example
226 
227```css
228/* Small checkbox with expanded hit area */
229.checkbox {
230  position: relative;
231  width: 20px;
232  height: 20px;
233}
234 
235.checkbox::after {
236  content: "";
237  position: absolute;
238  top: 50%;
239  left: 50%;
240  transform: translate(-50%, -50%);
241  width: 40px;
242  height: 40px;
243}
244```
245 
246### Tailwind Example
247 
248```tsx
249<button className="relative size-5 after:absolute after:top-1/2 after:left-1/2 after:size-10 after:-translate-1/2">
250  <CheckIcon />
251</button>
252```
253 
254### Collision Rule
255 
256If the extended hit area overlaps another interactive element, shrink the pseudo-element — but make it as large as possible without colliding. Two interactive elements should never have overlapping hit areas.
257