DongHyeonka 7625dc4548 fix(theme): 열린 modal의 가림막이 스크롤바 자리까지 덮게 한다
문제: :root의 scrollbar-gutter: stable(1105/15-05)은 일반 스크롤바를 쓰는
브라우저에서 문서가 스크롤되지 않아도 오른쪽 15 px를 비워 둔다. 그 자리에는
root의 배경색이 보인다. 고정 위치 상자와 top layer의 ::backdrop은 그 자리
앞에서 끝나서, drawer·modal을 열면 오른쪽 끝에 가림막이 덮지 않은 밝은
세로 띠가 남는다. compact 골든(390 px, drawer 열림)이 가림막이 375 px에서
끝나는 모습을 정답으로 고정했다. header 띠도 같은 자리 앞에서 끝난다.

고른 방법:
- modal이 열린 동안 root 배경색을 가림막을 페이지 바탕 위에 겹친 불투명한
  색으로 바꾼다. primitives.css의 :root:has(.ui-dialog[open])이
  background-color: var(--dialog-backdrop-on-surface)를 쓴다.
- 새 컴포넌트 토큰 셋(component.css). --dialog-backdrop-weight(55%)를
  --dialog-backdrop(::backdrop이 칠하는 반투명 가림막, 값은 전과 같다)과
  --dialog-backdrop-on-surface(color-mix in srgb로 페이지 바탕과 섞은 색)가
  같이 읽는다. 브라우저는 반투명 색을 sRGB에서 겹치므로 두 색이 맞는다.
- body가 페이지 바탕(--color-surface)을 직접 칠한다. 그래서 root 배경은
  스크롤바 자리(와 overscroll)에만 보이고, 열린 modal 아래 페이지가 두 번
  어두워지지 않는다. modal이 없으면 둘이 같은 색이라 화면이 그대로다.
- 검사: tests/visual/scrollbar-gutter.visual.spec.ts. 시각 프로젝트에서
  Chromium을 --hide-scrollbars 없이 띄우고, 스크롤되지 않는 /not-found
  (390x844)에서 스크롤바 자리와 바로 옆 가림막의 평균 픽셀 색을 비교한다.
  닫힘 → drawer 열림 → 다시 닫힘 세 번 본다. 실패 메시지에 root의 계산된
  배경(색·이미지)과 열린 .ui-dialog 수를 적어, 규칙이 안 맞은 것과 맞았는데
  그 자리에 안 그려진 것을 구분한다. 08-R2 probe의 잘못된 단언 둘을
  고쳤다. 자리가 비어 있으면 clientWidth가 창 폭이라 자리 위치는 body의
  오른쪽 끝으로 찾는다. 그 자리의 hit test는 늘 null이라 픽셀을 본다.
  허용 차이 12는 drawer 그림자(70 px blur)가 옆 띠를 약 3단계 어둡게 하는
  몫이다. 덮지 않은 띠는 약 120 차이 난다.
- header 띠는 받아들이고 design-system-platform.md 8.2에 적었다. header
  색으로 칠하려면 root 배경이 셸의 header 높이·색을 알아야 하고, 셸이 없는
  화면에서는 그 띠를 빼야 한다. 완료 기준은 가림막만 요구한다.
버린 대안:
- 첫 시도: :root:has(.ui-dialog:modal)에서 가림막 색 gradient 한 겹을 페이지
  바탕 위에 얹었다. desktop batch에서 그 자리가 페이지 바탕색 그대로였다
  (gutter rgb(248 250 252), 옆 가림막 rgb(122 128 136)). 그 실행만으로는
  규칙이 안 맞았는지(:modal의 :has() 무효화), 이미지 층이 그 자리에 안
  그려졌는지 가를 수 없다. 그래서 둘 다 피한다. 배경색 자체를 바꾸고,
  showModal()이 세우는 [open] 속성으로 고른다. Dialog primitive는 브라우저에서
  늘 showModal()로 열기 때문에 열린 .ui-dialog는 modal이다.
- ::backdrop에 음수 inset(right: -N px): 스크롤바 자리는 viewport의
  padding box 밖이라 고정 위치 상자가 잘린다(스펙 기준, 화면 확인은 안 함).
- scrollbar-gutter를 거두기: 15-05의 첫 화면 shift를 다시 연다.
- modal이 열린 동안 root 배경만 바꾸고 body를 비워 두기: 페이지 전체가
  가림막 아래에서 한 번 더 어두워진다.

위험·한계: :has()를 모르는 브라우저(Firefox 121 미만 등)는 이 규칙을 버리고
전처럼 띠가 남는다. 그 자리 색은 가림막의 blur(2px)를 따르지 않는 평평한
색이다. 오른쪽 drawer(placement="end")는 drawer와 창 끝 사이에 가림막 색 띠가
남는다(템플릿은 쓰지 않음, 미확인). RTL, Firefox, WebKit은 보지 않았다.
문서가 스크롤되면 그 자리의 스크롤바는 전처럼 가림막 밖이다.
--hide-scrollbars로 찍는 compact 골든은 전체 페이지(1377 px)를 찍으므로,
열린 modal 동안 어두워진 root 배경이 창 높이(844 px) 아래의 오른쪽 15 px
띠에도 보인다. 실제 브라우저에서 그 부분은 스크롤바 아래에 있다. compact
골든 1장은 desktop에서 다시 찍었다(test:visual:update). 바뀐 것은 x 375~390
띠가 높이 전체에서 가림막 색이 된 것뿐이다. 나머지 골든 4장은 바뀌지
않았다(body와 root가 같은 색). 레이아웃은 바꾸지 않았다.

검증: desktop batch에서 확인.
corepack pnpm test:visual tests/visual/scrollbar-gutter.visual.spec.ts
corepack pnpm test:visual:update 뒤 corepack pnpm test:visual
node scripts/r5-15-scrollbar.mjs 3 <out.json> (15-R3, 첫 화면 shift 0 유지)

Refs: 1106/08-03
2026-11-06 07:24:02 +09:00
2026-08-01 19:39:59 +09:00
2026-08-01 19:39:59 +09:00

Clean Architecture Frontend Template

A React/Vite reference implementation where architecture boundaries, integration behavior, release coherence, accessibility, performance, and operations are executable contracts rather than conventions.

Start locally

Requirements: the exact Node.js version in .nvmrc (currently 24.14.0) and Corepack. The repository pins pnpm in package.json.

Product source, tests, build/quality scripts, and supported tool configuration are TypeScript/TSX. allowJs is disabled. Node-side .ts scripts run directly on the pinned Node 24 runtime and are checked with NodeNext resolution plus erasable-syntax enforcement. Project-owned executable source contains no JavaScript-family files; negative architecture, security, and type-compatibility fixtures are TypeScript/TSX as well.

corepack pnpm install --frozen-lockfile
corepack pnpm dev

Runtime configuration

Runtime-public settings are validated against one schema before the product tree mounts (runtimeConfigV2ArtifactSchema in src/contracts/release-artifacts.ts). Client secrets are forbidden.

The source of truth is config/runtime/<profile>.json, one file per environment: local, development, staging, production. corepack pnpm build writes dist/config.json from the selected profile (scripts/generate-runtime-config.ts). public/config.json is only the local profile for corepack pnpm dev; the build replaces it, so settings put there never reach a deployment. Keep it equal to config/runtime/local.json plus BUILD_ID: local-build and RELEASE_ID: local-release; tests/unit/deployment-admission.test.ts fails when the two differ.

Build and deploy variables, lowest precedence first:

Variable Sets Default
APP_PROFILE which config/runtime/<profile>.json is used local; an empty value fails the build
RUNTIME_API_BASE_URL API_BASE_URL, overriding the profile; the CI workflow cannot pass it (see below) the profile value
RUNTIME_TELEMETRY_ENDPOINT TELEMETRY_ENDPOINT, overriding the profile; the CI workflow cannot pass it (see below) the profile value
VITE_BUILD_ID BUILD_ID in the runtime config and the release manifest local-build for local and development; a staging or production build fails without it
RELEASE_ID RELEASE_ID in the runtime config and the release manifest local-release
RELEASE_TARGET the environment FE-GATE-027 admits the build to; must equal APP_PROFILE none; admission refuses without it

verify:documentation fails if this table stops naming a variable the build or admission reads (scripts/verify-documentation-readiness.ts).

Only the two RUNTIME_* values can differ from the reviewed profile. Anything else changes by editing the profile file. Staging and production reject demo auth, non-HTTPS endpoints and the names reserved for examples and tests (example.com, example.net, example.org and their subdomains, .example, .invalid, .test). The shipped staging and production profiles use *.example.com, so admission refuses them until a project sets its own endpoints.

In CI the only way to set the endpoints is to commit them to config/runtime/<profile>.json. The CI contract binds just APP_PROFILE and RELEASE_TARGET to the build job (scripts/contracts/ci-gates.ts), so a RUNTIME_* repository variable never reaches the build.

A local production build and its admission check:

APP_PROFILE=production \
RUNTIME_API_BASE_URL=<your-api-origin>/ \
RUNTIME_TELEMETRY_ENDPOINT=<your-telemetry-endpoint> \
VITE_BUILD_ID=<unique build id> RELEASE_ID=<unique release id> \
corepack pnpm build
APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission

With CI=true the gate runner (corepack pnpm ci:gate) also requires VITE_COMMIT_SHA, SOURCE_DATE_EPOCH and CI_RUNNER_IMAGE before it runs a gate (scripts/lib/build-environment.ts, scripts/run-ci-gate.ts). The CI variable list is in docs/operations/ci-quality-gates.md.

Included starter experience

The default build mounts a domain-neutral application shell with a header, responsive sidebar, route focus management, session integration status, a persistent system / light / dark theme selector, and a language selector.

The route list is ROUTE_REGISTRY (src/features/installed-feature-contracts.ts): the platform routes of src/contracts/routes.ts plus the routes of every installed feature, the removable reference feature included. The platform overview page (/examples/platform) shows the composed list at runtime, so this README keeps no copy of it and adding a feature does not edit it.

AUTH_MODE=demo is credential-free and accepted only in local/development environments. Deployments use AUTH_MODE=external and provide the opaque auth owner described in docs/architecture/starter-experience.md. The client route policy is user experience only; server authorization remains authoritative.

Support scope

Four tiers. The status words on the right are the ones the catalogs and design documents use; the next table maps them.

Tier What it covers Status words
Default In the default build and covered by the merge gates: the application shell and example routes, the REST HTTP executor, TanStack Query server state, Local/Session Storage registries, cross-tab invalidation, runtime config profiles and the release manifest check, AUTH_MODE=external (demo only in local/development), the typed message catalog, and the removable reference feature. dist/ is served by a static host (docs/architecture/static-delivery.md) COMPOSED
Optional (recipe) Not installed. A project copies one of the recipes in config/recipes/frontend-capability-recipes.json and narrows it (docs/architecture/optional-adapter-recipes.md). realtime, offline-indexeddb, service-worker-pwa and file-transfer also ship a tested reference runtime that the default build leaves out RECIPE_AVAILABLE, NOT_INSTALLED, AVAILABLE_NOT_COMPOSED
Experimental Designed and decided, but the runtime is missing or unfinished; finish it before building on it. GraphQL, gRPC-Web, Connect-Web and Protobuf adapters, Range resumable download, IndexedDB query persistence, the local preview decode-safety probe. src/features/local-draft-feature is an architecture sample, not installed DESIGNED_NOT_IMPLEMENTED
Not supported Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs NOT_SELECTED, PLATFORM_LIMITED

The rows come from docs/architecture/browser-data-capability-completion-ledger.md, docs/architecture/client-cache-and-storage.md and docs/architecture/api-contract-schema-mapper-and-server-state.md.

Status word Where it appears Meaning Tier
COMPOSED capability ledger, design documents wired into the default production path Default
INSTALLED a project's own recipe catalog (step 10 of the recipe procedure) the project added the recipe Default, for that project
RECIPE_AVAILABLE recipe catalog status a recipe exists to copy; nothing is installed Optional
NOT_INSTALLED recipe catalog defaultStatus; a declared feature the build or FEATURE_OVERRIDES left out. A sample directory that is no feature at all carries a src/features/<dir>/NOT_A_FEATURE marker file instead not part of the build Optional (recipe) or Experimental (feature)
AVAILABLE_NOT_COMPOSED capability ledger; recipe referenceRuntime.status code and tests exist; the default build leaves it out Optional
DESIGNED_NOT_IMPLEMENTED capability ledger, design documents design approved, runtime missing Experimental
NOT_SELECTED capability ledger, design documents deliberately not chosen Not supported
PLATFORM_LIMITED capability ledger browsers cannot guarantee it; offered only behind a probe and a fallback, if at all Not supported as a guarantee

Gate results (PASS, PASS_SCOPED, UNVERIFIED, FAIL_UNVERIFIED) are verdicts on evidence, not support tiers.

Browsers: the build targets Chrome and Edge 111, Firefox 128, and Safari and iOS 16.4. That is the higher of Vite 8's default JavaScript target (baseline-widely-available; vite.config.ts sets no build.target) and the CSS targets of Tailwind CSS 4. There is no browserslist. The end-to-end suite runs on the desktop Chromium, Firefox and WebKit builds that Playwright 1.62 pins, plus one Chromium phone-size smoke (playwright.config.ts). Older versions inside the target range and real mobile browsers are not tested.

Architecture

This repository is a Frontend Application Foundation: a starter/composition skeleton plus a reusable capability platform. Platform capabilities stay horizontal while product business features use vertical slices.

src/ has nine top-level folders. The descriptions match the table in docs/architecture/layers.md, which also names every import rule:

  • src/bootstrap — the composition root: runtime configuration, concrete adapter construction and the React mount
  • src/apps — deployable apps: each app-module.ts declares an app and its context budget; template-app.ts is the app this build produces
  • src/contexts — bounded contexts: each context-module.ts declares its app, route root and feature budget
  • src/features — removable vertical slices (src/features/<id>/{domain,application,contracts,adapters,presentation}) and the installed-feature catalogs (src/features/*.ts)
  • src/presentation — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers
  • src/adapters — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more
  • src/application — generic use cases, ports, policies and view-models
  • src/contracts — shared vocabulary and registries read by several layers, the workers and the build and release scripts
  • src/platform — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence

Dependencies point inward. Every folder may also import contracts and platform:

presentation -> application -> contracts -> platform
adapters -----^
bootstrap composes concrete adapters
apps -> contexts -> features   (an app deploys contexts; a context owns features)
feature use case -> feature port <- feature-owned capability binding

Domain code lives inside each feature; there is no top-level domain folder.

See docs/architecture/frontend-application-foundation.md, docs/architecture/overview.md, docs/architecture/layers.md, and docs/architecture/starter-experience.md. The removable vertical slice is under src/features/reference-feature; its domain, application input, HTTP binding, contracts, route runtime, and presentation own their contributions. The central installed catalogs only aggregate selected contributions. The generic starter routes continue to typecheck, test, and build after that feature is removed.

Platform capability review

The starter shell is implemented, but the repository review also records the remaining work required before feature teams can use every declared contract through one end-to-end application path:

These documents distinguish repository defaults from opt-in adapters and project-owned integrations. They are target designs and review findings; a capability is not treated as implemented until its branch acceptance criteria and executable gates pass.

Documentation

docs/README.md sorts the documents into current contracts, target designs and work history. docs/manual/ is the step-by-step guide (Korean) for adding a feature, starting from corepack pnpm create:feature <id>.

Files you can delete after copying

These record how the template was built. Nothing in the build or the gates reads them, except the one file noted below (tests/unit/deletable-history-documents.test.ts checks this).

Path Contents
docs/superpowers/ past plans and specs
docs/reviews/ reviews and the review guide. Keep docs/reviews/adapters/: check:adapter-inventory (FE-GATE-010) reads its INVENTORY.md, whose rows link to the adapter reviews beside it, and docs/operations/adapter-remediation-ledger.md cites those reviews
SPEC.md, tasks/ requirements and task list of the 2026-09-25 review fix round
CLAUDE.md review instructions for the template repository itself; replace it with your own
PRODUCT.md product context of the template itself (users, purpose, principles) for design tools; replace it with your product's

The reference feature is not in this list: deleting its directory alone leaves tests, policy entries and CI scripts behind that fail the gates. scripts/test-sample-removal.ts removes it from a copy of the repository and lists everything that has to go with it (its header comment, and the files outside the feature's folders in scripts/lib/removable-template-features.ts); do the same in your project and run the gates. The documents keep naming the sample's paths: the documentation check accepts them once src/features/reference-feature/feature-module.ts is gone.

Verification

Common local checks:

corepack pnpm lint
corepack pnpm check:types
corepack pnpm check:types:app
corepack pnpm check:types:node
corepack pnpm check:types:test
corepack pnpm check:architecture
corepack pnpm test:all
corepack pnpm test:contract
corepack pnpm test:e2e
corepack pnpm test:a11y
corepack pnpm build
corepack pnpm check:bundle
corepack pnpm test:performance
corepack pnpm verify:compatibility
corepack pnpm verify:release
corepack pnpm check:registries
corepack pnpm drill:runbooks
corepack pnpm check:ci

drill:runbooks stops at the first drill that is not PASS. Without provider evidence every drill ends UNVERIFIED (exit 3), because a drill never reports a check it could not run locally as PASS; see "Runbook jobs" in docs/operations/ci-quality-gates.md.

test:all is the ordinary product-development loop and intentionally excludes host-level CI-runner assurance. Run corepack pnpm test:system only on the compatible Linux assurance host described in docs/testing/taxonomy.md.

check:types는 source, Node scripts/config와 tests를 분리된 TypeScript project로 모두 검사한다. type/architecture/security/registry의 invalid fixture는 config/ci/gates.json에서 “실패해야 통과”하는 negative gate로 실행된다. 도구 호환성 결정은 VD-01에 기록돼 있다.

Application feature input은 module augmentation으로 닫힌 ID와 정확한 input shape를 제공하며, 공통 Result<Value, Failure = AppFailure>는 error registry의 failure kind만 application/presentation 경계를 통과시킨다. Architecture gate는 TypeScript/TSX의 static, dynamic, type import를 별도 정적 그래프로 분석하고 runtime/source 영역의 JavaScript 재유입도 거절한다. 해석되지 않은 import, parse failure, 금지 계층 edge와 순환 의존은 모두 fail-closed이며 전용 TypeScript/TSX negative fixture로도 검증된다.

Install the pinned Playwright browser engines before the first cross-browser run:

corepack pnpm exec playwright install --with-deps chromium firefox webkit

Two gates intentionally need external evidence:

  • review:a11y-manual (release gate FE-GATE-028) needs a signed human keyboard/focus/screen-reader review of every registered route, one record per route at artifacts/tests/a11y-manual/<ROUTE_ID>.md. The routes are ROUTE_REGISTRY; verify:documentation fails, naming the route ID, when a registered route has no record. The merge gate FE-GATE-009 runs only review:a11y-manual -- --format-only, which checks that every route record keeps the template's fields, reviewed or still pending.
  • collect:web-vitals-evidence stays FAIL_UNVERIFIED until a reviewed minimum eligible-sample threshold and 28 days of production data exist.

Live hosting verification (FE-GATE-019, production stage) requires HOSTING_BASE_URL and the promoted release deployed by the workflow's deployment job. That job is an empty slot until the project fills it in config/ci/product-gates.json (docs/operations/ci-quality-gates.md); until then the result is UNVERIFIED, not PASS. A host serving another release fails, and so does one without HTTP/2 or entry compression.

CI and evidence

The gate registry is config/ci/gates.json; the Gitea workflow is .gitea/workflows/quality-gates.yml. It follows:

MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY

DOCUMENTATION_READY is independent. No gate is downgraded to a warning.

The workflow runs on pull requests, pushes to main and develop, and v* tags. The Git host of this repository may not have Actions enabled, so a pull request can show no gate status at all; no status is not a pass. Until the host runs the workflow and marks the merge gates as required checks, run the 14 merge gates locally before merging (FE-GATE-008 and 009 need Playwright browsers; FE-GATE-012 builds the app first; FE-GATE-013 needs a Linux host where bubblewrap may create unprivileged user and network namespaces, which Ubuntu 23.10 and later refuse by default — its first step says so, and docs/operations/ci-quality-gates.md lists the fixes). Product checks listed in config/ci/product-gates.json (PRODUCT-GATE-NNN) run in the workflow's own product_merge_gate job, which the release stage waits for:

for gate in 001 002 003 004 005 006 007 008 009 010 011 012 013 020; do
  corepack pnpm ci:gate -- "FE-GATE-$gate" || break
done

To run them as the workflow does, give the workflow's environment first. CI=true makes the runner and the release build require the CI build identity; builds a test makes of a copy (fixture builds, the visual goldens' build, the dev servers of the browser tests) run as local builds whatever this says (localBuildEnvironment in scripts/lib/build-environment.ts). Run it in a clean clone: ci:gate stops a gate at its first failing command.

export CI=true VITE_COMMIT_SHA="$(git rev-parse HEAD)" VITE_BUILD_ID=local-ci-1 \
  RELEASE_ID=local-ci-1 CI_RUNNER_IMAGE="local/runner@sha256:$(printf 'a%.0s' $(seq 64))"

Machine-readable evidence is written below artifacts/; generated evidence is ignored by Git while .gitkeep files preserve the taxonomy.

Run the gates one at a time in a checkout: they and the evidence checks read the fixed dist/ and artifacts/ paths. Two Playwright runs can share a checkout when each has its own TEST_RUN_ID; its build, results and report go below .tmp/runs/<id>/. The test servers always pick a free port. The variables are listed in docs/testing/frontend-platform-testing-strategy.md (13.6).

Operational details are in docs/operations/, with incident procedures in docs/runbooks/.

Updating a copied project

Template versions are Git tags vX.Y.Z. CHANGELOG.md lists the changes between tags, marks security fixes [보안] and contract changes [계약] (backend, deployment, CI or feature code must change too), and names the affected paths. Its unreleased section summarizes one sync range (the section head names the base commit and the branch); take that range as a whole and do its "먼저 할 일" (BREAKING) steps in order before running the gates.

Record where you started. Right after copying, commit a one-line .template-origin file at the root of your project with the template tag (or commit) you copied and the date, for example v0.2.0 2026-09-26.

Take a template fix with Git. cherry-pick works even when your repository does not share the template's history, because it merges against the picked commit's parent:

git remote add template <template repository URL>
git fetch template --tags
git log --oneline <your origin>..template/main   # what changed since you copied
git cherry-pick -x <commit>                      # one fix; -x records its origin

Take an unreleased range as a whole. A repository that shares the template's history merges the range's branch. One that does not (it started from a copy of the files) merges three-way against the range base, which leaves the files both sides changed as conflicts; resolve them and commit:

git merge --no-ff template/<range branch>                     # shared history
git merge-recursive <range base> -- HEAD template/<range branch>  # no shared history

Keep the base you synced from where your project records it: .template-origin (below), or your own lock file (tech-log keeps it as sourceRevision in template.lock.json). Move it to the range end once the range is in.

When the files have moved or diverged too far for a clean pick, read the change as a diff and apply it by hand:

git diff <commit>^ <commit> -- <paths from CHANGELOG>

Afterwards run the local merge gates from "CI and evidence", apply the backend or deployment change a [계약] row names, and update .template-origin once you have caught up to a tag. git revert undoes a pick.

Defects: if a problem reproduces on an unmodified checkout of your .template-origin commit, it is a template defect. Report it on the template repository with that commit and the reproduction; the template maintainer classifies it and ships the fix with a CHANGELOG entry. A problem that needs your changes to reproduce belongs to your project, and applying a template fix to your copy is your project's job.

S
Description
No description provided
Readme
20 MiB
Languages
TypeScript 98.2%
Python 1%
CSS 0.5%
Shell 0.3%