arkaos 4.28.0 → 4.30.0

package/departments/brand/skills/design-system/references/interaction-states.md

@@ -0,0 +1,306 @@
+# Interaction and states
+
+> Source: merge of `references/interaction-and-states.md` from the **hallmark** skill repo (MIT — see `hallmark.LICENSE` in this references directory) and `skill/reference/interaction-design.md` from the **impeccable** repo (Apache-2.0 — see `impeccable.LICENSE` in this references directory). The eight-state model and input-field rules are hallmark's; keyboard-navigation patterns, gesture discoverability, and the dropdown-clipping/anchor-positioning material are impeccable's. Rule anchors follow impeccable's `<!-- rule:… -->` convention (the two source files carried none; the IDs below are minted for this port).
+
+Every interactive element has eight states. Most AI-generated UI styles two (default, hover) and forgets the rest. That's where interfaces break.
+
+## The eight states
+
+| State | When | Treatment |
+| --- | --- | --- |
+| Default | At rest | Base styling |
+| Hover | Pointer over (only with `@media (hover: hover)`) | Small shift: colour, 1px translate, subtle border |
+| Focus | Keyboard or programmatic focus | Visible ring, `:focus-visible` |
+| Active / Pressed | During press | Pressed-in: darker, translate(0 1px) |
+| Disabled | Not interactive | Reduced opacity (0.5) + `cursor: not-allowed` + `aria-disabled` |
+| Loading | Processing | Inline spinner or progress, label stays readable |
+| Error | Failed state | Red border, error icon, message, `aria-invalid` |
+| Success | Completed | Green check, confirmation, auto-dismiss |
+
+If any of these is missing on a production element, the element isn't finished. <!-- rule:interaction-eight-states -->
+
+**The common miss**: designing hover without focus, or vice versa. They're different states — keyboard users never see hover states. <!-- rule:interaction-hover-focus-distinct -->
+
+## Focus rings
+
+Visible, always, on every interactive element. The default focus ring most browsers give you is fine; a custom one is better.
+
+```css
+:focus { outline: none; }
+:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: 2px;
+  border-radius: inherit;
+}
+```
+
+Requirements:
+
+- 2–3px, ≥ 3:1 contrast against both element and page.
+- 2px offset from the element (not inside it).
+- `:focus-visible`, not `:focus`, so it's keyboard-only.
+- Consistent across all interactive elements.
+- Never `outline: none` without a replacement. `outline: none` with no other focus style is the most common accessibility bug and an immediate audit failure. <!-- rule:interaction-no-bare-outline-none -->
+
+## Hit targets
+
+Minimum 44×44 CSS px for any touch-reachable element. <!-- rule:interaction-hit-target-44 --> Use padding or an `::before` overlay to expand the hit target without changing visual size:
+
+```css
+.icon-btn {
+  position: relative;
+}
+.icon-btn::before {
+  content: "";
+  position: absolute;
+  inset: -12px;
+}
+```
+
+## Forms
+
+- Labels above inputs. Visible. Never placeholder-as-label — placeholders disappear on input. <!-- rule:interaction-no-placeholder-label -->
+- Placeholders show format, not instruction. `Placeholder: 01 Jan 2026`, not `Placeholder: Enter your birth date`.
+- Helper text below input. Error text replaces helper text.
+- Validate on **blur**, not on every keystroke (exception: password strength). Revalidate on change once the field has been blurred once (the "touched" pattern). <!-- rule:interaction-validate-on-blur -->
+- Error message: (1) what broke, (2) why, (3) what to do. One sentence if possible.
+- Associate errors with `aria-describedby`. Set `aria-invalid="true"` on the field.
+- Required fields marked with `aria-required`, never with colour alone.
+- Disable the submit button only when the form is in a known-invalid or in-flight state. Never on idle.
+
+## Input field states — the exhaustive checklist
+
+This is where the most "almost right" UIs lose. An input field with two states (default + hover) and a different border-width on focus reads as a default settings page — the geometry shifts, the eye notices, the page feels untuned. Every text input, textarea, select, and combobox must satisfy every rule below.
+
+### The no-layout-shift rule
+
+**Border thickness is constant across every state.** Default · hover · focus · error · disabled — the `border-width` value never changes. Layout shift on focus is a tell. State changes go to `background-color`, `outline`, or `box-shadow`, never to `border-width`. <!-- rule:interaction-constant-border-width -->
+
+```css
+.input {
+  border: 1px solid var(--color-rule-2);   /* 1px, always — every state */
+  outline: 2px solid transparent;          /* reserved slot for focus ring; no shift on activate */
+  outline-offset: 1px;
+}
+```
+
+The outline starts transparent at 2 px so when the focus ring appears, the box geometry is already correct. No layout shift. No paint thrash.
+
+### State-by-state recipe
+
+| State | Treatment | Why |
+| --- | --- | --- |
+| **Default** | `border: 1px solid var(--color-rule-2)` · `background: var(--color-paper)` · placeholder in `var(--color-muted)` | Visible field, readable empty signal |
+| **Hover** | `background: var(--color-paper-2)` (4–6 % darker than paper) · border unchanged | Subtle background shift, no border flash. Border colour changing alone is missable. |
+| **Focus** | `outline: 2px solid var(--color-focus)` · `outline-offset: 1px` · border may deepen to `var(--color-ink-2)` but width stays 1 px | Outline is the focus signal; never animated; ≥ 3:1 contrast against page AND field. |
+| **Active / typing** | Same as focus. Don't add a separate "typing" state. | Focus already says "active here". A second signal is noise. |
+| **Filled** | Same as default — the value carries the state. Optionally a subtle ink-2 border to visually distinguish from empty. | Don't fight the user's content with a styled chrome change. |
+| **Disabled** | `opacity: 0.55` · `cursor: not-allowed` · placeholder `var(--color-rule-2)` · `aria-disabled="true"` · `tabindex="-1"` | Three independent signals (opacity + cursor + colour) so no single channel carries the whole load. |
+| **Error** | `border-color: var(--color-error, oklch(58% 0.20 25))` · helper-text replaced by error message · `aria-invalid="true"` · small ⚠ glyph at right edge | Border colour flip is OK *because* helper-text and aria signal it too. Never colour alone. |
+| **Success** | Subtle accent-coloured border (3 % chroma above default) · small ✓ glyph · auto-clear if user re-edits | Quiet; success doesn't deserve celebration unless it was hard. |
+| **Loading** (validating, async) | Inline spinner at the right edge replacing the standard glyph slot · field stays editable but submit disabled | Don't lock the user out of the field. They may want to fix what they typed. |
+
+### Heights and rhythm
+
+- **Input height = button height.** A page with 44 px buttons and 38 px inputs feels untuned. Pick one base height (44 px is the touch-target floor) and apply it to every text input AND every adjacent button. <!-- rule:interaction-input-button-height -->
+- **Vertical padding = `(height − line-height-px) / 2`.** No magic numbers.
+- **Right-edge slot reserved.** Every input reserves a ~24 px right-edge slot for an optional clear button, error glyph, or loading spinner. If unused, the slot sits empty — never reflow on icon appearance.
+
+### Labels, helper, error
+
+- **Label above** the input, 4–8 px gap. Never inline (placeholder-as-label is a tell).
+- **Helper text below**, ~4 px gap. Same `font-size` as the label, lower visual weight.
+- **Error replaces helper** — same position, same size, error colour. Never both at once (causes vertical jump on validation).
+- **Helper has stable height.** Reserve a 1-line height even when empty, so adding an error doesn't push the page down. CSS: `min-height: 1lh` on the helper container.
+
+### Don't, list
+
+- Don't transition `border-width`, `padding`, or `height` on any state. Always layout-shift.
+- Don't transition the focus ring's `opacity` or `transform`. Focus must be instant.
+- Do put hover effects inside `@media (hover: hover)` so touch users don't get stuck states.
+- Don't disable the field as a way to indicate "wait, loading" — use a loading state with the field still editable.
+- Don't change `cursor` on `:focus`. The pointer is already a beam; don't fight it.
+- Don't use `outline: none` on focus without an explicit replacement.
+
+### Specific control overrides
+
+- **Textarea.** Same rules as input, plus `resize: vertical` (never `none`, never `both` on a small textarea), `min-height: 6rem` for multi-line UX.
+- **Select.** Custom-styled `<select>` only if you can replicate native a11y (keyboard, screen-reader). Otherwise leave it native and style the wrapper.
+- **Checkbox / radio.** Use `accent-color: var(--color-accent)` for cheap correct styling on modern browsers; only build a custom one when the design requires it. If custom: still a 1 px outline-offset focus ring.
+- **Toggle / switch.** It IS a checkbox. Same a11y rules. The visual design doesn't change the contract.
+- **Range / slider.** The thumb gets focus state, not the track. Thumb hit-target ≥ 44 px even if visual size is smaller (use a transparent expansion).
+- **File input.** Always wrap in a styled label. Native `<input type="file">` is unstyleable; the label is the surface.
+- **Combobox / search.** Listbox sits below, `aria-expanded` mirrors visibility, arrow-keys cycle, Enter selects, Escape closes — and the listbox doesn't push page content (use `position: absolute` + a parent `position: relative`).
+
+## Modals and overlays
+
+- Use the native `<dialog>` element. It handles focus trap, escape to close, and `::backdrop` styling for free (`dialog.showModal()`).
+- **Centre it explicitly.** A `<dialog>` opened with `showModal()` centres on its own — but the moment you add custom positioning (a `margin-top`, a `top`, a stray `transform`) it can snap to the viewport's top-left corner. Pin it: `position: fixed; inset: 0; margin: auto; height: fit-content; max-height: min(80vh, 40rem);`. A non-`<dialog>` overlay centres via its container instead: `position: fixed; inset: 0; display: grid; place-items: center;`. Never ship a modal or command palette stuck in the corner. <!-- rule:interaction-modal-centred -->
+- Set `inert` on the page content behind a modal so tab order doesn't leak — the modern replacement for hand-rolled focus-trap JavaScript:
+
+  ```html
+  <!-- When modal is open -->
+  <main inert>
+    <!-- Content behind modal can't be focused or clicked -->
+  </main>
+  <dialog open>
+    <h2>Modal Title</h2>
+    <!-- Focus stays inside modal -->
+  </dialog>
+  ```
+
+- Close on: escape key, backdrop click, explicit close button.
+- First focus goes to the first interactive element, not the close button.
+
+## Dropdowns, tooltips, popovers
+
+- Use the Popover API (`popover` attribute). It handles light-dismiss (click outside closes), stacking, and escape for free, works in every modern browser, and places the element in the **top layer** — above all other content regardless of z-index or overflow. No z-index wars, no portal needed, accessible by default.
+
+  ```html
+  <button popovertarget="menu">Open menu</button>
+  <div id="menu" popover>
+    <button>Option 1</button>
+    <button>Option 2</button>
+  </div>
+  ```
+
+- Position with CSS Anchor Positioning where it's available; fall back to `position: fixed` + `getBoundingClientRect()`.
+- Never put a dropdown inside an `overflow: hidden` container without escape. It will clip.
+- Flip when near the viewport edge.
+
+### The dropdown-clipping rule
+
+Dropdowns rendered with `position: absolute` inside a container that has `overflow: hidden` or `overflow: auto` will be clipped. This is the single most common dropdown bug in generated code. <!-- rule:interaction-dropdown-no-overflow-clip -->
+
+**CSS Anchor Positioning.** The modern solution tethers an overlay to its trigger without JavaScript:
+
+```css
+.trigger {
+  anchor-name: --menu-trigger;
+}
+
+.dropdown {
+  position: fixed;
+  position-anchor: --menu-trigger;
+  position-area: block-end span-inline-end;
+  margin-top: 4px;
+}
+
+/* Flip above if no room below */
+@position-try --flip-above {
+  position-area: block-start span-inline-end;
+  margin-bottom: 4px;
+}
+```
+
+Because the dropdown uses `position: fixed`, it escapes any `overflow` clipping on ancestor elements. The `@position-try` block handles viewport edges automatically. **Browser support**: Chrome 125+, Edge 125+. Not yet in Firefox or Safari — use a fallback for those browsers.
+
+**Popover + anchor combo.** Combining the Popover API with anchor positioning gives you stacking, light-dismiss, accessibility, and correct positioning in one pattern — the `popover` attribute supplies the top layer, the anchor supplies the tether.
+
+**Portal / Teleport pattern.** In component frameworks, render the dropdown at the document root and position it with JavaScript:
+
+- **React**: `createPortal(dropdown, document.body)`
+- **Vue**: `<Teleport to="body">`
+- **Svelte**: use a portal library or mount to `document.body`
+
+Calculate position from the trigger's `getBoundingClientRect()`, then apply `position: fixed` with `top` and `left` values. Recalculate on scroll and resize.
+
+**Fixed positioning fallback.** For browsers without anchor-positioning support, `position: fixed` with manual coordinates avoids overflow clipping. Check viewport boundaries before rendering: if the dropdown would overflow the bottom edge, flip it above the trigger; if it would overflow the right edge, align it to the trigger's right side instead.
+
+## Undo over confirm
+
+- For reversible actions, skip the confirm dialog — users click through confirmations mindlessly. Do the thing. Show a toast with an Undo button for 5–10 seconds; actually delete after the toast expires. <!-- rule:interaction-undo-over-confirm -->
+- For destructive, irreversible actions (delete account, drop table), high-cost actions, or batch operations, keep the confirm — and make the user type the thing being destroyed, not just click "OK".
+
+## Keyboard navigation patterns
+
+### Roving tabindex
+
+For component groups (tabs, menu items, radio groups), one item is tabbable; arrow keys move within: <!-- rule:interaction-roving-tabindex -->
+
+```html
+<div role="tablist">
+  <button role="tab" tabindex="0">Tab 1</button>
+  <button role="tab" tabindex="-1">Tab 2</button>
+  <button role="tab" tabindex="-1">Tab 3</button>
+</div>
+```
+
+Arrow keys move `tabindex="0"` between items. Tab moves to the next component entirely.
+
+### Skip links
+
+Provide skip links (`<a href="#main-content">Skip to main content</a>`) for keyboard users to jump past navigation. Hide off-screen, show on focus. <!-- rule:interaction-skip-links -->
+
+## Gesture discoverability
+
+Swipe-to-delete and similar gestures are invisible. Hint at their existence:
+
+- **Partially reveal**: show the delete button peeking from the edge.
+- **Onboarding**: coach marks on first use.
+- **Alternative**: always provide a visible fallback (menu with "Delete").
+
+Don't rely on gestures as the only way to perform actions. <!-- rule:interaction-gesture-fallback -->
+
+## Loading and empty states
+
+- **Skeleton** screens over spinners for content that has a predictable shape (lists, cards, tables) — they preview the content shape and feel faster than generic spinners.
+- **Inline spinners** for in-button state. Replace the label, don't add beside it.
+- **Optimistic updates**: show success immediately, roll back on failure. Use for low-stakes actions (likes, follows), not payments or destructive actions. <!-- rule:interaction-optimistic-low-stakes -->
+- **Empty states** always have: an illustration or icon (a small one), a one-line explanation of why it's empty, an action to fix it.
+- Never show a generic "No results" with no context.
+
+## Bans
+
+- Placeholder-as-label.
+- Hover-only functionality (touch users can't hover).
+- Focus rings removed without replacement.
+- Confirmation dialogs for low-stakes actions.
+- Touch targets < 44px.
+- Custom cursors on interactive elements.
+- Disabled elements with no explanation of why they're disabled.
+- Colour-only error states.
+- Spinners where a skeleton would show layout.
+- Generic error messages.
+- Custom controls without ARIA/keyboard support.
+
+---
+
+## Contrast discipline
+
+Output must pass the contrast gates of the design-review skill (`departments/brand/skills/design-review/` — upstream: hallmark slop-test gates 40–41) before shipping. Compute contrast for every `(color, background-color)` pair on the page. The common failures generated output trips on:
+
+1. **Text on a flipped surface.** `.section--ink { background: var(--color-ink); }` flips the surface dark; nested text still inherits `color: var(--color-ink)` → ink-on-ink. Fix: any rule that sets a dark `background` must *also* set `color: var(--color-paper)` in the same rule.
+2. **Button text on accent fill.** `background: var(--color-accent); color: white;` — but white is 4.5:1 against this accent only if `--color-accent` is dark enough. Use `var(--color-accent-ink)` instead, which the theme guarantees passes ≥ APCA Lc 60.
+3. **Muted text on tinted paper.** `color: var(--color-muted); background: var(--color-paper-3);` — both mid-lightness, often falls below 4.5:1. Use `--color-neutral` (darker) or lift the background to `--color-paper`.
+4. **Focus ring on accent-coloured button.** `outline: 2px solid var(--color-focus);` on a button whose fill is `--color-accent` — if `--color-focus = --color-accent`, the ring vanishes. Use the contrast pair: `--color-focus` set to a colour with ≥ 3:1 against both the element and the page.
+
+### Computation
+
+For each `(text-colour, background-colour)` pair the page actually renders:
+
+- Run **APCA Lc** (preferred — perceptual) or **WCAG 2.1 ratio**.
+- Pre-check: if both are in OKLCH with `|L_a − L_b| < 50 %`, flag for full check.
+- Body text passes at **APCA Lc ≥ 60** ≈ WCAG 4.5:1.
+- Large text / focus rings / icons pass at **APCA Lc ≥ 45** ≈ WCAG 3:1.
+
+### Token contract
+
+Every theme MUST define `--color-accent-ink` — the text colour to use whenever `--color-accent` fills a surface that carries text. The accent-ink colour is verified ≥ APCA Lc 60 against the accent at the time the theme is built. Code that uses `background: var(--color-accent)` must also set `color: var(--color-accent-ink)`. Falling back to hardcoded `color: white` is a tell — the theme's accent could be a light colour, and white-on-light is the bug. <!-- rule:interaction-accent-ink-contract -->
+
+### When the surface flips
+
+The rule: **any rule that overrides `background-color` must also state the appropriate `color`.** Don't rely on inheritance for surface-flipping classes. <!-- rule:interaction-surface-flip-color --> Example:
+
+```css
+/* WRONG — text inherits color: var(--color-ink); section is now dark; ink-on-ink */
+.section--manifesto { background: var(--color-ink); }
+
+/* RIGHT */
+.section--manifesto {
+  background: var(--color-ink);
+  color: var(--color-paper);
+}
+```
+
+Same applies to per-theme overrides like `[data-theme="manifesto"] .vs__col:first-child { background: var(--color-ink); }` — set `color: var(--color-paper)` at the same time, OR declare the rule on a parent and let descendants inherit explicitly.

package/departments/brand/skills/design-system/references/themes/carnival.md

@@ -0,0 +1,303 @@
+# Theme — Carnival
+
+> Source: verbatim port of `references/themes/carnival.md` from the **hallmark** skill repo (MIT — see `hallmark.LICENSE` one directory up, in the references root). Sanitized for ArkaOS: diversification-log path under `.arka/design/`, design stamps rendered as `[arka:design-dna]`. Upstream cross-references (`site/css/tokens.css`, `site/examples/*`, `custom-theme.md`, `layout-and-space.md`, slop-test gate numbers) name hallmark repo files that are not bundled here and travel as plain text.
+
+Loud-maximalist editorial. **Duo-tone accent system across six named palette drops** (each its own mood), chunky variable display, decorative ornaments, hard-offset shadows, tinted paper. The loud sibling to Riso / Manifesto / Brutal — but **decorative, not raw**.
+
+Loaded eagerly by the design-system skill whenever the catalog pick is `carnival`. The default palette ("Cold Snap") and font stack live in `site/css/tokens.css` (upstream hallmark repo — not bundled here) under `[data-theme="carnival"]`; this file carries the **palette drops** (six variants) plus the rules that tokens cannot encode.
+
+## Axes (diversification)
+
+- **Paper band** — light (`L 88–95%`, tinted — varies by drop)
+- **Display style** — **display-heavy** (Big Shoulders Display 800, variable-width axis)
+- **Accent hue** — **per-drop**. Each drop has its own duo-tone hue pair (warm+warm, cool+warm, warm+cool, etc.). The drop name is recorded alongside the theme name in the diversification log so consecutive builds rotate drops, not just themes.
+
+## Palette drops
+
+A drop is a named duo-tone palette that preserves Carnival's structural signature (saturated accent-1 + complementary accent-2 + tinted paper + deep ink) while rotating hue. **Every Carnival build picks one drop.** The catalog of six:
+
+### Drop 01 · Cold Snap *(default)*
+
+Warm + warm. Indie record-label, winter, scrappy. The canonical Carnival.
+
+- `--color-paper: oklch(92% 0.045 50)` — warm pink-cream
+- `--color-paper-2: oklch(88% 0.050 45)`
+- `--color-paper-3: oklch(82% 0.060 40)`
+- `--color-ink: oklch(18% 0.080 20)` — deep aubergine
+- `--color-ink-2: oklch(28% 0.060 25)`
+- `--color-muted: oklch(45% 0.05 30)`
+- `--color-rule: oklch(40% 0.18 25)` — oxblood rules (decorative)
+- `--color-accent: oklch(86% 0.18 95)` — mustard
+- `--color-accent-2: oklch(40% 0.21 25)` — oxblood
+- `--color-accent-ink: oklch(18% 0.080 20)`
+- `--color-focus: oklch(40% 0.21 25)`
+
+**When to pick:** independent music · winter releases · DIY scrappy · the brief mentions cassettes, vinyl, EPs.
+
+### Drop 02 · Citrus Riot
+
+Loud + neon. 90s zine, summer, electric. Lime against magenta — the hardest collision in the catalogue.
+
+- `--color-paper: oklch(94% 0.040 85)` — pale acid cream
+- `--color-paper-2: oklch(90% 0.048 82)`
+- `--color-paper-3: oklch(84% 0.055 80)`
+- `--color-ink: oklch(20% 0.07 145)` — deep forest
+- `--color-ink-2: oklch(32% 0.05 140)`
+- `--color-muted: oklch(48% 0.04 130)`
+- `--color-rule: oklch(28% 0.28 350)` — deep magenta rules
+- `--color-accent: oklch(82% 0.20 130)` — chartreuse-lime
+- `--color-accent-2: oklch(28% 0.28 350)` — deep magenta (reads AA on paper, and as text)
+- `--color-accent-ink: oklch(20% 0.07 145)`
+- `--color-focus: oklch(28% 0.28 350)`
+
+**When to pick:** zine collectives · summer drops · skate / DIY culture · briefs that want LOUD without referencing music.
+
+### Drop 03 · Diner Sign
+
+Americana. Cream + cherry red + navy. Postwar diner, road trip, neon-and-chrome.
+
+- `--color-paper: oklch(95% 0.035 90)` — bright cream
+- `--color-paper-2: oklch(91% 0.042 88)`
+- `--color-paper-3: oklch(86% 0.050 85)`
+- `--color-ink: oklch(16% 0.04 30)` — black-brown
+- `--color-ink-2: oklch(28% 0.05 30)`
+- `--color-muted: oklch(45% 0.04 35)`
+- `--color-rule: oklch(30% 0.16 250)` — navy rules
+- `--color-accent: oklch(60% 0.22 25)` — cherry red
+- `--color-accent-2: oklch(30% 0.16 250)` — navy
+- `--color-accent-ink: oklch(95% 0.035 90)`
+- `--color-focus: oklch(30% 0.16 250)`
+
+**When to pick:** food + drink · hospitality · vintage Americana · briefs mentioning burgers, milkshakes, motels, roadside.
+
+### Drop 04 · Studio Night
+
+Cool + cool. Dusk warmth, cyan + plum. Late-night booth, blue hour, podcast studio at midnight.
+
+- `--color-paper: oklch(88% 0.05 25)` — warm dusk pink
+- `--color-paper-2: oklch(84% 0.055 22)`
+- `--color-paper-3: oklch(78% 0.06 20)`
+- `--color-ink: oklch(20% 0.05 270)` — deep navy-black
+- `--color-ink-2: oklch(32% 0.045 265)`
+- `--color-muted: oklch(48% 0.04 260)`
+- `--color-rule: oklch(24% 0.18 320)` — deep plum rules
+- `--color-accent: oklch(78% 0.18 220)` — cyan
+- `--color-accent-2: oklch(24% 0.18 320)` — deep plum (reads AA on paper, and as text)
+- `--color-accent-ink: oklch(20% 0.05 270)`
+- `--color-focus: oklch(24% 0.18 320)`
+
+**When to pick:** late-night radio · podcasts about anything · music + atmosphere · briefs mentioning "late", "after dark", "blue hour", "moonlight".
+
+### Drop 05 · Aqua Park
+
+Cool + warm. Turquoise against coral. Summer pool, motel sign, vacation.
+
+- `--color-paper: oklch(94% 0.040 180)` — pale aqua-cream
+- `--color-paper-2: oklch(90% 0.048 178)`
+- `--color-paper-3: oklch(84% 0.055 175)`
+- `--color-ink: oklch(20% 0.06 200)` — deep teal
+- `--color-ink-2: oklch(32% 0.05 198)`
+- `--color-muted: oklch(48% 0.04 195)`
+- `--color-rule: oklch(36% 0.24 35)` — deep coral rules
+- `--color-accent: oklch(72% 0.16 195)` — turquoise
+- `--color-accent-2: oklch(36% 0.24 35)` — deep coral (reads AA on paper, and as text)
+- `--color-accent-ink: oklch(20% 0.06 200)`
+- `--color-focus: oklch(36% 0.24 35)`
+
+**When to pick:** summer brands · vacation / hospitality · skate / surf / pool · briefs mentioning summer, beach, motel, sun.
+
+### Drop 06 · Pressroom
+
+Warm + cool. Amber-gold against slate-blue. 1950s journalism, print shop, broadsheet weight.
+
+- `--color-paper: oklch(89% 0.025 65)` — warm slate-cream
+- `--color-paper-2: oklch(85% 0.030 62)`
+- `--color-paper-3: oklch(79% 0.035 58)`
+- `--color-ink: oklch(16% 0.02 60)` — ink-black
+- `--color-ink-2: oklch(28% 0.025 58)`
+- `--color-muted: oklch(45% 0.025 55)`
+- `--color-rule: oklch(34% 0.10 240)` — slate-blue rules
+- `--color-accent: oklch(78% 0.18 75)` — amber-gold
+- `--color-accent-2: oklch(34% 0.10 240)` — slate-blue
+- `--color-accent-ink: oklch(16% 0.02 60)`
+- `--color-focus: oklch(34% 0.10 240)`
+
+**When to pick:** journalism · newsletters · editorial / opinion · briefs mentioning "press", "newspaper", "broadsheet", "subscription".
+
+### Drop rotation rule
+
+The diversification log (`.arka/design/log.json`) records the drop alongside the theme: `"theme": "carnival", "drop": "studio-night"`. **A new Carnival build picks a drop that hasn't appeared in the last 3 entries.** If only Cold Snap is in the log, any of the other five is valid. If the brief contains a strong drop signal (see "when to pick" above), honour the signal even if it tightens diversification.
+
+### Pick the drop by domain first
+
+Match the brief's **domain** before reaching for the loudest palette:
+
+- food / drink / hospitality / street market → **Diner Sign** (or Cold Snap)
+- independent music / labels / EPs → **Cold Snap** (or Pressroom)
+- late-night / radio / podcast / after-dark → **Studio Night**
+- summer / pool / beach / vacation → **Aqua Park**
+- zine / skate / DIY / deliberately chaotic → **Citrus Riot**
+- journalism / newsletter / editorial → **Pressroom**
+
+Citrus Riot and Aqua Park are the highest-chroma drops — reach for them when the brief genuinely *wants* maximum loudness, not as a default. A food market reads better in Diner Sign than in lime-on-magenta.
+
+### When to construct a custom drop instead
+
+If the brief explicitly names a brand colour that doesn't fit any catalog drop — e.g. *"our brand is teal and beige"* — route to the **custom theme** branch (see `custom-theme.md`) instead of stretching a Carnival drop. Drops are curated, not infinite. Six is the right number for now.
+
+## Reference register
+
+Dropout TV · Fly.io · Stones Throw Records · Third Man Records · Drag City · Moodelier · Kelsey Dake · Bold Monday.
+
+The aesthetic: independent music labels, comedy networks, illustrator portfolios, hot-sauce brands, indie game studios. Things with **character**. Things that print posters as a side hustle. Things that sound loud out loud.
+
+**Patron-saint reference (internal):** *Dropout TV homepage* + *Stones Throw artist pages*. When in doubt about decorative density, ask "would Dropout or Stones Throw run this much density?" If less, add ornaments. If more, you've gone too far.
+
+## Signature moves
+
+The theme's seven tics. A Carnival build should exhibit at least five of them.
+
+1. **Duo-tone accent system.** Sections alternate which accent fills them. Section 1 fills with `--color-accent` (mustard); section 2 fills with `--color-accent-2` (oxblood); section 3 mustard again; etc. One section never shows both — they are *competing*, not blended.
+
+   ```css
+   .section:nth-of-type(odd)  { --section-fill: var(--color-accent); }
+   .section:nth-of-type(even) { --section-fill: var(--color-accent-2); }
+   ```
+
+2. **Decorative ornaments.** Use `✱` (asterisk operator), `❋` (heavy six-petalled), `◆` (black diamond) as bullets, section dividers, and rhythmic spacers. Patterns:
+   - Section dividers: `✱ ✱ ✱ ✱` (repeated 4×, centred)
+   - List bullets: `❋` (replaces • / disc)
+   - Section heading prefixes: `◆ Section Name` (left-aligned, ornament in accent colour)
+
+3. **Layered colour blocks that bleed off the page edge.** Accent fills extend 24px past the page max-width on the left or right, so they read as **posters pinned to the wall**, not as buttons.
+
+   ```css
+   .colour-block { margin-inline: calc(var(--page-gutter) * -1); padding-inline: var(--page-gutter); }
+   ```
+
+4. **Hard-offset drop shadow.** Every card, CTA, and image gets `box-shadow: 4px 4px 0 var(--color-ink)`. No soft shadows ever. The shadow is **flat ink, offset**. This is the single most-recognisable Carnival move.
+
+5. **All-caps headlines with Big Shoulders variable-width, tightly tracked.** `font-variation-settings: "wdth" 110, "wght" 800;`. Track them **tight**, not loose: `letter-spacing: -0.005em` on the hero word, `0.02em` on section heads. The loose `0.04em` look reads as AI-spread and is reserved **only** for the marquee banner (where horizontal spread is the point). Keep line-height tight too: `0.82` for single hero words, `0.92` for multi-line heads. The effect is a marquee poster set by a typographer, not a stretched default.
+
+6. **Halftone pattern fills** in placeholder image regions. Pure CSS, no images:
+
+   ```css
+   .halftone {
+     background-image: radial-gradient(var(--color-ink) 1.5px, transparent 1.5px);
+     background-size: 12px 12px;
+   }
+   ```
+
+   Used wherever the page would otherwise have a photo placeholder.
+
+7. **Marquee scroll** on banner OR footer with decorative dot separators. *"NEW EP ◆ OUT NOW ◆ ON CASSETTE ◆ BLUE VINYL ◆ NEW EP ◆..."* — horizontal scroll, honours `prefers-reduced-motion: reduce` (freeze at static state).
+
+## Layout pitfalls (must avoid)
+
+Carnival's dense visual language has known traps. Read this list **before** writing a card layout — these are mistakes that have happened in earlier builds and shipped looking broken.
+
+1. **Halftone portrait + side-by-side text in a narrow card → text gets covered.** When pairing a halftone "host portrait" / "artist portrait" with a show / artist name in the same card, **never use a 2-column grid where the content column can collapse below 200 px**. On a 3-up `repeat(3, 1fr)` desktop grid, the content column inside each card is ~150–180 px wide and a 5 rem portrait squeezes the title into overlap. The safe patterns:
+   - **Vertical stack** (portrait on top, content below — the portrait sits naturally in the top-left of the card content area because of card padding). This is the default for portrait-paired cards.
+   - **Side-by-side ONLY at 2-up or 1-up grids** where the content column has ≥ 250 px to breathe.
+   - **Sticker corner** — portrait positioned `absolute; top: 0; right: 0` as a small badge, with text content flowing full-width below.
+
+   Concretely: if the card is in a `repeat(3, 1fr)` grid and includes a portrait + title pair, the card must use `display: flex; flex-direction: column;` with the portrait at a fixed `width: 4.5rem; height: 4.5rem;` (not `width: 100%`). Halftone squares **never** overlap typography.
+
+2. **Hard-offset shadow on a card next to a viewport edge → shadow gets clipped.** When a card sits flush against the right edge of the page gutter, its `4px 4px 0` shadow extends past the page max-width. Add `padding-right: max(var(--page-gutter), 8px)` to grids that include shadowed cards near the edge, or set the shell to have ≥ 8 px right margin past the card grid.
+
+3. **Duo-tone fill on a card whose content includes both accents → reads as "blended", not "competing".** A mustard tile must never contain an oxblood badge inside it. Pick one accent per tile. (Signature #1 explicitly says this — but it's worth restating here because it gets violated when adding a sticker or a "NEW" badge.)
+
+4. **Marquee scroll that doesn't repeat its content → gap at end of loop.** The marquee must contain the same scrolling text repeated at least twice (or use `aria-hidden` siblings) so the scroll animation reads as continuous, not as a single string sliding off.
+
+5. **Big Shoulders width axis used without `font-variation-settings` → no width variation.** Setting `font-stretch` on Google's Big Shoulders Display does not work — only `font-variation-settings: "wdth" 110` does. If you see a hero that's supposed to be width-110 but renders at width-100, this is the bug.
+
+6. **Section head detached from, or mis-centred over, its body.** The section head (heading + any lede) sits **tight above** the content it names — about `1.25rem` (`--section-head-gap`) — and **shares that content's alignment**. Don't cap the head at a narrow `max-width` / `ch` and then `margin-inline: auto` it: that strands a centred head over a full-width, left-flush grid (the classic accidental mismatch). Left-flush grid → left-flush head. (See the alignment-coherence note in `layout-and-space.md`.)
+
+7. **Newsletter / CTA button not aligned with the input beside it.** When a button sits next to a form input in one row, they must share the **same height, vertical padding, and border width**, and the row must use `align-items: center` — otherwise the button floats above the input's baseline. If a label is stacked above the input it makes that column taller; centre the row on the *control*, not the column (give the field `align-items: center` or pull the label out of the flex row).
+
+## Macrostructure affinity
+
+**Carnival loves these.**
+
+- **Marquee Hero** — the canonical Carnival opening; large word, scrolling banner under
+- **Type Specimen** — the page IS the type; Big Shoulders Display 96 px+ as content
+- **Manifesto** — short loud declarative statements (works for Carnival's voice too, but louder palette)
+- **Stat-Led** — when the page leads with numbers, Carnival displays them big-and-mustard
+- **Photographic** — image-led with halftone treatments and ornament captions
+- **Bento Grid** (loud variant) — gridded blocks where each tile alternates accent colour
+
+## Macrostructure rejection
+
+**Carnival refuses these.**
+
+- **Long Document** — too quiet; Carnival doesn't sustain over 1500 words
+- **Letter** — too intimate; Carnival never whispers
+- **Quote-Led** — too pensive
+- **Conversational FAQ** — too soft
+- **Workbench** — too technical; Carnival is poster art, not product spec
+
+If the brief would otherwise land in one of these, redirect to Marquee Hero or Manifesto.
+
+## Voice fixtures
+
+Sample lines the Carnival voice should *read like*. Short. Loud. Declarative. Caps on the headlines, not on the body.
+
+- *"FIVE NEW FLAVORS. ALL TOO HOT."*
+- *"WE PRESS RECORDS. THAT'S IT."*
+- *"NEW SEASON. NEW SHOWS. SAME CHAOS."*
+- *"ONE EP. THREE ARTISTS. NO REGRETS."*
+- *"THE GAME IS PIXEL ART. THE GAME IS HARD."*
+
+Body copy is **shorter than other themes**. 1–2 short sentences per paragraph. Paragraphs separated by ornament dividers, not whitespace alone.
+
+**Voice rules:**
+- Headlines: ALL CAPS, ≤ 6 words, period at end (not exclamation — the loudness is in the type, not the punctuation).
+- Body: sentence case, short, present-tense.
+- Numerals over words always (*5* not *five*).
+- Never any of: "experience", "journey", "elevate", "curate", "platform", "ecosystem", "transform". These are SaaS-default AI tells; Carnival is independent, not platformed.
+
+## Anti-patterns (theme-specific)
+
+- **Never soft shadows.** Carnival is hard-offset (`4px 4px 0`) or no shadow. If you find yourself reaching for `0 8px 24px`, redirect.
+- **Never both accents in one block.** Mustard *or* oxblood per section, never blended.
+- **Never sentence-case headlines.** Headlines are ALL CAPS or `font-variant: all-petite-caps`.
+- **Never light-grey text.** Body text is full-ink. Carnival doesn't do "subtle".
+- **Never long paragraphs.** If a paragraph exceeds 3 sentences, break it with an ornament divider or split into two blocks.
+- **Never neutral CTAs.** Every CTA fills with one of the two accent colours.
+- **Never thin rules.** Rules are 2 px solid in oxblood. Hairlines belong to Boutique / Specimen.
+- **Emoji as decoration is allowed when typographic** (✱ ❋ ◆ are typographic ornaments, not emoji). Smiley-face / heart emoji are still banned per universal anti-patterns.
+
+## How Carnival differs from neighbouring themes
+
+| vs | difference |
+|---|---|
+| **Riso** | Riso is risograph print-craft (peach paper, CMYK misregistration on display, cyan + yellow). Carnival is *editorial maximalism* — duo-tone, oxblood-on-pink, decorative ornaments, variable-width type. Different parent tradition. |
+| **Manifesto** | Manifesto is BLACK paper + ALL CAPS red Anton. Carnival is *tinted warm paper* + duo accents + ornaments. Inverted polarity — Manifesto is dark, Carnival is light. |
+| **Brutal** | Brutal is raw graphic-design brutalism (heavy borders, slab type, no ornaments). Carnival is **decorative** — ornaments, layered blocks, variable type, character. |
+| **Sport** | Sport is athletic italic uppercase (Inter Tight italic 700). Carnival is poster-art expressive (Big Shoulders 800 with width axis). Sport feels Nike; Carnival feels Drag City. |
+
+## Test brief expectations
+
+Carnival should be a candidate when the brief mentions:
+
+- *record label · podcast · comedy · indie · zine · poster · illustrator · games · hot sauce · merch · streetwear · cassette · vinyl · cassettes · live show · zine · brand of one*
+- product categories: music · comedy · games · illustration · hot sauce · merch · skateboards · gig posters
+- emotional tone: *loud, fun, scrappy, chaotic, layered, character-led, decorative*
+
+Briefs that say *enterprise / scale / API / B2B / dashboard* never route to Carnival.
+
+## Build hint
+
+When emitting a Carnival page, the first 12 lines of CSS should establish the four most important tells:
+
+```css
+body { background: var(--color-paper); color: var(--color-ink); font-family: var(--font-body); }
+h1, h2 { font-family: var(--font-display); font-weight: 800; font-variation-settings: "wdth" 110; letter-spacing: 0.02em; line-height: 0.92; text-transform: uppercase; } /* hero word goes tighter: letter-spacing: -0.005em; line-height: 0.82 */
+.card, .cta { box-shadow: 4px 4px 0 var(--color-ink); border: 2px solid var(--color-ink); }
+.section:nth-of-type(odd)  { background: var(--color-accent);   color: var(--color-accent-ink); }
+.section:nth-of-type(even) { background: var(--color-accent-2); color: var(--color-paper); }
+.ornament { color: var(--color-accent); }
+.halftone { background-image: radial-gradient(var(--color-ink) 1.5px, transparent 1.5px); background-size: 12px 12px; }
+```
+
+Those rules carry 70 % of the theme's identity. The rest is content fit.