FEED-DESIGN-SYSTEM

The /feed surface's design contract. Everything the module renders — the index, the thread page, the rails, the inspector, the composer — draws from the layers documented here. If a value you need is not here, add it here first; never hand-tint at the point of use.

Upstream context: docs/themes.md (§5 defines the feed bridge, §7 the always-dark panel rule), docs/UI-UX-BRIEF.md (the editorial thesis), docs/PRD.md (the feed's product scope).

1. Design thesis

The feed is an editorial social-forum hybrid: the rhythm of a timeline, the structure of a forum. Its visual language is the site's own — a near-monochrome canvas, one terminal-tinted action colour, monospace used as a structural device (metadata, counts, telemetry, section labels) rather than as decoration. Nothing on the surface is a screenshot number: every count, score and chart is derived from the corpus at render time.

Three commitments the module never breaks:

1. Role names, not hues. Colour is always consumed through the --color-feed-* bridge (§2). A component that needs a colour asks for a role (mint, azure, ink-2), never a hex.
2. The theme flips, the module does not. Light and dark are one token set re-scoped by .dark (§6). No surface hardcodes a text colour that should flip.
3. Motion is state, not decoration. Animation announces arrivals and marks activity (§7); nothing loops when nothing is live.

2. Colour tokens — the --color-feed-* bridge

Defined in resources/css/app.css (@theme), re-scoped for dark in the .dark block. Every value is a var() alias over the editorial ink / signal / info / danger scales — a pure alias layer, enforced by FeedTest (each declaration must start with var().

Rules

• mint and azure are roles. Because they alias signal-* and info, the public accent picker (data-accent) re-tunes the feed for free. Never write text-emerald-* or text-blue-* in a feed view.
• feed-mint is the action colour; feed-azure is the navigation colour. A button that acts is mint; a link that moves you is azure. They are never swapped.
• The always-dark terminal panels (code sample, review diff) are the one fixed-colour surface — static ink-950/ink-800/ink-300 tokens that never re-scope (docs/themes.md §7). feed.css may contain exactly one hex literal: the diff's delete red #f87171, which must not brighten with the theme. FeedTest pins this.

3. Type vocabulary

Base scale is the site's editorial scale (1.200 minor third) — the feed adds four named grades in feed.css so metadata never composes font-mono text-[10px] … by hand:

Weight (font-semibold) and colour (text-feed-mint, text-feed-ink) stay utilities so a variant is visible where it is used. Body copy and headings use the shared scale (text-sm, text-base, clamp()ed h1) — the feed invents no sizes of its own beyond the four grades.

4. Component vocabulary

All defined in resources/css/feed.css. Markup adds utilities for padding and layout; anything structural or stateful lives here.

Fragments on the index

• Broadcast band — identity (avatar, name, role, verification) + the headline, the four-figure readout, the always-dark topic-signal panel and the ticker; then the section tabs. Tabs name routes that exist; nothing is a dead link.
• Command bar — live pill above the filter row, so an arrival never moves the stream.
• Three-column grid — lg:grid-cols-[minmax(0,1fr)_20rem], xl:grid-cols-[14rem_minmax(0,1fr)_20rem]; on phones the stream is order-1. Pinned by FeedTest's responsive contract.
• Stream — one card per row; each card is author → body → artefact → tags → meta bar. The artefact is the type's own: terminal panel (code), poll bars, topic tile, accepted-answer callout.
• Inspector widgets — every widget is a .feed-card with a .feed-eyebrow header and .feed-inset tiles; every figure is derived from the passed collections.

5. The broadcast layer

The feed reads as a broadcast surface, not a timeline: a loud top band that states what the platform is and how much of it is live, a moving ticker that surfaces the actual vocabulary of the corpus, a single-column wire of cards, and a console-style rail on the left.

Rules the layer obeys

1. One home for the totals. The corpus figures (posts / people / solved / unanswered) live in the hero and nowhere else on the page. FeedTest pins substr_count($html, 'People') === 1. The inspector shows reader-specific numbers instead (your posts, member since) and corpus-derived but non-duplicated figures (answer rate, peak week).
2. Every figure is real. The hero readout, the topic meters, the ticker tags and the activity chart all read the memoised posts / topics / typeCounts / trendingTags computed properties. The band adds zero SQL — the page still renders four owned queries.
3. The marquee loops on a duplicate track. The second copy is inert aria-hidden="true", so the loop is seamless without duplicating focusable links or tripping the focusable-inside-aria-hidden rule.
4. Drama comes from scale and structure, not decoration. No glass, no neon, no gradient wash of a second hue. The impact is a huge headline, a hard-edged grid texture, one solid accent block, and a real ticker.

The composer (pages/feed/⚡composer-modal.blade.php)

The write surface rides the same tokens as the rest of the module; the modal shell is the app's (x-app.ui.modal), the composer's insides are the module's. The composer never hardcodes a surface colour — a sticky bar on a phone fills with bg-feed-canvas, never a raw bg-white/dark:bg-zinc-800 pair (that pair once shipped here; it stranded a light bar on the dark canvas exactly like the amber chip did).

Rules the composer obeys:

1. Sticky bars are canvas-filled, not colour-guessed. The dialog is the scroll container at every size, so header and publish bar are sticky on phones and must carry a token fill.
2. Fields never re-declare their run. A form-field change is one edit in feed.css, not twelve in the Blade.
3. The preview is the proof. It renders through the same vocabulary the wire card uses — same title weight, same terminal panel for snippets — so what an author approves is what a reader sees.
4. In the grid texture's zone, content paints above it. Children of .feed-dropzone carry relative — the ::before is positioned and would otherwise paint over in-flow text.

6. Interaction & spacing rhythm

• Spacing sits on Tailwind's 4px grid; the module's recurring paddings are p-2 (rails), p-4 (cards/widgets), p-2.5 / p-3 (insets).
• Surfaces separate by fill, not by heavier borders: canvas → card → well/raised is a three-step ladder; the hairline is always 1px.
• Hover is a fill or a border shift (150ms --ease-soft); the active page or tab is a spine or an underline, not a heavier shadow.
• Focus is the global :focus-visible outline; interactive elements that suppress it use the shared focus-ring utility.

7. Theming — how the module matches the rest of the app

• Dark is the site default; partials/theme-boot applies .dark pre-paint. The feed flips through the same .dark re-scope as every public surface — it ships no private dark palette.
• The dashboard's Soft UI scope ([data-sui]) never reaches the feed: the two surfaces are intentionally different voices of one brand.
• The accent picker (data-accent on <html>) re-tunes signal-*, and the bridge resolves feed-mint from it — so mint, the live dot, pinned spines and the action glow all follow the visitor's chosen accent while azure stays navigational blue.
• Semantic warning (attention chips) and danger (error chips, unanswered counts) also re-scope, which is why .feed-chip.is-attention / .is-error are token-built rather than raw amber/red utilities: a raw bg-amber-500/15! chip is a light chip stranded on the dark canvas.

8. Motion

9. Accessibility contract

• Landmarks: skip link → <main id="main">; the band labelled by its h1 (feed-cover-heading); both pinned by FeedTest.
• Live regions: the stream and the count line are aria-live="polite"; the arrivals pill announces the pending count.
• Menus/tabs: aria-haspopup, x-bind:aria-expanded, aria-current, role="menu"/"menuitem"/"listbox", Escape to close.
• The composer's type chips are a toggle group: aria-pressed marks the selected type, and the active rail item carries aria-current="page".
• The marquee's duplicated track is inert aria-hidden="true" — a seamless loop without duplicate focus stops.
• Every <img> (post media) carries the author's own alt; icons are aria-hidden; telemetry charts carry an sr-only summary.
• Text pairs were chosen against the surfaces they sit on (ink-3 never on well fills at small sizes except for non-essential metadata).

10. Conventions for change

1. New colour need → add a --color-feed-* role in app.css (a var() alias, both themes), then consume it. FeedTest rejects raw values.
2. A utility run repeated three or more times → promote it to a class in feed.css's primitives section and migrate every use.
3. New chip tone → a named is-* variant, never an ad-hoc tint.
4. New figure on the page → decide its single home first. The corpus totals belong to the band; the inspector carries reader-specific and derived-not-duplicated numbers only.
5. New motion → one signature loop per surface. The band owns the rise choreography and the ticker; nothing else animates continuously.
6. Tests guard the system: the bridge purity, the one-hex rule, the responsive grid tracks, the landmarks, the active-tab contract, the compare notes headline and the single-home totals rule.