@teamblind-chorus/ui 1.0.0

package/agents/images.md

@@ -0,0 +1,66 @@
+# Images — generate vs. placeholder
+
+How to fill Chorus image slots (`Thumbnail.src`, `Feed.thumbnail`, `FeedAd.media`, `ProfileHeader` avatar/cover, `ProfileCarousel.items[].cover`, every `"assetType": "image"` slot) so a screen reads as finished — not a wall of placeholders, and not hallucinated real brands.
+
+This is the **method** behind AGENTS.md rule #9 ("when the composition gives a clear subject, swap the placeholder for a context-appropriate image"). Rule #9 names the goal; this file is the decision tree, the sanctioned generation path, and the handoff report.
+
+## The decision tree (run per image slot)
+
+```
+Is a real asset given (data field, URL, upload)?
+  └─ yes → use it. Done.
+Does the composition imply a CLEAR subject?
+  ├─ no  → /placeholder.png. (No subject to depict — the branded placeholder is honest, not unfinished-by-mistake.)
+  └─ yes → is the subject BRAND-SAFE TO SYNTHESIZE?
+        ├─ yes (abstract avatar, generic cover band, topic/content thumbnail,
+        │       illustrative scene) → GENERATE it (see below).
+        └─ no  (a real company's actual logo, a real named person's face,
+                a copyrighted mark) → /placeholder.png + TODO.
+                Never synthesize a real brand/person — a plausible fake is worse
+                than an honest placeholder.
+```
+
+**The hybrid rule in one line:** generate where the subject is clear *and* safe to invent (avatars, covers, post thumbnails, illustrations); placeholder where the subject is real-world-specific (actual logos, real people) or absent — and always *report* what stayed on placeholder.
+
+## Generate ≠ invent a stock URL
+
+anti-patterns §13 forbids "an invented stock URL" / inline-SVG wordmark / `display:none` as a placeholder workaround. That prohibition stands. It is **not** the sanctioned path here. Sanctioned generation is: produce the asset with your image-generation tool (e.g. `imagegen`), upload it through your asset pipeline (e.g. `lovable-assets`), and store the returned URL in the data field. The difference: a generated, uploaded, self-hosted asset is a real asset the app owns; a pasted `images.unsplash.com/…` URL is an unowned, breakable, off-contract reference. Generate-and-host = allowed; link-to-someone-else's-image = forbidden.
+
+### Prompt shape per slot
+
+- **Avatar (person / anonymous member)** — abstract or illustrative profile, no real face: "minimal flat illustrative avatar, neutral studio background, no text." Square. Feed/List/Metadata leading.
+- **Channel / org logo** — only if generic/fictional. A real company → placeholder + TODO. Generic → "simple geometric monogram logo, flat, single accent color, transparent or neutral fill."
+- **Cover band (ProfileHeader / Carousel cover)** — "calm abstract gradient/texture banner, on-brand neutral palette, no text, wide aspect." Wide.
+- **Post thumbnail** — match the body topic: "editorial photo of <topic>, natural light, uncluttered." 80×80 crop-safe.
+
+Keep generated imagery calm and on-palette so it sits under Chorus tokens; the slot's footprint/chrome never changes — **only the `src` URL changes**.
+
+## Make the data model image-ready (the upstream fix)
+
+The most common cause of placeholder-everywhere is a mock/data model with **no image field** — so the screen has nothing to bind, and every slot hardcodes `/placeholder.png`. Fix it at the type, once:
+
+```ts
+// ❌ Drift root — no image field, so every Thumbnail/Feed slot hardcodes the placeholder
+type Author = { id: string; handle: string; role: string };
+type Post   = { id: string; title: string; body: string };
+
+// ✅ Image-ready — every entity that feeds an image slot carries the field,
+//    initialized to the placeholder. Swapping in a real/generated image is then
+//    a one-field edit, never a schema migration.
+type Author = { id: string; handle: string; role: string; avatarUrl: string };  // = "/placeholder.png" until filled
+type Post   = { id: string; title: string; body: string; thumbnailUrl: string };
+```
+
+When you scaffold mock data, **add the image field and seed it** (placeholder, or a generated URL per the tree above) — don't omit the field and hardcode `/placeholder.png` at the call site. A seeded field is swappable; a hardcoded `src` is a find-and-replace across screens.
+
+## Report what stayed on placeholder (the handoff)
+
+A placeholder left silently reads as "done." After composing a screen (or a batch), **post an image-status line** so remaining slots are a visible TODO, not a mistake:
+
+> `Images: 4 real · 6 generated · 3 on placeholder — TODO: <ChannelLogo (real Acme logo), 2× real-author avatars>. Say the word to generate/swap.`
+
+List the placeholder slots and *why* each stayed (real-brand/real-person → needs a real asset; no subject → intentionally blank). This makes the hybrid policy auditable and lets the user green-light the real-asset items in one turn.
+
+---
+
+See also: [anti-patterns.md §13](anti-patterns.md) (placeholder 404 / forbidden workarounds), AGENTS.md rule #9 (the image-slot contract), and each `*/*.spec.json` image-slot description.

package/agents/manifest.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "name": "@teamblind-chorus/design-system",
+  "version": "0.0.0",
+  "description": "Machine-readable inventory of the Chorus design system. External consumers (Claude Design, the docs site, AI agents, design-tool plugins) MUST read this file as the single entry point — never crawl schema/ to infer the system's shape. The file is hand-authored and kept in lock-step with schema/components/<family>/ folders; any new family or sub-component lands here before it lands anywhere else.",
+  "agentEntrypoint": "../AGENTS.md",
+  "catalog": "catalog.md",
+  "design": "DESIGN.md",
+  "tokens": {
+    "reference": "tokens/reference.json",
+    "system": "tokens/system.json",
+    "component": "tokens/component.json",
+    "resolved": {
+      "light": "tokens/resolved.light.json",
+      "dark": "tokens/resolved.dark.json",
+      "web": "tokens/resolved.web.json",
+      "webDark": "tokens/resolved.web.dark.json"
+    },
+    "build": "tokens/build-resolved.mjs",
+    "note": "Three-tier source: `ref.*` raw, `sys.*` semantic (the default tier for bindings), `comp.*` reserved-but-empty. External renderers should read the `resolved.*` bundles — flat `path → { $value, $type }` maps with all `{ref.…}` references dereferenced and theme/breakpoint overlays applied. `resolved.light.json` and `resolved.dark.json` are full bundles (one entry per token); `resolved.web.json` and `resolved.web.dark.json` are sparse — only the tokens that change at the `web` (≥800px) breakpoint. Regenerate with `node schema/tokens/build-resolved.mjs` (or `npm run build:tokens`) whenever a source file changes."
+  },
+  "icons": {
+    "svg": "icons/svg/",
+    "manifest": "icons/icons.json",
+    "build": "../packages/ui/src/icons/build-icons.mjs",
+    "generated": "../packages/ui/src/icons/index.js",
+    "exportSubpath": "@teamblind-chorus/ui/icons",
+    "note": "Schema-first, like tokens: the source artwork (`icons/svg/*.svg`) and manifest (`icons/icons.json` — per-icon keywords + alias map) live here; `packages/ui` generates the consumable React module (`index.js`, exported as `@teamblind-chorus/ui/icons`) via `npm run build:icons`. Product surfaces import the generated module, never the schema sources. Regenerate whenever an svg or the manifest changes."
+  },
+  "schemas": {
+    "family": "family.schema.json",
+    "spec": "spec.schema.json"
+  },
+  "packages": {
+    "components": {
+      "name": "@teamblind-chorus/ui",
+      "entry": "packages/ui/src/index.js",
+      "icons": "packages/ui/src/icons/index.js",
+      "styles": "packages/ui/src/styles.css",
+      "iconsExportSubpath": "@teamblind-chorus/ui/icons",
+      "stylesExportSubpath": "@teamblind-chorus/ui/styles.css",
+      "published": false,
+      "distribution": "source",
+      "note": "Workspace-only, source-distributed. External tools either (a) read JSX directly from `entry` (compile JSX themselves) or (b) consume the structural contract via `schema/components/<family>/<sub>.spec.json` and re-render with their own renderer. Either path MUST also load `styles.css` once at the app entry — the JSX emits inline `--<component>-*` plumbing vars but expects the static rules in `styles.css` to receive them. The package is marked `private: true` and intentionally pinned at version `0.0.0` until a publishing decision is made."
+    },
+    "tokens": {
+      "name": "@teamblind-chorus/tokens",
+      "published": false,
+      "distribution": "source",
+      "note": "Workspace-only. External tools should prefer the `tokens.resolved.*` bundles above over the three-tier source files unless they specifically need the reference graph."
+    }
+  },
+  "components": [
+    { "family": "badge",          "root": "components/badge/badge.family.json" },
+    { "family": "banner",         "root": "components/banner/banner.family.json" },
+    { "family": "bottom-sheet",   "root": "components/bottom-sheet/bottom-sheet.family.json" },
+    { "family": "bubble",         "root": "components/bubble/bubble.family.json" },
+    { "family": "button",         "root": "components/button/button.family.json" },
+    { "family": "suggestion-list", "root": "components/suggestion-list/suggestion-list.family.json" },
+    { "family": "avatar-rail",    "root": "components/avatar-rail/avatar-rail.family.json" },
+    { "family": "chip",           "root": "components/chip/chip.family.json" },
+    { "family": "dialog",         "root": "components/dialog/dialog.family.json" },
+    { "family": "divider",        "root": "components/divider/divider.family.json" },
+    { "family": "directory-list", "root": "components/directory-list/directory-list.family.json" },
+    { "family": "feed",           "root": "components/feed/feed.family.json" },
+    { "family": "form-field",     "root": "components/form-field/form-field.family.json" },
+    { "family": "header",         "root": "components/header/header.family.json" },
+    { "family": "list",           "root": "components/list/list.family.json" },
+    { "family": "metadata",       "root": "components/metadata/metadata.family.json" },
+    { "family": "nav-card",       "root": "components/nav-card/nav-card.family.json" },
+    { "family": "nav-list",       "root": "components/nav-list/nav-list.family.json" },
+    { "family": "navigation-bar", "root": "components/navigation-bar/navigation-bar.family.json" },
+    { "family": "page-shell",     "root": "components/page-shell/page-shell.family.json" },
+    { "family": "profile-header", "root": "components/profile-header/profile-header.family.json" },
+    { "family": "progress",       "root": "components/progress/progress.family.json" },
+    { "family": "carousel",       "root": "components/carousel/carousel.family.json" },
+    { "family": "side-sheet",     "root": "components/side-sheet/side-sheet.family.json" },
+    { "family": "skeleton",       "root": "components/skeleton/skeleton.family.json" },
+    { "family": "status-tag",     "root": "components/status-tag/status-tag.family.json" },
+    { "family": "switch",         "root": "components/switch/switch.family.json" },
+    { "family": "tab-bar",        "root": "components/tab-bar/tab-bar.family.json" },
+    { "family": "tabs",           "root": "components/tabs/tabs.family.json" },
+    { "family": "thumbnail",      "root": "components/thumbnail/thumbnail.family.json" },
+    { "family": "toast",          "root": "components/toast/toast.family.json" },
+    { "family": "tooltip",        "root": "components/tooltip/tooltip.family.json" }
+  ]
+}

package/agents/patterns/README.md

@@ -0,0 +1,59 @@
+# Patterns
+
+Canonical visual references for Chorus. Each pattern pairs an **image board** (`<slug>.png`) with a spec note (`<slug>.md`) covering intent, layout, tokens, and components. Boards are grouped by *what the surface does* — each `.png` is a montage of representative screens so an agent can learn a category's recurring patterns and visuals at a glance.
+
+Schemas say *what is allowed*; patterns say *what good looks like*.
+
+## Precedence (read this first)
+
+Patterns are **descriptive**, not prescriptive. The list below is **authority on conflict**, distinct from [`AGENTS.md`](../AGENTS.md) "Read order" (the *intake sequence*). Read order = where to look first; precedence = who wins when two sources disagree.
+
+1. **Hard rules** in [`AGENTS.md`](../AGENTS.md) — always win.
+2. **Component specs** in [`schema/components/<family>/<sub>.spec.json`](../schema/components) and [`schema/DESIGN.md`](../schema/DESIGN.md) — authoritative for props, slots, sizes, appearances, states, and cross-cutting design rules.
+3. **Resolved tokens** in [`schema/tokens/`](../schema/tokens) — authoritative for color/type/space/radius values.
+4. **Patterns (this directory)** — visual reference and rationale only. If a pattern note conflicts with a spec or token, the spec/token wins; treat the pattern as out of date and fix it.
+
+## How agents should use this
+
+1. Scan for the closest intent match (use `status: canonical` first).
+2. Read the `.md` for load-bearing tokens, components, and layout decisions.
+3. Pull the image in if pixel-level alignment matters (spacing rhythm, hierarchy, dark/light parity).
+4. Cross-check against `*.spec.json` and `resolved.*.json` — those are the contract; this is the inspiration.
+
+## File layout
+
+```
+patterns/
+  README.md              # this file — index
+  <slug>.png             # image board (montage of representative screens), sRGB; dark variant: <slug>.dark.png
+  <slug>.md              # spec note for the board
+```
+
+Each board groups screens by *function*, not by destination. A single screen's patterns may be referenced from more than one board (e.g. the Company feed appears in both [layout](layout.md) and [browsing](browsing.md)).
+
+## Index
+
+<!-- Keep alphabetical. Add a row when you add a board. -->
+
+| Board | Status | Covers |
+|-------|--------|--------|
+| [actions](actions.md) | canonical | Forms, inputs, checklists, filters, and primary-commit surfaces — verification, registration, reviews, Filter Settings, create shortcuts. |
+| [browsing](browsing.md) | canonical | Entity discovery & navigation — channel drawers, all/followed lists, Explore rails, search suggestions, company feed; Follow/Unfollow toggles. |
+| [communications](communications.md) | canonical | Authored content & engagement — posts, polls, gated previews, comment threads, channel picker, offer/poll compose. |
+| [layout](layout.md) | canonical | Page scaffolding & nav chrome — Home, Company, Explore, Jobs, Notifications + channel profile; bars, tabs, filter rails, shared gutter. |
+| [modals](modals.md) | canonical | Overlay surfaces — confirmation & info Dialogs, full-screen disclosure, bottom-anchored CTAs, BottomSheet purchase flows. |
+| [visual](visual.md) | canonical | Image-bearing surfaces — empty-state illustrations, photo grids, brand/media cards, category tiles, illustration banners; the `/placeholder.png` image-area contract. |
+
+> Board slugs use single-word `lowercase` names.
+
+## Status values
+
+- **canonical** — signed-off reference. Agents should bias toward matching this.
+- **draft** — proposed direction; do not assume tokens/components are final.
+- **deprecated** — kept for diffing against newer canonical versions. Do not copy.
+
+## Adding a board
+
+1. Drop `<slug>.png` (a montage of representative screens; optional `<slug>.dark.png`) here. Prefer device-frame-free crops at component-pixel density.
+2. Create `<slug>.md` with frontmatter (`name`, `image`, `status`) and the sections used by existing boards: **Intent**, **Board cells** (one line per screen in the montage), **Layout**, **Tokens in use**, **Components**, **Notes**.
+3. Add a row to the index above.

package/agents/patterns/actions.md

@@ -0,0 +1,50 @@
+---
+name: actions
+image: ./actions.png
+status: canonical
+---
+
+## Intent
+
+Task-completion surfaces — the user supplies input and commits. Verification forms, keyword/post registration, service-agreement checklists, comment composition, job filter settings, and the home content-creation shortcuts. Each surface is keyboard-first and terminates in **one** high-emphasis primary commit (a full-width or trailing blue `button / standard`), with neutral escapes parked around it. Reach here for the anatomy of "fill something in, then commit it".
+
+## Board cells
+
+1. **Work-email verification** — `navigation-bar / sub` (Company), explainer copy, `form-field / input` (`name@amazon.com`), primary "verify" CTA, neutral "Back", keyboard up.
+2. **Keyword registration** — title `form-field / input`, primary "Register" CTA, helper text.
+3. **Service-agreement checklist** — `button / check` agreement rows, `form-field / input` email, primary "Next" CTA, keyboard up.
+4. **Comment composition** — post body above a reply composer: `form-field / textarea` + image-attach `button / icon`, two privacy `button / check` toggles ("Company name undisclosed" / "Company colleague"), primary "Register" CTA, keyboard up.
+5. **Filter Settings** — `form-field / search` company filter, multi-select company checklist, primary "Apply", "Reset Filter" text reset.
+6. **Home action shortcuts** — Create a Post / Share a Story / Create a Story entry card on the feed.
+
+## Layout
+
+- **Single primary commit per surface** — one blue `button / standard` (filled primary). It anchors the bottom of the form or trails the input; never two competing primaries.
+- **Escapes are subordinate** — "Back"/"Reset Filter"/"Not now" render as `button / text`, visually lighter than the commit.
+- **Inputs stack vertically** with helper/placeholder text in secondary color directly under or inside the field.
+- **Checklists** are `button / check` rows (commit option state) or a search-filtered selection list; the commit (`Apply`/`Next`) lives at the bottom.
+
+## Tokens in use
+
+- **color**: primary CTA `sys.color.primary` bg + `sys.color.onPrimary` label; input fill `sys.color.surfaceContainerLow`; placeholder + helper `sys.color.onSurfaceVariant`; text escapes in `sys.color.onSurface` (neutral) or accent blue (link-shape).
+- **spacing**: `sys.layout.stack.lg` between form blocks, `sys.layout.stack.md` within a block; page shell pays `sys.layout.page.md` once.
+- **typography**: field + body input `sys.typo.body.md`; titles `sys.typo.heading.md` bold; helper `sys.typo.body.sm` secondary; CTA `sys.typo.label.lg`.
+- **radius**: inputs/buttons `sys.radius.md`; filter chips fully rounded.
+
+## Components
+
+- [[form-field/input]] — verification, title, email entry.
+- [[form-field/textarea]] — multiline comment body.
+- [[form-field/search]] — company filter in Filter Settings.
+- [[button/standard]] — the primary commit (verify / Register / Next / Apply).
+- [[button/text]] — Back, Reset Filter, secondary escapes.
+- [[button/check]] — agreement rows + multi-select company checklist.
+- [[navigation-bar/sub]] · [[navigation-bar/search]] — top chrome.
+
+## Notes
+
+- **FormField is `visualReuse: "locked"`** (AGENTS.md principle 5) — use it only for real text entry, never borrowed for shape.
+- **Apply / Reset is a pair**: `Apply` = primary `button / standard`; `Reset Filter` = `button / text`. Don't promote Reset to a second filled button.
+- **Comment composer pairs privacy toggles with the commit** — the "Company name undisclosed" / "Company colleague" options are `button / check`, the image attach is a `button / icon`, and the commit is the single primary "Register"; don't model the privacy options as a second commit.
+- Checkmarks and grid glyphs are **SVG icon components**, never typed `✓` characters (rule 10).
+- Source mixes EN/KR; demo strings render English per AGENTS.md rule 7.

package/agents/patterns/browsing.md

@@ -0,0 +1,52 @@
+---
+name: browsing
+image: ./browsing.png
+status: canonical
+---
+
+## Intent
+
+Entity discovery and navigation — channel drawers, all/followed channel lists, Explore trending rails, search empty/suggestion states, and the company feed. Lists of entities (channels, companies, posts) are the spine; the per-row commit is **Follow / Unfollow** (`button / toggle`), and the **whole row is the nav click target**. Reach here for "browse a set of things and follow/open one".
+
+## Board cells
+
+1. **My Channel drawer** — grouped `nav-list` (Favorites, Channels I'm Following) + "Create Channel" header action; the channel side-navigation.
+2. **All Channels** — channel `list / entry` with a Followed-Channels section carrying `button / toggle` "Unfollow".
+3. **Followed Channels** — "Recent Visits" header, per-row `button / toggle` "Unfollow" with member counts.
+4. **Explore** — Trending Channels rows with `button / toggle` "Follow", "New Channels" media `nav-card`s, `tab-bar`.
+5. **Search no-results** — empty state + "Popular Channels" / "Popular Companies" suggestion lists with "View All".
+6. **Company feed** — company `tabs` + recruiter `banner` + POPULAR `feed / post` items.
+
+## Layout
+
+- **Entity row anatomy** — leading avatar/logo `thumbnail`, name (bold) + one-line meta (member count / blurb), trailing `button / toggle` commit.
+- **Grouping by relationship** — sections ("Favorites", "Following", "Recent Visits") separate the same row shape by scope; keep as discrete sections with their own headers.
+- **Discovery rails** — Explore mixes vertical channel rows with media-card previews; section headers carry a trailing "View All / See all" `button / text`.
+- **Empty state** — "No results" headline then suggestion lists, so the surface never dead-ends.
+
+## Tokens in use
+
+- **color**: `sys.color.surface` page, `sys.color.onSurface` names, `sys.color.onSurfaceVariant` meta; Follow = brand-blue solid (`sys.color.primary` / `onPrimary`), Unfollow = outlined neutral; accent blue on "See all" links.
+- **spacing**: `sys.layout.stack.md` between rows, `sys.layout.stack.lg` between sections; one shared gutter (`sys.layout.page.md` once).
+- **typography**: channel name `sys.typo.heading.sm` bold; meta `sys.typo.label.sm`; section headers `sys.typo.heading.md` bold.
+- **radius**: avatars circular; media cards `sys.radius.md`; toggle pills fully rounded.
+
+## Components
+
+- [[nav-list]] — channel drawer / side navigation, grouped.
+- [[list/standard]] — avatar-anchored channel rows.
+- [[directory-list]] — dense followed/all-channel directories.
+- [[button/toggle]] — Follow / Unfollow, the per-row commit (parity in both states).
+- [[nav-card]] — "New Channels" media preview cards.
+- [[avatar-rail]] — horizontal entity quick-nav where used.
+- [[navigation-bar/sub]] · [[tab-bar]] — chrome.
+- [[feed/post]] — company-feed stream.
+- [[button/text]] — "View All / See all" section actions.
+
+## Notes
+
+- **Rows are the click target** (AGENTS.md): the leading avatar and the trailing toggle are *not* separate hit areas — tapping the row opens the channel, the toggle only flips follow state.
+- **Follow / Unfollow is one `button / toggle`** shown in both states — this board is the parity reference; don't model them as two different buttons.
+- **AvatarRail ≠ SuggestionList ≠ nav-list**: horizontal quick-nav vs vertical follow-suggestion block vs grouped menu. Pick by the cell's job, don't interchange.
+- "View All / See all" link-affordance text buttons use `appearance="accent"` (AGENTS.md rule 8).
+- Source mixes EN/KR; demo strings render English per AGENTS.md rule 7.

package/agents/patterns/communications.md

@@ -0,0 +1,56 @@
+---
+name: communications
+image: ./communications.png
+status: canonical
+---
+
+## Intent
+
+Authored content and engagement — posts, embedded polls, gated previews, comment threads, the channel picker for posting, and offer/poll compose. `feed` is the spine for content streams; `list / radio` carries poll options; compose surfaces commit via a Cancel/Post action bar. Reach here for "read, react to, or author a post or comment".
+
+## Board cells
+
+1. **Poll post** — `feed / post` body + `list / radio` poll with result bars ("128 Participants") + Like / Comment / Message footer.
+2. **Gated preview** — blurred body behind a "Tap to View" reveal CTA; "Prevent preview" affordance.
+3. **Post + reply** — long-form post body, inline "Register" CTA, comment compose with keyboard up.
+4. **Comment thread** — `feed` comment stream, nested replies on a sunken surface, persistent bottom compose bar.
+5. **Select Channel sheet** — `bottom-sheet` channel picker with `form-field / search` and grouped channel rows (where to post).
+6. **Offer/Poll compose** — Cancel/Post action bar, title input, "Create an Offer or Poll" pill, "Popular Tags" chip row, keyboard up.
+
+## Layout
+
+- **Post anatomy** — author block (avatar, channel + time, workplace · role · alias), title, body, then a footer action row (heart / comment / message / view). Two meta lines on the author block are load-bearing.
+- **Poll** — a soft container quoting `banner` shape: leading Poll icon, participant header, helper, then `list / radio` option rows with result bars.
+- **Comment thread** — sort/jump `button / text` controls on top; nested replies use a `sys.color.surfaceContainerLow` block (not a left rule); compose bar pinned to the bottom safe area.
+- **Compose** — top bar is a modal action bar (Cancel / Post), *not* a `navigation-bar`; channel + identity rows, title/body inputs, an offer/poll FAB, and a Popular Tags chip rail.
+
+## Tokens in use
+
+- **color**: active heart + Poll icon in coral (`sys.color.brand`); links / Cancel-Post-valid / jump controls in accent blue (`sys.color.primary`); verified badge accent blue; nested-reply block `sys.color.surfaceContainerLow`; Popular Tags chips `chip / tag` `accent` (primaryContainer + primary label).
+- **spacing**: `sys.layout.stack.lg` between title/body/poll and between comments; footer row gap `sys.layout.stack.md`.
+- **typography**: post title `sys.typo.heading.md`–`display.md` bold; body `sys.typo.body.lg`; comment body `sys.typo.body.md`; meta `sys.typo.label.sm`.
+- **radius**: poll container `sys.radius.md`, option rows `sys.radius.sm`; offer pill + chips fully rounded.
+
+## Components
+
+- [[feed/post]] — post and comment streams.
+- [[list/radio]] — poll options.
+- [[form-field/input]] — title / body / comment compose bar.
+- [[bottom-sheet]] — Select Channel picker (paired trigger from compose).
+- [[form-field/search]] — channel search inside the picker.
+- [[list/standard]] — channel rows in the picker.
+- [[button/text]] — Cancel / Post, sort, jump-to-latest, load-earlier.
+- [[button/fab]] — "Create an Offer or Poll" pill (`appearance: secondary`).
+- [[chip/tag]] — Popular Tags (clickable suggestions, `accent`).
+- [[badge]] — verified checkmark on author handles.
+- [[button/toolbar]] — post-level action cluster (share / subscribe / bookmark / overflow).
+
+## Notes
+
+- **Compose top bar is an action bar** (Cancel / Post), not `navigation-bar/*`. Don't retrofit a sub bar.
+- **The offer/poll pill IS `button / fab` `secondary`** — the canonical commit for compose; "Post" in the top bar is finalize chrome (`button / text`), so the ≤1-FAB rule holds.
+- **Comment compose bar is persistent**, docked while scrolling — model as a pinned `form-field/input`, never a `bottom-sheet`.
+- **Popular Tags are `chip / tag` `accent`, not `chip / filter`** — taps insert a tag, they don't toggle filter state.
+- **Poll options are `list / radio`** inside a banner-shaped container; don't bake results into the title string.
+- "Tap to View" gated reveal is an overlay affordance over blurred media — out-of-system chrome; don't synthesize a component.
+- Source mixes EN/KR; demo strings render English per AGENTS.md rule 7.

package/agents/patterns/layout.md

@@ -0,0 +1,72 @@
+---
+name: layout
+image: ./layout.png
+status: canonical
+---
+
+## Intent
+
+Page-level scaffolding and navigation chrome across the five main tab destinations — **Home, Company, Explore, Jobs, Notifications** — plus a channel profile. This board is the reference for *frame*, not content: how a screen seats its top bar, in-page tabs, filter rail, scrolling body, and bottom tab bar so every destination reads as one geometry. When composing any full screen, match the scaffold here before filling slots.
+
+## Board cells
+
+1. **Home** — `navigation-bar / main` (hamburger · wordmark · icon cluster), `avatar-rail` feed-mode chips (For You / Recent / Popular), recruiter + keyword banners, `feed / post` stream, `tab-bar`.
+2. **Company** — `navigation-bar / sub` "Company", `tabs / underline` (MY COMPANY / FOLLOWING), `chip / filter` company-scope rail, collapsible "Overview" `banner`, `feed / post`.
+3. **Explore** — `tabs / underline` (Explore / My Channels), "Recommended for you" preview cards, "Hot Posts" section, `tab-bar`.
+4. **Jobs** — `navigation-bar / search`, `tabs / underline` with inline counts (Jobs 3,401 / Saved 4), `chip / filter` facet rail, bookmarkable job list, "Job saved" `toast`.
+5. **Notifications** — `navigation-bar / sub`, settings-off `banner` ("Open iOS Settings"), recruiter banner, bell-leading notification `list`.
+6. **Channel profile (dark)** — `profile-header` hero band, `tabs`, branded `feed` — dark-theme parity reference.
+
+## Layout
+
+- **One bar at top, one bar at bottom.** Exactly one `navigation-bar` (`home` for landing, `page` for drill-ins, `search` when the input is the screen) and one `tab-bar` (6 items, Create as the coral commit). Never stack two top bars.
+- **In-page modes are `tabs / underline`** with a sliding indicator (Company, Explore, Jobs). These are *page* tabs — distinct from Home's `avatar-rail` feed-mode chips, which are the rail primitive, not `tabs`.
+- **Filter rails** sit directly under the tabs as a horizontally scrollable `chip / filter` row (company scope, job facets).
+- **Body** scrolls under fixed chrome: `feed / post` for authored streams, `list` for notification/job rows.
+
+### Fixed-chrome scroll contract (the bars must NOT scroll)
+
+`NavigationBar` and `TabBar` render **in flow** — the components do not pin themselves (they only pay their own `env(safe-area-inset-*)`). Pinning is the **page shell's** job. Without it the whole page scrolls and both bars drift off-screen with the content. **Use `<PageShell nav={…} tabBar={…}>` — it ships this contract** (the `.chorus-page-shell` / `.chorus-page-shell__body` classes), so you don't hand-author it; a dev-only `usePinnedBarGuard` warns when a bar renders inside a scrolling region instead. The shell is a full-height flex column where only `<main>` scrolls:
+
+```css
+/* What <PageShell> / .chorus-page-shell ships — the §A.4 skeleton. */
+.page-shell {
+  display: flex;
+  flex-direction: column;
+  height: 100dvh;          /* dynamic viewport — survives mobile URL-bar show/hide */
+}
+.page-shell > main {
+  flex: 1 1 auto;
+  min-height: 0;           /* lets the flex child shrink so it — not the shell — scrolls */
+  overflow-y: auto;
+}
+```
+
+`NavigationBar` (first child) and `TabBar` (last child) are flex items at their natural height; `<main>` takes the remaining space and is the **only** scroll region — so the bars stay put. `position: sticky`/`fixed` on the bars is neither needed nor wanted here (it would re-introduce double safe-area insets). `min-height: 0` on `<main>` is the load-bearing line: omit it and the flex child refuses to shrink, the shell overflows, and the page scrolls as one piece again.
+
+## Tokens in use
+
+- **color**: `sys.color.surface` page, `sys.color.onSurface` titles, `sys.color.onSurfaceVariant` meta; coral accent on the Create tab + active heart + Poll; accent blue on inline/link affordances. Dark cell renders the same roles from `resolved.dark.json`.
+- **spacing**: one shared horizontal gutter — page shell pays `sys.layout.page.md` once; full-bleed chrome (bars, rails, feed, banners) stretches edge-to-edge inside it. `sys.layout.stack.lg` between feed cards.
+- **typography**: feed/section titles `sys.typo.heading.md` bold; meta `sys.typo.label.sm`.
+- **radius**: chips fully rounded; cards/banners `sys.radius.md`.
+
+## Components
+
+- [[navigation-bar/main]] · [[navigation-bar/sub]] · [[navigation-bar/search]] — top chrome, one per screen.
+- [[tab-bar]] — bottom nav, Create as accent.
+- [[tabs/underline]] — in-page modes with sliding indicator.
+- [[chip/filter]] — company-scope + job-facet rails.
+- [[avatar-rail]] — channel + feed-mode rail on Home.
+- [[banner]] — promo / overview / settings-off rows.
+- [[feed/post]] — authored stream.
+- [[toast]] — "Job saved" with Undo.
+- [[profile-header]] — channel hero (dark cell).
+
+## Notes
+
+- **One geometry across the flow** (AGENTS.md hard rule 6): all three `navigation-bar` subs share `56px` min-height and `8/8` padding; bar/row heights stay stable as you move between destinations.
+- **Pay the gutter once.** Do not wrap full-bleed components in a second `layout.container.md`; rails inside a `Section`/`Feed` enter `embedded` mode so the gutter isn't double-paid.
+- "For You / Recent / Popular" are `avatar-rail` chips, **not** `tabs / underline` — don't swap the primitive.
+- Dark channel-profile cell is a parity check: every composition must render under both `resolved.light` and `resolved.dark`.
+- Source mixes EN/KR; demo strings render English per AGENTS.md rule 7.

package/agents/patterns/modals.md

@@ -0,0 +1,50 @@
+---
+name: modals
+image: ./modals.png
+status: canonical
+---
+
+## Intent
+
+Overlay surfaces that interrupt the flow for a commit or disclosure — confirmation Dialogs, info Dialogs, a full-screen disclosure panel, bottom-anchored confirmation CTAs, and BottomSheet purchase flows. These are the interaction-contract primitives: `dialog` and `bottom-sheet` are `visualReuse: "locked"` — chosen for behavior (scrim, focus trap, ARIA), never borrowed for shape. Reach here for "block the screen until the user decides".
+
+## Board cells
+
+1. **Confirmation Dialog** — centered modal confirm ("I've checked it!") with scrim over a profile.
+2. **"About the Scores" info Dialog** — scrim over recommended companies, bulleted explainer + `button / icon` X close.
+3. **"Overview" disclosure panel** — full-screen scrollable info (Workplace / Employees / Contractors) with linked references and a single "Got It" primary dismiss.
+4. **Channel-profile bottom CTA** — bottom-anchored confirm button (DM guidance) over a channel surface.
+5. **Story purchase Dialog** — centered dialog over Story media, primary action + X close.
+6. **Ad-hide promotion BottomSheet** — pricing rows ($9.90/month, 7-day free trial) + commit / "Do it later" stack.
+
+## Layout
+
+- **Dialog** — centered card, scrim behind, title + body + 1–2 actions; a trailing `button / icon` X for dismissable info dialogs.
+- **BottomSheet** — drag handle, rounded top corners, scrim over the parent; content scrolls while the primary CTA stays pinned to the safe area.
+- **Disclosure panel** ("Overview") — near-full-screen scrollable info with a single bottom dismiss ("Got It") — a maximal dialog, not a new destination.
+- **Action stack** — purchase/confirm sheets pin a full-width primary commit with a neutral secondary ("Do it later" / Cancel) directly beneath.
+
+## Tokens in use
+
+- **color**: dialog/sheet surface `sys.color.surface` + `sys.color.onSurface`; scrim is the tokenized `scrim` ref over the parent; primary commit `sys.color.primary` / `onPrimary`; neutral dismiss on `sys.color.surface` with `sys.color.onSurface`; destructive commits carry `sys.color.error`.
+- **spacing**: row/section gaps `sys.layout.stack.md`–`lg`; action stack hugs the bottom safe area.
+- **typography**: dialog/sheet title `sys.typo.heading.sm`–`lg` bold; body `sys.typo.body.md`; CTA `sys.typo.label.lg`.
+- **radius**: dialog card `sys.radius.lg`; sheet top corners `sys.radius.lg`; buttons `sys.radius.md`.
+
+## Components
+
+- [[dialog]] — confirmation + info modals (About the Scores, Story purchase).
+- [[bottom-sheet]] — purchase / committed-sheet flows (ad-hide, channel-context CTAs).
+- [[button/standard]] — primary commit + neutral dismiss; `flavor: "destructive"` for irreversible commits.
+- [[button/icon]] — X close (renders `XIcon`).
+- [[banner]] — in-sheet description / teaching blocks.
+
+## Notes
+
+- **Dialog vs BottomSheet, both locked, never inline** (AGENTS.md principles 2 & 5): Dialog for modal commits, BottomSheet for committed-sheet flows. Pick by interaction, not visual fit.
+- **Every dialog / bottom-sheet needs a paired trigger** — the screen validator fails an orphaned overlay; document the triggering action.
+- **Destructive primary commits escalate to a Dialog/Sheet, never a FAB** and never fire inline — the *overlay* owns the irreversible action.
+- **Bounded surface hosting a full-bleed child** (a `list` inside a sheet) must break padding with the negative-margin opt-out so row content aligns to the sheet's content box.
+- X close is a `button / icon` with `XIcon`, never a typed `×` character (AGENTS.md rule 10).
+- Purchase sheets use a **stacked full-width action pair** when the commit is the surface's whole purpose (not the sheet's inline `primaryAction`/`secondaryAction`).
+- Source mixes EN/KR; demo strings render English per AGENTS.md rule 7.

package/agents/patterns/visual.md

@@ -0,0 +1,55 @@
+---
+name: visual
+image: ./visual.png
+status: canonical
+---
+
+## Intent
+
+Image-bearing and expressive surfaces — empty-state illustrations, photo grids, media-rich cover cards, colorful category tiles, illustration banners, and gated-channel covers. This board is the reference for the **image-area contract**: every `assetType: "image"` slot fills with the universal `/placeholder.png` and swaps to a context image by changing only the `src`, never the slot's footprint. Reach here for "this surface carries pictures, not just text".
+
+## Board cells
+
+1. **"Push notifications are off" empty state** — mascot illustration, numbered enable steps, primary "Open iOS Settings", "Not now".
+2. **Recruiting list** — company-logo `thumbnail` rows + pricing tags + "Set up your team" CTA banner.
+3. **Profile photo grid** — `profile-header` + a 3-column photo gallery.
+4. **Profile mini-card** — author card (Block / Join Team / Action Tag) + illustration recruiter banner.
+5. **Recommended Industries** — colorful category tiles (Facilities Services, Real Estate, …) + "Trending now".
+6. **Gated private channel** — `profile-header` with a full-bleed brand-tonal cover + overlay `badge` (NSFW), a centered lock-icon empty state, and a primary "Follow and request approval" CTA beside a Follow `button / toggle`.
+
+## Layout
+
+- **Empty state** — centered illustration + headline + (optional numbered steps) + a single primary CTA. Never a bare blank surface.
+- **Media rows / cards** — leading logo/cover `thumbnail` at a fixed footprint, text beside or below; covers are full-bleed within their card.
+- **Photo grid** — uniform-cell gallery under the profile header; cells crop to fill (`object-fit: cover`).
+- **Category tiles** — image/color-filled tiles with an overlaid label; the label must clear contrast against the tile (scrim if needed).
+- **Cover + gated empty state** — a full-bleed `profile-header` cover (brand-tonal, with an overlay `badge`) seats above a centered lock-icon empty state; the empty state pairs a short explainer with a single primary "request access" CTA — never a bare blank panel.
+
+## Tokens in use
+
+- **color**: `sys.color.surface` page; text over imagery resolves to the pre-paired `on*` for its host (or a scrim + `inverseOnSurface`); empty-state CTA `sys.color.primary` / `onPrimary`. Category-tile fills must pass AA against their label in both themes.
+- **spacing**: grid gutters and card gaps `sys.layout.stack.md`; one shared page gutter `sys.layout.page.md`.
+- **typography**: empty-state headline `sys.typo.heading.md` bold; card titles `sys.typo.heading.sm`; meta `sys.typo.label.sm`.
+- **radius**: cards / tiles `sys.radius.md`; avatars circular; grid cells `sys.radius.sm`.
+
+## Components
+
+- [[thumbnail]] — logo / cover image slots (`assetType: image`).
+- [[feed/ad]] — media-rich promotional cards.
+- [[carousel/post]] · [[carousel/profile]] — horizontally scrollable media previews.
+- [[profile-header]] — hero/cover band above the photo grid.
+- [[nav-card]] — cover-bearing category / channel tiles.
+- [[banner]] — illustration recruiter banner.
+- [[badge]] — logo / status overlay on a thumbnail.
+
+## Notes
+
+- **`/placeholder.png` is the single universal image-area placeholder** (AGENTS.md rule 9): fill every `assetType: image` slot with it while scaffolding; swap to a context image only by changing `src`, never the footprint or chrome. When no context image can be inferred, fall back to `/placeholder.png` — not a glyph-in-circle or invented stock URL.
+- **Full-bleed covers promote the outline stroke to the `::after` overlay layer** (AGENTS.md rule 3) — an inset shadow paints *below* an opaque cover child and gets masked at the edges it touches.
+- **Illustrations are imagery; icons are SVG glyph components** (rule 10) — the mascot is an image asset, but the numbered-step glyphs and CTAs use icon components, never typed characters.
+- **Brand/vendor marks render at authentic colors** (company / vendor logos) — they are not theme tokens; don't recolor.
+- **Gated / empty channel states stay token-true** — a centered lock-`icon` + explainer + single primary "request access" CTA; the lock is an SVG icon component (rule 10), never a typed glyph.
+- **Category tiles must pair contrast, not compose it** (rule 11): `onSurface` text over a colored/image tile usually fails AA — add a scrim or pick a pre-paired fill, don't hand-tune the foreground.
+- **Empty states are still token-true surfaces** — illustration + token-driven CTA; no off-scale spacing for the artwork.
+- Dark parity applies to every media surface — verify covers and tiles under `resolved.dark.json` too.
+- Source mixes EN/KR; demo strings render English per AGENTS.md rule 7.

package/agents/reconstruct.md

@@ -0,0 +1,55 @@
+# Chorus reconstruction prompt
+
+Paste the block below into a Chorus-aware agent (Lovable etc.) to rebuild ad-hoc,
+agent-invented UI as pure Chorus. Strongest with `LOVABLE.md` loaded as the system
+prompt — this block is a thin **driver**; the full rules live in `LOVABLE.md` and the
+guides it tells the agent to read, so the prompt stays short (lower token cost).
+
+---
+
+```text
+Chorus reconstruction pass — rebuild every ad-hoc component as pure Chorus.
+
+GOAL: every hand-built component (raw div/button, Tailwind, shadcn, inline styles, hex)
+becomes pure Chorus. No mixed renders — a screen is 100% Chorus or not done. The old UI
+is the source of a migration to @teamblind-chorus/ui + @teamblind-chorus/tokens; don't preserve or
+"match" it — the old style is the bug.
+
+FIRST read node_modules/@teamblind-chorus/ui/agents/: catalog.md, manifest.json, compose.md,
+anti-patterns.md. The component name is not the contract — bindings are in
+components/<family>/<sub>.spec.json.
+
+DO, in order:
+1. INVENTORY every non-Chorus component in src/ (one line each: file → what it is).
+2. MAP each intent via catalog.md to a family + sub. If none fits, climb the ladder
+   (recompose slots → LEGO-combine → new primitive with every value a var(--sys-*)),
+   then flag a one-line "Chorus gap". Never fall back to raw HTML/Tailwind/shadcn.
+3. REBUILD with the real import from @teamblind-chorus/ui (icons from @teamblind-chorus/ui/icons),
+   honoring the spec; then delete the old component + its CSS.
+
+NON-NEGOTIABLE (else discard + regenerate):
+- Tokens only: no hex, no Tailwind colors, no off-scale px; card edge = inset shadow,
+  never border:.
+- Typography = className="sys-typo-<role>-<rung>" (NO `font: var(--sys-typo-*)` token).
+- Compound children: <Tabs> needs <Tab>; List/SuggestionList/AvatarRail take an items
+  array — never bare text.
+- One gutter at the shell; full-bleed children (Tabs/Feed/List/Carousel/bars) never
+  wrapped in a padded div. Floating action = <Button variant="fab">, not a pinned
+  standard button. Fixed bars via .page-shell (height:100dvh + <main> overflow-y:auto).
+
+VERIFY: eslint.config.js extends @teamblind-chorus/ui/eslint — fix every chorus/* error (never
+suppress); run the §E pre-flight checklist + rail self-diagnostic (anti-patterns.md).
+
+SCOPE (optional): "SCOPE: <area/route globs>" limits the pass to that boundary —
+inventory, rebuild, and lint only inside it; outside files are reported, never edited
+(boundary rules: agents/scoped-adoption.md).
+
+DELIVER: a before→after table (component → Chorus family/sub, or "gap") and screens with
+zero mixed renders. If scope is large, reconstruct the entry screen first, list the rest.
+```
+
+---
+
+The ESLint preset (`@teamblind-chorus/ui/eslint`, wired in the VERIFY step) is the safety net:
+even if the model drops a rule mid-session, `chorus/*` errors fail the build and its own
+fix loop catches the drift.