@teamblind-chorus/ui 1.0.0

package/agents/scoped-adoption.md

@@ -0,0 +1,111 @@
+# Scoped adoption — Chorus in a designated area of an existing app
+
+Protocol for the third first-turn branch in `LOVABLE.md`: the user wants Chorus in a
+**specific area** of an in-progress project — not a full migration (§D), not a blank
+scaffold (greenfield). Triggers: the first message names a target area / route /
+feature ("apply Chorus to the settings tab", "the community feed uses Chorus"), or
+says to initialize and **stand by** for an area they'll designate next.
+
+Everything in `LOVABLE.md` still applies *inside* the designated area. This file only
+defines what changes **at and outside the boundary**.
+
+## First-turn behaviour
+
+1. Run §A.0 end-to-end (install, stylesheets, placeholder, lint preset — scoped, see
+   below) and post the readiness line.
+2. Post a drift report **scoped to the designated area** (same shape as §D.1 — counts
+   + worst offenders — but only for files the area renders). If no area is named yet,
+   skip the report and say so in one line.
+3. **Stand by.** Do NOT reconstruct the entry screen, do NOT post an app-wide
+   migration plan, do NOT touch files outside the area. The §D "reconstruct the
+   representative screen immediately" step is **suspended** in this mode — the
+   reconstruction target is the designated area, on the user's brief.
+
+## The boundary — declare it, then respect it
+
+* **Declare the Chorus boundary at route / screen granularity** whenever possible.
+  State it explicitly in your first scoped reply: *"Chorus boundary: `/community/*`
+  (CommunityPage + children)."* Everything inside renders 100% Chorus; everything
+  outside stays untouched — visually and in code.
+* **The zero-mixed-render rule applies per screen *inside* the boundary.** A screen
+  inside the boundary is 100% Chorus or not done. Screens outside the boundary are
+  out of scope — their drift is *reported, never edited*.
+* **Sub-screen areas.** If the designated area is a region within a screen that also
+  has legacy UI (e.g. "only the comment section"), first propose widening the boundary
+  to the whole screen — that's the only way to honor zero-mixed-render literally. If
+  the user declines, the area's **container element is the declared boundary**: inside
+  it 100% Chorus, outside it untouched, and you state the exception in one line
+  ("mixed render sanctioned at `<CommentSection>` per scoped boundary"). Never
+  restyle legacy siblings "for consistency".
+* **§D.4 neighbor migration is capped at the boundary.** "Touched files AND immediate
+  visual neighbors" never drags in files outside the declared area. Out-of-boundary
+  drift goes on the next-PR shopping list (§D.5), nothing more.
+* **Widening is the user's call.** They can grow the boundary ("now also the profile
+  page") or switch to full §D at any time. You may *suggest* widening when the
+  boundary forces an awkward seam; you never widen unilaterally.
+
+## Embedded host shell — who pays the gutter
+
+The §A.4 PageShell contract assumes Chorus owns the viewport. In scoped adoption it
+usually doesn't:
+
+* **Area = whole route/screen** → use `<PageShell>` normally inside that route.
+* **Area = region embedded in a legacy frame** → do NOT install `<PageShell>` (a
+  100dvh flex column inside a host layout breaks the host's scroll). Instead, treat
+  the **legacy container as the shell**: it pays the horizontal gutter **once**, and
+  Chorus full-bleed children (`List`, `Feed`, `Carousel`, `Tabs`, …) are its direct
+  children with no extra `padding-inline` / `px-*` wrapper.
+  * If the legacy container already pays its own padding, that *is* the single
+    gutter — do not re-pay it on a Chorus wrapper.
+  * If it pays none, add it once at the area root:
+    `style={{ paddingInline: 'var(--sys-layout-page-md)' }}`.
+* The rail self-diagnostic (LOVABLE.md § rail) still applies *within the area*: every
+  full-bleed child's left edge must align to the area's single gutter.
+
+## ESLint preset — scope it to the area
+
+`export default [ ...chorus ]` repo-wide would flood an unmigrated codebase with
+`chorus/*` errors and push you toward either suppressing (forbidden) or migrating
+everything (scope violation). Scope the preset with flat-config `files`:
+
+```js
+// eslint.config.js
+import chorus from "@teamblind-chorus/ui/eslint";
+export default [
+  ...chorus.map((cfg) => ({
+    ...cfg,
+    files: ["src/pages/community/**", "src/components/community/**"], // = the declared boundary
+  })),
+];
+```
+
+* "Chorus lint green" (§E checklist) means green **within the scoped `files` globs**.
+* When the user widens the boundary, widen the globs in the same change — the lint
+  scope and the declared boundary must never disagree.
+* Never silence a `chorus/*` error inside the boundary; outside the boundary the
+  rules simply don't run.
+
+## CSS coexistence — safe by construction
+
+Importing `@teamblind-chorus/tokens/tokens.css` + `@teamblind-chorus/ui/styles.css` app-wide is
+safe for the untouched legacy area. The only global effects are:
+
+* a `button/input/select/textarea { font-family: inherit }` reset (form controls
+  inherit the body font — benign, usually invisible);
+* `:root` custom properties (`--sys-*`, `--ref-*`, `--chorus-placeholder-image`) —
+  inert until something consumes them;
+* `.chorus-*` / `.sys-typo-*` classes — inert on legacy markup.
+
+The Pretendard `<link>` loads a font; it restyles nothing until a rule asks for it.
+So: import the stylesheets once at app entry as §A.0 says — do NOT try to
+conditionally load CSS per route, and do not warn the user about "global conflicts".
+
+## Exit paths
+
+* **Widen** — user names more areas; repeat the boundary declaration, widen the lint
+  globs, migrate the new area.
+* **Graduate to §D** — user asks for the full conversion; run §D from step 1 with the
+  already-migrated areas as the reference target (skip §D.3's proactive
+  reconstruction — it exists).
+* **Escape hatch (§D.7)** still works as documented: "just add the feature" demotes
+  everything to a drift note; new code stays pure Chorus.