palace-ui 0.0.0-stage → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/SPEC.md ADDED
@@ -0,0 +1,751 @@
1
+ # Palace UI — Design Specification
2
+
3
+ > AI-first design spec. When building UIs for projects that use Palace UI,
4
+ > follow this document exactly. Include `palace.css` and write HTML using
5
+ > these classes. Do not invent new patterns — use what's here.
6
+
7
+ ## Philosophy
8
+
9
+ - **Retro-technical.** Hard edges (border-radius: 0 everywhere), thick 2px borders, chunky offset box-shadows. Gradients on text, thin decorative stripes (≤3px), and narrow fixed bars (e.g. sticky CTAs) only — never on large surfaces or card backgrounds.
10
+ - **Three-color accent system.** Hot pink `#ff2d9b`, electric purple `#5b4cff`, cyan `#00e5ff`. These rotate across card lists and provide visual rhythm.
11
+ - **Snappy interactions.** All transitions are `0.1s`. Hovers lift elements up-left and cast a hard shadow down-right. Fast, mechanical feedback.
12
+ - **Uppercase everything.** All headings, labels and buttons are `text-transform: uppercase` with tracked letter-spacing. Body text and status messages, which are sentences, are the exception.
13
+ - **Dark on light.** `#0a0a0a` text on `#f0f0f0` background. Cards are white `#fff`. Code blocks invert to dark `#0a0a0a` backgrounds.
14
+ - **No border radius.** Ever. `border-radius: 0` is the rule, not the exception.
15
+ - **Content-width containers.** Max-width `640px` for main content, `420px` for auth/narrow forms.
16
+
17
+ ## Setup
18
+
19
+ ### Fonts
20
+
21
+ palace-ui ships Space Grotesk and JetBrains Mono as woff2 files in `fonts/`
22
+ (SIL Open Font License 1.1) and loads them from `palace.css` itself. Do not add
23
+ Google Fonts links: they send every visitor's IP address to Google, which German
24
+ courts have held to violate the GDPR without consent. Keep `fonts/` next to
25
+ `palace.css` when serving.
26
+
27
+ ### Stylesheet
28
+
29
+ ```html
30
+ <link rel="stylesheet" href="/vendor/palace-ui/palace.css">
31
+ ```
32
+
33
+ Or if consuming via npm with a build tool:
34
+
35
+ ```css
36
+ @import 'palace-ui/palace.css';
37
+ ```
38
+
39
+ ## Token Reference
40
+
41
+ ### Colors
42
+
43
+ | Token | Value | Usage |
44
+ |---|---|---|
45
+ | `--p-accent-1` | `#ff2d9b` | Primary action, CTA buttons, first card in rotation |
46
+ | `--p-accent-2` | `#5b4cff` | Secondary action, links, input focus, second card |
47
+ | `--p-accent-3` | `#00e5ff` | Tertiary accent, navbar user, code highlights, third card |
48
+ | `--p-text` | `#0a0a0a` | Body text, borders |
49
+ | `--p-text-secondary` | `#444` | Body copy in cards, descriptions |
50
+ | `--p-text-muted` | `#666` | Subtitles, labels |
51
+ | `--p-text-faint` | `#6b6b6b` | Table headers, brand labels, meta text |
52
+ | `--p-bg` | `#f0f0f0` | Page background |
53
+ | `--p-surface` | `#fff` | Card/container backgrounds |
54
+ | `--p-surface-inset` | `#f7f7f7` | Inset/recessed surfaces |
55
+ | `--p-dark` | `#0a0a0a` | Dark backgrounds (navbar, code, hover fills) |
56
+ | `--p-error` | `#ff4444` | Error states, danger zones: fills, borders, the error box |
57
+ | `--p-error-text` | `#c40000` | Red text (danger buttons, error text): 6.3:1 on white, where `#ff4444` is 3.4:1 |
58
+ | `--p-success` | `#00ff88` | Success states |
59
+ | `--p-warning` | `#ffcc00` | Warning states |
60
+ | `--p-info` | `var(--p-accent-3)` | Informational states (semantic alias for cyan) |
61
+ | `--p-overlay` | `rgba(10, 10, 10, 0.7)` | Overlay/backdrop for dialogs |
62
+ | `--p-hover-bg` | `#e8e8e8` | Subtle hover background for rows/lists |
63
+ | `--p-code-bg` | `#1a1a2e` | Inline code background on dark surfaces |
64
+ | `--p-code-highlight` | `#00ff88` | Highlighted code text (values, keys) |
65
+
66
+ ### Typography
67
+
68
+ | Token | Value |
69
+ |---|---|
70
+ | `--p-font` | `'Space Grotesk', system-ui, sans-serif` |
71
+ | `--p-font-mono` | `'JetBrains Mono', monospace` |
72
+
73
+ ### Spacing
74
+
75
+ | Token | Value | Usage |
76
+ |---|---|---|
77
+ | `--p-space-xs` | `4px` | Tight gaps |
78
+ | `--p-space-sm` | `8px` | Button gaps, small margins |
79
+ | `--p-space-md` | `16px` | Card margins, standard padding |
80
+ | `--p-space-lg` | `24px` | Card padding, section spacing |
81
+ | `--p-space-xl` | `32px` | Intermediate section gaps |
82
+ | `--p-space-2xl` | `48px` | Hero padding, major section gaps |
83
+
84
+ ### Spacing Rules
85
+
86
+ Three mechanisms for spacing, each with a clear use case:
87
+
88
+ 1. **`margin-bottom`** — spacing between sibling elements. All vertical inter-element spacing uses `margin-bottom` only (single-direction margins). Elements push the next sibling down; never pull themselves away with `margin-top`. This keeps spacing predictable, portable, and avoids margin-collapsing surprises.
89
+
90
+ 2. **`gap`** — spacing inside flex/grid containers. Preferred when the parent is `display: flex` or `display: grid`. No margin needed on children.
91
+
92
+ 3. **`.stack-*`** — spacing between children of a non-flex/grid container. Apply to the parent; children get uniform vertical spacing via the owl selector (`> * + *`). Available sizes: `stack-xs` (4px), `stack-sm` (8px), `stack-md` (16px), `stack-lg` (24px), `stack-xl` (32px), `stack-2xl` (48px).
93
+
94
+ **Never** use `padding` to create distance between sibling elements — padding is for internal space within an element.
95
+
96
+ **Exceptions:** dividers (`.divider`, `.divider-danger`, `.gradient-stripe`) use top+bottom margin because they are structural separators by nature. Tight optical adjustments inside components (e.g. `.stat-label` 2px nudge) are exempt.
97
+
98
+ ### Layout
99
+
100
+ | Token | Value |
101
+ |---|---|
102
+ | `--p-container-width` | `640px` |
103
+ | `--p-container-narrow` | `420px` |
104
+ | `--p-navbar-height` | `52px` |
105
+
106
+ ## Component Catalog
107
+
108
+ ### Page Shell
109
+
110
+ Every page follows this structure:
111
+
112
+ ```html
113
+ <!DOCTYPE html>
114
+ <html lang="en">
115
+ <head>
116
+ <meta charset="utf-8">
117
+ <meta name="viewport" content="width=device-width, initial-scale=1">
118
+ <title>Page Title</title>
119
+ <!-- palace (keep fonts/ next to palace.css) -->
120
+ <link rel="stylesheet" href="/vendor/palace-ui/palace.css">
121
+ </head>
122
+ <body>
123
+ <!-- optional navbar -->
124
+ <!-- content -->
125
+ </body>
126
+ </html>
127
+ ```
128
+
129
+ ### Navbar
130
+
131
+ ```html
132
+ <nav class="navbar">
133
+ <a href="/" class="navbar-brand">App Name</a>
134
+ <div class="navbar-right">
135
+ <span class="navbar-user">Username</span>
136
+ <button class="btn btn-sm">Log Out</button>
137
+ </div>
138
+ </nav>
139
+ ```
140
+
141
+ With an icon beside the brand name (`.navbar-brand` uses `inline-flex` layout with `gap: 10px`; images/SVGs are auto-sized to 24×24):
142
+
143
+ ```html
144
+ <nav class="navbar">
145
+ <a href="/" class="navbar-brand">
146
+ <img src="/icons/app-icon.svg" alt="">
147
+ <span>App Name</span>
148
+ </a>
149
+ <div class="navbar-right">
150
+ <span class="navbar-user">Username</span>
151
+ <button class="btn btn-sm">Log Out</button>
152
+ </div>
153
+ </nav>
154
+ ```
155
+
156
+ Light variant for pages that need a white navbar:
157
+
158
+ ```html
159
+ <nav class="navbar navbar-light">
160
+ <a href="/" class="navbar-brand">App Name</a>
161
+ <div class="navbar-right">
162
+ <span class="navbar-user">Username</span>
163
+ <button class="btn btn-sm">Log Out</button>
164
+ </div>
165
+ </nav>
166
+ ```
167
+
168
+ ### Page Header
169
+
170
+ Standard spacing for non-hero pages (after navbar). Provides `48px` top padding and consistent gaps between h1, subtitle, and content.
171
+
172
+ ```html
173
+ <div class="container page-header">
174
+ <h1>Page Title</h1>
175
+ <p class="subtitle">Helpful subtitle</p>
176
+ <!-- content -->
177
+ </div>
178
+ ```
179
+
180
+ Combines with any container class:
181
+
182
+ ```html
183
+ <div class="container-narrow page-header">
184
+ <h1>Narrow Page</h1>
185
+ <p class="subtitle">For auth forms</p>
186
+ <!-- content -->
187
+ </div>
188
+ ```
189
+
190
+ Spacing: `48px` top padding, `8px` below h1, `32px` below `.subtitle`. Do **not** use on landing/hero pages (those use custom hero spacing).
191
+
192
+ ### Hero Section (Landing Pages)
193
+
194
+ ```html
195
+ <div class="container" style="padding-top: 80px; padding-bottom: 48px;">
196
+ <p class="brand">App Name</p>
197
+ <h1 class="h1-hero">Main Headline Here</h1>
198
+ <p class="tagline">
199
+ A sentence or two explaining what this does. Keep it short.
200
+ </p>
201
+ <div style="display: flex; gap: 12px; flex-wrap: wrap; margin-top: 32px;">
202
+ <a href="/signup" class="cta cta-primary">Sign Up</a>
203
+ <a href="/login" class="cta cta-secondary">Log In</a>
204
+ </div>
205
+ </div>
206
+ ```
207
+
208
+ When the app has a visual mark/icon, use `.brand-lockup` instead of a standalone `.brand`:
209
+
210
+ ```html
211
+ <div class="container" style="padding-top: 80px; padding-bottom: 48px;">
212
+ <div class="brand-lockup" style="margin-bottom: 32px;">
213
+ <img src="/icons/app-icon.svg" alt="">
214
+ <div>
215
+ <p class="brand" style="font-size: 17px; letter-spacing: 3px;">App Name</p>
216
+ <p class="subtitle">Short descriptor</p>
217
+ </div>
218
+ </div>
219
+ <h1 class="h1-hero">Main Headline Here</h1>
220
+ <!-- ... -->
221
+ </div>
222
+ ```
223
+
224
+ ### Brand Lockup
225
+
226
+ Icon beside app name and descriptor, forming a single cohesive block. The icon scales to match the combined text height.
227
+
228
+ ```html
229
+ <div class="brand-lockup">
230
+ <img src="/icons/app-icon.svg" alt="">
231
+ <div>
232
+ <p class="brand">App Name</p>
233
+ <p class="subtitle">Short descriptor</p>
234
+ </div>
235
+ </div>
236
+ ```
237
+
238
+ Use in hero sections and landing pages where the app has a visual mark. The `.brand` and `.subtitle` classes handle typography; `.brand-lockup` handles layout only.
239
+
240
+ ### Card List (3-Color Rotation)
241
+
242
+ When you have a list of cards, the accent color auto-rotates via `nth-child`:
243
+
244
+ ```html
245
+ <div class="container">
246
+ <div class="card">
247
+ <h2>First Card</h2>
248
+ <p>Description goes here. Color will be accent-1 (pink).</p>
249
+ </div>
250
+ <div class="card">
251
+ <h2>Second Card</h2>
252
+ <p>This one gets accent-2 (purple).</p>
253
+ </div>
254
+ <div class="card">
255
+ <h2>Third Card</h2>
256
+ <p>This one gets accent-3 (cyan).</p>
257
+ </div>
258
+ </div>
259
+ ```
260
+
261
+ For explicit accent control (e.g. server-rendered cards), use the `--accent` custom property:
262
+
263
+ ```html
264
+ <div class="card" style="--accent: var(--p-accent-2)">
265
+ <h2>Specific Accent</h2>
266
+ </div>
267
+ ```
268
+
269
+ ### Static Card
270
+
271
+ For cards used as form containers or static content that should not lift on hover:
272
+
273
+ ```html
274
+ <div class="card-static">
275
+ <label for="name">Name</label>
276
+ <input type="text" id="name" placeholder="Enter your name">
277
+ </div>
278
+ ```
279
+
280
+ Use `.card-static` instead of `.card` when the card is a container (e.g. auth forms, settings panels) rather than a clickable list item.
281
+
282
+ ### Buttons
283
+
284
+ Size modifiers compose with any color variant:
285
+
286
+ ```html
287
+ <!-- Size modifiers -->
288
+ <button class="btn btn-sm btn-primary">Small Primary</button>
289
+ <button class="btn btn-primary">Medium Primary</button>
290
+ <button class="btn btn-lg btn-primary">Large Primary</button>
291
+
292
+ <!-- Primary (hot pink) — main actions -->
293
+ <button class="btn btn-primary">Create</button>
294
+
295
+ <!-- Secondary (purple) — secondary actions -->
296
+ <button class="btn btn-secondary">Copy</button>
297
+
298
+ <!-- Outline (transparent) — tertiary actions -->
299
+ <button class="btn btn-outline">View Details</button>
300
+
301
+ <!-- Danger (red) — destructive inline actions -->
302
+ <button class="btn btn-sm btn-danger">Revoke</button>
303
+
304
+ <!-- Danger full-width — destructive section actions -->
305
+ <button class="btn btn-danger btn-block">Delete My Account</button>
306
+
307
+ <!-- CTA (larger) — hero sections. `.cta` is a semantic alias for `.btn-lg` -->
308
+ <a href="/signup" class="cta cta-primary">Sign Up</a>
309
+ <a href="/login" class="cta cta-secondary">Log In</a>
310
+
311
+ <!-- Disabled (any button) -->
312
+ <button class="btn btn-primary" disabled>Processing...</button>
313
+ ```
314
+
315
+ ### Forms
316
+
317
+ ```html
318
+ <div class="card">
319
+ <label for="name">Your Name</label>
320
+ <input type="text" id="name" placeholder="Enter your name" style="margin-bottom: 16px;">
321
+ <button class="btn-primary" style="width: 100%;">Submit</button>
322
+ </div>
323
+ ```
324
+
325
+ A `<select>` is styled like the text inputs, with a drawn chevron:
326
+
327
+ ```html
328
+ <label for="direction">Direction</label>
329
+ <select id="direction"><option>Anticlockwise</option><option>Clockwise</option></select>
330
+ ```
331
+
332
+ Inline form (input + button side by side):
333
+
334
+ ```html
335
+ <div style="display: flex; gap: 8px;">
336
+ <input type="text" placeholder="Label" style="flex: 1;">
337
+ <button class="btn-primary">Create</button>
338
+ </div>
339
+ ```
340
+
341
+ ### Status Messages
342
+
343
+ ```html
344
+ <!-- Success — use role="status" for polite announcements -->
345
+ <div class="status status-success" role="status">Account created successfully</div>
346
+
347
+ <!-- Error — use role="alert" for urgent announcements -->
348
+ <div class="status status-error" role="alert">Something went wrong</div>
349
+
350
+ <!-- Warning — use role="alert" for urgent announcements -->
351
+ <div class="status status-warning" role="alert">Your session will expire soon</div>
352
+
353
+ <!-- Info — use role="status" for polite announcements -->
354
+ <div class="status status-info" role="status">New features are available</div>
355
+
356
+ <!-- Neutral (base, no color variant) -->
357
+ <div class="status">Neutral message</div>
358
+ ```
359
+
360
+ Use `role="alert"` for error and warning messages (assertive — interrupts the user). Use `role="status"` for success and info messages (polite — announced at the next opportunity). Omit the role for neutral/static messages that don't need to be announced.
361
+
362
+ Show/hide with JavaScript:
363
+ ```js
364
+ function showStatus(el, msg, type) {
365
+ el.textContent = msg;
366
+ el.className = 'status status-' + type; // 'success', 'error', 'warning', 'info'
367
+ el.style.display = 'block';
368
+ }
369
+ ```
370
+
371
+ ### Tables
372
+
373
+ ```html
374
+ <table>
375
+ <thead>
376
+ <tr>
377
+ <th>Name</th>
378
+ <th>Value</th>
379
+ <th>Date</th>
380
+ </tr>
381
+ </thead>
382
+ <tbody>
383
+ <tr>
384
+ <td>Compression</td>
385
+ <td style="font-weight: 600;">12 clicks</td>
386
+ <td>Mar 1, 2026</td>
387
+ </tr>
388
+ </tbody>
389
+ </table>
390
+ ```
391
+
392
+ ### Code Blocks
393
+
394
+ Standard code block:
395
+ ```html
396
+ <pre>const config = {
397
+ server: "https://example.com"
398
+ };</pre>
399
+ ```
400
+
401
+ Dark reveal panel (for secrets, API keys, terminal output):
402
+ ```html
403
+ <div class="code-reveal">
404
+ <p class="eyebrow" style="color: var(--p-accent-3); margin-bottom: 10px;">
405
+ Copy this — you won't see it again
406
+ </p>
407
+ <code>sk_live_abc123def456</code>
408
+ <div style="display: flex; gap: 8px; margin-top: 12px;">
409
+ <button class="btn-secondary">Copy</button>
410
+ </div>
411
+ </div>
412
+ ```
413
+
414
+ ### Tags & Badges
415
+
416
+ ```html
417
+ <!-- Tag (bordered, light background) -->
418
+ <span class="tag">Volume Spacer</span>
419
+
420
+ <!-- Badge (dark background, white text) -->
421
+ <span class="badge">clicks</span>
422
+ ```
423
+
424
+ ### Steps (Numbered Instructions)
425
+
426
+ ```html
427
+ <div class="steps">
428
+ <div class="step">
429
+ <span class="step-num">1</span>
430
+ <p><strong>Create an account</strong> with a passkey</p>
431
+ </div>
432
+ <div class="step">
433
+ <span class="step-num">2</span>
434
+ <p><strong>Get an API key</strong> and paste the config</p>
435
+ </div>
436
+ <div class="step">
437
+ <span class="step-num">3</span>
438
+ <p><strong>Go.</strong> Start using the tools</p>
439
+ </div>
440
+ </div>
441
+ ```
442
+
443
+ ### Stack Spacing
444
+
445
+ Uniform vertical spacing between direct children. Apply to the parent element.
446
+
447
+ ```html
448
+ <div class="stack-md">
449
+ <p>First item</p>
450
+ <p>16px gap</p>
451
+ <p>16px gap</p>
452
+ </div>
453
+ ```
454
+
455
+ Available: `stack-xs` (4px) · `stack-sm` (8px) · `stack-md` (16px) · `stack-lg` (24px) · `stack-xl` (32px) · `stack-2xl` (48px)
456
+
457
+ For flex/grid parents, prefer `gap` instead. `.stack-*` is for flow-layout contexts where children are block-level elements stacked vertically.
458
+
459
+ ### Dividers
460
+
461
+ ```html
462
+ <!-- Standard dashed divider -->
463
+ <hr class="divider">
464
+
465
+ <!-- Danger divider (above danger zones) -->
466
+ <hr class="divider-danger">
467
+ ```
468
+
469
+ ### Danger Zone
470
+
471
+ ```html
472
+ <hr class="divider-danger">
473
+ <div class="danger-zone">
474
+ <h2>Danger Zone</h2>
475
+ <p>This will permanently delete your account. This cannot be undone.</p>
476
+ <button class="btn btn-danger btn-block">Delete My Account</button>
477
+ </div>
478
+ ```
479
+
480
+ ### Footer
481
+
482
+ ```html
483
+ <div class="container">
484
+ <div class="footer">
485
+ Built with care. <a href="/">Home</a>
486
+ </div>
487
+ </div>
488
+ ```
489
+
490
+ ### Empty States
491
+
492
+ ```html
493
+ <p class="empty">No items yet</p>
494
+ ```
495
+
496
+ ### Gradient Stripe
497
+
498
+ A thin (3px) animated gradient divider. Uses the 3-accent gradient with a shifting `background-position`.
499
+
500
+ ```html
501
+ <hr class="gradient-stripe">
502
+ ```
503
+
504
+ Use between header and content, or between major sections as a vibrant alternative to `.divider`.
505
+
506
+ ### Stat Callout
507
+
508
+ Oversized number with a small label below. Picks up the card's `--accent` color automatically.
509
+
510
+ ```html
511
+ <div>
512
+ <div class="stat">180mm</div>
513
+ <div class="stat-label">Travel</div>
514
+ </div>
515
+ ```
516
+
517
+ Group multiple stats in a flex row with `.stat-row`:
518
+
519
+ ```html
520
+ <div class="stat-row">
521
+ <div>
522
+ <div class="stat">180mm</div>
523
+ <div class="stat-label">Travel</div>
524
+ </div>
525
+ <div>
526
+ <div class="stat">20%</div>
527
+ <div class="stat-label">Sag</div>
528
+ </div>
529
+ </div>
530
+ ```
531
+
532
+ ### Sticker Tags
533
+
534
+ Filled accent-colored tags with slight rotation for a sticker-board feel. Use instead of `.tag` when you want more visual pop.
535
+
536
+ ```html
537
+ <span class="tag-sticker">Volume Spacer</span>
538
+ <span class="tag-sticker">Custom Tune</span>
539
+ <span class="tag-sticker">Bleed Kit</span>
540
+ ```
541
+
542
+ Rotation alternates automatically via `nth-child`. Tags pick up `--accent` from their parent card.
543
+
544
+ ### Entrance Animation
545
+
546
+ Fade-up entrance for staggered card lists. Apply `.fade-up` and set `animation-delay` per element.
547
+
548
+ ```html
549
+ <div class="card fade-up" style="animation-delay: 0s">...</div>
550
+ <div class="card fade-up" style="animation-delay: 0.1s">...</div>
551
+ <div class="card fade-up" style="animation-delay: 0.2s">...</div>
552
+ ```
553
+
554
+ Uses `animation-fill-mode: both` so elements stay hidden until their delay fires.
555
+
556
+ ### Watermark Background
557
+
558
+ Fixed-position SVG watermarks for visual texture. Non-interactive (`pointer-events: none`), very low opacity.
559
+
560
+ ```html
561
+ <div class="watermarks">
562
+ <svg style="top: 10%; left: -5%;"><!-- SVG content --></svg>
563
+ <svg style="top: 50%; right: -5%;"><!-- SVG content --></svg>
564
+ </div>
565
+ ```
566
+
567
+ ### Lists
568
+
569
+ Lists inside `.container` or `.container-narrow` are automatically styled with proper padding and markers:
570
+
571
+ ```html
572
+ <div class="container">
573
+ <ul>
574
+ <li>Unordered list item</li>
575
+ <li>Another item</li>
576
+ </ul>
577
+ <ol>
578
+ <li>Ordered list item</li>
579
+ <li>Another item</li>
580
+ </ol>
581
+ </div>
582
+ ```
583
+
584
+ ### Dialog
585
+
586
+ A native `<dialog>` styled as a card: border, purple offset shadow, overlay backdrop. Actions go in a `<menu>`; its buttons share the width equally.
587
+
588
+ ```html
589
+ <dialog>
590
+ <h2>Title</h2>
591
+ <p class="subtitle">Supporting line</p>
592
+ <p>Body text.</p>
593
+ <menu>
594
+ <li><button class="btn">Cancel</button></li>
595
+ <li><button class="btn btn-primary">Confirm</button></li>
596
+ </menu>
597
+ </dialog>
598
+ ```
599
+
600
+ ### Kbd
601
+
602
+ Inline keyboard key: bordered, uppercase mono, with a small pink offset shadow.
603
+
604
+ ```html
605
+ <kbd>Ctrl</kbd> + <kbd>Z</kbd>
606
+ ```
607
+
608
+ ## Accessibility
609
+
610
+ ### Focus Visible
611
+
612
+ All interactive elements (buttons, links, inputs) have `:focus-visible` styles with a `2px` outline in accent-2 (purple) and `2px` offset. Buttons also get a lift + shadow on focus.
613
+
614
+ ### Reduced Motion
615
+
616
+ The system respects `prefers-reduced-motion: reduce`. When enabled, all animations and transitions are effectively disabled (duration set to `0.01ms`).
617
+
618
+ ### Contrast
619
+
620
+ - Third-card headings (cyan rotation) use dark text (`--p-text`) instead of cyan for accessible contrast on white
621
+ - `--p-text-faint` is `#6b6b6b` (4.5:1 contrast ratio on `#f0f0f0`)
622
+
623
+ ## Icon Style
624
+
625
+ When creating SVG icons for palace-ui projects:
626
+
627
+ - Use **stroke-based** icons (not filled)
628
+ - `stroke-linecap: square` and `stroke-linejoin: miter` (matches the hard-edge aesthetic)
629
+ - `stroke-width: 2` (matches `--p-border-width`)
630
+ - Color with `currentColor` so icons inherit text color
631
+
632
+ ## Layout Patterns
633
+
634
+ ### Auth Pages (Login, Register)
635
+
636
+ Use `container-narrow page-header` (420px). No navbar. Centered with top padding.
637
+
638
+ ```html
639
+ <body>
640
+ <div class="container-narrow page-header">
641
+ <p class="brand">App Name</p>
642
+ <h1>Page Title</h1>
643
+ <p class="subtitle">Helpful subtitle</p>
644
+ <div class="card">
645
+ <!-- form contents -->
646
+ </div>
647
+ <p style="margin-top: 20px; text-align: center; font-size: 13px; color: var(--p-text-muted);">
648
+ Already in? <a href="/login">Log in</a>
649
+ </p>
650
+ </div>
651
+ </body>
652
+ ```
653
+
654
+ ### Dashboard Pages
655
+
656
+ Navbar + container with `page-header`. Use `divider` between major sections.
657
+
658
+ ```html
659
+ <body>
660
+ <nav class="navbar">...</nav>
661
+ <div class="container page-header">
662
+ <h1>Dashboard</h1>
663
+ <p class="subtitle">Manage your stuff</p>
664
+ <!-- content sections -->
665
+ <hr class="divider">
666
+ <!-- more sections -->
667
+ <hr class="divider-danger">
668
+ <div class="danger-zone">...</div>
669
+ </div>
670
+ </body>
671
+ ```
672
+
673
+ ### Landing/Public Pages
674
+
675
+ Full container, no navbar. Hero section, then card list, then footer.
676
+
677
+ ```html
678
+ <body>
679
+ <div class="container" style="padding-top: 80px; padding-bottom: 48px;">
680
+ <!-- hero -->
681
+ </div>
682
+ <div class="container" style="padding-bottom: 20px;">
683
+ <!-- card list -->
684
+ </div>
685
+ <div class="container">
686
+ <div class="footer">...</div>
687
+ </div>
688
+ </body>
689
+ ```
690
+
691
+ ## Interaction Rules
692
+
693
+ 1. **Hover = lift + shadow.** Elements move `translate(-1px, -1px)` or `translate(-2px, -2px)` and cast a hard shadow in the opposite direction. Shadow color matches the element's accent.
694
+ 2. **Focus = border-color + shadow.** Input focus changes border to accent-2 (purple) and adds a `3px 3px 0` shadow. Number inputs focus to accent-1 (pink).
695
+ 3. **Disabled = flat gray.** `#ddd` background, `#999` text, `#ccc` border. No transform, no shadow, `cursor: not-allowed`.
696
+ 4. **Transitions are 0.1s.** Never slower. The UI should feel mechanical and responsive.
697
+ 5. **Links underline with border-bottom**, not `text-decoration`. Hover swaps from accent-2 (purple) to accent-1 (pink).
698
+ 6. **`@keyframes` ≠ transitions.** The 0.1s rule applies to hover/focus transitions. Entrance animations (`@keyframes`) and infinite loops (gradient-shift) use their own appropriate durations.
699
+ 7. **Gradient stripes** are decorative (≤3px). They use the 3-accent gradient with animated `background-position`. This is not a "gradient surface."
700
+
701
+ ## Color Usage Rules
702
+
703
+ - **accent-1 (pink):** Primary buttons, first card in a list, CTA buttons, link hover color
704
+ - **accent-2 (purple):** Secondary buttons, links, input focus borders, second card
705
+ - **accent-3 (cyan):** Navbar user name, code highlights, key reveal borders, third card
706
+ - **Never mix** accent colors in a single element (except the gradient on h1 text)
707
+ - **The 3-color rotation** applies to any list of sibling cards: 1=pink, 2=purple, 3=cyan, 4=pink...
708
+ - **Error is always `#ff4444`**, success is always `#00ff88`, warning is `#ffcc00`, info is `#00e5ff`. Status colors are not accent colors. Text on a status color is always dark `--p-text`; red text uses `--p-error-text`, never `#ff4444`.
709
+
710
+ ## Do's and Don'ts
711
+
712
+ ### Do
713
+ - Use uppercase for headings, labels, buttons and badges; status messages are sentences in sentence case
714
+ - Use the 3-color card rotation for any list of cards
715
+ - Keep `border-radius: 0` everywhere
716
+ - Use `2px solid` borders on cards, buttons, inputs
717
+ - Use hard shadows (`Npx Npx 0 color`) — never blurred shadows
718
+ - Use `font-weight: 700` for headings and buttons
719
+ - Use `letter-spacing` on all uppercase text (0.5px to 2px)
720
+ - Keep containers at 640px max width
721
+ - Use dashed borders for dividers (`2px dashed #ccc`)
722
+
723
+ ### Don't
724
+ - Add border-radius to anything
725
+ - Use `box-shadow` with blur (the third value must always be `0`)
726
+ - Use gradients on large surfaces or card backgrounds (allowed on: text, decorative stripes ≤3px, narrow fixed bars)
727
+ - Use colors outside the token system
728
+ - Use `text-decoration: underline` for links (use `border-bottom` instead)
729
+ - Use hover/focus transitions slower than `0.1s` (keyframe animations are exempt)
730
+ - Put body text in uppercase (only headings, labels, buttons)
731
+ - Use more than 640px for content width
732
+ - Create soft/subtle hover effects — make them obvious
733
+
734
+ ## Responsive Breakpoint
735
+
736
+ Single breakpoint at `480px`:
737
+
738
+ ```css
739
+ @media (max-width: 480px) {
740
+ /* h1 shrinks, container gets tighter padding, cards lose some padding */
741
+ }
742
+ ```
743
+
744
+ Palace CSS handles h1, container, and card adjustments automatically. For page-specific adjustments:
745
+
746
+ ```css
747
+ @media (max-width: 480px) {
748
+ .hero { padding: 48px 16px 32px; }
749
+ .cta-row { flex-direction: column; }
750
+ }
751
+ ```